sensitivebox 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. sensitivebox-0.1.0/LICENSE +21 -0
  2. sensitivebox-0.1.0/PKG-INFO +424 -0
  3. sensitivebox-0.1.0/README.md +403 -0
  4. sensitivebox-0.1.0/pyproject.toml +90 -0
  5. sensitivebox-0.1.0/pyproject.toml.orig +68 -0
  6. sensitivebox-0.1.0/src/sensitivebox/__init__.py +10 -0
  7. sensitivebox-0.1.0/src/sensitivebox/alerts/__init__.py +94 -0
  8. sensitivebox-0.1.0/src/sensitivebox/alerts/config.py +85 -0
  9. sensitivebox-0.1.0/src/sensitivebox/alerts/defaults.toml +126 -0
  10. sensitivebox-0.1.0/src/sensitivebox/alerts/engine.py +624 -0
  11. sensitivebox-0.1.0/src/sensitivebox/alerts/events.py +87 -0
  12. sensitivebox-0.1.0/src/sensitivebox/alerts/globs.py +84 -0
  13. sensitivebox-0.1.0/src/sensitivebox/alerts/model.py +215 -0
  14. sensitivebox-0.1.0/src/sensitivebox/alerts/mute.py +55 -0
  15. sensitivebox-0.1.0/src/sensitivebox/alerts/replay.py +99 -0
  16. sensitivebox-0.1.0/src/sensitivebox/alerts/routing.py +247 -0
  17. sensitivebox-0.1.0/src/sensitivebox/api/__init__.py +6 -0
  18. sensitivebox-0.1.0/src/sensitivebox/api/app.py +225 -0
  19. sensitivebox-0.1.0/src/sensitivebox/api/data.py +109 -0
  20. sensitivebox-0.1.0/src/sensitivebox/api/host.py +27 -0
  21. sensitivebox-0.1.0/src/sensitivebox/api/model.py +90 -0
  22. sensitivebox-0.1.0/src/sensitivebox/api/security.py +89 -0
  23. sensitivebox-0.1.0/src/sensitivebox/api/server.py +108 -0
  24. sensitivebox-0.1.0/src/sensitivebox/api/state.py +220 -0
  25. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/archivo-latin-wdth-normal-DY7AcnAa.woff2 +0 -0
  26. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/ibm-plex-mono-medium-BpyVxOr_.woff2 +0 -0
  27. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/index-BH9EydfS.js +10 -0
  28. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/index-RMruxW54.css +1 -0
  29. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-on-dark-CpSxozdM.png +0 -0
  30. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-on-light-DgUAeHTp.png +0 -0
  31. sensitivebox-0.1.0/src/sensitivebox/api/static/assets/mark-raised-Bg5z6PGs.png +0 -0
  32. sensitivebox-0.1.0/src/sensitivebox/api/static/index.html +14 -0
  33. sensitivebox-0.1.0/src/sensitivebox/browser.py +106 -0
  34. sensitivebox-0.1.0/src/sensitivebox/cli.py +467 -0
  35. sensitivebox-0.1.0/src/sensitivebox/collector.py +319 -0
  36. sensitivebox-0.1.0/src/sensitivebox/completion.py +117 -0
  37. sensitivebox-0.1.0/src/sensitivebox/daemon.py +181 -0
  38. sensitivebox-0.1.0/src/sensitivebox/data/icons/128.png +0 -0
  39. sensitivebox-0.1.0/src/sensitivebox/data/icons/256.png +0 -0
  40. sensitivebox-0.1.0/src/sensitivebox/data/icons/512.png +0 -0
  41. sensitivebox-0.1.0/src/sensitivebox/data/proart-p16.tar.gz +0 -0
  42. sensitivebox-0.1.0/src/sensitivebox/data/sensitivebox.desktop.in +8 -0
  43. sensitivebox-0.1.0/src/sensitivebox/data/sensitivebox.service.in +11 -0
  44. sensitivebox-0.1.0/src/sensitivebox/doctor.py +322 -0
  45. sensitivebox-0.1.0/src/sensitivebox/fixtures.py +177 -0
  46. sensitivebox-0.1.0/src/sensitivebox/history.py +298 -0
  47. sensitivebox-0.1.0/src/sensitivebox/hwmon/__init__.py +20 -0
  48. sensitivebox-0.1.0/src/sensitivebox/hwmon/classify.py +74 -0
  49. sensitivebox-0.1.0/src/sensitivebox/hwmon/discovery.py +139 -0
  50. sensitivebox-0.1.0/src/sensitivebox/hwmon/ids.py +35 -0
  51. sensitivebox-0.1.0/src/sensitivebox/hwmon/model.py +78 -0
  52. sensitivebox-0.1.0/src/sensitivebox/hwmon/normalise.py +42 -0
  53. sensitivebox-0.1.0/src/sensitivebox/hwmon/reader.py +65 -0
  54. sensitivebox-0.1.0/src/sensitivebox/inspect.py +175 -0
  55. sensitivebox-0.1.0/src/sensitivebox/live.py +56 -0
  56. sensitivebox-0.1.0/src/sensitivebox/notify/__init__.py +7 -0
  57. sensitivebox-0.1.0/src/sensitivebox/notify/base.py +60 -0
  58. sensitivebox-0.1.0/src/sensitivebox/notify/desktop.py +84 -0
  59. sensitivebox-0.1.0/src/sensitivebox/notify/log.py +30 -0
  60. sensitivebox-0.1.0/src/sensitivebox/operations.py +44 -0
  61. sensitivebox-0.1.0/src/sensitivebox/output.py +76 -0
  62. sensitivebox-0.1.0/src/sensitivebox/process.py +25 -0
  63. sensitivebox-0.1.0/src/sensitivebox/py.typed +0 -0
  64. sensitivebox-0.1.0/src/sensitivebox/redact.py +85 -0
  65. sensitivebox-0.1.0/src/sensitivebox/report.py +357 -0
  66. sensitivebox-0.1.0/src/sensitivebox/runtime.py +313 -0
  67. sensitivebox-0.1.0/src/sensitivebox/sample.py +84 -0
  68. sensitivebox-0.1.0/src/sensitivebox/service.py +112 -0
  69. sensitivebox-0.1.0/src/sensitivebox/simulate.py +220 -0
  70. sensitivebox-0.1.0/src/sensitivebox/sources/__init__.py +83 -0
  71. sensitivebox-0.1.0/src/sensitivebox/sources/apps.py +135 -0
  72. sensitivebox-0.1.0/src/sensitivebox/sources/bluez.py +96 -0
  73. sensitivebox-0.1.0/src/sensitivebox/sources/bluez_watch.py +214 -0
  74. sensitivebox-0.1.0/src/sensitivebox/sources/changes.py +121 -0
  75. sensitivebox-0.1.0/src/sensitivebox/sources/cpu.py +152 -0
  76. sensitivebox-0.1.0/src/sensitivebox/sources/dbus.py +174 -0
  77. sensitivebox-0.1.0/src/sensitivebox/sources/logind.py +88 -0
  78. sensitivebox-0.1.0/src/sensitivebox/sources/memory.py +127 -0
  79. sensitivebox-0.1.0/src/sensitivebox/sources/net.py +128 -0
  80. sensitivebox-0.1.0/src/sensitivebox/sources/power_profiles.py +116 -0
  81. sensitivebox-0.1.0/src/sensitivebox/sources/power_supply.py +70 -0
  82. sensitivebox-0.1.0/src/sensitivebox/sources/psi.py +78 -0
  83. sensitivebox-0.1.0/src/sensitivebox/sources/report.py +85 -0
  84. sensitivebox-0.1.0/src/sensitivebox/sources/wifi.py +90 -0
  85. sensitivebox-0.1.0/src/sensitivebox/sources/wifi_nm.py +269 -0
  86. sensitivebox-0.1.0/src/sensitivebox/status.py +205 -0
  87. sensitivebox-0.1.0/src/sensitivebox/store/__init__.py +5 -0
  88. sensitivebox-0.1.0/src/sensitivebox/store/changes.py +58 -0
  89. sensitivebox-0.1.0/src/sensitivebox/store/db.py +423 -0
  90. sensitivebox-0.1.0/src/sensitivebox/store/events.py +337 -0
  91. sensitivebox-0.1.0/src/sensitivebox/store/mutes.py +58 -0
  92. sensitivebox-0.1.0/src/sensitivebox/store/quality.py +51 -0
  93. sensitivebox-0.1.0/src/sensitivebox/store/read.py +40 -0
  94. sensitivebox-0.1.0/src/sensitivebox/store/schema.py +194 -0
  95. sensitivebox-0.1.0/src/sensitivebox/store/status.py +105 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sensitive Box contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,424 @@
