@monster-orange/den 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,146 @@ 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.7] - 2026-11-07
+
+Agents read slices, wait in the background and hand back plainly (den#5,
+the default-pack guardrails issue). Every persona in Den's default pack
+gets Den's shared instructions and, on Claude Code, Den's hooks, with no
+setup. `doctor` warns about polling loops it sees in the local dev metrics.
+
+### Added
+
+- **The Stop hook reads every last message.** With a `## Hand-back`
+  heading it checks the whole hand-back, as before. Any other last message
+  gets the plain-writing check: every ID explained. It still never blocks
+  twice in a row.
+- **`URL: none` in a hand-back.** Work with no page (a CLI change, a
+  refused request) says `URL: none`, with a reason if it likes. An empty
+  or missing URL still fails.
+
+- **`down --json` and `web down --json`.** The clean-up steps answer in
+  JSON like every other onboarding step: `{ ok, workspace, services }` and
+  `{ ok, url, port, running, stopped }`. Both are safe to re-run.
+
+- **Hooks for default-pack agents.** A Claude Code agent from Den's default
+  pack runs with Den's own hooks, in its own `--settings` file (never your
+  `~/.claude`). A `PreToolUse` hook on Bash and Read blocks reading all of
+  a log or a large file into the conversation (`cat`, `less`, `tail` from
+  a line such as `tail +1`, a Read with no limit; a plain `tail` passes) and says to read a slice or use a
+  subagent. It blocks a foreground `sleep`, alone or in an `until`/`while`/
+  `for` loop, and says to run in the background or use a wait primitive.
+  It blocks nothing else.
+- **Shared persona instructions.** Every default-pack persona's role prompt
+  ends with Den's `guardrails/instructions.md`: write plainly, in short
+  sentences; say what every issue or ID is; ask each decision as a numbered
+  yes/no question; no caveat sections; and the hand-back template (URL,
+  machine, branch, what changed, what to click, decisions).
+- **The hand-back check.** `<cli> agents handback-check <file|->` rejects a
+  hand-back with a missing part, an unexplained ID, or a decision that is
+  not a numbered yes/no question, and says what to fix. A `Stop` hook runs
+  the same check on a turn that ends with a `Hand-back` heading, and sends
+  Claude back to fix it once.
+- **doctor warns about polling loops.** It reads the end of the local
+  `.dev-metrics/events.jsonl` (at most 8 MB) and warns when one command,
+  run from one place, ran more than 600 times in an hour:
+  `looks like a polling loop: status in services/api, 1200 calls in an hour (…)`.
+  It is local and sends nothing.
+- **Each dev-metrics line records `cwd`**, relative to the distribution root
+  (`.` at the root, `outside` elsewhere), never an absolute or home path.
+  Like every field, it is sent only when you opt in.
+
+### Metrics (before → after)
+
+- Polling loops a week: 18,600 → under 100 expected, since the hook blocks
+  them. The "after" is counted on the candidate's first week.
+- Incomplete hand-backs: not measured → 0 for default-pack agents (the Stop
+  hook sends them back). The candidate's first run sets the baseline.
+- Hand-backs with an unexplained ID: no baseline → 0 for default-pack
+  agents. The candidate's first run sets the baseline.
+- doctor on a replay of a three-day polling burst: no warning → it warns.
+
+### Migrations
+
+- None needed. To turn the guardrails off for Den's pack, set
+  `agents.default_pack: { hooks: false, instructions: false }`. To turn
+  them on for your own pack, write its `persona_packs` entry as
+  `{ path: <dir>, hooks: true, instructions: true }`. A persona's
+  `den_hooks` / `den_instructions` front matter wins over its pack's.
+
+## [0.4.6] - 2026-11-07
+
+Den in five minutes, set up by your own agent (ON-2, with ON-4's dry run).
+A developer pastes one line into their agent, and every command the agent
+runs answers in JSON, never prompts, and is safe to re-run.
+
+### Added
+
+- **Set up by your agent.** `den --help` and the README print the line to
+  paste: "Set up Den for me by following
+  https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md". The install-den skill it points
+  at ships in the package as `skills/install-den/SKILL.md`: plain Markdown
+  with Claude skill front matter, at most three questions, no secrets in
+  chat, no edits to the person's repos, nothing sent off the machine.
+- **`<cli> repo add <path|git-url>`** adds a repo with no prompts and never
+  writes into it. A git URL is cloned where Den keeps managed clones. A repo
+  with no manifest (or `--sidecar`) gets a side-car manifest in the
+  distribution's `manifests/`, detected from its Makefile `up` target, its
+  compose file or its `package.json` `dev`/`start` scripts (and `test`), and
+  validated before it is written. When detection can't decide, nothing is
+  written and the answer asks, with the choices; a re-run passes
+  `--run "<cmd>"`. `--health <url>` adds a health check. The workspace is
+  `-w`, else the focused one, else a new `default`. The same repo again
+  answers `existed: true`.
+- **`--json` for setup.** `create --yes --json` (a directory that already
+  holds the distribution is `existed: true`), `up --json` (each service's
+  result and health), `doctor --json` and `mcp connect --json`. Stdout is
+  one JSON object, the log goes to stderr, and a failure carries a `fix`
+  the agent can run or an `ask` for the person.
+- **`doctor --json`'s onboarding checks:** Node 22.13 or later, git, Docker
+  (only when a registered repo needs it), the web server and its URL, and
+  Den's MCP through it, each `ok`, `warn` or `fail`. The human `doctor` is
+  unchanged.
+- **`mcp connect --runtime claude|codex|gemini|grok`** names the agent by
+  its runtime. Grok CLI is a new client: Den writes its own
+  `[mcp_servers.<cli>]` table in `~/.grok/config.toml` (or the project's
+  `.grok/config.toml`), as xAI documents. A config file that already has the
+  entry is no longer rewritten.
+- **`create` picks a free web port.** When 7777 is in use on this machine,
+  `create` picks the next free port above it (never 7778, 7791 or 7799),
+  writes it to the new distribution's `config/local/user.yml` and says so,
+  in JSON as `port` and `portPicked`. `--port <n>` sets it outright. The
+  check connects and binds only; it sends nothing to the port's holder.
+  `DEN_WEB_PORT_START` moves the starting port.
+- **`web up --json`** answers `{ ok, url, port }` once the server answers,
+  and `doctor --json`'s web check carries the `port`.
+
+### Changed
+
+- `create` into a directory that already holds the same distribution says
+  so and exits 0, instead of refusing a non-empty directory.
+
+### Fixed
+
+- **An opted-in CLI sends its metrics.** The CLI records each run as it
+  exits, and a send started then never ran. With `metrics.share: true`, the
+  CLI now hands the event to a small detached sender that gives up after 2
+  seconds. The web server sends as before. Not opted in, nothing is sent.
+- **Linked devices read plainly.** A device approved with a code says
+  "approved with a code", not "signed in with approved with a code".
+- **An agent's refusal names the admin password.** It said "the lock",
+  which 0.4.4 removed.
+
+### Metric
+
+- Time from the paste to "service running, MCP connected" (R11): not
+  measured before; ON-4's dry run (create, repo add, up, web up, doctor,
+  mcp connect, each run twice) now records it, about 16 s locally. Target:
+  5 minutes or less.
+
+### Migrations
+
+- None.
+
 ## [0.4.5] - 2026-11-07
 
 Sign in with GitHub as the owner, from your other devices; approve a

