@monster-orange/den 0.4.18 → 0.4.20

package/CHANGELOG.md

@@ -4,6 +4,166 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.20] - 2026-11-09
+
+### Added
+
+- **1Password works for a Den running as a service.** A Den under launchd
+  does not read your login shell, so `op` had no
+  `OP_SERVICE_ACCOUNT_TOKEN` and every 1Password `secret_env` ref failed
+  with a bare "not resolved". `secrets.onepassword.token` in
+  `config/local/user.yml` (per machine) now says where the token comes
+  from: `keychain:<service>` (macOS), `file:<path>` (mode 600 only) or
+  `env:<VAR>` (the default is `env:OP_SERVICE_ACCOUNT_TOKEN`, as before).
+  A bad value is refused at config load, naming the key. The token is read
+  when a ref is resolved, never cached, and goes only into the `op` child's
+  env; it is never logged, stored, put in an error, the activity records
+  or an API response.
+- **"Not resolved" now says why.** A 1Password ref that fails reports one
+  of: no service-account token or session, no access to the vault, item or
+  field not found, rate limited, or a short safe summary. A token source
+  that fails (keychain item missing, file mode wrong, env var unset) is
+  named, never the token.
+- **doctor** adds a `1password` row, "this process has no service-account
+  token. Set secrets.onepassword.token.", when 1Password is the provider
+  and the source yields none (a warning).
+- **Settings › Secrets** shows the token's source, never the token
+  (`GET /api/settings` gains `op_token_source`, a string).
+
+## [0.4.19] - 2026-11-08
+
+### Added
+
+- **The server agent (ON-6).** Every Den has its own agent, named after the
+  distribution ("Acme agent"), for anything about the server itself: set it
+  up, add a repo, fix a failing service, change a setting, explain what's
+  running. It belongs to no workspace. It is a normal Den agent underneath
+  (record, session, Resume, rotation, hooks), with Den's persona `server`
+  and the plain-writing rule, in a reserved scope, `den-server`.
+  - It acts only through Den's MCP, which serves it the whole Den. Each
+    write (`workspace_create`, `repo_add`, `service_try`) is held for the
+    person's Allow, so it only reads until they allow one. It starts in an
+    empty folder of its own (`<state_dir>/server-agent`).
+  - A fresh Den's first page (`/`, while no workspace has a repo) is that
+    agent in a terminal framed as the page, with Open in Agents. With an
+    installed runtime that carries Den's tools, it starts by itself, with
+    "Let's set up <name>. Where are your repos?", with the folder above the
+    Den's as the default, in its first turn. With none, the page shows how
+    to install one and the manual path for this Den, from its folder:
+    `cd <dir>` → `./bin/<cli> repo add <path>` → `./bin/<cli> up`.
+  - After setup it is in the rail (`/server-agent`), ⌘K has "Ask <name>",
+    and Agents lists it first, under "Server".
+  - Its runtime: the page's Runs on picker (`agents.server_runtime` in
+    `config/local/user.yml`), else the first installed one with Den's tools.
+  - Its model: the page's Model picker beside it (`agents.server_model`),
+    with only the runtime's own models, else Sonnet when the runtime has it.
+    A new model takes effect at the next start (a fresh conversation).
+  - Den's own MCP tools run without Claude Code's own prompt, for this
+    agent only (`mcp__<server>` in its settings file's `permissions.allow`).
+    Reads just run; each write still waits for the person's Allow in the
+    browser, so it asks once. The org's immediate actions (`mcp.actions`)
+    still ask in the terminal (`permissions.ask`). Workspace agents are
+    unchanged.
+  - On a fresh Den, one line above its terminal: "Claude asks whether to
+    trust this folder. Choose Yes." Den doesn't answer Claude's folder-trust
+    prompt for the person.
+  - `GET /api/server-agent`, `POST /api/server-agent/start`,
+    `POST /api/server-agent/runtime` and `POST /api/server-agent/model`.
+    Only a person starts it or picks its runtime or model: an agent's token
+    or claim gets 403.
+
+### Changed
+
+- **The install-den skill does three things only (ON-1, slimmed).** It
+  installs Den after checking Node and git, helps pick its name and folder
+  (default `~/<name>`), then runs `web up` and hands over the one-time link
+  from `web claim-link`: "Den's own agent takes it from there." It no
+  longer adds repos, starts services or connects itself to Den's MCP.
+- **`npx @monster-orange/den@latest create`.** The skill, the README, the
+  docs, `create`'s own `fix` lines and `--help` name `@latest`. A bare name
+  could reuse an older Den cached in `~/.npm/_npx`.
+- **workspace_create makes the workspace active.** On the person's Allow,
+  the MCP's `workspace_create` creates the workspace and activates it, so
+  `service_try` can start its services. `service_try` on a workspace that
+  isn't active says so in the browser ("Start <service> (this activates
+  <workspace>)") and does both on the one Allow. Before, the server agent
+  was refused with "Workspace is not active", and nothing it could call
+  activated one. `<cli> workspace create` is unchanged.
+- **The drafted manifest has a health URL when the dev server's port is
+  known.** `manifest_draft` and `repo add` draft
+  `health: { local: { url: http://localhost:<port>/ } }` when the start
+  script names a port (`--port`, `-p`, `PORT=`) or runs a dev server with a
+  fixed default (Vite 5173, Next 3000, Angular 4200, and a few
+  more). So the service gets a health check and Visit ↗. `--health` still
+  wins. With no port, nothing is guessed.
+- **The ON-4 dry run follows the two agents:** install, the setup link, the
+  fresh first page, then the server agent's MCP calls, with `repo_add` and
+  `service_try` each allowed from the signed-in browser. It now asserts 5
+  minutes or less.
+- **An accessibility check runs with the tests.** axe-core (WCAG 2.0 and
+  2.1 A and AA, plus best practice) scans the rail, an open pinned-service
+  panel, the Start agent dialog and the server agent's page, in light and
+  dark, at 1440×900 and 390×844. Any violation fails it.
+
+### Fixed
+
+- **No Stop hook error at the end of setup.** The server agent was given the build agents' hand-back template, so
+  after the service came up it wrote a hand-back, and Den's Stop hook sent it back because a decision didn't end in
+  "?". The person saw "Stop hook error" and waited a turn. The server agent now has no hand-back template, and its
+  Stop hook skips the hand-back check. It still asks it to explain every ID, and session rotation is unchanged.
+
+- **The Stop hook no longer flags Den's own name.** A Den whose name looks
+  like an ID (`t2` → "T2") had the server agent's first greeting rejected
+  ("'T2' is not explained"), and the person saw "Stop hook error". Den now
+  tells the hook the ID-shaped words in its own title and the workspace's
+  name (`--known`), and it never flags those. Any other bare ID is still
+  flagged.
+- **No What's new over a brand-new Den.** On a fresh Den (no repo in any
+  workspace yet, the server agent page's `fresh`) the release notes no
+  longer open by themselves over the agent and the approvals. That version
+  counts as seen. `/api/server-info` has `fresh`.
+- **The "log in here" line shows on every fresh run.** The server agent
+  page chose the line from the runtime picker's runtime, which can read
+  none (or another one) while the agent runs. It now uses the runtime the
+  agent runs on (`runningRuntime`, from its record). And a start that isn't
+  running yet when the page reads it back is read again, a second apart, so
+  the terminal and its lines come up without a reload.
+- **The Graph's empty View says where a service is.** With the View on a
+  workspace with no services (right after onboarding), Open in Graph for
+  a service in another workspace showed "No services in workspace" only.
+  It now also says "<service> is in <workspace>, outside this View." with
+  Show <workspace>, the same line as over a drawn graph.
+- **Open Terminal on Windows.** On the signed-out page it did nothing on Windows. Windows has no `ssh://` app by default, so
+  there the link is gone and the ssh command is the step: "Open Windows Terminal or PowerShell, paste this, and press
+  Enter." Elsewhere, if the page still has focus 2 seconds after the click, it says "Nothing opened? Copy the command
+  below and paste it into your terminal app." The command and its copy button always show.
+
+- **No "down" flash after Start.** Starting a dev server from the
+  pinned-service panel showed "starting…", then "down: fetch failed" for
+  a second or two, then up. The server's ready event ended "starting…",
+  and the header's next health paint still held the service's down result
+  from before Start. Now, while a Start or Restart is in flight, a down
+  reads "starting…" until the first up or the 120 s timeout. The ready
+  event ends it only when health already says up.
+- **Open in Graph says when a service is outside the View.** With the View
+  on one workspace, Open in Graph for a service in another landed on a
+  Graph without its card. Now the Graph says "<service> is in
+  <workspace>, outside this View." with a Show <workspace> button. The
+  button switches the View the way the top bar does, then focuses the
+  card. The View never switches by itself.
+- **The phone drawer keeps the rail a nav.** Under 720 px, ☰ made the
+  rail's `<nav>` itself a dialog, which a nav may not be. The dialog is
+  now a box around the rail ("Pages"); focus, Tab, Esc and the scrim work
+  as before.
+- **The chosen persona's role and tag are readable.** On the chosen row's
+  tint, in light, they were 4.49:1, under 4.5:1. They read in the muted
+  colour there now.
+
+### Migrations
+
+- No workspace may be named `den-server`: creating one is refused. Rename a
+  workspace with that name before moving to 0.4.19.
+
 ## [0.4.18] - 2026-11-08
 
 ### Added

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.18/hero-dark.png">
-  <img src="docs/images/0.4.18/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.20/hero-dark.png">
+  <img src="docs/images/0.4.20/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -22,11 +22,12 @@ Paste this line into your coding agent (Claude Code, Codex, Gemini, Grok, …):
 Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md
 ```
 
-The agent follows the [install-den skill](skills/install-den/SKILL.md). It asks you at most three questions,
-creates your Den, adds one of your repos without changing it, starts it, checks it, and connects itself to Den's
-MCP server. Then it tells you what's running and the URL to open. It never asks for a password in chat, never
-edits your repos and sends nothing off your machine. Every step it runs answers in JSON and is safe to re-run:
-see [Set up by your agent](docs/distributions.md#set-up-by-your-agent).
+The agent follows the [install-den skill](skills/install-den/SKILL.md). It checks Node and git, installs Den,
+asks you its name and folder, starts it, and hands you a one-time link. Open it: your Den's own agent takes it
+from there. That agent finds your repos, adds them without changing them and starts one, and each change waits
+for you to allow it in the browser. Neither agent asks for a password in chat, edits your repos or sends anything
+off your machine. Every step answers in JSON and is safe to re-run: see
+[Set up by your agent](docs/distributions.md#set-up-by-your-agent) and [The server agent](docs/distributions.md#the-server-agent).
 
 ## What Den is
 
@@ -38,7 +39,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.18/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.20/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +69,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.18/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.18/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.18/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.18/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.20/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.20/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.20/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.20/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started
@@ -79,7 +80,7 @@ yours. Den connects them and turns on good practice from the start.
 You need Node 22.13 or later, and Docker for anything that runs in containers. mkcert is only needed if you want Den to issue local HTTPS certificates.
 
 ```sh