1
+ Metadata-Version: 2.4
2
+ Name: sensitivebox
3
+ Version: 0.1.0
4
+ Summary: Read-only Linux hwmon sensor daemon with alerting and a neo-skeuomorphic local web UI.
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: Environment :: Console
9
+ Classifier: Intended Audience :: End Users/Desktop
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Topic :: System :: Monitoring
14
+ Classifier: Typing :: Typed
15
+ Requires-Dist: dbus-fast>=5.2,<6
16
+ Requires-Dist: msgspec>=0.19,<1
17
+ Requires-Dist: starlette>=1.10.0
18
+ Requires-Dist: uvicorn>=0.54.0
19
+ Requires-Python: >=3.12
20
+ Description-Content-Type: text/markdown
21
+
22
+ # Sensitive Box
23
+
24
+ A read-only Linux hardware monitor that **alerts you before something overheats**, with memory
25
+ pressure and network activity alongside thermals, fans and power.
26
+
27
+ > **v0.1.0.** The first shareable release: discovery, alerts, the daemon, the command line,
28
+ > and the local dashboard.
29
+
30
+ ## Install
31
+
32
+ ```sh
33
+ uv tool install sensitivebox
34
+ sbox enable
35
+ sbox open
36
+ ```
37
+
38
+ `uv tool install sensitivebox` is the PyPI install. The same wheel is attached to the
39
+ [v0.1.0 GitHub release](https://github.com/JonDanMa/sensitivebox/releases/tag/v0.1.0):
40
+
41
+ ```sh
42
+ uv tool install "https://github.com/JonDanMa/sensitivebox/releases/download/v0.1.0/sensitivebox-0.1.0-py3-none-any.whl"
43
+ ```
44
+
45
+ End users do not need Node. The release wheel contains the built dashboard.
46
+
47
+ From a checkout, for development:
48
+
49
+ ```sh
50
+ uv sync
51
+ uv run sbox --help
52
+ ```
53
+
54
+ Both `sbox` and `sensitivebox` are installed and accept the same commands.
55
+
56
+ ## Web UI
57
+
58
+ The dashboard is at `/`. Alerts (acknowledge, and mute labelled Snooze) are at `/log`. A rule's
59
+ replay is at `/rule/<id>`. Settings, including the remembered theme and rule edits, are at
60
+ `/settings`. Click a reading to open its history. The design system is at `/styleguide`.
61
+
62
+ Build the UI, then run `sbox watch` or `sbox demo heatwave --no-notify` and open
63
+ `http://127.0.0.1:7878/`. Without a build, the server explains how to build it. `pnpm dev` answers
64
+ the API from a scripted machine, including the rule routes the daemon does not have yet.
65
+
66
+ ```sh
67
+ cd ui
68
+ pnpm i
69
+ pnpm dev # http://localhost:5173/ (the styleguide is /styleguide)
70
+ pnpm test # unit tests
71
+ pnpm test:e2e # Playwright snapshots, behaviour and accessibility checks
72
+ pnpm build # writes to src/sensitivebox/api/static (not committed)
73
+ ```
74
+
75
+ Only people working on the UI need Node and pnpm.
76
+
77
+ ## Landing page
78
+
79
+ The public landing page lives in `ui/site/`, with its own Vite entry point and a
80
+ canonical URL of `https://sbox.mosys.ai/`. Its build is independent of the local
81
+ dashboard: it neither includes the fixture API nor writes into the Python package.
82
+
83
+ ```sh
84
+ cd ui
85
+ pnpm install --frozen-lockfile
86
+ pnpm site:dev
87
+ pnpm site:check
88
+ pnpm site:build
89
+ pnpm site:budget
90
+ pnpm site:test
91
+ pnpm site:preview
92
+ ```
93
+
94
+ Development serves `http://127.0.0.1:5174/`; the built preview serves
95
+ `http://127.0.0.1:4174/`. Static output is `ui/site/dist/`. Fonts, icons and dashboard
96
+ captures are served locally. The labelled call-preparation example uses scripted
97
+ browser-only data; it reads no device data, calls no AI service and pauses no real job.
98
+
99
+ The page presents the approved finished-product direction, including the operator's
100
+ own local AI and private SSH connections. It does not change the daemon's current
101
+ capabilities or the installation status documented above. See the landing-page
102
+ decisions in [the bible](docs/BIBLE.md#public-landing-page-decisions-approved-2026-11-13).
103
+ Building or previewing the site does not publish it.
104
+
105
+ The opening fills a normal desktop viewport through the privacy principles, with
106
+ extra height allowed for larger text or short windows. The four principles stay
107
+ on one row: four at desktop widths, two below 1100px, and one below 600px. The
108
+ smaller-screen carousel supports mouse dragging, touch scrolling, arrow keys and
109
+ Home/End, with Space to pause or resume and no visible controls. Both rest for
110
+ three seconds between moves; phones glide for 660ms and tablets for 1.1 seconds.
111
+ It pauses on hover/focus or while offscreen and stays manual under reduced
112
+ motion. Below 800px the mesh is drawn
113
+ once, refreshing only when its size or theme changes. Both mountain backgrounds
114
+ are self-hosted; the light circles use a still, CSS pearlescent finish. The light
115
+ sky is a whitened sunrise gradient in CSS, with softer mesh dots for readability.
116
+
117
+ `pnpm site:test` builds the landing and runs its browser regression checks,
118
+ including 320px layouts, desktop height, carousel behaviour, and accessibility.
119
+
120
+ ## Commands
121
+
122
+ | Command | Purpose |
123
+ |---|---|
124
+ | `sbox` | One status report: host, key readings, stored alert states and freshness. |
125
+ | `sbox watch` | Run the daemon in the foreground, with desktop notifications and history. |
126
+ | `sbox demo heatwave` | Run a packaged scenario with popups and in-memory history. |
127
+ | `sbox doctor` | List every sensor, stable ID, group, limits, default rules and unavailable reasons. |
128
+ | `sbox apps` | Show current memory PSI and the top five apps while memory is tight. |
129
+ | `sbox rules` | Show each configured rule's matched signals, state and reason. |
130
+ | `sbox rule cpu-hot` / `sbox rules cpu-hot` | Replay retained input frames through the real engine. |
131
+ | `sbox mute cpu-hot 30m` / `sbox unmute cpu-hot` | Hold or release every notification severity for a rule. |
132
+ | `sbox quiet 22:00-07:00` / `sbox quiet off` | Recurring local quiet hours for every rule; critical still gets through. |
133
+ | `sbox log` / `sbox log -f` | Group incidents, or follow their individual events. |
134
+ | `sbox log --weekly` | Per-rule ISO-week alert quality measurements. |
135
+ | `sbox log --daemon` | Read the user-service journal; combine with `-f` to follow. |
136
+ | `sbox enable` / `sbox disable` | Enable/start or disable/stop the systemd user service now. |
137
+ | `sbox open [log\|settings]` / `sbox open rule cpu-hot` | Launch a loopback dashboard URL in the default browser. |
138
+ | `sbox report [--fixture]` | Export a private diagnostic archive or reusable machine fixture. |
139
+ | `sbox completion bash` | Print a sourceable bash completion script; `zsh` is also supported. |
140
+
141
+ Use `uv run` before these commands when working from the checkout.
142
+
143
+ `run` remains a hidden alias of `watch` for one release, with exactly the same arguments.
144
+ Old simulation flags now explain how to use `demo`. The old `dump` and `install-service` stubs
145
+ have been removed. The dashboard is the next milestone; `open` launches its URL
146
+ without checking for a listener and explains that the page needs the service.
147
+
148
+ ## Status and scripting
149
+
150
+ ```sh
151
+ sbox
152
+ sbox --json
153
+ sbox rules --json
154
+ sbox doctor --json
155
+ ```
156
+
157
+ Readings come from one fresh sample. Alert state comes from the newest stored evaluations;
158
+ a one-shot command never starts a new alert engine or creates/migrates the history database.
159
+ An evaluation is fresh for three times its signal's poll interval plus the store's 5-second
160
+ flush allowance. Missing or stale state shows **Unknown**, with a hint to start `sbox watch`.
161
+ A changed rule configuration requires restarting the daemon before its state is trusted.
162
+
163
+ | Exit code from plain `sbox` | Meaning |
164
+ |---|---|
165
+ | 0 | Alert state is fresh and no warning or critical alert is open. |
166
+ | 1 | A warning is open, or alert state is stale or missing. |
167
+ | 2 | A critical alert is open; this wins over other stale state. |
168
+ | 3 | Operational failure: invocation, configuration, fixture or database error. |
169
+
170
+ Info alerts, Pending, Warming and a fresh Unknown signal do not raise the health code.
171
+ Host uptime comes from `/proc/uptime` and is labelled **host uptime**. Status and heartbeats
172
+ show explicit mute counts and remaining durations when their boot identity is available. Today's
173
+ and this month's stored byte totals remain **unavailable**; unavailable never means zero. Network counters in doctor are explicitly labelled **since boot**.
174
+
175
+ Every command accepts `--json` before or after the command. One-shot results have the shape
176
+ `{"version":1,"kind":"status","data":{...}}`; live commands emit newline-delimited JSON
177
+ (NDJSON), including startup, alert, status and stopped events. In JSON mode, errors and diagnostic
178
+ logs are JSON on stderr; stdout contains no prose. Usage errors return 3, including typos, which
179
+ suggest a command without running the correction. Text output has no colour escapes, so pipes
180
+ and `NO_COLOR` work without special handling.
181
+
182
+ ## Foreground monitoring
183
+
184
+ ```sh
185
+ sbox watch
186
+ sbox watch --interval 2
187
+ sbox watch --db ./history.db --json
188
+ ```
189
+
190
+ The daemon polls every second by default, feeds the alert engine, stores history in
191
+ `~/.local/state/sensitivebox/sensitivebox.db` (or `$XDG_STATE_HOME/sensitivebox/sensitivebox.db`),
192
+ and sends desktop notifications. Critical alerts use critical urgency; resolved alerts use low
193
+ urgency. Output retains startup and alert lines, followed by the 30-second heartbeat and one
194
+ status summary line. There is no full-screen redraw. Ctrl-C or SIGTERM stops it cleanly.
195
+
196
+ Memory and network have a 2-second sampling tier, batteries and chargers 5 seconds, and app
197
+ memory at most every 20 seconds while memory is tight. Sleep and shutdown pause evaluation;
198
+ resume warms rules again without closing an open alert or sending a duplicate notification.
199
+
200
+ User rules in `~/.config/sensitivebox/rules.toml` (or `$XDG_CONFIG_HOME/sensitivebox/rules.toml`)
201
+ override shipped defaults by ID. Rule states are shown per matched signal, so one critical
202
+ signal cannot disappear behind a rule summary. An unmatched rule is Unknown.
203
+
204
+ ## Local API
205
+
206
+ `watch`, its hidden `run` alias, and `demo` serve the API on **127.0.0.1:7878** inside the same
207
+ asyncio loop that polls and alerts. An occupied port prints **API unavailable** while monitoring
208
+ continues normally; stopping that daemon still returns 0. No external bind is supported.
209
+
210
+ | Route | Response |
211
+ |---|---|
212
+ | `GET /api/sensors` | Timestamp, freshness, grouped readings with labels/units/limits/missing reasons/evaluations, redacted apps, Bluetooth and Wi-Fi status. |
213
+ | `GET /api/host` | Hostname, Ubuntu release, kernel, package version; absent facts are null. |
214
+ | `GET /api/history?id=<signal>&range=1h` | `{t, avg}` raw samples, Unix seconds and null gaps. |
215
+ | `GET /api/history?id=<signal>&range=6h` (or `24h`) | `{t, avg, min, max}` minute buckets, including the partial current minute. |
216
+ | `GET /api/alerts?limit=100` | `{incidents, truncated}`, open and recently closed (24h), newest first; limit 1–10000. |
217
+ | `POST /api/alerts/<incident-id>/ack` | `{}` body; updated incident. Repeat acknowledgement of an open incident succeeds. |
218
+ | `POST /api/alerts/<incident-id>/mute` | `{"duration":"15m","renotify":true}`; updated incident, with its rule muted. |
219
+ | `GET /api/stream` | SSE `snapshot` and `alert` events with increasing IDs. Current snapshot first, then future events. |
220
+
221
+ Sensor reads return 503 until the first poll. Afterward a stale snapshot remains available with
222
+ `fresh:false`. Missing readings stay null; real zero readings stay zero. Minute averages exclude
223
+ missing readings; empty minutes are null. Every history column has the same length. Today's and
224
+ this month's network totals remain unavailable until persistent totals are implemented.
225
+
226
+ Each signal's evaluations carry `rule_id`, lowercase `state`, `when`, resolved threshold `value`,
227
+ effective recovery `clear`, and the rule's `severity` (even when OK). Unavailable thresholds and
228
+ clears are null. The signal's own `value` remains the reading. GET and SSE use the same shape.
229
+
230
+ API JSON has no CLI envelope. Unknown incidents return 404, closed incidents 409. Ack changes no
231
+ evaluation or notification. Mute uses the CLI's duration syntax, including `15m`, `30m`, `1h`,
232
+ and `until-reboot`, with re-notification on expiry enabled by default. Mutations return 200;
233
+ bad JSON or unknown fields return 400 and a non-JSON content type returns 415.
234
+
235
+ For POST, first GET any API route to receive the `sbox_csrf` cookie, then send its value as
236
+ `X-CSRF-Token` with `Content-Type: application/json` and the exact page origin in `Origin`.
237
+ POSTs require a loopback Host, same-origin Origin and the session token. Cross-origin CORS is
238
+ not enabled. API responses are no-store. JSON/SSE/errors redact private text, including app
239
+ names and home paths; stable sensor IDs remain unchanged. Built UI files are served unchanged.
240
+
241
+ Each SSE subscriber has a 64-event queue. Slow clients are disconnected on overflow; reconnecting
242
+ receives the current snapshot, with no replay (even with Last-Event-ID). Fetch chart history from
243
+ `/api/history`. Built files are served directly, missing assets return 404, and client routes
244
+ such as `/styleguide` and `/rule/cpu-hot` receive index.html. API routes never fall back to HTML.
245
+
246
+ Only the writer upgrades older history schemas. New evaluations preserve open-alert severity
247
+ and incident kind, including during missing readings and resume. Legacy evaluations stay
248
+ Unknown until refreshed. The 400-day 15-minute rollups are retained unchanged.
249
+
250
+ ## Mutes, history and weekly measurements
251
+
252
+ ```sh
253
+ sbox mute cpu-hot 30m
254
+ sbox mute cpu-hot until-reboot --no-renotify
255
+ sbox unmute cpu-hot
256
+ sbox quiet 22:00-07:00 --no-renotify
257
+ sbox quiet off
258
+ sbox log cpu-hot --since yesterday --limit 50
259
+ sbox log --since 2026-11-01T09:00:00+01:00
260
+ sbox log -f --json
261
+ sbox log --weekly
262
+ sbox rule cpu-hot --json
263
+ ```
264
+
265
+ Mutes live in SQLite and are visible to the running daemon. They survive daemon restarts in the
266
+ same boot. Timed and until-reboot mutes clear on reboot. Expiry and cooldown use monotonic time,
267
+ which stops during suspend. Explicit rule mutes hold all severities. Quiet schedules use local
268
+ civil time, follow timezone/DST changes, and hold info/warning while allowing critical through.
269
+ Comma-separated quiet intervals are supported.
270
+
271
+ Muting changes notification delivery only: alerts still evaluate, appear in history and affect
272
+ health. Automatic release re-notifies a still-open alert unless `--no-renotify` was selected.
273
+ Manual `unmute` and `quiet off` re-notify regardless of that preference. Releases pass through
274
+ cooldown and, when held, wait until cooldown ends while the same alert remains open.
275
+
276
+ One-shot `log` groups incidents newest first, showing severity, rule, firing duration, peak and
277
+ resolved time, with held/delivered reasons on the same line (for example, `muted (quiet hours)`).
278
+ Peaks survive raw-history pruning; older incidents without a recorded peak show `unavailable`.
279
+ For below rules the peak is the lowest reading; missing data never becomes a numeric peak. Its default
280
+ range starts at local midnight yesterday, with Today and Yesterday headings. `--since` also
281
+ accepts durations, ISO dates and timestamps. `--limit` defaults to 100, accepts 1–10000, and
282
+ reports truncation. `-f` appends individual events as NDJSON with `--json`; Ctrl-C stops it.
283
+ `log --daemon` reads only the Sensitive Box user-service journal.
284
+
285
+ Weekly rows record the computation zone and use ISO weeks beginning Monday at local midnight.
286
+ Fires belong to the opening week; active firing minutes split across occupied weeks. Median
287
+ and percent closed under five minutes describe incidents closed that week. Suspend and daemon
288
+ downtime do not count; incomplete durations are flagged. Muted percentage is separate from
289
+ acknowledgement, which stays unavailable until an acknowledgement producer records a fact.
290
+ The alerts page marks a noisy rule and asks whether an alert was useful.
291
+
292
+ Alert events, weekly measurements and change markers are kept for 400 days, preserving older
293
+ facts needed to identify still-open incidents. Kernel, BIOS, package-version and power-profile
294
+ observations begin as baselines. Apt tracking starts at the current readable EOF and records
295
+ new completed upgrades across rotation and restart; older upgrades are not imported.
296
+
297
+ `rules` without an ID lists every configured rule. `rule <id>` and `rules <id>` replay the same
298
+ retained history; bare `rule` errors with a `sbox rules` hint. An unknown ID suggests the nearest
299
+ configured rule without running a correction or the list. Both commands complete rule IDs.
300
+
301
+ Replay includes guards, chip limits, rule edits and sleep
302
+ lifecycle events. One checkpoint at the ring boundary preserves live engine state across pruning;
303
+ daemon-session events reproduce Warming on restart. History readers never create or migrate a
304
+ database. Raw inputs remain one hour and the 400-day 15-minute rollups remain unchanged.
305
+
306
+ ## Service and diagnostic archives
307
+
308
+ ```sh
309
+ sbox enable
310
+ sbox disable
311
+ sbox open
312
+ sbox open rule cpu-hot
313
+ sbox report --output ./diagnostics.tar.gz
314
+ sbox report --fixture --output ./machine.tar.gz
315
+ ```
316
+
317
+ Enable writes the user unit under `$XDG_CONFIG_HOME/systemd/user/` and the launcher under
318
+ `$XDG_DATA_HOME/applications/` (using the standard home defaults when unset), then enables and
319
+ starts the service. Disable stops/disables it and leaves both files. Both commands refuse a
320
+ differing existing unit or launcher. Generated commands refer to the installed `sbox` executable;
321
+ install at its intended location before enabling. Subprocesses use argument vectors and bounded
322
+ waits. The default browser opens an app window when its command is recognized as Chromium-based;
323
+ otherwise the platform default opener handles the URL. The API is not served until Prompt 4.
324
+
325
+ Reports are mode-0600 tarballs and refuse to overwrite any existing destination. Both forms strip
326
+ app names by default; `--keep-app-names` permits them. MACs, Wi-Fi network names, Bluetooth device
327
+ names and home paths are stripped. Ownership metadata is cleared. Existing alert titles may
328
+ retain their hostname. Archives include structured diagnostics and bounded operations history
329
+ when a database is selected, never a raw database or journal. Fixture-mode reports also include
330
+ allowlisted `sys/`, `proc/`, `dbus/` inputs with safe relative links, readable by `doctor` after
331
+ extraction. Missing inputs stay unavailable. Collection is bounded to 64 KiB per file, 4096 members
332
+ and 16 MiB of content; omissions are listed in the manifest and budget failures exit 3.
333
+
334
+ The hidden `--root` can collect either report form without host fallback. `enable`, `disable`,
335
+ `open` and `log --daemon` reject it before accessing the host. Fixture mute controls require an
336
+ explicit `--db`; reports include only an explicitly selected database when `--root` is used.
337
+
338
+ ## Demos
339
+
340
+ ```sh
341
+ sbox demo idle
342
+ sbox demo heatwave
343
+ sbox demo memory-crunch --no-notify
344
+ sbox demo suspend-resume --json
345
+ ```
346
+
347
+ A canonical machine fixture ships inside the Python package, so demos work after wheel
348
+ installation outside the checkout. They use the real collector, engine, store and notifiers,
349
+ with scripted readings and shipped default rules, independent of personal overrides.
350
+
351
+ | Scenario | Behavior |
352
+ |---|---|
353
+ | `idle` | Nothing fires. |
354
+ | `heatwave` | CPU 40 → 95 → 84 °C; CPU hot fires at about 65 s and resolves at about 113 s. |
355
+ | `memory-crunch` | Memory stall, pressure, OOM and low-memory alerts, followed by recovery. |
356
+ | `suspend-resume` | Sleep at 55–75 s with CPU hot open; no no-data alert or duplicate notification. |
357
+
358
+ Popups are enabled by default; `--no-notify` disables them. Without a session bus, the scenario
359
+ continues and explains that notifications were not sent. Demo history is always in memory;
360
+ `--db` is rejected. No hardware files are changed.
361
+
362
+ ## Doctor and apps
363
+
364
+ Doctor reports unavailable and junk sensors as well as working ones, including ENODATA, bad
365
+ values and dropped junk limits. Stable IDs use `<chip>/<bus id>/<channel>`, never `hwmonN`.
366
+ Its **DEFAULT RULES** column deliberately describes shipped coverage; `rules` instead uses the
367
+ effective defaults plus user overrides. Doctor JSON includes the same diagnostic information
368
+ as text, with structured sensor and source fields.
369
+
370
+ Memory used means **MemTotal − MemAvailable**, never “free”. Pressure is Linux PSI, not usage
371
+ percentage. `apps` reads the current user's cgroup v2 `app.slice`, only above 80% memory used or
372
+ when pressure is high/rising. Healthy memory prints current PSI and says apps were not sampled.
373
+ Missing cgroup support is reported with a reason.
374
+
375
+ All command output, including JSON, errors and live diagnostics, passes through shared
376
+ redaction. MAC addresses, MAC-derived interface names, Wi-Fi network names and Bluetooth device
377
+ names are omitted or masked. Bluetooth devices are described by class and battery level.
378
+
379
+ ## Shell completion
380
+
381
+ For bash:
382
+
383
+ ```sh
384
+ source <(sbox completion bash)
385
+ ```
386
+
387
+ For zsh, after completion initialization:
388
+
389
+ ```sh
390
+ autoload -Uz compinit
391
+ compinit
392
+ source <(sbox completion zsh)
393
+ ```
394
+
395
+ The script supports both executable names, public commands, scenarios and options. It includes
396
+ configured rule-ID candidates for rule inspection, muting and log filters. Regenerate/re-source it after changing your rules. Hidden `run` and
397
+ test flags are excluded. No `eval` is needed.
398
+
399
+ ## Development and fixture roots
400
+
401
+ ```sh
402
+ uv sync
403
+ scripts/check.sh
404
+ uv run sbox demo heatwave --no-notify
405
+ uv run sbox doctor --root tests/fixtures/proart-p16
406
+ ```
407
+
408
+ The hidden test-only `--root` works before or after a command. Each machine/case contains
409
+ `sys/`, `proc/` and `dbus/`; empty components represent unavailable sources. Readers never fall
410
+ back to host hardware or buses when a root is selected, and fixture mode never connects real
411
+ notification buses. D-Bus replies are JSON snapshots adapted to the normal bus protocol;
412
+ missing replies mean unavailable, malformed JSON is an operational error. There is no fixture
413
+ inheritance. Counter-reset frames remain grouped within their case.
414
+
415
+ Install bash and zsh to run shell completion tests locally. CI installs zsh for the same tests.
416
+ The full check runs locked dependency sync, lint, formatting, strict types and pytest, including
417
+ installed-wheel checks. Tests use fixtures, fake buses and injected clocks, never real hardware.
418
+
419
+ The design and roadmap live in [docs/BIBLE.md](docs/BIBLE.md). See
420
+ [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
421
+
422
+ ## License
423
+
424
+ [MIT](LICENSE)