@monster-orange/den 0.4.4 → 0.4.6

package/docs/distributions.md

@@ -12,6 +12,7 @@ Den's own checkout is itself a distribution, named `den`.
 - [The bin shim](#the-bin-shim)
 - [make: den.mk](#make-denmk)
 - [Two roots](#two-roots)
+- [Dev metrics: local unless you opt in](#dev-metrics-local-unless-you-opt-in)
 - [Pinning and upgrading](#pinning-and-upgrading)
 - [Developing Den against a distribution](#developing-den-against-a-distribution)
 
@@ -31,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).
@@ -47,6 +62,85 @@ 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 }` |
+
+### 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
+
+- `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                                                                                             |
@@ -379,9 +473,23 @@ a ref that is not set is **not configured**, and its feature says so
 ("not configured: set secrets.provider and secrets.refs.sudo in
 config/acme.yml") instead of running a CLI. Typing the password always
 works; only the saved password needs `refs.sudo`.
+
+**Saving writes `refs.sudo` for you** (LK-4, 0.4.5). When `secrets.provider`
+is `1password` or `doppler`, its CLI is available, and no `refs.sudo` is
+set, the admin password prompt (shown when a command is about to run sudo)
+still offers "Save to 1Password". Saving creates the item
+(1Password: a Password item "<Product> admin password", field `password`,
+in your default vault; Doppler: the key `<PREFIX>_LOCAL_ADMIN_PWD`) and
+then writes that ref to `config/local/user.yml`, because the password is
+the person's, not the distribution's. From then on it survives restarts.
+A failed save writes nothing, and its error never carries the password.
+`env` keeps nothing past the process, so it offers no save. A `refs.sudo`
+in the distribution's config always wins over the one in user.yml.
+
 `/api/sudo-password/vault-status` reports `backend`, `label`,
-`configured`, `backendAvailable`, `reason` and `hasStored` (`opAvailable`
-is a deprecated alias of `backendAvailable`, kept for one minor).
+`configured`, `canSave` (saving works with no YAML to edit),
+`backendAvailable`, `reason` and `hasStored` (`opAvailable` is a
+deprecated alias of `backendAvailable`, kept for one minor).
 
 The admin password is for sudo, and nothing else (LK-0). It is no sign-in
 and no access check: starting, stopping and resuming agents, sessions and
@@ -572,6 +680,10 @@ 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).
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -1209,11 +1321,13 @@ are the same directory.
 
 On localhost nothing asks you to sign in: every page, the agents and the
 terminal work as they are, and the admin password (R8) is the only prompt,
-asked only when a command Den runs needs sudo. The edge counts as local too (0.4.3): opening
-`https://acme.acme.localhost` from this machine asks for nothing.
-Signing in is for when the server is reached from another machine: the
-edge for a client the edge says is elsewhere, a LAN address, or a bind
-that isn't loopback (`DEN_BIND_HOST`).
+asked only when a command Den runs needs sudo. Through the edge, a browser
+the edge shows is on this machine asks for nothing either. Signing in is
+for everything else: the edge for a client it can't place here (0.4.5), a
+LAN address, or a bind that isn't loopback (`DEN_BIND_HOST`). From another
+device, sign in with GitHub as the Den's owner, approve the computer with
+the code its page shows, or open a one-time link (below, and
+[Signing in with GitHub](#signing-in-with-github)).
 
 There is no password. Reading `web.secret` (32 random bytes, mode 0600 in
 the state dir, made at the first `web up`) proves you are this computer's
@@ -1221,7 +1335,10 @@ user, and the CLI does that for you:
 
 ```bash
 ./bin/acme web open        # start if needed, and sign this browser in (a new tab)
-./bin/acme web login       # print a one-time sign-in link, for another browser
+./bin/acme web login       # a one-time sign-in link and its code; waits until it's used
+./bin/acme web login --no-wait  # the link alone (asks for no code), and return
+./bin/acme web approve ABC-123  # approve the computer showing this code
+./bin/acme web approve --list   # the computers waiting with a code
 ./bin/acme web sessions    # the signed-in browsers: id, created, last seen, host, user agent
 ./bin/acme web logout <id> # sign out one browser (an id prefix from `web sessions`)
 ./bin/acme web logout      # sign out every browser
@@ -1238,7 +1355,19 @@ user, and the CLI does that for you:
   among them; its URL comes from the edge config, and a name the edge
   doesn't route here is refused, saying what to add), and
   `web login --origin http://<lan name>:<port>` for any other allowed name
-  (the signed-out page there shows the exact command).
+  (the signed-out page there shows the exact command, under "Other ways").
+- **`web login` waits** (0.4.5). Besides the link it prints an
+  8-character code ("It asks for this code: ABCD-EFGH") and blocks until
+  the link is used, then says who: "Signed in: Safari on macOS
+  (100.64.0.7) at 10:42". Nobody within the minute: "Expired: nobody used
+  the link", exit 1. The link's page asks for the code before it signs in,
+  so the link alone is useless; once opened it waits 5 minutes for the
+  code. A wrong code is refused; five burn the link ("Refused: too many
+  wrong codes", exit 1), more than 20 wrong a minute (any link) are slowed,
+  and the link still works once. The CLI asks the running server through
+  its bearer and never logs the code. `--no-wait` prints the link alone and
+  returns, as before (no code); with no server running `web login` does
+  that too, and says so.
 - **The cookie** (`den_session_<port>`) is HttpOnly, SameSite=Strict and
   Path=/, and Secure when the request came over HTTPS through the edge. The
   session lives server-side (`web-sessions.json`, 0600, in the state dir)
@@ -1256,36 +1385,111 @@ user, and the CLI does that for you:
   The Host allowlist, the Origin check and the CSRF token are what stop
   another site or a rebinding DNS name. From another machine, every page
   and call needs a signed-in browser (or a bearer). A page there shows
-  "Sign in to use <name>" with the command to run; it never asks for a
+  "Sign in to <name>" and the ways to sign in (below); it never asks for a
   secret. `/api` answers 401 `signin_required`.
-- **The edge counts as local.** A request for the edge hostname from the
-  edge (an edge peer, below) is treated as loopback: no sign-in on any
-  route, the agents and the terminal included. Host, Origin, CSRF and the
-  agent-token rules still apply. Who the client is comes from the left-most
-  `X-Forwarded-For` entry the edge sends:
+- **The signed-out page says where to act.** It names the machine Den runs
+  on ("You're opening Den from another computer. Den runs on
+  **studio**, so it needs to know this is you."), then:
+  - **Sign in with GitHub**, only when a client id is set (below);
+  - **Approve this computer**: a code (`XXX-XXX`) and the command that
+    approves it, to run on that machine (`<cli> web approve <code>`), or
+    Settings › Access › Waiting devices there. The page signs itself in
+    when it's approved and goes to the page you asked for; it counts down
+    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;
+  - **Other ways**, collapsed: the one-time link with
+    `web login --origin`.
+
+  Every command the page prints names the machine it runs on and has a
+  copy button. It is `<cli>` when the first `<cli>` on that machine's PATH
+  is this distribution's, else the absolute path of its bin.
+
+- **The machine's name** on the page is `web.machine_name` from
+  `config/local/user.yml` (Settings › Access › Machine name), else the short
+  host name (up to the first dot). It is never taken from the browser's
+  Host. The ssh one-liner's target is the Host the browser used, without
+  the port (the machine's host name if it had none).
+- **Codes.** About 30 bits (Crockford base32: no I, L, O or U; typed in any
+  case, the dash optional); the page polls with a separate 128-bit id. A
+  code expires after 10 minutes and works once; at most five wait at once
+  (a sixth drops the oldest). They live in the server's memory only.
+  Approving is rate-limited (10 a minute) and recorded in the activity log
+  with who approved, never the code. The new session is "approved with a
+  code". **Deny** (Settings › Access, or `web deny` through the API) tells
+  the page it was refused.
+- **Seeing that you're signed in.** The chip at the foot of the rail says
+  "Local" (this machine), "Signed in · this device" (a code or a one-time
+  link) or "@<login>" (GitHub), and opens Settings › Access. The first page
+  after a sign-in says "This device is signed in to Den on <machine>",
+  once. Linked devices lists every session (GitHub, a code, a one-time
+  link): how it signed in, when, from where (the address and the browser
+  and OS), last seen, and **Revoke**; the one you're using says "This
+  device".
+- **The edge counts as local only when it shows the client is.** A
+  request for the edge hostname from the edge (an edge peer, below) is
+  treated as loopback (no sign-in on any route, the agents and the
+  terminal included) when the client the edge reports is this machine.
+  Host, Origin, CSRF and the agent-token rules still apply. Who the client
+  is comes from the right-most `X-Forwarded-For` entry, the one the edge
+  itself appended (anything left of it came from the client, and is never
+  believed):
   - loopback, or one of this machine's own interface addresses (a LAN
-    address, or a VPN's such as a Tailscale `100.x`): local;
+    address, or a VPN's such as a Tailscale `100.x`): local, no sign-in;
   - missing, or a container/VM network's address (the Docker ranges, or a
     subnet of one of this machine's Docker/OrbStack/VM bridges): Den can't
     tell (Docker Desktop and OrbStack on macOS hand the edge their
     gateway's address, and a TCP passthrough in front of the edge hides the
-    client), so local;
-  - any other address: another machine, which needs a sign-in.
-
+    client), so it signs in: `web.edge_unattested`, below;
+  - any other address: another machine, which signs in.
+
+  `web.edge_unattested: local` in `config/local/user.yml` counts a client
+  Den can't place as local again (0.4.4's behaviour). It is read only from
+  that file (a choice for that machine); the distribution config's key is
+  ignored with a warning. The default is `signin`. A request straight to
+  the server's port on localhost (loopback Host and peer) never signs in.
   With `DEN_BIND_HOST` beyond loopback (a deliberate exposure, other than
-  the Linux edge's Docker bridge address) the edge needs a sign-in as
-  before. With `forwardedHeaders.insecure` (the edge's default) Traefik
-  keeps an `X-Forwarded-For` the client sent, so this is a convenience,
-  not a boundary: whoever can reach the edge can use the terminal.
+  the Linux edge's Docker bridge address) the edge always signs in.
+
+- **The edge believes forwarded headers only from its own networks.** Den
+  renders each entrypoint with `forwardedHeaders.trustedIPs` set to
+  loopback and the Docker ranges (`127.0.0.1/32`, `::1/128`,
+  `172.16.0.0/12`, `192.168.65.0/24`), never `forwardedHeaders.insecure`,
+  so a client can't hand the edge an `X-Forwarded-For` of its own. An
+  `edge.args` entry that sets `forwardedHeaders` or `proxyProtocol` is
+  dropped, and `edge up` says so.
+- **A TCP passthrough in front of the edge** (a gateway that publishes
+  `:443` and passes TLS through) hides the client: the edge sees the
+  gateway's address. Have the gateway send the PROXY protocol, and list it
+  in `edge.proxy_protocol.trusted_ips` (empty by default; IP addresses or
+  CIDRs; `config/local/user.yml`'s list replaces the team's):
+
+  ```yaml
+  edge:
+    proxy_protocol:
+      trusted_ips: [172.18.0.5]
+  ```
+
+  Every entrypoint then takes the PROXY protocol from those addresses, and
+  the client it carries is what Den sees. Configuring the gateway is the
+  gateway's job.
+
+- **`edge up` recreates the edge when its command changed.** It compares
+  the running edge's command with the one it renders and says why ("acme-edge's
+  settings changed (forwarded-header trust): recreating it once. Routes
+  drop only while it restarts."). Upgrading to 0.4.5 does this once.
 
 - **"Your edge is reachable from other machines".** When Den can tell, at
   start, that the edge is reachable beyond this machine (an edge hostname
   that resolves to an address that isn't loopback, such as a LAN or
   Tailscale address, or the edge container publishing a port on every
   interface, from `docker inspect`), it writes "Your edge is reachable from
-  other machines; anyone who can reach it can use terminals. Auth is
-  coming." once to `web.log`, and every page shows it as a banner (dismissed
-  per browser).
+  other machines. A browser it can't place as this one signs in first
+  (Sign in with GitHub, or a pairing link)." once to `web.log`, and every
+  page shows it as a banner (dismissed per browser). With
+  `web.edge_unattested: local` it says instead that anyone it can't place
+  can use terminals, and to remove the key to have them sign in.
 - **localhost is the canonical name.** A cookie set on `localhost` isn't
   sent to `127.0.0.1`, so the links Den prints use `localhost`.
 - **Browsers.** Chromium, Firefox and Safari 16.4 or later: a sign-in link
@@ -1319,6 +1523,76 @@ logout --all` the old token is refused; the CLI reads the new one.
   421 `misdirected`, so a LAN client can't send the edge's name straight to
   the server's port.
 
+## Signing in with GitHub
+
+A Den has one owner: a GitHub account. Once it is linked, that account
+signs in from any device (a phone, another laptop, a browser through the
+edge) with **Sign in with GitHub** on the signed-out page. Den stores only
+the account's id and login, never a token, and no other account gets in.
+
+```bash
+./bin/acme web owner link    # link the owner: GitHub's device flow, in the terminal
+./bin/acme web owner         # show who it is (also: web owner show, --json)
+./bin/acme web owner unlink  # forget the owner (signed-in browsers stay signed in)
+```
+
+- **`web owner link`** prints `https://github.com/login/device` and a code.
+  Enter the code there and approve; Den asks GitHub who approved, stores
+  `owner: github:<id>` and the login in `web-owner.json` (0600, in the
+  state dir) and throws the token away. A second link is refused until
+  `web owner unlink`. Settings › Access does the same in the browser
+  (Link your GitHub account, Unlink): shell-grade actions, for a signed-in
+  browser and never an agent's token.
+- **Sign in with GitHub** on the signed-out page shows a code and
+  `github.com/login/device`. The server runs the flow, and when the owner
+  approves it sets the same never-expiring session cookie a one-time link
+  sets, and the page reloads signed in. Another account sees "@<login>
+  isn't allowed on this Den". The token is thrown away either way. At most
+  three sign-ins wait for GitHub at once; a code expires as GitHub says
+  (15 minutes). With no owner linked the page says to run
+  `web owner link`.
+- **Settings › Access** lists the linked devices (the browser, how it
+  signed in, the client address when the edge vouched for one, created and
+  last seen; "This device" on yours), each with **Revoke**, which ends its session at once (its
+  open terminals included). **Pair a device** makes a one-time link and a
+  QR code for an edge hostname you pick (`web login --host <name>` in the
+  browser): scan it on the other device within 60 seconds.
+- **`web.github_client_id`** is the GitHub App's client id (public; no
+  secret). The default is Den's own App, **Monster Orange Den**
+  (`Iv23liKL12gnN6WvRV5b`), so Sign in with GitHub works out of the box. A
+  distribution that ships its own App sets its client id here (below);
+  `config/local/user.yml`'s wins over the team's. An empty value
+  (`github_client_id: ""`) turns Sign in with GitHub off: the page then
+  offers the code and the one-time link only.
+- **Expiring tokens.** If the App hands out expiring tokens (GitHub's
+  answer carries `expires_in` or a `refresh_token`), sign-in still
+  completes, and Den says once, in the log and on stderr, to switch off
+  token expiry in the App's settings ("Expire user authorization tokens");
+  it never prints the token. `GET /api/web/owner` reports it as
+  `tokenExpiry: true`.
+
+### The GitHub App (once, by whoever ships the Den)
+
+Den's default App is Monster Orange Den. A distribution that wants its own
+(its name on GitHub's approval page) needs a GitHub App with the device
+flow on. Create it once (organization or account › Settings › Developer settings › GitHub
+Apps › New GitHub App):
+
+1. No callback URL; untick "Request user authorization during
+   installation". Webhook off.
+2. **Enable Device Flow**: ticked. The device flow needs only the client
+   id.
+3. **Expire user authorization tokens**: off. Den never asks for
+   `offline_access`, and keeps no token either way.
+4. Account permissions: none. Den reads only `GET /user` (the id and the
+   login), which needs none. Repository permissions are only for features
+   that act on a repository (Den's default App has Issues for feedback).
+5. **Where can this GitHub App be installed**: Any account. GitHub lets only
+   members of the owning organization authorize a private App, so anyone
+   else couldn't sign in.
+6. Put the **Client ID** in `web.github_client_id`. Never generate or
+   share a client secret or a private key for Den: it never uses one.
+
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
@@ -2129,6 +2403,26 @@ with both workspaces named. Any key of `agents:` other than `max_concurrent`
 and `persona_packs` is an agent id, and its only key is `grants`. A grant
 naming a workspace that doesn't exist stops `start`, naming the key.
 
+## Dev metrics: local unless you opt in
+
+Den records each command it runs (its name, surface, duration and exit
+code, never arguments or values) as one JSON line in
+`.dev-metrics/events.jsonl` under the distribution root. That file stays
+on the machine.
+
+Nothing is sent anywhere unless the engineer opts in, per machine:
+
+```yaml
+# config/local/user.yml (gitignored)
+metrics:
+  share: true
+```
+
+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
+`DEV_METRICS_DISABLED=1` stop sending even when opted in.
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that

package/docs/reference.md

@@ -110,9 +110,14 @@ That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
   workspace's checkout, with an MCP server pinned to that workspace and a
   token of its own. The web UI's Agents tab lists them and opens their
   terminals.
-- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in.
-  Through the edge or on a non-loopback bind, every route needs one:
-  `<cli> web login` prints a one-time link (`web open` opens it).
+- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in,
+  nor through the edge when it shows the browser is on this machine.
+  Anywhere else, every route needs one: Sign in with GitHub as the Den's
+  owner (`<cli> web owner link` links the account once), approving the
+  computer with the code its page shows (`<cli> web approve <code>`, or
+  Settings › Access › Waiting devices), or a one-time link (`<cli> web
+login`, which waits until it's used; `web open` opens it; Settings ›
+  Access pairs a device with a QR code). The rail's chip shows who you are.
 - **Web UI and CLI** over the same state.
 
 ## Strategies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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` and `choices`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person
+   **one** question: the `ask` text, with the choices numbered. 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}`;