@monster-orange/den 0.4.18 → 0.4.19

package/CHANGELOG.md

@@ -4,6 +4,140 @@ 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

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.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.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.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.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.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
@@ -1609,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`.
 
@@ -2261,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

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.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",

package/skills/install-den/SKILL.md

@@ -1,25 +1,28 @@
 ---
 name: install-den
-description: Install and set up Den, Monster Orange's local dev orchestrator, for a developer in five minutes. Use when the person says "set up Den", "install Den", "get me started with Den", or pastes a link to this file.
+description: Install Den, Monster Orange's local dev orchestrator, and hand the person over to Den's own agent, in five minutes. Use when the person says "set up Den", "install Den", "get me started with Den", or pastes a link to this file.
 ---
 
 # Install Den
 
-You are setting up Den on this person's machine. Den runs their repos locally, shows them in a browser, and gives you
-(the agent) an MCP server to work with. Aim to be done in five minutes. Keep your messages short and plain.
+You are installing Den on this person's machine. Den runs their repos locally and shows them in a browser. Your job
+is short: install it, name it, start it, and hand over the link. **Den's own agent takes it from there.** It adds
+their repos and starts their services, with the person allowing each change in the browser.
+
+You do three things only. You don't add repos or create workspaces: those are Den's own agent's job. Keep your
+messages short and plain.
 
 ## Hard rules
 
 - **Never ask for a token, password or secret in chat.** If a step needs one, tell the person which command to run
   themselves.
-- **Never edit the person's repos.** Den's files go in the Den folder only. Read the repo; don't write to it.
-- **Send nothing off this machine.** No uploads, no telemetry, no pasting their code anywhere. The only downloads are
-  Den from npm and a repo the person gave you as a git URL.
-- **Sudo is the person's job.** Never run `sudo` yourself. When a Den step needs it, Den asks for the password in its
-  own prompt (in the terminal or the browser), and the person types it there.
+- **Never edit the person's repos.** Don't touch them at all.
+- **Send nothing off this machine.** No uploads, no telemetry. The only download is Den from npm.
+- **Sudo is the person's job.** Never run `sudo` yourself.
+- **Never open the setup link yourself**, and never fetch it. It signs in one browser, once. Give it to the person.
 - Every step below is safe to re-run. If you are unsure whether a step ran, run it again.
 
-## 1. Check the prerequisites
+## 1. Install Den, after checking Node and git
 
 Run these and read the results. Don't install anything without saying so first.
 
@@ -27,88 +30,45 @@ Run these and read the results. Don't install anything without saying so first.
    (for example `brew install node`, or `nvm install 22`).
 2. `npm --version`: needs 9 or later. It comes with Node.
 3. `git --version`: needs to be there.
-4. `docker info`: only matters if the repo runs in containers (it has a `docker-compose.yml` or `compose.yaml`).
-   If Docker is needed and not running, ask them to start it.
 
 If anything is missing, stop here, tell them what and how to fix it, and wait.
 
-## 2. Ask at most three questions
-
-Ask them together, each with a default, so the person can just say "yes":
+## 2. Pick the folder and the name
 
-1. **Where should your Den live?** Default: `~/den`. It must be a new or empty folder.
-2. **Which repo should we start with?** Default: the folder you're in now. A local path or a git URL.
-3. **What should we call your Den?** Default: `den`. Lowercase letters, numbers and dashes. This also becomes the
-   command name, so `acme` gives you `./bin/acme`.
+Ask both together, each with a default, so the person can just say "yes":
 
-Below, `<dir>` is the Den folder, `<repo>` the repo path, and `<name>` the name.
+1. **What should we call your Den?** Default: `den`. Lowercase letters, numbers and dashes. This also becomes its
+   command, so `acme` gives you `./bin/acme`.
+2. **Where should it live?** Default: `~/<name>`. It must be a new or empty folder.
 
-## 3. Create the Den
+Below, `<name>` is the name and `<dir>` the folder.
 
 Every Den command below takes `--json`. It then prints one JSON object on stdout and its log on stderr. Read `ok`
 first. When `ok` is false, the object says why (`error`) and either a command to run (`fix`) or a question for the
-person (`ask`, sometimes with `choices`).
+person (`ask`).
 
-1. `npx @monster-orange/den create <name> <dir> --yes --json`. It answers `{ok, dir, cli, existed, port, next}`. If
-   the folder already holds this Den, it answers `ok` with `existed: true` and changes nothing. `port` is the browser
-   UI's port. When another Den already uses the usual one on this machine, Den picks the next free port and says so
-   (`portPicked`). Remember the port for the hand-back.
+1. `npx @monster-orange/den@latest create <name> <dir> --yes --json`. It answers `{ok, dir, cli, existed, port}`. If the
+   folder already holds this Den, it answers `ok` with `existed: true` and changes nothing. When another Den already
+   uses the usual port, it picks the next free one and says so (`portPicked`).
 2. `cd <dir> && npm install`
 3. From here on, the Den command is `./bin/<name>`, run from `<dir>`.
 
-## 4. Add the repo without changing it
-
-1. `./bin/<name> repo add <repo> --json`. `<repo>` can be a path or a git URL. Den clones a URL into its own folder.
-   - If the repo has its own `.<name>.yml`, Den uses it.
-   - If it doesn't, Den works out how the repo starts and writes a side-car manifest into `<dir>/manifests/`. It never
-     writes into the repo. It looks for a Makefile `up` target, then a compose file, then the `dev` or `start` script
-     in `package.json`. `--sidecar` asks for this explicitly, and fails if the repo has its own manifest.
-   - If you can see which port the app listens on, add `--health http://localhost:<port>/`. Den then checks that it
-     answers.
-2. If the answer has `ask`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person **one**
-   question: the `ask` text, with any `choices` numbered (there may be none). Then re-run with their answer:
-   `./bin/<name> repo add <repo> --run "<their command>" --json`.
-3. The answer names the repo (`repo`), the workspace it joined (`workspace`) and where its manifest is (`manifest`).
-   A workspace is Den's name for a set of repos that run together. The first one is called `default`.
-
-## 5. Start it and check it
-
-1. `./bin/<name> up <repo> --json`. `<repo>` is the `repo` value from step 4. Each service comes back with a
-   `result` (`started` or `already-running`) and a `health` (`ok`, or `unknown` when it has no health check).
-2. `./bin/<name> web up --no-open --json`. This starts the browser UI, and answers `{ok, url, port}`. The MCP server
-   reads through it.
-3. `./bin/<name> doctor --json`. Each check comes back as `ok`, `warn` or `fail`. The checks are Node, git, Docker
-   (only if a repo needs it), the web server (with its `url` and `port`) and Den's MCP. Fix every `fail` before you hand back.
-
-## 6. Connect yourself to Den's MCP
-
-1. `./bin/<name> mcp connect --runtime <you> --json`. `<you>` is `claude`, `codex`, `gemini` or `grok`. For any other
-   agent, `./bin/<name> mcp config` prints the JSON to add by hand.
-2. `./bin/<name> mcp clients` shows whether you are connected.
-3. If the answer has `restart: true`, you load the new MCP server only when you start again. Tell the person to
-   restart you once.
-
-## 7. Hand back
-
-Tell the person, in a few short sentences. Explain every name you use the first time (for example, "a workspace is a
-set of repos that run together").
-
-- **Open:** the `url` from `web up` or from the doctor's `web` check, for example `http://localhost:<port>`. Never
-  assume a port: use the one Den gave you.
-- **What's running:** each service from `up`, and whether it's healthy.
-- **Your Den:** where it lives (`<dir>`) and its command (`./bin/<name>`).
-- **Decisions, if any:** as numbered yes/no questions, for example "1. Restart me now so I can use Den's tools?"
-- **Three next things we can do together:**
-  1. Add another repo.
-  2. Look at a service's logs, or run its tests.
-  3. Start an agent session on this repo from the browser.
+## 3. Start the web server and hand over the link
+
+1. `./bin/<name> web up --no-open --json`. It answers `{ok, url, port}`.
+2. `./bin/<name> web claim-link --json`. It answers `{url, expiresAt}`: a one-time setup link that signs the
+   person's browser in, so they can allow Den's agent's changes. It lasts 30 minutes and works once.
+3. Hand over, in a few short sentences:
+   - **Open** the `url` from `claim-link`, in your browser on this machine. "Den's own agent takes it from there."
+   - **Your Den** lives in `<dir>`, and its command is `./bin/<name>`.
+   - If the link has expired, run `./bin/<name> web claim-link` yourself for a new one.
+
+That's all. Don't go on to add repos.
 
 ## When something fails
 
 1. Read the JSON. If it has `fix`, run that command, then re-run the step that failed.
-2. If it has `ask`, the person has to decide or act (sudo, a password, starting Docker, signing in). Ask them the
-   question, show any `choices` numbered, and wait.
+2. If it has `ask`, the person has to decide or act. Ask them the question, show any `choices` numbered, and wait.
 3. If there is neither, ask the person **one** clear question, with your best guess as the default.
-4. Never work around a failure by editing their repo, turning off a check, or skipping a step without saying so.
-5. If you're stuck after two tries, stop. Tell them what you ran, what it said, and where Den writes its logs
+4. If you're stuck after two tries, stop. Tell them what you ran, what it said, and where Den writes its logs
    (`~/.<name>/`), so they can get help.