-npx @monster-orange/den create acme     # your own Den, named after your product
+npx @monster-orange/den@latest create acme     # your own Den, named after your product
 cd acme && npm install
 ./bin/acme register ../shop-api          # add a repo (repeat for each one)
 ./bin/acme up                            # start everything, in order

package/docs/distributions.md

@@ -19,8 +19,8 @@ Den's own checkout is itself a distribution, named `den`.
 ## Create one
 
 ```sh
-npx @monster-orange/den create acme          # writes ./acme
-npx @monster-orange/den create acme ~/src/acme-dev --title "Acme Dev"
+npx @monster-orange/den@latest create acme          # writes ./acme
+npx @monster-orange/den@latest create acme ~/src/acme-dev --title "Acme Dev"
 ```
 
 From a Den checkout, `./bin/den create acme ../acme` does the same.
@@ -72,26 +72,33 @@ Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/
 
 That file is the install-den skill, also in the package at
 `skills/install-den/SKILL.md`: plain Markdown any agent can follow, with
-Claude skill front matter. `den --help` prints the line. The skill runs the
-commands below. Each one takes `--json`, never prompts, and is safe to
+Claude skill front matter. `den --help` prints the line. The skill does three
+things only: it installs Den (after checking Node and git), helps the person
+pick its name and folder (default `~/<name>`), then runs `web up` and hands
+over the one-time link from `web claim-link`: "Den's own agent takes it from
+there." It adds no repo and creates no workspace: that is
+[the server agent](#the-server-agent)'s job. Every command below also stays a
+person's own: `npm i -g @monster-orange/den` → `den create <name>` →
+`<cli> repo add` → `<cli> up` skips both agents. The skill runs the first
+of the commands below, and the server agent the rest through MCP. Each one takes `--json`, never prompts, and is safe to
 re-run. With `--json`, stdout carries exactly one JSON object and the
 command's log goes to stderr. When `ok` is false the object says why
 (`error`) and carries either a command the agent can run (`fix`) or a
 question for the person (`ask`, sometimes with `choices`).
 
-| Step                                                       | Answers                                                                      |
-| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `npx @monster-orange/den create <name> [dir] --yes --json` | `{ ok, dir, cli, existed, files, port, portPicked?, next }`                  |
-| `<cli> repo add <path\|git-url> --json`                    | `{ ok, existed, repo, workspace, mode, path, manifest, services, next }`     |
-| `<cli> repo detect <folder> --json`                        | `{ ok, path, repos, workspaces, truncated, skipped, rule, next }`            |
-| `<cli> repo add <path> --dry-run --json`                   | `{ ok, dryRun, repo, workspace, path, manifest, draft, validation, next }`   |
-| `<cli> onboard status --json`                              | `{ ok, checks: [{ id, status, detail, fix?, ask? }], next }`                 |
-| `<cli> up <repo> --json`                                   | `{ ok, workspace, services: [{ address, result, health, detail? }], next }`  |
-| `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
-| `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
-| `<cli> mcp connect --runtime <runtime> --json`             | `{ ok, server, clients: [{ id, ok, said, file?, changed? }], restart, web }` |
-| `<cli> down <repo> --json`                                 | `{ ok, workspace, services, all? }`                                          |
-| `<cli> web down --json`                                    | `{ ok, url, port, running, stopped }`                                        |
+| Step                                                              | Answers                                                                      |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `npx @monster-orange/den@latest create <name> [dir] --yes --json` | `{ ok, dir, cli, existed, files, port, portPicked?, next }`                  |
+| `<cli> repo add <path\|git-url> --json`                           | `{ ok, existed, repo, workspace, mode, path, manifest, services, next }`     |
+| `<cli> repo detect <folder> --json`                               | `{ ok, path, repos, workspaces, truncated, skipped, rule, next }`            |
+| `<cli> repo add <path> --dry-run --json`                          | `{ ok, dryRun, repo, workspace, path, manifest, draft, validation, next }`   |
+| `<cli> onboard status --json`                                     | `{ ok, checks: [{ id, status, detail, fix?, ask? }], next }`                 |
+| `<cli> up <repo> --json`                                          | `{ ok, workspace, services: [{ address, result, health, detail? }], next }`  |
+| `<cli> web up --no-open --json`                                   | `{ ok, url, port, version? }`                                                |
+| `<cli> doctor --json`                                             | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
+| `<cli> mcp connect --runtime <runtime> --json`                    | `{ ok, server, clients: [{ id, ok, said, file?, changed? }], restart, web }` |
+| `<cli> down <repo> --json`                                        | `{ ok, workspace, services, all? }`                                          |
+| `<cli> web down --json`                                           | `{ ok, url, port, running, stopped }`                                        |
 
 ### repo add
 
@@ -119,7 +126,12 @@ question for the person (`ask`, sometimes with `choices`).
   the answer has `ask` and `choices`, nothing is written, and a re-run names
   the command with `--run "<cmd>"`. A Makefile `test` target or a
   `package.json` `test` script becomes the repo's `tests.unit`.
-  `--health <url>` adds an HTTP health check.
+  `--health <url>` adds an HTTP health check. Without it, when the start
+  script names a port (`--port`, `-p`, `PORT=`) or runs a dev server with a
+  fixed default port (Vite 5173, Next 3000, Angular 4200,
+  Gatsby 8000, webpack-dev-server 8080), the side-car gets
+  `http://localhost:<port>/` as its health URL, so the service has Visit ↗.
+  No port: no health URL is guessed.
 - The workspace is `-w <workspace>` (made and activated if it doesn't exist),
   else the focused one, else a new `default` workspace.
 - The same repo again answers `ok` with `existed: true`. A different repo
@@ -184,11 +196,11 @@ token (an MCP server outside an agent's session, or anything else on this
 machine) reads "Something on this machine (no agent identity) wants to:",
 with "If you didn't ask an agent to do this, Deny." under it.
 
-| MCP tool           | What Allow runs                                         |
-| ------------------ | ------------------------------------------------------- |
-| `workspace_create` | The Workspaces page's create: an empty workspace        |
-| `repo_add`         | `repo add <path> --json`, a local folder inside home    |
-| `service_try`      | `up` for one service, as the Services page's Start does |
+| MCP tool           | What Allow runs                                                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `workspace_create` | The Workspaces page's create: an empty workspace, made active                                                                                      |
+| `repo_add`         | `repo add <path> --json`, a local folder inside home                                                                                               |
+| `service_try`      | `up` for one service, as the Services page's Start does; an inactive workspace is activated first ("Start <service> (this activates <workspace>)") |
 
 - **Den writes the dialog.** Its line and its Review come from the action
   and its arguments, never from the agent. `repo_add`'s Review is its dry
@@ -607,12 +619,12 @@ The backend is a strategy, chosen with `secrets.provider` in the org config
 (per engineer in `config/local/user.yml`, per shell with
 `<PREFIX>_SECRETS_PROVIDER`):
 
-| `secrets.provider` | What it is                                                                               |
-| ------------------ | ---------------------------------------------------------------------------------------- |
-| `none`             | No store. Nothing is resolved, no CLI is run; `den create` scaffolds this                |
-| `env`              | Plain environment variables of the process running Den                                   |
-| `doppler`          | The `doppler` CLI (`secrets.doppler: { project, config }` for a default scope)           |
-| `1password`        | The `op` CLI (`secrets.onepassword.account` for the account, else your own `OP_ACCOUNT`) |
+| `secrets.provider` | What it is                                                                                                                                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `none`             | No store. Nothing is resolved, no CLI is run; `den create` scaffolds this                                                                                                    |
+| `env`              | Plain environment variables of the process running Den                                                                                                                       |
+| `doppler`          | The `doppler` CLI (`secrets.doppler: { project, config }` for a default scope)                                                                                               |
+| `1password`        | The `op` CLI (`secrets.onepassword.account` for the account, else your own `OP_ACCOUNT`; [a service-account token for a service](#1password-for-a-den-running-as-a-service)) |
 
 ```yaml
 # config/acme.yml
@@ -787,6 +799,49 @@ OPENAI_API_KEY (names only; not resolved in a dry run)`.
   (`[A-Za-z_][A-Za-z0-9_]*`). A `stacks:` entry in the org config takes
   `secret_env` too.
 
+## 1Password for a Den running as a service
+
+A Den started by launchd or systemd does not read your login shell, so
+`op` has no `OP_SERVICE_ACCOUNT_TOKEN` and every 1Password ref fails.
+`secrets.onepassword.token` says where this machine keeps the
+service-account token. It is per machine: Den reads it from
+`config/local/user.yml` only, and a value in the distribution's config is
+ignored.
+
+```yaml
+# config/local/user.yml
+secrets:
+  onepassword:
+    token: keychain:op-service-account # or file:~/.config/op/token | env:OP_SERVICE_ACCOUNT_TOKEN
+```
+
+| Value                | Where the token comes from                                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `keychain:<service>` | macOS: `security find-generic-password -s <service> -w`, run with no shell. Refused on other systems                     |
+| `file:<path>`        | A file whose mode is exactly 600 (a group or other bit refuses it). `~` expands; a trailing newline is dropped           |
+| `env:<VAR>`          | The env var `<VAR>` of the process running Den. With no key set the default is `env:OP_SERVICE_ACCOUNT_TOKEN`, as before |
+
+- **Checked at config load.** A value that is none of these shapes is
+  refused, naming `secrets.onepassword.token`. The message never repeats
+  the value.
+- **Read each time.** The token is read when a ref is resolved, never
+  cached or written anywhere, and passed only in the `op` child's env as
+  `OP_SERVICE_ACCOUNT_TOKEN`. It is never in a log, an error, the activity
+  records or an API response.
+- **Why a ref failed.** A `secret_env` key that does not resolve says why,
+  in plain words: no service-account token or session; no access to the
+  vault; item or field not found; rate limited; or a short summary of
+  what `op` said. When the token source itself fails (the keychain item is
+  missing, the file's mode is wrong, the env var is unset) the message
+  names the source, never the token.
+- **doctor.** With `secrets.provider: 1password` and a source that yields
+  no token, `doctor` adds a `1password` row: "this process has no
+  service-account token. Set secrets.onepassword.token." It is a warning,
+  not a failure (a signed-in `op` app needs no token). `doctor` only looks
+  a keychain item up; it never reads the token.
+- **Settings.** Settings › Secrets shows the source (`keychain: <service>`,
+  `file: <path>`, `env: <VAR>` or "not set"), never the token.
+
 ## The edge and TLS
 
 The edge is one Traefik per org that routes `<name>.<edge.domain>` (and
@@ -1609,7 +1664,12 @@ user, and the CLI does that for you:
     the 10 minutes, and an expired code is a click away from a new one.
     From a computer with SSH access to it, the page gives the one-liner
     (`ssh <host> '<cli> web approve <code>'`) and, when the host is a name,
-    an Open Terminal (`ssh://`) link;
+    an Open Terminal (`ssh://`) link. On Windows, which has no `ssh://`
+    app by default, there is no link: the one-liner is the step, with
+    "Open Windows Terminal or PowerShell, paste this, and press Enter."
+    Elsewhere, if the page still has focus 2 seconds after a click on Open
+    Terminal (no app took the link), it says "Nothing opened? Copy the
+    command below and paste it into your terminal app.";
   - **Other ways**, collapsed: the one-time link with
     `web login --origin`.
 
@@ -2261,6 +2321,64 @@ start` and `<cli> doctor` say why den-pty is unavailable.
   limit) is refused with that reason; point `<PREFIX>_HOME` somewhere
   shorter.
 
+## The server agent
+
+Every Den has its own agent, named after the distribution ("Acme agent"),
+for anything about the server itself: set it up, add a repo, fix a failing
+service, change a setting, explain what's running. It belongs to no
+workspace. It is a normal Den agent underneath (its record, its session,
+Resume after a restart, rotation and Den's hooks), with Den's persona
+`server` and the plain-writing rule, in a reserved scope, `den-server`: no
+workspace may take that name.
+
+- **It acts only through Den's MCP.** Its MCP server
+  (`<cli> mcp --workspace den-server --actor agent:server`) serves the whole
+  Den, not one workspace, so it may use the onboarding tools a workspace's
+  agent is refused. Every write (`workspace_create`, `repo_add`,
+  `service_try`) is [held for the person](#onboarding-writes-held-for-the-person):
+  until they allow one in the browser, it only reads. It starts in an empty
+  folder of its own (`<state_dir>/server-agent`), with no checkout to edit,
+  and its runtime asks before every command (`permission_mode: ask`).
+  Den's own MCP tools are the exception, for this agent only: its settings
+  file allows `mcp__<server>` (the `--mcp-config` server), so reads just
+  run and each write asks once, in the browser. The org's immediate actions
+  (`mcp.actions`) stay in `permissions.ask`. On a fresh Den the page says
+  above its terminal: "Claude asks whether to trust this folder. Choose
+  Yes." Den doesn't answer that prompt for the person.
+- **Where it lives.** On a fresh Den (no repo in any workspace yet), the
+  first page, `/`, is that agent in a terminal framed as the page, with
+  Open in Agents as the way out. After setup it is one click away in the
+  rail ("Acme agent", `/server-agent`), and ⌘K has "Ask Acme". Agents lists
+  it first, under "Server", not under a workspace.
+- **Its onboarding:** `onboard_status`, then "Let's set up Acme. Where are
+  your repos? I'll look in <the folder above the Den's> unless you name
+  another folder." in its first turn, `repos_detect` and suggested workspaces, `workspace_create`,
+  `manifest_draft` and `repo_add` for each repo, `service_try` (and
+  `doctor` when it fails), then "Here's what's running, and three things to
+  try next."
+- **What runs it.** A catalog runtime that is installed and carries Den's
+  tools: the person's choice (`agents.server_runtime` in
+  `config/local/user.yml`, set from the page's Runs on picker), else the
+  first one found. Den can tell a runtime is installed, not that it is
+  logged in: one that isn't asks in its own terminal, on the page. On a
+  fresh Den with such a runtime it starts by itself, once per page load;
+  after setup it starts only from its Start button. With no runtime, the
+  page shows how to install one and the manual path for this Den, from its
+  folder: `cd <dir>`, `./bin/<cli> repo add <path>`, `./bin/<cli> up`.
+- **Its model.** The page's Model picker, beside Runs on, offers the
+  runtime's own models (`agents.server_model`). With none saved, Sonnet
+  when the runtime has it, else the runtime's default. A new model starts
+  a fresh conversation at the next start.
+- **Only a person starts it or picks its runtime or model.** An agent's token, or a
+  request claiming to be an agent, is refused (403).
+
+| Route                            | What it does                                                                |
+| -------------------------------- | --------------------------------------------------------------------------- |
+| `GET /api/server-agent`          | Its name, runtime (or none), state, session, fresh, manual                  |
+| `POST /api/server-agent/start`   | `{ runtime? }`: start it, or resume or relaunch it                          |
+| `POST /api/server-agent/runtime` | `{ runtime: id \| null }`: the person's choice of runtime                   |
+| `POST /api/server-agent/model`   | `{ model: id \| null }`: the person's choice of model, one of the runtime's |
+
 ## Agents
 
 An agent is a **persona** (who) in a **workspace** (where), run by a

package/docs/reference.md

@@ -7,7 +7,7 @@ The technical reference that used to be the README. It will be split into separa
 1. **Create** a distribution named after your product:
 
    ```sh
-   npx @monster-orange/den create acme      # → ./acme
+   npx @monster-orange/den@latest create acme      # → ./acme
    cd acme && npm install
    ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.18",
+  "version": "0.4.20",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -90,6 +90,7 @@
     "@types/semver": "7.7.1",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
+    "axe-core": "4.10.3",
     "eslint": "^8.56.0",
     "husky": "^8.0.3",
     "jest": "^29.7.0",