@astrofoundry/pi-astro 0.40.71 → 0.40.73

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.
package/README.md CHANGED
@@ -80,7 +80,7 @@ pi # launch; confirm [Extensions] lists astro-subagents, grimoire
80
80
 
81
81
  **Bundled subagents** (call them as `astro.<name>`):
82
82
  - General-purpose: `code-reviewer`, `google-tech-lead`, `spec-writer`, `tester-api`, `tester-ui`, `ui-architect`, `ui-design-system`, `ui-frontend-developer`
83
- - Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first; sanitized host checks, Mealie and Paperless dumps, stack image updates with rollback, and the documented manager upgrade, both with buttons on the daily report), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi consoles of sites 37 and Mira: reads and every Network API write, through the cloud with local fallback; FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository, public route checks), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Europa health), `media` (trendarr: trending titles, recommendations from the library, Radarr and Sonarr adds, SABnzbd pause), `research` (internet research in a thread per request in #research: numbered questions first, then facts checked in a sandbox Chrome at Mira with a UAE address, per-category defaults, captchas solved by an owner in a live view), `home` (Home Assistant: health, problems, logs, updates, and actions)
83
+ - Specialists (one homelab area each, need the host setup in [specialists/README.md](specialists/README.md)): `arcane` (Arcane container platform, GitOps first; sanitized host checks, Mealie and Paperless dumps, stack image updates with rollback, and the documented manager upgrade, both with buttons on the daily report), `identity` (Zitadel, Pomerium routes through the homelab repository, certificates), `network` (UniFi consoles of sites 37 and Mira: reads and every Network API write, through the cloud with local fallback; FreeRADIUS, Tailscale), `dns` (Technitium resolvers, Cloudflare zones), `edge` (Frontdoor VPS over IAP, nginx SNI allowlist through the homelab repository, public route checks), `security` (Wazuh, CrowdSec, log archive, read-only), `backup` (vzdump, Restic layers, GCS offsite, restore tests), `proxmox` (guest lifecycle, snapshots, resources; no create or destroy), `inference` (llama.cpp on Nexus, Europa health), `media` (trendarr: trending titles, recommendations from the library, Radarr and Sonarr adds, SABnzbd pause), `research` (internet research in a thread per request in #research: numbered questions first, then facts checked in a sandbox Chrome at Mira with a UAE address, per-category defaults, captchas solved by an owner in a live view), `home` (Home Assistant: health, problems, logs, updates, actions, every API its interface uses, and its YAML files)
84
84
  - Release notes: `release-reviewer` (no tools; judges whether an update could break how we use a tool or image, for the Cortex Tools Report and the Arcane Daily Report)
85
85
  - Supervision: `foreman` (read only; diagnoses an unattended update that failed its check, through the specialists)
86
86
  - Flourish pipeline: `flourish-input-vision` (image to spec), `flourish-input-narrative` (text to spec), `flourish-input-codebase` (HTML to spec), `flourish-architect` (spec to plan), `flourish-template-developer` (plan to SDK template, needs `@flourish/sdk`), `flourish-example-builder` (template to realistic example), `flourish-preview-runner` (multi-breakpoint preview + screenshots, needs `@flourish/sdk`), `flourish-reviewer` (audit)
package/agents/home.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: home
3
- description: Watches and operates Home Assistant through the home tool, covering versions and Supervisor health, integrations that did not load, repairs, waiting updates, backups, disk space, unavailable entities, logs, updates, restarts, and any Home Assistant action. Use for what is wrong with the smart home, why a device or integration fails, installing a Home Assistant update, and switching or checking a device.
3
+ description: Watches and operates Home Assistant through the home tool, covering versions and Supervisor health, integrations that did not load, repairs, waiting updates, backups, disk space, unavailable entities, logs, updates, restarts, any Home Assistant action, and through its WebSocket, REST, and Supervisor APIs everything its own interface can read or change (entities, devices, areas, integrations, automations, scripts, helpers, dashboards, add-ons), and reads and changes its YAML configuration files. Use for what is wrong with the smart home, why a device or integration fails, installing an update, switching or checking a device, and creating or changing automations, dashboards, and settings.
4
4
  tools: home, subagent
5
5
  skills: home
6
6
  systemPromptMode: replace
@@ -10,13 +10,15 @@ maxSubagentDepth: 1
10
10
  model: openai-codex/gpt-6-astra
11
11
  thinking: xhigh
12
12
  ---
13
- You are the home specialist. The `home` tool is your only way to reach Home Assistant, which runs as a virtual machine at Mira. You have no shell, no web, and no file access; if a task needs anything else, say so and stop.
13
+ You are the home specialist. The `home` tool is your only way to reach Home Assistant, which runs as a virtual machine at Mira. You have no shell and no web, and the only files you reach are Home Assistant's YAML files through the tool's `file-` commands; if a task needs anything else, say so and stop.
14
14
 
15
15
  Rules:
16
16
 
17
17
  - Read first: `status` or `problems` before you explain or change anything. Name what you read, not what you assume.
18
18
  - A part that could not be read is a finding, never a pass. Say which part.
19
- - Change only what the task asks for. `update`, `restart`, `action`, and `integration-remove` ask an owner for approval in chat; say what you are about to run and why before you call them.
19
+ - Change only what the task asks for. `update`, `restart`, `action`, `integration-remove`, `ws`, `file-write`, `file-replace`, `file-restore`, `file-remove`, and every `rest` or `supervisor` call that is not a `get` ask an owner for approval in chat; say what you are about to send and why before you call them.
20
+ - Read before you write: fetch the current automation, dashboard, or options, change only what the task names, and send the whole object back. Read it again afterwards and report what changed.
21
+ - For a YAML file, read it, change the smallest text with `file-replace`, and report the `check` result and the `backup` stamp. Never write a line that reads `[redacted]`, and never ask for `secrets.yaml`.
20
22
  - Find the cause before you restart. Read `logs core` or the add-on's log for a failing integration; a restart is the last step, not the first.
21
23
  - Never print a token, a password, or a URL that carries one; summarise such a log line.
22
24
  - Keep replies short: the finding, the cause when you know it, and the one next step. When the owner must act, start with `**Needs you:**`.
@@ -21,6 +21,14 @@ describe("approvals", () => {
21
21
  expect(isRisky("home", ["restart"])).toBe(true);
22
22
  expect(isRisky("home", ["integration-remove", "01JABCDEFGHJKMNPQRSTVWXYZ0"])).toBe(true);
23
23
  expect(isRisky("home", ["integrations", "--failed"])).toBe(false);
24
+ expect(isRisky("home", ["ws", "config/entity_registry/update", "{}"])).toBe(true);
25
+ expect(isRisky("home", ["ws-read", "config/entity_registry/list"])).toBe(false);
26
+ expect(isRisky("home", ["rest", "post", "/api/config/automation/config/1", "{}"])).toBe(true);
27
+ expect(isRisky("home", ["rest", "get", "/api/config"])).toBe(false);
28
+ expect(isRisky("home", ["supervisor", "post", "/host/reboot"])).toBe(true);
29
+ expect(isRisky("home", ["supervisor", "get", "/addons"])).toBe(false);
30
+ for (const name of ["file-write", "file-replace", "file-restore", "file-remove", "files-setup"]) expect(isRisky("home", [name, "configuration.yaml"]), name).toBe(true);
31
+ for (const name of ["file-list", "file-read", "file-backups"]) expect(isRisky("home", [name, "configuration.yaml"]), name).toBe(false);
24
32
  expect(isRisky("home", ["problems"])).toBe(false);
25
33
  expect(isRisky("home", ["logs", "core", "50"])).toBe(false);
26
34
  expect(isRisky("identity", ["zitadel", "DELETE", "/v2/users/1"])).toBe(true);
@@ -50,8 +50,9 @@ export const RISKY: Readonly<Record<string, readonly RegExp[]>> = {
50
50
  // Adds and queue pauses run on the caller's request; removing a queue record deletes its download,
51
51
  // and a date repair rewrites Jellyfin's "date added" on every item it finds late.
52
52
  media: [/^queue-remove\b/, /^jellyfin\s+date-repair\b/],
53
- // Everything that changes Home Assistant: an update, a restart, and any action (lights, locks, scenes).
54
- home: [/^(update|restart|action|integration-remove)\b/],
53
+ // Everything that changes Home Assistant: an update, a restart, any action (lights, locks, scenes), any
54
+ // WebSocket command outside the wrapper's read list, and every REST or Supervisor call that is not a GET.
55
+ home: [/^(update|restart|action|integration-remove|files-setup|file-(write|replace|restore|remove))\b/, /^ws(\s|$)/, /^(rest|supervisor)\s+(post|put|delete)\b/],
55
56
  };
56
57
 
57
58
  export function isRisky(service: string, args: readonly string[]): boolean {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrofoundry/pi-astro",
3
- "version": "0.40.71",
3
+ "version": "0.40.73",
4
4
  "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: home
3
- description: How the home specialist reads Home Assistant's health, finds what is wrong, reads logs, installs updates, restarts Core, and runs Home Assistant actions through the home tool.
3
+ description: How the home specialist reads Home Assistant's health, finds what is wrong, reads logs, installs updates, restarts Core, runs actions, reads or changes anything else through Home Assistant's WebSocket, REST, and Supervisor APIs, and reads or changes its YAML configuration files with the home tool.
4
4
  ---
5
5
 
6
6
  # Home specialist
@@ -21,6 +21,20 @@ Home Assistant OS runs as VM 112 `homeassistant` on SPACE-X at Mira, in the IoT
21
21
  | `["update", "update.home_assistant_core_update", "--confirm"]` | install one waiting update; asks an owner |
22
22
  | `["restart", "--confirm"]` | restart Home Assistant Core; asks an owner |
23
23
  | `["action", "light.turn_on", "{\"target\":{\"entity_id\":\"light.kitchen\"},\"data\":{\"brightness_pct\":40}}"]` | run any Home Assistant action; the JSON may hold `target` and `data`; asks an owner |
24
+ | `["check-config"]` | validate the configuration files; changes nothing |
25
+ | `["ws-read", "config/entity_registry/list"]` | a WebSocket command that only reads; the tool refuses any other type |
26
+ | `["ws", "config/entity_registry/update", "{\"entity_id\":\"light.x\",\"name\":\"Desk\"}"]` | any WebSocket command; asks an owner |
27
+ | `["rest", "get", "/api/config/automation/config/1699999999999"]` | GET any route under `/api/` |
28
+ | `["rest", "post", "/api/config/automation/config/1699999999999", "{...}"]` | any other REST call (`post`, `put`, `delete`); asks an owner |
29
+ | `["supervisor", "get", "/addons/core_matter_server/info"]` | GET a Supervisor endpoint |
30
+ | `["supervisor", "post", "/addons/core_matter_server/restart"]` | any other Supervisor call; asks an owner |
31
+ | `["file-list"]` | the YAML files of the configuration folder |
32
+ | `["file-read", "configuration.yaml"]` | one YAML file; a second argument is the first line to show |
33
+ | `["file-backups", "configuration.yaml"]` | the stamps of the copies kept of one file |
34
+ | `["file-replace", "configuration.yaml", "{\"old\":\"...\",\"new\":\"...\"}", "--confirm"]` | replace one exact text in a file; asks an owner |
35
+ | `["file-write", "packages/lights.yaml", "<content>", "--confirm"]` | write a whole file; asks an owner |
36
+ | `["file-restore", "configuration.yaml", "<stamp>", "--confirm"]` | put back one kept copy; asks an owner |
37
+ | `["file-remove", "packages/old.yaml", "--confirm"]` | delete a file; asks an owner |
24
38
 
25
39
  ## Output
26
40
 
@@ -34,6 +48,42 @@ Home Assistant OS runs as VM 112 `homeassistant` on SPACE-X at Mira, in the IoT
34
48
  - `update`: `{ "status": "update started", "entity" }`. The install runs in Home Assistant; read `status` again after a few minutes.
35
49
  - `restart`: `{ "status": "restart requested" }`. The tool cannot reach Home Assistant while it restarts.
36
50
  - `action`: `{ "status": "done", "action" }`.
51
+ - `file-read`: `{ "path", "lines", "from", "content", "next" }`; `next` is the line to continue from when the file is longer than one answer.
52
+ - `file-write`, `file-replace`, `file-restore`, `file-remove`: `{ "status": "written" | "replaced" | "restored" | "removed", "path", "backup", "check": "valid" }`, or `{ "status": "rolled back", "check": "invalid", "errors" }` when the change broke a valid configuration and the tool put the previous file back.
53
+
54
+ ## Everything else: the three generic doors
55
+
56
+ Home Assistant's own web interface works through these same APIs, so what the interface can do, `ws`, `rest`, and `supervisor` can do. Reads are free; every change asks an owner, so say first what you will send and why. Answers above 60,000 characters are cut (a list keeps its first items and reports `total` and `shown`), and values under secret-looking keys read `[redacted]`. Names below were checked against Home Assistant 2026.11.1; when a call is refused, read the error and do not guess a second name.
57
+
58
+ | Task | Read | Change |
59
+ |---|---|---|
60
+ | Entities | `ws-read config/entity_registry/list`, `.../get {"entity_id"}` | `ws config/entity_registry/update {"entity_id", "name", "new_entity_id", "area_id", "disabled_by", "hidden_by", "icon"}`, `ws config/entity_registry/remove {"entity_id"}` |
61
+ | Devices | `ws-read config/device_registry/list` | `ws config/device_registry/update {"device_id", "name_by_user", "area_id", "disabled_by"}` |
62
+ | Areas, floors, labels | `ws-read config/area_registry/list` (also `floor_registry`, `label_registry`) | `ws config/area_registry/create {"name"}`, `.../update {"area_id", ...}`, `.../delete {"area_id"}` |
63
+ | Integrations | `integrations`; `rest get /api/config/config_entries/flow_handlers` | reload: `rest post /api/config/config_entries/entry/<entry_id>/reload`; add: `rest post /api/config/config_entries/flow {"handler": "<domain>"}`, then `rest post /api/config/config_entries/flow/<flow_id> {...the fields its form asks for}`; options: the same under `/api/config/config_entries/options/flow`; delete: `integration-remove` |
64
+ | Automations | `ws-read automation/config {"entity_id"}`, `rest get /api/config/automation/config/<id>`, runs: `ws-read trace/list {"domain": "automation"}` then `trace/get {"domain", "item_id", "run_id"}` | `rest post /api/config/automation/config/<id> {...the whole automation}`, `rest delete` the same path; turn on or off with `action automation.turn_on` |
65
+ | Scripts, scenes | `rest get /api/config/script/config/<key>`, `/api/config/scene/config/<id>` | `rest post` or `rest delete` the same path |
66
+ | Helpers | `ws-read input_boolean/list` (also `input_number`, `input_select`, `input_text`, `input_datetime`, `counter`, `timer`, `schedule`) | `ws input_boolean/create {"name"}`, `.../update {"input_boolean_id", ...}`, `.../delete {"input_boolean_id"}` |
67
+ | Dashboards | `ws-read lovelace/dashboards/list`, `ws-read lovelace/config {"url_path": null}` (null is the default dashboard) | `ws lovelace/config/save {"url_path", "config"}`; read the whole config first, change it, send it whole |
68
+ | Repairs | `ws-read repairs/list_issues` | `ws repairs/ignore_issue {"domain", "issue_id", "ignore": true}` |
69
+ | Backups | `ws-read backup/info`, `ws-read backup/agents/info` | `ws backup/generate_with_automatic_settings`, `ws backup/delete {"backup_id"}`; never `backup/restore` without the owner's explicit request |
70
+ | History and log book | `ws-read history/history_during_period {"start_time", "end_time", "entity_ids": [...]}`, `ws-read logbook/get_events {"start_time", "entity_ids": [...]}`, `ws-read system_log/list` | |
71
+ | Core settings | `ws-read get_config` | `ws config/core/update {"location_name", "time_zone", "unit_system", ...}` |
72
+ | Add-ons (the interface calls them Apps) | `supervisor get /addons`, `/addons/<slug>/info`, `/addons/<slug>/stats`, `/store/addons` | `supervisor post /addons/<slug>/start`, `/stop`, `/restart`, `/update`, `/uninstall`; `supervisor post /store/addons/<slug>/install`; options: `supervisor post /addons/<slug>/options {"options": {...all options}}` |
73
+ | Supervisor, system, host | `supervisor get /supervisor/info`, `/core/info`, `/os/info`, `/host/info`, `/network/info`, `/resolution/info`, `/jobs/info`, `/mounts` | `supervisor post /core/update`, `/os/update`, `/supervisor/update`, `/core/restart`, `/host/reboot`, `/host/shutdown`, `/supervisor/repair`, `/resolution/healthcheck` |
74
+ | Templates | | `rest post /api/template {"template": "{{ states('sun.sun') }}"}` renders one; it is a POST, so it asks |
75
+
76
+ ## YAML files
77
+
78
+ The file commands reach the YAML files below Home Assistant's configuration folder (`configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml`, packages, blueprints, ESPHome files) through the Advanced SSH & Web Terminal add-on. They never reach `secrets.yaml`, hidden folders such as `.storage`, or any file that is not YAML.
79
+
80
+ - Prefer the API when it covers the task: automations, scripts, and scenes made in the interface change through `rest post /api/config/<automation|script|scene>/config/<id>`, which also reloads them. Use the files for `configuration.yaml`, packages, and what only YAML can express.
81
+ - `file-read` shows the value of a secret-named key (`password`, `token`, `api_key`, ...) as `[redacted]`; a `!secret name` reference stays readable. The tool refuses to write a text that carries `[redacted]`, so never retype a masked line: change the lines around it with `file-replace`, whose `old` text must occur exactly once in the file.
82
+ - Every change keeps a copy of the previous file (`backup` is its stamp, `none` for a new file) and runs the configuration check before and after. A change that turns a valid configuration invalid is undone at once; read `errors`, fix the text, and try again. A configuration that was invalid before stays changed, and `check` reads `invalid before and after`.
83
+ - A changed file takes effect after a reload or a restart: `action homeassistant.reload_all`, the domain's own reload such as `action automation.reload`, or `restart --confirm` for what no reload covers (for example a new integration in `configuration.yaml`).
84
+ - `file-backups` lists the stamps of one file; `file-restore` puts one back and keeps a copy of the file it replaces.
85
+
86
+ Limits: `ws-read` knows registries, lists, history, traces, and dashboards; a read it does not know goes through `ws` and asks. Never read `backup/config/info`, `application_credentials`, or Thread credentials on your own: they hold secrets.
37
87
 
38
88
  ## Finding a cause
39
89
 
@@ -54,5 +104,6 @@ Short and factual. Name devices and integrations by their Home Assistant names.
54
104
  ## When to stop and report
55
105
 
56
106
  - The tool reports a missing secret or config field, or cannot reach Home Assistant at all: operator task; quote the error. Whether the VM runs is `astro.proxmox`'s question (`space-x`, VM 112).
57
- - The task needs a file edit in Home Assistant's configuration, a new integration, a pairing, or a dashboard change: those need the web UI; say what to open.
107
+ - The task needs a file edit in Home Assistant's configuration, or a pairing that needs a button press, a code, or a login in a browser: say what the owner has to open or press.
108
+ - A change you cannot undo (deleting an integration, an automation, a dashboard, a backup; uninstalling an add-on; a host shutdown): name what will be lost in the approval text, and stop when the owner did not ask for exactly that.
58
109
  - The task would restore a backup or reset Home Assistant: stop and ask the owner.
@@ -63,7 +63,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
63
63
  - `arcane manager-upgrade <version>` (`lib/arcane-manager.ts`) follows arcane/AGENTS.md "Manager upgrades": the official image's revision label must equal the release tag's commit (GitHub API), `manager-prepare` records `compose.before.yaml` and every container before the pin commit, the pin goes through the `arcane-gitops` checkout (`git` is exported from `lib/repo.ts` for this), the wait polls `gitops list` and the deployed Compose hash every 30 s for up to 30 minutes, then pull, cold backup, `up -d --no-deps --pull never`, and checks. Any failure before the restart reverts the pin (`stopped`); a failed check after it reverts the pin and runs `manager-rollback` (`rolled back`). The answer always exits 0 with `status`, so the bridge and the agent both see it.
64
64
  - `research` is a pure forced-command wrapper: every call is one JSON request on stdin to `request` on VM 110 (`10.1.100.10`, user `spc-research`, key `SSH_KEY_SANDBOX`), whose entry hands it to `spc-research-op` as `researcher` (tracked in the homelab repository's `06-space-x-proxmox/research/system/`). The op attaches one playwright-cli session per Discord thread (`t<id>`) to the shared Chrome over CDP on `127.0.0.1:9222` and opens its own tab; cookie, storage, `run-code`, and browser lifecycle commands are refused. `script` runs the agent's code in the thread folder as `researcher` (5 minutes), on a VM that reaches only the internet (Mira's Sandbox zone plus the VM's own nftables). Defaults stay on Cortex in `work/research/defaults.json`, out of the sandbox's reach. `captcha-help` is in `RISKY`, so its owner approval is the moment the owner solved the challenge in the live view (`research-browser.37pla.net`); the bridge renders that ticket with the channel's `liveView` link.
65
65
  - `media` runs trendarr unchanged: `trendarrCli` in `media.json` is its `dist/cli.js`, started with `process.execPath` because sudo's PATH has no node. Each call gets `HOME` set to a fresh `0700` directory under `~/.specialists/work/media/` that holds only `.trendarr/config.json` (`0600`, trendarr's own schema, built from the note fields and `media.json`) and is removed in `finally`; trendarr reads no environment variables and has no config flag, and Node's `os.homedir()` follows `$HOME` on POSIX. Every call passes `--json`; `init` is refused. An add prints trendarr's per-ID `results` and exits 0 even when trendarr exits 1 for a failed ID, because the gate shows only stderr on failure; other failures carry trendarr's stderr without its `warning:` lines, which go into the JSON as `warnings`. The bridge's slash commands and Add buttons call the same wrapper through the entry point (`extensions/astro-discord/media.ts`). `queue` and `queue-remove` (since 0.40.66) skip trendarr, which has no queue records: the wrapper calls `/api/v3/queue` of Radarr and Sonarr itself with the note's keys in the `X-Api-Key` header and prints only `stuckRecords` fields (no paths or download ids); `queue-remove` sends `DELETE /api/v3/queue/<id>?removeFromClient=true&blocklist=false`, needs `--confirm`, and is in `RISKY`. The `jellyfin` commands (since 0.40.68, pure parts in `lib/media-dates.ts`) exist because Jellyfin adds a renamed or moved file as a new item: the library rename of 2026-11-10 turned 873 of 875 episodes into "added today". `date-check` reads every movie, episode, season, and series from `/Items` (one request per type without a limit, because pages of an unsorted list can overlap), Radarr's and Sonarr's files, and each app's whole history from `/api/v3/history/since`; files match by their last path segments (`pathKey`: two for a movie, three for an episode), so the mount points may differ. `planDates` follows the arcane repository's `media/AGENTS.md`: a movie or episode gets its earliest successful import (`firstArrival`; without an import record the earliest of the file's own import date and its rename and deletion records, since a file a disk scan found has none), a season and a series their earliest episode, an empty season its series; only a date more than a day late changes, so a date only ever moves back, and an item Radarr or Sonarr has no file for is reported as unmatched and left alone. `date-repair --confirm` applies the plan through Jellyfin's own `POST /Items/<id>`, the call behind its metadata editor: the item as `GET /Items/<id>?userId=<an administrator>` returns it (without a user id an API key gets 400) with only `DateCreated` changed and `People` left out, because Jellyfin rewrites people only when the request carries them; a test on one episode showed only `DateCreated` and `Etag` differing afterwards. Jellyfin keeps running, and five failed updates stop the run. The API key travels as `Authorization: MediaBrowser Token="<key>"`, the scheme of the server's own `/api-docs/openapi.json` (12.4.0). `bazarr status` reads `/api/system/status` and `/api/system/health` with `X-API-KEY` and prints versions and issues only; the Sonarr and Radarr versions Bazarr reports show that it reaches them. Both read their own config shape (`jellyfinUrl`, `bazarrUrl`), so the trendarr commands run without those keys.
66
- - `home` (since 0.40.70) reaches Home Assistant, VM 112 on SPACE-X at Mira (`homeAssistantUrl` in `home.json`, token `HOMEASSISTANT_TOKEN`), which replaced a Raspberry Pi with a failing SD card on 2026-11-12. `lib/home-assistant.ts` opens the WebSocket API (`/api/websocket`: `auth_required`, `auth` with the token, `auth_ok`), sends commands with ids, and closes; the wrapper runs on the installer's Node, which has a global `WebSocket`. The Supervisor's state (`/supervisor/info`, `/core/info`, `/os/info`, `/host/info`, `/resolution/info`, `/addons`) is reachable only through the `supervisor/api` command, because Core's REST proxy (`/api/hassio/...`) forwards logs and backups and nothing else (`PATHS_ADMIN` in Core's `hassio/http.py`, read at tag 2026.11.1); `logs` uses that proxy with `?lines=`. `status` prints named fields only (`pick`), so add-on options and addresses stay inside. `homeProblems` turns a snapshot into one line per finding: Core not running, safe or recovery mode, an unhealthy or unsupported Supervisor, its resolution issues, integrations that did not load (`setup_error`, `setup_retry`, ...), open repairs, waiting `update.*` entities, a newest backup older than 48 hours or failed for a location, a disk above 85 %; a part that could not be read is a line too (`unread`), never a pass. `update`, `restart`, `action` (any Home Assistant action with `target` and `data`), and `integration-remove` (since 0.40.71: `DELETE /api/config/config_entries/entry/<id>`, for leftovers such as the Pi's Bluetooth adapter after the move to a VM) change things and are in `RISKY`; all but `action` also need `--confirm`. Arguments are checked before config and secret are read. The agent has no `read` tool. The morning run reads `home problems` (`homeStatus` in `daily-run.ts`): each line is an item under Home, and the tagged message posts once per set of problems. Cortex reaches `10.1.70.32:8123` through the policies `Home Assistant - from Cortex` on both consoles.
66
+ - `home` (since 0.40.70) reaches Home Assistant, VM 112 on SPACE-X at Mira (`homeAssistantUrl` in `home.json`, token `HOMEASSISTANT_TOKEN`), which replaced a Raspberry Pi with a failing SD card on 2026-11-12. `lib/home-assistant.ts` opens the WebSocket API (`/api/websocket`: `auth_required`, `auth` with the token, `auth_ok`), sends commands with ids, and closes; the wrapper runs on the installer's Node, which has a global `WebSocket`. The Supervisor's state (`/supervisor/info`, `/core/info`, `/os/info`, `/host/info`, `/resolution/info`, `/addons`) is reachable only through the `supervisor/api` command, because Core's REST proxy (`/api/hassio/...`) forwards logs and backups and nothing else (`PATHS_ADMIN` in Core's `hassio/http.py`, read at tag 2026.11.1); `logs` uses that proxy with `?lines=`. `status` prints named fields only (`pick`), so add-on options and addresses stay inside. `homeProblems` turns a snapshot into one line per finding: Core not running, safe or recovery mode, an unhealthy or unsupported Supervisor, its resolution issues, integrations that did not load (`setup_error`, `setup_retry`, ...), open repairs, waiting `update.*` entities, a newest backup older than 48 hours or failed for a location, a disk above 85 %; a part that could not be read is a line too (`unread`), never a pass. `update`, `restart`, `action` (any Home Assistant action with `target` and `data`), and `integration-remove` (since 0.40.71: `DELETE /api/config/config_entries/entry/<id>`, for leftovers such as the Pi's Bluetooth adapter after the move to a VM) change things and are in `RISKY`; all but `action` also need `--confirm`. Since 0.40.72 three generic doors reach everything Home Assistant's own interface can do, the model of the community's ha-mcp server without a second server that holds an administrator token: `ws <type> [json]` (any WebSocket command), `rest <get|post|put|delete> <path> [json]` (any route under `/api/`; dot segments, escapes, and `/api/websocket` refused), and `supervisor <get|post|put|delete> <endpoint> [json]` (through `supervisor/api`; logs and downloads refused because they are not JSON). Reads need no approval: `rest get`, `supervisor get`, and `ws-read`, which sends only the types in `READ_COMMANDS` of `lib/home-assistant.ts` (registries, lists, history, traces, dashboards, the helpers' `<domain>/list`; never `backup/config/info`, `application_credentials`, or `auth`, which return credentials). Everything else is in `RISKY` (`/^ws(\s|$)/` so that `ws-read` stays free). Generic answers pass `redactSecrets` and `bounded` (60,000 characters; a list keeps its first items). `restart` treats a connection Core closes as started, because Core often closes the socket before it sends the result. No Home Assistant API reads or writes files (ha-mcp needs its own component inside Home Assistant for that), so the `file-` commands (since 0.40.73, pure parts in `lib/home-files.ts`) go through the Advanced SSH & Web Terminal add-on (`a0d7b954_ssh`, port 22 on the host network): `files-setup` adds one `authorized_keys` line, `restrict,command="sudo -n /usr/local/bin/spc-home-entry \"$SSH_ORIGINAL_COMMAND\""`, and one `init_commands` line that writes the entry script, because the add-on copies `authorized_keys` lines verbatim and evaluates `init_commands` at every start (`init-ssh/run`, `init-user/run` of hassio-addons/app-ssh, read 2026-11-12); the owner's other options go back unchanged and are never printed, and `--no-password` empties the SSH password, which turns password login off. The script (`entry/remote/spc-home-entry.sh`, embedded as `ENTRY_SCRIPT`; a test compares them and runs it) serves YAML paths below `/homeassistant` without hidden folders, dot segments, or `secrets.yaml`, and copies the current file to `.spc-home-backups/<path>.<UTC stamp>` before every write, restore, and removal, under a stamp no copy has yet. The wrapper reads the add-on's port and user name from `/addons/a0d7b954_ssh/info`, masks secret-named values in `file-read` (`redactYaml`; a mask, not a boundary), refuses to write a text that carries `[redacted]`, and wraps every change in two configuration checks (`changeChecked`): a change that turns a valid configuration invalid is restored from the kept copy, one made while it was already invalid stays. The four changing commands and `files-setup` are in `RISKY`. The skill's table of commands was checked against Core 2026.11.1 and the Supervisor's route table. Arguments are checked before config and secret are read. The agent has no `read` tool. The morning run reads `home problems` (`homeStatus` in `daily-run.ts`): each line is an item under Home, and the tagged message posts once per set of problems. Cortex reaches `10.1.70.32` on TCP 8123, 4357, and 22 through the policies `Home Assistant at Mira - from Cortex` on both consoles.
67
67
  - `arcane release-notes <stack>[/<service>]` is `lib/releases.ts`: a single-image check and `resolveRef` give the running and latest versions, `HttpRegistry.labels` reads `org.opencontainers.image.source` from the latest image (index to linux/amd64 manifest to config blob), and the anonymous GitHub releases API (60 requests an hour, up to 3 pages of 100) gives the releases in between, oldest first. `condenseNotes` keeps each release under 12,000 characters by section priority; `capTotal` drops the oldest releases past 40,000 characters in total.
68
68
 
69
69
  ## Gate
@@ -15,7 +15,7 @@ A specialist is a Pi subagent that is the only way to operate one area of the ho
15
15
  | `astro.inference` | MLX embedding and reranking servers on Nexus, Europa health | `nexus-status|start|stop|restart|log|disk`, `macos-updates`; `europa-health` |
16
16
  | `astro.media` | trendarr over TMDB, OMDb, and the `media` project on VM 100 (Radarr, Sonarr, SABnzbd, Jellyfin, Bazarr) | `trending`, `search`, `recommend`, `add-movies`, `add-series` (at most 20 IMDb IDs), `sabnzbd status|pause|resume`, `queue`, `queue-remove <radarr|sonarr> <id> --confirm`, `jellyfin status|date-check`, `jellyfin date-repair --confirm`, `bazarr status`; trendarr's JSON plus its warnings, the queue, Jellyfin, and Bazarr commands straight from those apps |
17
17
  | `astro.research` | the research sandbox, VM 110 at Mira (Chrome on a virtual screen, scripts, thread folders), through the forced-command key of user `spc-research`; defaults in `~/.specialists/work/research/defaults.json` | `browser <session> <playwright-cli args>`, `captcha`, `captcha-help` (owner approval: solved in the live view), `script`, `read`, `files`, `toolbox`, `defaults list|set|unset`; the sandbox's JSON |
18
- | `astro.home` | Home Assistant at Mira (VM 112 on SPACE-X, `10.1.70.32:8123`), through its WebSocket API and log routes with a long-lived access token | `status`, `problems`, `entities`, `logs <core\|supervisor\|host\|addon <slug>>`, `integrations`, `integration-remove <entry_id> --confirm`, `update <update.entity> --confirm`, `restart --confirm`, `action <domain.action> [json]`; named fields only |
18
+ | `astro.home` | Home Assistant at Mira (VM 112 on SPACE-X, `10.1.70.32:8123`), through its WebSocket API and log routes with a long-lived access token | `status`, `problems`, `entities`, `logs <core\|supervisor\|host\|addon <slug>>`, `integrations`, `check-config`, `ws-read <type> [json]`, `rest get <path>`, `supervisor get <endpoint>`; with approval `integration-remove <entry_id> --confirm`, `update <update.entity> --confirm`, `restart --confirm`, `action <domain.action> [json]`, `ws <type> [json]`, `rest <post\|put\|delete> <path> [json]`, `supervisor <post\|put\|delete> <endpoint> [json]`; generic answers are redacted and cut to 60,000 characters. YAML files through a forced-command key in the Advanced SSH & Web Terminal add-on: `file-list`, `file-read`, `file-backups`; with approval `file-write`, `file-replace`, `file-restore`, `file-remove`, each with a kept copy and a configuration check; never `secrets.yaml` or hidden folders |
19
19
 
20
20
  Call one with `/run astro.<name> -- <task>` or through the `subagent` tool (both from the bundled `astro-subagents` extension). `/run` saves the specialist's session under `~/.pi/agent/subagent-sessions/<agent>/`; `/run astro.<name> --continue -- <task>` resumes the last one started from the same directory, so the specialist keeps what it saw. Sessions older than 7 days are deleted. Specialists may call each other once (`maxSubagentDepth: 1`). They run on `openai-codex/gpt-6-astra` with `xhigh` thinking, set by `model` and `thinking` in each `agents/<name>.md`; an agent without these fields inherits the caller's model and thinking. Each tool takes `args`, an array of strings; `["--help"]` lists the subcommands.
21
21
 
@@ -45,7 +45,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
45
45
  - `proxmox`: `PVE_TOKEN_ID` (plain, `spc-proxmox@pve!cortex`), `PVE_TOKEN_SECRET`, `PVE_SPACEX_TOKEN_ID` and `PVE_SPACEX_TOKEN_SECRET` (the same user on SPACE-X), `SSH_KEY_PULSAR_B64` (trusted by Pulsar and SPACE-X). `proxmox.json` also needs `spacexApiUrl`, `spacexCertSha256`, `spacexNode`, `spacexHost`, `spacexUser`, and `known_hosts` the SPACE-X host key.
46
46
  - `inference`: `SSH_KEY_NEXUS_B64`.
47
47
  - `media`: `TMDB_ACCESS_TOKEN` (TMDB API Read Access Token), `OMDB_API_KEY`, `RADARR_API_KEY`, `SONARR_API_KEY` (Settings, General, Security; each app has one), `SABNZBD_API_KEY` (the API key, not the NZB key, which can only add NZBs and cannot read or pause the queue), `JELLYFIN_API_KEY` (Jellyfin's Dashboard, API Keys, New API Key; only the `jellyfin` commands read it), `BAZARR_API_KEY` (Bazarr's Settings, General, Security, API Key; only `bazarr status` reads it).
48
- - `home`: `HOMEASSISTANT_TOKEN` (a long-lived access token of an administrator: Home Assistant, User profile, Security, Long-lived access tokens).
48
+ - `home`: `HOMEASSISTANT_TOKEN` (a long-lived access token of an administrator: Home Assistant, User profile, Security, Long-lived access tokens), `SSH_KEY_HOME_B64` (the key of the file commands).
49
49
  2. **Identities.** Zitadel (`https://auth.37pla.net/ui/console`): service user `spc-arcane` with Access Token Type JWT and a JSON key; service user `spc-identity` with a Personal Access Token and the Instance Owner role. Technitium (cluster primary): user `spc-dns` in the Administrators group with an API token; the cluster syncs the user to every node. Cloudflare: an account-owned API token with `Zone:Read` and `DNS:Edit` on both zones. GCP project `frontdoor-1337`: service account `spc-edge` with `roles/iap.tunnelResourceAccessor` and `roles/compute.viewer`, JSON key. Proxmox (`ssh pulsar`): user `spc-proxmox@pve`, role `SpecialistGuest` = `VM.Audit VM.PowerMgmt VM.Snapshot VM.Snapshot.Rollback VM.Config.CPU VM.Config.Memory VM.Config.Options VM.Config.Network VM.Config.CDROM VM.GuestAgent.Audit`, ACLs `PVEAuditor` on `/` and `SpecialistGuest` on `/vms` for both the user and the token `spc-proxmox@pve!cortex` (`-privsep 1`).
50
50
  3. **Services.** Arcane (Settings, Authentication, Federated Credentials): Issuer `https://auth.37pla.net`, Audience `387825541182390275`, Subject exact = `spc-arcane` user ID, Role Admin, Global, lifetime 300. UniFi: the account key and a local key per console (fields above) and policies on 37 allowing Cortex `10.0.40.37` to TCP 22 on `10.0.20.10`, `10.0.10.37`, `10.0.90.10`, TCP 5380 on `10.0.40.53`, TCP 8006 on `10.0.10.37`, TCP 8081 on `10.0.60.5`, TCP 443 on the Mira console `10.1.60.1`, and TCP 22 and 8006 on SPACE-X `10.1.10.37` (that one also on Mira); the homelab `03-cortex-macmini/README.md` lists them with their ids. GitHub: `spc-arcane-gitops` as a write deploy key on `astronaute77/arcane`, `spc-edge-homelab` and `spc-identity-homelab` as write deploy keys on `astronaute77/homelab`.
51
51
  4. **Sudo and user**, as an administrator:
@@ -124,6 +124,7 @@ Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trend
124
124
  - Pulsar, root, two more keys: `spc-backup-pulsar-entry.sh`, `spc-proxmox-pulsar-entry.sh` (tracked in `02-pulsar-proxmox/pulsar/system/`).
125
125
  - SPACE-X, root: `spc-proxmox-spacex-entry.sh` for the same proxmox key (tracked in `06-space-x-proxmox/system/`).
126
126
  - Synapse, Pulsar, and SPACE-X, root: the dns node key, forced to `spc-dns-node-entry.sh` with the node as its argument: `local` on Synapse (technitium1), `pct:107` on Pulsar (technitium2), `pct:100` on SPACE-X (technitium3) (tracked in `01-synapse-dns/system/`).
127
+ - Home Assistant (VM 112 on SPACE-X): no manual install. `specialist-cli home -- files-setup "<public key>" [--no-password] --confirm` writes the key, bound to `spc-home-entry.sh`, and the script itself into the options of the Advanced SSH & Web Terminal add-on, sets the add-on to start at boot, and starts it. The add-on rewrites both at every start. The policies `Home Assistant at Mira - from Cortex` must allow TCP 22.
127
128
  - VM 100, user `arcane`: `spc-backup-arcane-entry.sh` (tracked as `host/spc-backup-arcane-entry` in the `astronaute77/arcane` repository, next to the host backup scripts).
128
129
  - VM 100, user `spc-arcane` (no docker group): `spc-arcane-host-entry.sh` hands each command to the root-owned `spc-arcane-op.py` (installed as `/usr/local/sbin/spc-arcane-op`), the only command `spc-arcane-sudoers` allows; it runs the reviewed probes from `/usr/local/lib/spc-arcane` and the fixed manager and database steps. `spc-arcane-install.sh` creates the user and installs all of it from `/tmp/spc-arcane`; the files are tracked under `host/` in the arcane repository, the probes under `host/spc-arcane-probes/` (moved from the arcane-ops CLI, retired on 2026-10-19). Add `"hostAddress": "10.0.40.30", "hostUser": "spc-arcane"` to `arcane.json`; other arcane commands do not read them.
129
130
  - Nexus, user `nexus`: `spc-inference-nexus-entry.sh` as `/usr/local/sbin/spc-inference-nexus-entry` (tracked in `04-nexus-macstudio/system/`).
@@ -161,6 +162,6 @@ The `astro-discord` extension gives Discord users access to the specialists from
161
162
 
162
163
  ## Rotation and operations
163
164
 
164
- Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `06-space-x-proxmox/system/`, `01-synapse-dns/system/`, `02-pulsar-proxmox/observability/system/`, `host/` of the `astronaute77/arcane` repository, `04-nexus-macstudio/system/`, and `00-frontdoor-vps/system/`.
165
+ Rotation steps for every field live in the homelab repository, `03-cortex-macmini/ROTATION.md`. After any change in Vaultwarden run `specialist-cli provision`. Host state and the sudo rules are documented in `03-cortex-macmini/README.md`; the forced-command scripts are tracked under `02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `06-space-x-proxmox/system/`, `01-synapse-dns/system/`, `02-pulsar-proxmox/observability/system/`, `host/` of the `astronaute77/arcane` repository, `04-nexus-macstudio/system/`, `06-space-x-proxmox/homeassistant/system/`, and `00-frontdoor-vps/system/`.
165
166
 
166
167
  All twelve specialists exist. See `AGENTS.md` for how to add one.
@@ -0,0 +1,93 @@
1
+ #!/bin/sh
2
+ # spc-home-entry: forced command of the home specialist's key inside the
3
+ # "Advanced SSH & Web Terminal" add-on of Home Assistant. The add-on's
4
+ # init_commands write this file at every start; the key's authorized_keys line
5
+ # runs it through sudo with the requested command as one argument.
6
+ # It serves YAML files below /homeassistant: no hidden folders (so never
7
+ # .storage), no dot segments, never secrets.yaml. Every change first copies the
8
+ # current file to .spc-home-backups/<path>.<UTC stamp>.
9
+ set -eu
10
+ set -f
11
+ root=/homeassistant
12
+ backups=$root/.spc-home-backups
13
+ # shellcheck disable=SC2086
14
+ set -- ${1:-}
15
+ op=${1:-}
16
+ path=${2:-}
17
+ stamp=${3:-}
18
+ valid() {
19
+ case "$1" in "" | /* | .* | */.* | *..* | *//* | *[!A-Za-z0-9_./-]*) return 1 ;; esac
20
+ case "$1" in *.yaml | *.yml) ;; *) return 1 ;; esac
21
+ case "$1" in secrets.yaml | */secrets.yaml) return 1 ;; esac
22
+ return 0
23
+ }
24
+ refuse() {
25
+ echo "spc-home-entry: $1" >&2
26
+ exit 2
27
+ }
28
+ args() {
29
+ [ "$1" -eq "$2" ] || refuse "usage: list | read <path> | backups <path> | write <path> | restore <path> <stamp> | remove <path>"
30
+ }
31
+ # Copies the current file aside under a stamp that no backup of it has yet.
32
+ keep() {
33
+ if [ ! -f "$root/$path" ]; then
34
+ echo "backup none"
35
+ return 0
36
+ fi
37
+ mkdir -p "$(dirname "$backups/$path")"
38
+ now=$(date -u +%Y%m%dT%H%M%SZ)
39
+ while [ -e "$backups/$path.$now" ]; do
40
+ sleep 1
41
+ now=$(date -u +%Y%m%dT%H%M%SZ)
42
+ done
43
+ cp -p -- "$root/$path" "$backups/$path.$now"
44
+ echo "backup $now"
45
+ }
46
+ case "$op" in
47
+ list)
48
+ args $# 1
49
+ cd "$root"
50
+ find . -maxdepth 6 -type f \( -name '*.yaml' -o -name '*.yml' \) ! -path '*/.*' ! -name secrets.yaml | sed 's|^\./||' | sort
51
+ ;;
52
+ read)
53
+ args $# 2
54
+ valid "$path" || refuse "refused path"
55
+ [ -f "$root/$path" ] || refuse "no such file: $path"
56
+ cat -- "$root/$path"
57
+ ;;
58
+ backups)
59
+ args $# 2
60
+ valid "$path" || refuse "refused path"
61
+ dir=$(dirname "$backups/$path")
62
+ [ -d "$dir" ] || exit 0
63
+ find "$dir" -maxdepth 1 -type f | sed -n "s|^.*/$(basename "$path")\.\([0-9]\{8\}T[0-9]\{6\}Z\)$|\1|p" | sort
64
+ ;;
65
+ write)
66
+ args $# 2
67
+ valid "$path" || refuse "refused path"
68
+ mkdir -p "$(dirname "$root/$path")"
69
+ keep
70
+ cat > "$root/$path.spc-tmp"
71
+ mv -- "$root/$path.spc-tmp" "$root/$path"
72
+ ;;
73
+ restore)
74
+ args $# 3
75
+ valid "$path" || refuse "refused path"
76
+ case "$stamp" in [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]T[0-9][0-9][0-9][0-9][0-9][0-9]Z) ;; *) refuse "refused stamp" ;; esac
77
+ [ -f "$backups/$path.$stamp" ] || refuse "no such backup: $path $stamp"
78
+ mkdir -p "$(dirname "$root/$path")"
79
+ keep
80
+ cp -p -- "$backups/$path.$stamp" "$root/$path.spc-tmp"
81
+ mv -- "$root/$path.spc-tmp" "$root/$path"
82
+ ;;
83
+ remove)
84
+ args $# 2
85
+ valid "$path" || refuse "refused path"
86
+ [ -f "$root/$path" ] || refuse "no such file: $path"
87
+ keep
88
+ rm -- "$root/$path"
89
+ ;;
90
+ *)
91
+ args 0 1
92
+ ;;
93
+ esac