@monster-orange/den 0.4.17 → 0.4.19

package/CHANGELOG.md

@@ -4,6 +4,183 @@ 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.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
+
+- **A pinned service opens a quick panel, not a page jump.** A click on a
+  pinned service's name in the rail (or Enter on its row, or its dot in
+  the collapsed rail) opens a panel beside the row, without leaving the
+  page. It has the service's workspace, state and URL; Visit ↗, Start or
+  Stop, Restart and Logs, which call what the Services page calls; the
+  repo's last test run with Run tests; the agents working in the repo,
+  each with Open, and Start agent here; and Open in Services, Open in
+  Graph and Unpin. It stays current while open. Esc or a click outside
+  closes it and focus goes back to the row. Under 640 px it is a bottom
+  sheet. ⌘-click or a middle click still opens Services in a new tab. The
+  Services card's name and the Graph card's new ⋯ open the same panel.
+- **Visit ↗ on every pinned row.** Always shown, it opens the service's
+  URL in a new tab. It is greyed out ("Not running") while the service is
+  down, and absent when the service has no URL. The hover × is gone:
+  Unpin is in the panel, and Delete on the row still unpins.
+- **Start agent here.** The Start dialog has a Folder field (optional):
+  the agent runs in that folder of the workspace's, or in a repo's
+  folder. The route takes it as `folder`, and refuses a folder outside
+  the workspace (403). The panel's Start agent here fills the workspace
+  and the repo's folder.
+- **Open in Graph focuses the service.** `/graph#focus=<repo>` or
+  `#focus=<repo>/<service>` opens the Graph on that card.
+
+### Fixed
+
+- **The panel's Logs reads the service's log.** It asks where the Logs
+  page asks (taillog for a local service), so a service with no `logs:`
+  block no longer says "Connection closed". The Services page's Logs
+  uses the same rule.
+- **"starting…" follows health.** After Start or Restart, the panel
+  leaves "starting…" once health says up, once it says down after a
+  moment, or after two minutes. Restart works again then, even when the
+  service's `up` never exits (a dev server).
+- **A pinned row's Visit ↗ greys out with the panel.** It reads the
+  panel's live state, so it greys out on the same health update, also
+  for a service outside the top bar's View.
+- **Open in Graph keeps its target.** The Graph page keeps the URL's
+  `#focus=` when it picks a workspace, so the card is focused and in view.
+
 ## [0.4.17] - 2026-11-08
 
 ### Fixed

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.17/hero-dark.png">
-  <img src="docs/images/0.4.17/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.19/hero-dark.png">
+  <img src="docs/images/0.4.19/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.17/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.19/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.17/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.17/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.17/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.17/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.19/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.19/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.19/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.19/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
@@ -368,6 +380,39 @@ The ☆ star on Workspaces rows, Services and Graph cards marks a
 favourite. It is one list, saved in `shell.pins`, so a star set on one
 page shows on all of them.
 
+### The service panel
+
+A pinned service in the rail has **↗** at the end of its row, always
+shown: it opens the service's URL in a new tab ("Visit <service> (opens a
+new tab)", the URL as its tooltip). It is greyed out, saying "Not
+running", while the service is down, and absent when the service has no
+URL.
+
+A click on the service's name (or Enter on its row, or its dot when the
+rail is collapsed) opens its **panel** beside the row, without leaving
+the page. ⌘-click, Ctrl-click or a middle click still opens Services in a
+new tab. Esc or a click outside closes it, and focus goes back to the
+row. Under 640 px wide it is a sheet at the bottom of the screen. The
+Services card's name and the Graph card's **⋯** open the same panel.
+
+Top to bottom, it has:
+
+- the name, workspace, health dot, state ("up 2h", "down: HTTP 502",
+  "starting…") and URL;
+- **Visit ↗**, then **Start** or **Stop**, **Restart** and **Logs**. These
+  call what the Services page calls (`/api/service/exec` with `up`,
+  `down` or `restart`, and `/api/service/logs`), each in a tab of the runs
+  dock. Logs opens the dock on that service;
+- **Last test run** (the server's run history, `GET /api/runs/last`) and
+  **Run tests**, which runs the repo's suites (`/api/run?pillar=suites`);
+- **Agents**: the agents working in the repo, each with **Open**, and
+  **+ Start agent here**, which opens the Start dialog with the workspace
+  and the repo's folder filled in;
+- **Open in Services**, **Open in Graph** and **Unpin** (or **Pin**).
+
+It stays current while it is open, from the same feeds the pages use. Delete
+on a pinned row still unpins it.
+
 ## Health checks
 
 A service declares its health per environment under `health`, in one of
@@ -1576,7 +1621,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`.
 
@@ -2228,6 +2278,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
@@ -2398,6 +2506,11 @@ started. The workspace header counts them ("2 agents").
   `agents.runtimes.<id>.bin` to its path in <your user.yml>, or run
   `<cli> agents doctor`" (see [Runtimes](#runtimes)). Nothing fails only
   after Start.
+- **Folder** (optional) is where the agent runs: a folder inside the
+  workspace's own, or a repo's folder of the workspace (relative to the
+  workspace's folder, or absolute). Empty, it runs in the workspace's
+  folder. A folder outside the workspace is refused (403). The service
+  panel's **Start agent here** fills it with the repo's folder.
 - The page and the CLI call the same operations and read the same agent
   records, so an agent started in one is listed in the other. A workspace
   lists its own agents only.
@@ -2412,7 +2525,7 @@ started. The workspace header counts them ("2 agents").
 
 The routes: `GET /api/workspaces/<ws>/agents`, `POST
 /api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, version?,
-permission?, allow?, instruction?, id? }`, see
+permission?, allow?, instruction?, id?, folder? }`, see
 [The Start dialog](#the-start-dialog)), `POST
 /api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, `POST
 /api/workspaces/<ws>/sessions` (a plain session), `GET /api/personas`

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.17",
+  "version": "0.4.19",
   "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",