package/README.md

@@ -10,10 +10,24 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.5/hero-dark.png">
-  <img src="docs/images/0.4.5/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.7/hero-dark.png">
+  <img src="docs/images/0.4.7/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
+
+Paste this line into your coding agent (Claude Code, Codex, Gemini, Grok, …):
+
+```text
+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).
+
 ## What Den is
 
 Den is an opinionated local development framework for solo developers and small teams. You point it at the
@@ -24,7 +38,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.5/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.7/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
@@ -54,10 +68,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.5/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.5/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.5/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.5/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.7/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.7/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.7/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.7/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

package/docs/distributions.md

@@ -32,8 +32,22 @@ From a Den checkout, `./bin/den create acme ../acme` does the same.
 | `--title <title>`       | `<Name>` Title Case | Brand name shown to people            |
 | `--cli <cli>`           | `<name>`            | The command people type               |
 | `--env-prefix <PREFIX>` | `<NAME>`            | Env-var prefix (`ACME` → `ACME_HOME`) |
+| `--yes`, `-y`           |                     | Never prompt (create never does)      |
+| `--json`                |                     | One JSON object on stdout             |
+| `--port <n>`            | `7777`, else free   | The web UI's port                     |
 
 `create` refuses a directory that is not empty and never overwrites a file.
+A directory that already holds this distribution (its `den.yml` names the
+same product and command) is not an error: `create` says so and writes
+nothing, so it is safe to re-run.
+
+The web UI's port is 7777 unless that port is in use on this machine (another
+Den already running, say). Then `create` picks the next free port above it,
+never a port Den itself reserves (7778, 7791, 7799), writes it to the new
+distribution's `config/local/user.yml` as `web: { port: N }`, and says so.
+`--port <n>` sets it outright. The check only connects and binds; it sends
+nothing to whatever holds the port. `DEN_WEB_PORT_START` moves the starting
+port (tests use it so none touches 7777).
 [`examples/distribution/`](../examples/distribution) is exactly the output of
 `den create acme`; a unit test regenerates it, so the two never drift
 (`npm run example:regen` after changing the scaffolder).
@@ -48,6 +62,91 @@ npm install
 make help
 ```
 
