# telamon-framework-system

> The Rust crate for Telamon system apps, with opt-in crash reports, Telamon OS state \(bootc status, boot history, update events\), polkit checks for root helpers and desktop notifications.

`telamon-framework-system` is for apps that work with the Telamon OS system: Telamon Updater, Telamon Monitor and the root helper behind them. It holds opt-in crash reports (the only telemetry a Telamon app may have), the types and files that describe the Telamon OS image state, a polkit check for root D-Bus helpers, and desktop notifications.

A light app can use [`crash`](https://telamon.eterneon.net/framework/telamon-framework-system/crash.md) alone: only the `polkit` and `notify` features bring in D-Bus. [telamon-framework-ui](https://telamon.eterneon.net/framework/telamon-framework-ui.md) already depends on this crate (without the features) for the crash hooks, so a GUI app gets `crash` without adding anything.

## Add it

```toml
telamon-framework-system = { git = "https://github.com/EternalCoder454/atlas-framework", tag = "v2.0.0", features = ["notify"] }
```

The commit is the one tagged `v1.4.0`. Pin apps to a commit or a release tag and build with `cargo build --locked`. Leave out `features` if the app needs neither feature.

## Features

| Feature | Default | What it adds |
|---|---|---|
| `polkit` | off | The [`polkit`](https://telamon.eterneon.net/framework/telamon-framework-system/polkit.md) module: the authorization check for a root helper. Pulls in `zbus` and `tokio` |
| `notify` | off | The [`notify`](https://telamon.eterneon.net/framework/telamon-framework-system/notify.md) module: desktop notifications over `org.freedesktop.Notifications`. Pulls in `zbus` and `tokio` |

## Pages

| Page | What it covers |
|---|---|
| [crash](https://telamon.eterneon.net/framework/telamon-framework-system/crash.md) | Opt-in crash reports: settings, endpoint, scrubbing, collecting, sending |
| [history](https://telamon.eterneon.net/framework/telamon-framework-system/history.md) | The versions this machine has booted |
| [bootc](https://telamon.eterneon.net/framework/telamon-framework-system/bootc.md) | Types for `bootc status --json` and the channel tag rewrite |
| [events](https://telamon.eterneon.net/framework/telamon-framework-system/events.md) | Update and rollback events the system helper records |
| [polkit](https://telamon.eterneon.net/framework/telamon-framework-system/polkit.md) | The authorization check for a root D-Bus helper (feature `polkit`) |
| [notify](https://telamon.eterneon.net/framework/telamon-framework-system/notify.md) | Desktop notifications the way KNotification sends them (feature `notify`) |
| [On-disk formats](https://telamon.eterneon.net/framework/telamon-framework-system/formats.md) | Every file these modules read or write, with paths and fields |

## Crate root

| Name | Kind | Description |
|---|---|---|
| `bootc`, `crash`, `events`, `history` | modules | Always available |
| `notify` | module | Feature `notify` |
| `polkit` | module | Feature `polkit` |


## Pages

- [crash](https://telamon.eterneon.net/framework/telamon-framework-system/crash.md): Opt-in crash reports, the only telemetry a Telamon app may have, with the per-user switch, the endpoint, scrubbing, the pending queue and sending after the user has seen the exact payload.
- [history](https://telamon.eterneon.net/framework/telamon-framework-system/history.md): The record of Telamon OS versions this machine has booted, one JSON line each, and the helpers that read and append to it.
- [bootc](https://telamon.eterneon.net/framework/telamon-framework-system/bootc.md): Typed views of bootc status --json for Telamon OS \(booted, staged and rollback images, the update channel and available updates\) and the channel tag rewrite.
- [events](https://telamon.eterneon.net/framework/telamon-framework-system/events.md): The update and rollback events the Telamon OS system helper records, one JSON line each, and the functions that read and append them.
- [polkit](https://telamon.eterneon.net/framework/telamon-framework-system/polkit.md): The polkit authorization check behind every admin action of a Telamon root D-Bus helper, failing closed, available with the polkit feature.
- [notify](https://telamon.eterneon.net/framework/telamon-framework-system/notify.md): Desktop notifications over org.freedesktop.Notifications, sent the way KNotification sends them so Plasma groups them under the app and honours the user's per-event choice, with the notify feature.
- [On-disk formats](https://telamon.eterneon.net/framework/telamon-framework-system/formats.md): Every file the system crate and the core crate read or write for other programs, with exact paths, keys, fields and permissions, and the format-version rule.