# Specialists A specialist is a Pi subagent that is the only way to operate one area of the homelab. It has one tool, one skill, and one Vaultwarden note. Every other agent is blocked from the area's CLIs and credentials. | Agent | Area | What it can do | |---|---|---| | `astro.arcane` | Arcane container platform (VM 100) and its GitOps repository | Every `arcane-cli` operation except its own `config`, `auth`, `self-update`; `update-report` (fresh check of every stack with running and latest release versions); `release-notes /` (GitHub notes between the two versions); `change-origin ` (whether a deployment-file change Wazuh saw is a GitOps commit or one of our operations); `project-status`, `deployment check|wait`; `stack-update ` (a stack's pending image updates through GitOps, redeploy, checks, and rollback; across a major version only with `--confirm`, owner approval; held stacks in the repository's `update-holds.json` are refused); `manager-upgrade ` and `manager-rollback ` (the documented manager upgrade, owner approval); `host `: sanitized host checks (memory, stats, logs, OOM, kernel OOM, audit, capacity, storage, Docker usage, service and queue checks) and `db-list|db-dump|db-restore` for Mealie and Paperless through user `spc-arcane` on VM 100; Compose changes of GitOps-managed projects through `git show|write|commit|push`, then `arcane-cli gitops` sync | | `astro.identity` | Zitadel; Pomerium, nginx, lego on VM 104; `02-pulsar-proxmox/dmz/` in the homelab repository | Any Zitadel API call (v2, management, admin, auth) with responses redacted; `dmz status|journal|config-template|render|pomerium-restart|nginx-reload|lego-renew|deploy-config`; `git` on the homelab checkout, writes limited to `02-pulsar-proxmox/dmz/` | | `astro.network` | UniFi, FreeRADIUS (LXC 108), Tailscale (LXC 105) | Read UniFi sites, devices, clients, networks, zones, firewall policies, WANs; create, update, delete firewall policies; RADIUS and Tailscale checks on Pulsar | | `astro.dns` | Technitium primary (Synapse) and secondary (LXC 107); Cloudflare zones `37pla.net`, `monadeo.com` | Read zones and records on both resolvers, resolve, stats; create and delete zones, add, update, delete records on the primary; Cloudflare zones and record add, update, delete | | `astro.edge` | Frontdoor VPS (`frontdoor-1337`) over an IAP tunnel; `00-frontdoor-vps/` in the homelab repository | `probe` the public path; `route-probe` (status of the Supabase, Grimoire, and Mealie public routes from Cortex); `vps status|nginx-conf|nginx-test|journal|wg|bouncer|updates|package|changelog|auto-upgrades|deploy-nginx|reboot --confirm`; `git` on the homelab checkout, writes limited to `00-frontdoor-vps/` | | `astro.security` | Wazuh, CrowdSec, rsyslog archive on VM 106 | Read-only: `status`, `attention`, `agents`, `alerts`, `decisions`, `bouncers`, `metrics`, `wazuh-alerts`, `wazuh-vulns`, `wazuh-events`, `wazuh-vuln-events`, `wazuh-log`, `remote-hosts`, `remote-log`, `journal` | | `astro.backup` | vzdump, the shared Restic repository (Pulsar host config, Arcane app backups), GCS offsite from LXC 102 | Status, journals, and manual runs of every layer; `restic-snapshots|stats|ls`, `restic-restore` into `/var/tmp/spc-restore` on Pulsar, `restore-clean` | | `astro.proxmox` | Proxmox VE on Pulsar | API token: `guests`, `guest`, `get `, `tasks`; `start`, `shutdown|reboot|stop --confirm`; snapshots create, delete, rollback; `set` of CPU, memory, options, network. Pulsar key: `host-status`, `host-journal`, `updates`, `guest-exec ` | | `astro.inference` | llama.cpp on Nexus, Europa health | `nexus-status|start|stop|restart|log|disk`; `europa-health` | | `astro.media` | trendarr over TMDB, OMDb, and the `media` project on VM 100 (Radarr, Sonarr, SABnzbd) | `trending`, `search`, `add-movies`, `add-series` (at most 20 IMDb IDs), `sabnzbd status|pause|resume`; always trendarr's JSON plus its warnings | Call one with `/run astro. -- ` or through the `subagent` tool (both from the bundled `astro-subagents` extension). `/run` saves the specialist's session under `~/.pi/agent/subagent-sessions//`; `/run astro. --continue -- ` 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/.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. ## How it is secured - Credentials and CLIs belong to a dedicated macOS user `specialist` on the host. Agents run as the main user and reach the wrappers only through `sudo -n -u specialist -H /usr/local/bin/specialist-cli`, the single passwordless sudo rule. General sudo asks for a password. - Credentials come from Vaultwarden (`homelab` / `specialists`, one Secure Note per specialist) through `specialist-cli provision`, into `0600` files. Wrappers never call `bw`. - The wrappers run on a root-owned Node in `/usr/local/libexec/specialist-node/` (latest LTS from nodejs.org), not on Homebrew's, because the main user owns all of `/opt/homebrew` and could otherwise swap the interpreter that reads every secret. `/usr/local/sbin/specialist-install` (root, one passwordless sudo rule) installs that Node, the wrappers, arcane-cli, trendarr, and the tools the wrappers run with secrets (`bw` and `jq` for `provision`, `gcloud` and its Python for `edge`) from downloads it checks against the publisher's checksums; it refuses older versions and keeps the previous one for `rollback`. - Arcane is reached with a Zitadel service user: a fresh token per call, exchanged for a 300 s Arcane token. Other services use API keys, a PAT, tokens, or SSH keys that the targets pin to forced commands. The VPS is reached through `gcloud compute start-iap-tunnel` with a service account that may only open IAP tunnels and read instances; its gcloud state lives in `/Users/specialist/.specialists/work/gcloud`. - Every call is logged in `/Users/specialist/.specialists/audit.log`. - The `specialist-gate` extension registers the tool only inside the matching specialist child and blocks other agents from calling the CLIs or reading `/Users/specialist`. `security-guard` carries the same blocks. Limits: `network` writes only firewall policies on UniFi. `security` is read-only. `identity` deploys only `config.yaml` to the DMZ. `edge` changes only `nginx.conf` on the VPS; `dns` writes only to the Technitium primary. `proxmox` cannot create, clone, or destroy guests, change disks, or touch the host. `backup` cannot change retention or schedules. `inference` cannot start Europa or change models. `media` adds titles and toggles the download queue; it cannot delete anything or change Radarr, Sonarr, or SABnzbd settings. ## Enable specialists on a host Host: Cortex (macOS on Apple silicon; Homebrew git; the specialists' Node, trendarr, `bw`, `jq`, `gcloud`, and gcloud's Python come from `specialist-install`). Steps 1 to 3 are one-time on the services; 4 to 8 are per host. 1. **Vaultwarden.** Account `specialists@monadeo.com` with **Can view** on collection `specialists` in organization `homelab`. Secure Notes with Hidden fields (`_B64` fields hold `base64 -i | tr -d '\n'`): - `arcane`: `ZITADEL_KEY_JSON`, `GITOPS_DEPLOY_KEY_B64`, `ZITADEL_USER_ID` (plain), `SSH_KEY_ARCANE_HOST_B64` (user `spc-arcane` on VM 100, for `host`, `manager-*`), and optionally `MEALIE_API_KEY` (only `host mealie-api` reads it). - `identity`: `ZITADEL_PAT`, `SSH_KEY_DMZ_B64`, `HOMELAB_DEPLOY_KEY_B64`. - `network`: `UNIFI_API_KEY`, `SSH_KEY_PULSAR_B64`. - `dns`: `TECHNITIUM_TOKEN`, `TECHNITIUM2_TOKEN` (Technitium API tokens of the primary and the secondary), `CLOUDFLARE_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`. - `edge`: `GCP_SA_KEY_JSON` (service account key), `SSH_KEY_FRONTDOOR_B64`, `HOMELAB_DEPLOY_KEY_B64`. - `security`: `SSH_KEY_OBS_B64`. - `backup`: `SSH_KEY_PULSAR_B64`, `SSH_KEY_ARCANE_B64`. - `proxmox`: `PVE_TOKEN_ID` (plain, `spc-proxmox@pve!cortex`), `PVE_TOKEN_SECRET`, `SSH_KEY_PULSAR_B64`. - `inference`: `SSH_KEY_NEXUS_B64`. - `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). 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 (both resolvers): a user with Zones View/Modify/Delete, Dashboard View, DNS Client View, and an API token each. 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`). 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: API key (Settings, API Keys) and policies 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`, `10.0.40.54`, TCP 8006 on `10.0.10.37`, and TCP 8081 on `10.0.60.5`. 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`. 4. **Sudo and user**, as an administrator: ```sh printf 'cortex ALL=(ALL) ALL\n' | sudo tee /etc/sudoers.d/cortex >/dev/null printf 'cortex ALL=(specialist) NOPASSWD: /usr/local/bin/specialist-cli\n' | sudo tee /etc/sudoers.d/specialists >/dev/null sudo chmod 0440 /etc/sudoers.d/cortex /etc/sudoers.d/specialists && sudo rm -f /etc/sudoers.d/cortex-nopasswd && sudo visudo -c sudo sysadminctl -addUser specialist -fullName "Specialists" -home /Users/specialist -shell /bin/zsh -password - sudo dscl . create /Users/specialist IsHidden 1 && sudo createhomedir -c -u specialist && sudo chmod 700 /Users/specialist sudo install -d -m 0755 -o root -g wheel /usr/local/sbin sudo install -m 0755 -o root -g wheel /specialists/entry/specialist-install.sh /usr/local/sbin/specialist-install printf 'cortex ALL=(root) NOPASSWD: /usr/local/sbin/specialist-install\n' > /tmp/specialist-install.sudoers && sudo visudo -cf /tmp/specialist-install.sudoers && sudo install -m 0440 -o root -g wheel /tmp/specialist-install.sudoers /etc/sudoers.d/specialist-install && rm /tmp/specialist-install.sudoers sudo /usr/local/sbin/specialist-install node 24.22.0 sudo install -m 0755 -o root -g wheel /specialists/entry/specialist-cli.sh /usr/local/bin/specialist-cli sudo /usr/local/sbin/specialist-install jq sudo /usr/local/sbin/specialist-install bw sudo /usr/local/sbin/specialist-install python sudo /usr/local/sbin/specialist-install gcloud ``` `specialist-cli` runs the wrappers with the Node that `specialist-install node` put in place, so that Node comes first. Add `cortex ALL=(specialist) NOPASSWD: ALL` as `/etc/sudoers.d/specialists-setup` (mode `0440`) for the duration of steps 5 to 7, then delete it. `specialist-cli` and `specialist-install` hold the same list of services; after an update that adds one (such as `media`), install both again with the same `sudo install` lines. 5. **Bootstrap**, as `specialist` (`sudo -u specialist -H zsh`, `umask 077`): `~/.config/specialists/client.env` with `BW_SERVER=https://vault.37pla.net`, `BW_CLIENTID`, `BW_CLIENTSECRET`; `~/.config/specialists/master-password`. Both `0600`. 6. **Install and configure**, as `specialist`: `sh /specialists/install/install.sh 2.12.0` (`` is the installed pi-astro directory, `~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro`). Write `~/.specialists/config/.json` for every specialist: ```json { "serverUrl": "http://10.0.40.30:3552", "zitadelDomain": "auth.37pla.net", "audience": "387825541182390275", "arcaneCli": "/Users/specialist/.specialists/bin/arcane-cli", "arcaneCliConfig": "/Users/specialist/.specialists/config/arcanecli.yml", "gitopsRemote": "git@github.com:astronaute77/arcane.git", "gitopsBranch": "main" } { "zitadelDomain": "auth.37pla.net", "dmzHost": "10.0.20.10", "dmzUser": "dmz", "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "02-pulsar-proxmox/dmz", "pomeriumConfig": "02-pulsar-proxmox/dmz/config.yaml" } { "unifiBaseUrl": "https://10.0.10.1/proxy/network/integration", "unifiCertSha256": "", "pulsarHost": "10.0.10.37", "pulsarUser": "root" } { "technitiumPrimaryUrl": "http://10.0.40.53:5380", "technitiumSecondaryUrl": "http://10.0.40.54:5380", "technitiumCatalog": "catalog.invalid" } { "gcloud": "/usr/local/libexec/specialist-gcloud/current/bin/gcloud", "gcloudPython": "/usr/local/libexec/specialist-python/current/bin/python3", "project": "frontdoor-1337", "zone": "us-east1-c", "instance": "frontdoor-1337", "serviceAccount": "spc-edge@frontdoor-1337.iam.gserviceaccount.com", "iapLocalPort": 22337, "sshUser": "spc-edge", "publicIp": "35.237.66.101", "probeHost": "auth.37pla.net", "homelabRemote": "git@github.com:astronaute77/homelab.git", "homelabBranch": "main", "repoArea": "00-frontdoor-vps", "nginxConf": "00-frontdoor-vps/nginx.conf" } { "obsHost": "10.0.90.10", "obsUser": "observability" } { "pulsarHost": "10.0.10.37", "pulsarUser": "root", "arcaneHost": "10.0.40.30", "arcaneUser": "arcane" } { "apiUrl": "https://10.0.10.37:8006", "certSha256": "", "node": "pulsar", "pulsarHost": "10.0.10.37", "pulsarUser": "root" } { "nexusHost": "10.0.40.38", "nexusUser": "nexus", "europaHealthUrl": "http://10.0.60.5:8081/health" } { "trendarrCli": "/Users/specialist/.specialists/bin/trendarr/node_modules/@astrofoundry/trendarr/dist/cli.js", "radarrUrl": "http://10.0.40.30:7878", "radarrQualityProfileId": 7, "radarrRootFolderPath": "/media/movies", "sonarrUrl": "http://10.0.40.30:8989", "sonarrQualityProfileId": 7, "sonarrRootFolderPath": "/media/tv", "sonarrMonitor": "all", "sabnzbdUrl": "http://10.0.40.30:8084", "maxEntries": 10 } ``` The `media` wrapper writes trendarr's `~/.trendarr/config.json` for each call into a private temporary HOME under `~/.specialists/work/media/` and removes it afterwards, so trendarr itself is never configured with `trendarr init`. Cortex reaches the three ports on `10.0.40.30` within its own VLAN. `sudo /usr/local/sbin/specialist-install trendarr ` installs trendarr behind the link `~/.specialists/bin/trendarr`, so that path stays valid across updates. Then `sudo -n -u specialist -H /usr/local/bin/specialist-cli provision`; it lists every note and field. Later updates go through the installer, one component at a time, each checked before and after the switch: ```sh sudo /usr/local/sbin/specialist-install node sudo /usr/local/sbin/specialist-install wrappers sudo /usr/local/sbin/specialist-install arcane-cli sudo /usr/local/sbin/specialist-install trendarr sudo /usr/local/sbin/specialist-install jq|bw|gcloud sudo /usr/local/sbin/specialist-install python sudo /usr/local/sbin/specialist-install rollback node|wrappers|arcane-cli|trendarr|python|gcloud|bw|jq sudo /usr/local/sbin/specialist-install status ``` - `node` accepts only an LTS release listed in `https://nodejs.org/dist/index.json`, checks the tarball against `SHASUMS256.txt`, and switches `current` only after every installed wrapper answers `--help` with it; `previous` keeps the last one. - `wrappers` takes the pi-astro tarball from the npm registry, checks its `sha512` integrity, copies what `install.sh` copies, writes `~/.specialists/bin/VERSION`, and restores the old files if any wrapper fails `--help`. `install.sh` stays the first-time installer (it also writes the default config files). - `arcane-cli` checks the release tarball against `arcane__checksums.txt`; it follows the Arcane server's version. - `python` installs a python-build-standalone `install_only_stripped` build (astral-sh), checked against the release's `SHA256SUMS`; before the switch it imports `ssl` and `sqlite3` and runs the current gcloud with the new Python. - `gcloud` assembles the SDK from Google's component snapshot `components-v.json` (core, core-nix, gcloud-deps, and their darwin-arm parts), each tarball checked against the snapshot's sha256, because Google lists the full archive's sha256 only in the table on its versioned-archives page, for the current release; it needs the installed Python and answers `gcloud version` before the switch. - `bw` takes `bw-macos-arm64-.zip` from the bitwarden/clients release `cli-v`, checked against the asset digest from the GitHub API; `jq` takes `jq-macos-arm64` from the jqlang/jq release, checked against its `sha256sum.txt`. - `trendarr` installs with the root-owned Node's npm, without install scripts, into `trendarr-`. - A version older than the installed one is refused; `rollback` swaps back to the kept previous copy. `status` prints the installed versions as JSON. 7. **SSH targets.** Each target gets an entry script from `entry/remote/` as `/usr/local/sbin/` (`0755`, root) and the public key in the right `authorized_keys` as `command="/usr/local/sbin/",no-port-forwarding,no-agent-forwarding,no-pty,no-X11-forwarding ssh-ed25519 ...`: - VM 104, user `dmz`: `spc-identity-dmz-entry.sh`. - Pulsar, root: `spc-network-pulsar-entry.sh`. - VM 106, user `observability`: `spc-security-obs-entry.sh` (tracked in the homelab repository, installed by `02-pulsar-proxmox/observability/deploy.sh`). - Frontdoor VPS: `spc-edge-frontdoor-install.sh` creates user `spc-edge` (group `systemd-journal`), installs `spc-edge-frontdoor-entry.sh` and the sudoers file `spc-edge-frontdoor-sudoers`, and writes `authorized_keys`. Copy the three files and the public key to `/tmp` with `gcloud compute scp --tunnel-through-iap`, then run it as root. - Pulsar, root, two more keys: `spc-backup-pulsar-entry.sh`, `spc-proxmox-pulsar-entry.sh` (tracked in `02-pulsar-proxmox/pulsar/system/`). - 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). - 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. - Nexus, user `nexus`: `spc-inference-nexus-entry.sh` as `/usr/local/sbin/spc-inference-nexus-entry` (tracked in `04-nexus-macstudio/system/`). 8. **Pi**, as the main user: `~/.pi/agent/specialists.json` (below) and the specialist blocks in `~/.pi/agent/security-guard.json` (`specialist-cli`, `arcane-cli`, `-u specialist` in `operations`; `/Users/specialist/**` in `reads` and `writes`; keep the default rules next to them). ```json { "entry": "/usr/local/bin/specialist-cli", "user": "specialist", "specialists": [ { "agent": "astro.arcane", "tool": "arcane", "service": "arcane", "timeoutMs": 8100000 }, { "agent": "astro.identity", "tool": "identity", "service": "identity", "timeoutMs": 120000 }, { "agent": "astro.network", "tool": "network", "service": "network", "timeoutMs": 120000 }, { "agent": "astro.dns", "tool": "dns", "service": "dns", "timeoutMs": 60000 }, { "agent": "astro.edge", "tool": "edge", "service": "edge", "timeoutMs": 300000 }, { "agent": "astro.security", "tool": "security", "service": "security", "timeoutMs": 120000 }, { "agent": "astro.backup", "tool": "backup", "service": "backup", "timeoutMs": 3600000 }, { "agent": "astro.proxmox", "tool": "proxmox", "service": "proxmox", "timeoutMs": 360000 }, { "agent": "astro.inference", "tool": "inference", "service": "inference", "timeoutMs": 1260000 }, { "agent": "astro.media", "tool": "media", "service": "media", "timeoutMs": 660000 } ] } ``` Check: `sudo -n -u specialist -H /usr/local/bin/specialist-cli arcane --caller test -- projects list` prints JSON; the same for `identity -- dmz status`, `network -- unifi sites`, `dns -- technitium primary zones`, `edge -- vps status`, `security -- attention`, `backup -- vzdump-tasks`, `proxmox -- guests`, `inference -- nexus-status`, `media -- sabnzbd status`; `/run astro.arcane -- list projects` works in Pi; `bash` with `arcane-cli --help` is blocked in a normal session. ## Discord The `astro-discord` extension gives Discord users access to the specialists from a channel. It runs in a headless Pi host on Cortex (LaunchAgent `com.astrofoundry.astro-discord`, user `cortex`), never in interactive sessions. - Channels are configured one by one (`channels.`): `trigger` is `always` (every message that names a specialist counts) or `mention` (only messages that start with `@Cortex` or reply to the bot); `specialists` is `*` or a list. A channel with one specialist needs no prefix: every message there is a task for it. In a channel with several, `dns list the zones` names the specialist; an addressed message without a name gets a reply asking for one. Threads inherit their parent channel's entry; unlisted channels are ignored. The bot replies at once with " is working on your task" and shows the typing indicator until the answer replaces that reply. Reactions on your message: ⏳ running, 🔒 waiting for an owner's approval, ✅ done, ❌ failed. `help` shows the specialists you may use in that channel and the commands (`status` lists running tasks; owners in the admin channel also see the `config` commands). Each channel and specialist has one conversation: a reply to the bot's answer, or another task for that specialist within 30 minutes, continues it with everything the specialist saw before; otherwise a new one starts, and a task beginning with `new` forces that. Replied-to and forwarded messages (text, embeds, attachment names) travel with the task, so "check this" on a forwarded alert works. Image attachments on the message or on what it quotes (up to 4, 8 MiB each) are downloaded and passed to the specialist, which sees them; other file types are named only. Sessions live under `~/.config/astro-discord/sessions//` and are deleted after 7 days. Long answers arrive as a `.md` attachment. When the bridge restarts, open approval requests are marked cancelled and running tasks interrupted in Discord; ask again. Scheduled reports are a list in the config, one entry per report: `"reports": [{ "report": "arcane", "channelId": "", "time": "06:00", "timeZone": "Europe/Madrid" }, { "report": "tools", "channelId": "", "time": "06:00", "timeZone": "Europe/Madrid" }]` (the earlier single `dailyReport` key is refused; move it into the list). The Arcane report posts an "Arcane Daily Report:" message every morning from a fresh `update-report`: one section per stack with updates, each service as current to target version with the kind of change, a release-notes verdict on every major version, and an Update button per stack that only owners can press (it runs `arcane stack-update `; the button turns into the outcome and the reason arrives as a note only the clicker sees). Stacks held in `update-holds.json` at the root of the arcane GitOps repository (`{ "supabase": "coordinated release: review first" }`) show the reason and get no button. Replying to the report asks the arcane specialist with the report as context. The tools report posts "Cortex Tools Report:": every tool on Cortex with a newer version (Homebrew packages installed on request and casks, Pi, pi-astro, and through `specialist-install` the wrappers, arcane-cli at the Arcane server's version, trendarr, and the specialist Node at the latest LTS), a release-notes verdict from `astro.release-reviewer` for the tools the specialists build on, an Update button per line, and one Upgrade everything for Homebrew. Only owners can press them; nothing is installed otherwise. After an update that needs it, the bridge, herdr, or Astrogate restarts as soon as nothing runs on it; after a day of waiting, a Restart now button appears. The bridge calls `sudo -n /usr/local/sbin/specialist-install` through the sudoers rule from step 4. - Media: where the `media` specialist is present (`config channel <#channel> always media`), `/trending [type] [min_rating] [count]`, `/search [type]`, and `/downloads <status|pause|resume|unpause>` run the wrapper without a model. Lists arrive as two messages, Movies and Series, each title with a button beside it: **Add** adds it at once and turns into Added, In library, or Not found (Retry after a failure); a greyed-out In library or No IMDb ID button needs nothing. Notes such as "downloads are paused" go only to the user who clicked. Owners and `access.media` users may use them; anyone else gets a refusal only they see, and in a channel without `media` the bot names the channels that have it. Plain messages in the channel still go to the agent, for requests by name ("add the new Dune"). At startup the bridge sets the three commands as the application's global commands (servers only). - Arcane manager: when the morning Arcane Daily Report shows a newer manager release, the `arcane` section carries an **Upgrade Arcane to vX** button. Only an owner's click on the newest report runs `arcane manager-upgrade <version>` through the entry point (one at a time, counted as open work so no bridge restart interrupts it); the button turns into the outcome, a reply gives the result, and a successful upgrade installs the matching `arcane-cli` with `specialist-install`. - Access: `owners` may use every specialist and decide approvals; `access.<specialist>` lists extra users for that specialist; everyone else gets no reply. Owners change the configuration from the admin channel (`adminChannelId`) without a shell: `config show`, `config channel <#channel> <always|mention> <*|dns,edge>`, `config channel <#channel> remove`, `config access <specialist> add|remove <@user>`; the bot writes `~/.config/astro-discord/config.json` on Cortex, which is also editable by hand and re-read on every message. Deny the bot's role View Channel on channels it must never read; that is the boundary the map cannot provide. - Approvals: a risky call (anything with `--confirm`, plus writes such as record or zone deletes, Zitadel changes, Pomerium deploys, service restarts, and on Arcane destructive actions: `down`, deletes, prunes, image, volume, or network removal, `system upgrade`, `gitops delete`, plus `manager-upgrade`, `manager-rollback`, `host db-restore`, and the Radarr host-config reads; `stack-update` asks only across a major version, through its `--confirm`; an owner's Update click on the report needs no approval; help lookups never ask) pauses the specialist and posts Approve/Deny buttons; only owners' clicks count; no decision within `approvalTimeoutMinutes` denies it. The specialist then reports the denial. Ambiguous tasks get a question back instead of an action. - Setup, as `cortex`: `d=$(mktemp -d) && cp ~/.pi/agent/npm/node_modules/@astrofoundry/pi-astro/extensions/astro-discord/*.ts "$d" && node --disable-warning=ExperimentalWarning "$d/setup.ts"` (Node does not strip types inside `node_modules`, so the files are copied first) prompts for the bot token and the ids, checks each against Discord, and writes `~/.config/astro-discord/{token,config.json,run.sh}` and the LaunchAgent; it prints the `launchctl bootstrap` line. After a pi-astro update restart the bridge with `launchctl kickstart -k gui/$(id -u)/com.astrofoundry.astro-discord`. Log: `~/Library/Logs/astro-discord.log`. - Discord side: application `Cortex` with a bot, Message Content Intent enabled, invited with scopes `bot` and `applications.commands` and permissions View Channel, Send Messages, Attach Files, Read Message History, Add Reactions. ## Rotation and operations 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/`, `02-pulsar-proxmox/observability/system/`, `host/` of the `astronaute77/arcane` repository, `04-nexus-macstudio/system/`, and `00-frontdoor-vps/system/`. All nine planned specialists exist. See `AGENTS.md` for how to add one.