+## Set up by your agent
+
+A developer pastes one line into their agent:
+
+```text
+Set up Den for me by following https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md
+```
+
+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
+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> 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
+
+`<cli> repo add <path|git-url> [--sidecar] [-w <workspace>] [--name <repo>]
+[--run "<cmd>"] [--down "<cmd>"] [--health <url>] [--branch <branch>]
+[--json]` adds a repo to a workspace without writing into the repo.
+
+- A path is the person's own checkout, added dev-managed at that path. A git
+  URL is cloned where Den keeps its managed clones
+  (`.<name>-services/<repo>/<branch>`, the remote's default branch unless
+  `--branch` says otherwise) and added managed. A clone that is already
+  there is used as it is.
+- A repo with its own manifest is used as it is. One without, or with
+  `--sidecar`, gets a side-car: a held manifest at
+  `manifests/<repo>.<name>.yml` ([below](#overriding-a-manifest)), keyed by
+  the repo's `origin` name or folder name. It is checked by the manifest
+  validator before it is written, and an existing one is never overwritten.
+  `--sidecar` on a repo with its own manifest is an error: Den always uses
+  the repo's own file (change it with an override instead).
+- The side-car's commands are detected from the repo's files, in this order:
+  a Makefile with an `up` target (`make up`, plus `down`, `setup` and
+  `restart` when present); otherwise a compose file
+  (`docker compose -f <file> up -d` and `down`) or `package.json`'s `dev`,
+  else `start`, script. One candidate decides. Two, or none, is a question:
+  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.
+- 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
+  under the same name is an error that offers `relocate` or `--name`.
+
+### up, doctor and mcp connect
+
+- `down --json` and `web down --json` are the clean-up steps. Each is safe
+  to re-run: `web down` answers `stopped: false` when the server wasn't
+  running, and `ok` is true once nothing answers on its port.
+
+- `up --json` runs `up` as usual, then reports each service it touched:
+  `result` is `started`, `already-running`, `failed` or `skipped`, and
+  `health` is the service's health after it started (a service with a
+  health check is waited on, up to 30 seconds). A healthy service is
+  `already-running` on a re-run.
+- `doctor --json` lists the onboarding checks first: `node` (22.13 or
+  later), `git`, `docker` (only when a registered repo has a compose file or
+  block, or a docker command), `web` (the web server answers at `url`) and
+  `mcp` (`<cli> mcp --call workspaces` gets an answer through it). Then one
+  `strategy:<kind>` check per row of the [human doctor](#doctor). `ok` is
+  false, and the exit code 1, when any check is `fail`.
+- `mcp connect --runtime <runtime>` names the agent by its runtime: `claude`
+  (the `claude-code` client), `codex`, `gemini` or `grok`. Grok CLI keeps its
+  MCP servers in `~/.grok/config.toml` (or `.grok/config.toml` with
+  `--project`), one `[mcp_servers.<name>]` table each
+  ([xAI's docs](https://docs.x.ai/build/features/mcp-servers)); Den writes
+  only its own table. A config file that already has the entry is left as
+  it is (`changed: false`).
+
 ## Layout
 
 | Path                      | What                                                                                             |
@@ -587,6 +686,22 @@ Acme doctor: strategies
 `session-backend` is never a doctor failure: nothing needs a session until
 one is started (see Sessions).
 
+`<cli> doctor --json` adds the onboarding checks (Node, git, Docker, the web
+server, Den's MCP) and answers with one JSON object: see
+[Set up by your agent](#up-doctor-and-mcp-connect).
+
+doctor also reads the end of the local `.dev-metrics/events.jsonl` (at
+most 8 MB of it, however big the file) and warns when one command, run
+from one place, ran more than 600 times in an hour. That is almost always
+an agent polling. It is a warning, never a failure, and nothing is sent
+(see [Dev metrics](#dev-metrics-local-unless-you-opt-in)):
+
+```
+Acme doctor: dev-metrics (local, never sent)
+
+  ⚠ looks like a polling loop: status in services/api, 1200 calls in an hour (2026-11-04T09:00:00Z–2026-11-04T09:59:57Z)
+```
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -1915,6 +2030,7 @@ server scoped to its workspace.
 <cli> agents resume <id> [-w <ws>]
 <cli> agents personas [--json]
 <cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
+<cli> agents handback-check <file|->    # is a hand-back complete and plain (see Guardrails)
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -2118,6 +2234,8 @@ standing: true # starts with its workspace (later slices)
 context: [docs/specs, the design system] # what to read first
 runtime: generic # default den-claude
 permission_mode: plan # den-claude only; default `default`
+den_hooks: false # Den's guardrail hooks for this persona (see Guardrails)
+den_instructions: false # Den's shared instructions for this persona
 argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
 ---
 
@@ -2139,6 +2257,104 @@ used without converting them. Files without front matter (a README) are
 skipped; two files with one id in a pack, or a pack that isn't a directory,
 are errors naming the file or the key.
 
+### Guardrails: hooks, shared instructions, hand-backs
+
+Every persona in Den's default pack gets two things with no setup: Den's
+**shared persona instructions** and, on den-claude, Den's **hooks**. Both
+are Den's own files, in `src/shared/agents/guardrails/` of the package.
+
+**Shared instructions** (`instructions.md`) are appended to the role prompt
+(den-claude's `--append-system-prompt`; any runtime that takes the role
+prompt gets them). They say:
+
+- write to people plainly, in short sentences;
+- never name an issue or ID without saying what it is;
+- ask each decision as a numbered yes/no question;
+- no caveat sections, and nothing the person doesn't need in order to act;
+- read a slice of a log, or hand it to a subagent; don't poll with `sleep`;
+- end a hand-back with the template below.
+
+**Hooks** (`hooks.json`, a Claude Code settings fragment) go in the agent's
+own settings file, `--settings <stateDir>/agent-files/<id>/settings.json`.
+Den never writes your `~/.claude`; your own hooks still run.
+
+- `PreToolUse` on `Bash|Read` (`pretooluse.mjs`, plain Node, no imports)
+  blocks, with a reason Claude sees (exit 2):
+  - reading all of a log or a large file into the conversation: a `Read`
+    with no `limit`, or `cat`, `less`, or `tail` from a line (`tail +1`,
+    `tail -n +1`), whose output reaches the conversation. A log is `*.log` or `*.log.<N>`, a `.jsonl` under
+    `.dev-metrics/`, or a `.jsonl` under `.claude/projects/` (a transcript).
+    Large is over 256 KB. `cat x.log | grep …`, `cat x.log > y`, a plain
+    `tail x.log` (10 lines) and `tail -n 100 x.log` pass. The reason says to read a slice or hand the
+    file to a subagent.
+  - `sleep` in the foreground, alone or in an `until …; do sleep …; done`,
+    `while` or `for` loop. A Bash call with `run_in_background`, and
+    `sleep … &`, pass. The reason says to run in the background or use a
+    wait primitive. Recent Claude Code versions have their own sleep guard,
+    which answers first (and also stops `sleep … &`). The sleep is blocked
+    either way; Den's hook covers runtimes and versions without that guard.
+  - Nothing else. Quoted text, heredoc bodies and other tools always pass,
+    and a hook that can't read its input lets the call through.
+- `Stop` (`stop-hook.ts`) checks a turn's last message, which is what the
+  person reads. With a `Hand-back` heading it gets the whole hand-back
+  check; any other message gets the plain-writing part only (every ID
+  explained). If the check fails, Claude is told what to fix and keeps
+  going (Claude Code's `decision: "block"`). It never blocks twice in a
+  row (`stop_hook_active`), so it can't loop. Den adds no `SubagentStop` hook: a subagent reports to its parent
+  agent, not to a person.
+
+**The hand-back template**, which the check enforces:
+
+```markdown
+## Hand-back
+
+- URL: <the full link the person opens, with https://>
+- Machine: <the machine it runs on>
+- Branch: <the branch>
+- What changed: <what is different now>
+- What to click: <the steps to see it working>
+- Decisions:
+  1. <a question the person answers yes or no>?
+```
+
+`<cli> agents handback-check <file|-> [--json]` runs the same check on a
+file or stdin: exit 0 when the hand-back passes, 1 with each problem. It
+rejects a hand-back when:
+
+- a part is missing or empty. A part is a line starting with its label and
+  a colon (bold is fine), or a heading that is its label. URL must hold a
+  link (`://`), or say `none` for work with no page (`URL: none — a CLI
+change` is fine). `Decisions: none` is allowed.
+- an ID is bare. An ID is `#<digits>`, or 1 to 4 capitals, an optional `-`,
+  digits and an optional `.<digits>` (`R12`, `AG-14`, `KB-4.1`). Links,
+  `inline code`, code blocks, and the URL and Branch parts are not checked.
+  An ID is explained (glossed) when
+  1. a parenthetical of two or more words follows it: `#5 (the hooks issue)`;
+  2. a colon or a spaced dash and two or more words follow it:
+     `R12: plain writing`;
+  3. it sits in a parenthetical of IDs only, right after a word:
+     `plain writing (R12)`, `the issues (#5, #6)`;
+  4. or the same ID was explained earlier in the text.
+- a decision isn't a numbered yes/no question: each item must be numbered
+  (`1.` or `1)`), end in `?`, not start with what, which, how, why, when,
+  where or who, and not offer a choice (`or`).
+
+**Turning them off or on.** They are on for Den's default pack and off for
+your own packs. A pack's setting applies to each of its personas; a
+persona's front matter (`den_hooks`, `den_instructions`) wins over it:
+
+```yaml
+agents:
+  default_pack: { hooks: false } # Den's pack: no hooks, instructions kept
+  persona_packs:
+    - personas # your pack: neither
+    - { path: more-personas, hooks: true, instructions: true } # both
+```
+
+A persona of yours that replaces a default one (same id) takes your
+pack's setting, not Den's pack's. Anything but `true` or `false`, or an
+unknown key, is an error naming the key.
+
 ### Runtimes
 
 `<cli> doctor` lists the runtime kind. Den knows the runtimes in its
@@ -2321,6 +2537,11 @@ metrics:
   share: true
 ```
 
+Each line also records `cwd`: where the command ran, relative to the
+distribution root (`.` for the root), or `outside` for anywhere else. It is
+never an absolute or home path. [`<cli> doctor`](#doctor) uses it to warn
+about polling loops.
+
 Only the boolean `true` counts. With it, and a Sentry DSN in
 `DEV_METRICS_SENTRY_DSN` (or a synced `dev-metrics.config`), each line is
 also sent, best effort. A DSN on its own never sends. `CI=true` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -25,7 +25,8 @@
     "README.md",
     "CHANGELOG.md",
     "docs/",
-    "!docs/images/"
+    "!docs/images/",
+    "skills/"
   ],
   "scripts": {
     "cli": "tsx src/ui/cli/index.ts menu",
@@ -44,7 +45,7 @@
     "gate:org-names": "node scripts/org-name-gate.mjs",
     "docs:shots": "node scripts/doc-shots.mjs",
     "docs:links": "node scripts/docs-links.js",
-    "example:regen": "rm -rf examples/distribution && ./bin/den create acme examples/distribution",
+    "example:regen": "rm -rf examples/distribution && ./bin/den create acme examples/distribution --port 7777",
     "dist-smoke": "bash scripts/dist-smoke.sh"
   },
   "keywords": [

package/skills/install-den/SKILL.md

@@ -0,0 +1,114 @@
+---
+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.
+---
+
+# 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.
+
+## 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.
+- Every step below is safe to re-run. If you are unsure whether a step ran, run it again.
+
+## 1. Check the prerequisites
+
+Run these and read the results. Don't install anything without saying so first.
+
+1. `node --version`: needs **22.13 or later**. If it's older or missing, say so and suggest their usual installer
+   (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":
+
+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`.
+
+Below, `<dir>` is the Den folder, `<repo>` the repo path, and `<name>` the name.
+
+## 3. Create the Den
+
+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`).
+
+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.
+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.
+
+## 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.
+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
+   (`~/.<name>/`), so they can get help.

package/src/shared/agent-setup.ts

@@ -0,0 +1,9 @@
+/**
+ * The one line a developer pastes into their agent to have it set Den up
+ * (ON-5): the agent follows the install-den skill published at this URL
+ * (skills/install-den/SKILL.md in the package).
+ */
+export const AGENT_SETUP_URL =
+  "https://raw.githubusercontent.com/Monster-Orange/den/main/skills/install-den/SKILL.md";
+
+export const AGENT_SETUP_LINE = `Set up Den for me by following ${AGENT_SETUP_URL}`;