@monster-orange/den 0.4.3 → 0.4.5

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)
 
@@ -352,7 +353,7 @@ where it is, under `secrets.refs`:
 
 | Ref                  | Feature                                                      |
 | -------------------- | ------------------------------------------------------------ |
-| `sudo`               | The saved local-dev sudo password (auto-unlock, "Save to …") |
+| `sudo`               | The saved admin password, for sudo (auto-load, "Save to …")  |
 | `journeys_agent_key` | The journeys agent's API key, when `CURSOR_API_KEY` is unset |
 
 ```yaml
@@ -377,19 +378,51 @@ secrets:
 and `env` need a `key` (or an env-shaped `field`). There are no defaults:
 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. The interactive unlock always
+config/acme.yml") instead of running a CLI. Typing the password always
 works; only the saved password needs `refs.sudo`.
-`/api/sudo-password/vault-status` reports `backend`, `label`,
-`configured`, `backendAvailable`, `reason` and `hasStored` (`opAvailable`
-is a deprecated alias of `backendAvailable`, kept for one minor).
 
-The lock (🔒 in the top bar) is asked for only when an action needs it,
-on any page: a page that thinks it's locked asks the server again first
-(another tab or device may have unlocked it), then, when a password is
-stored, loads it from the vault (once a page; a page view alone never
-wakes the vault), and only then shows the password field. Its popover is
-always on top, even over a dialog, and a dialog that needs the lock (Start
-agent) asks for the password itself.
+**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`, `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
+terminals, and a service whose commands run no sudo, never ask for it.
+Den asks only when a command it runs is about to run sudo without it:
+every service command (up, down, restart, setup, sync) gets a `sudo` shim
+first on its `PATH`. With a password held, the shim gives it to sudo. With
+none, sudo that needs no password (NOPASSWD, a warm cache) runs as it
+would, and anything else never prompts: the shim prints
+`<cli>: needs-sudo: sudo <command>` and fails, and the run's event stream
+carries `{ "type": "needs-sudo", "command": "sudo <command>", "step":
+"<service>" }` (sudo's own "a password is required" counts too, without
+the command). Only then does the page ask, saying "`sudo <command>` needs
+your admin password", with the 🔑 chip in the top bar while it waits. It
+asks the server first (another tab or device may have set it), then, when
+a password is stored, loads it from the vault (a page view alone never
+wakes the vault), and only then shows the password field, always on top,
+even over a dialog. After the password, the action runs again.
+
+Settings › Command line › Admin password says whether it is saved ("Saved
+in 1Password", "Saved for this session" or "Not saved"), with **Forget**:
+`POST /api/sudo-password/forget` drops the password the server holds and,
+when this server saved it to the vault or loaded it from there, clears the
+vault's copy. `GET /api/sudo-password/status` answers `set`,
+`passwordless`, `saved` (`vault`, `session` or null) and `vault` (`{
+configured, label }`, read from the config alone).
 
 A `1password` distribution with no refs gets one warning, in the web
 server's startup log and in `<cli> validate`, with the YAML to add.
@@ -1190,12 +1223,14 @@ are the same directory.
 ## Signing in
 
 On localhost nothing asks you to sign in: every page, the agents and the
-terminal work as they are, and the lock (R8) is the only prompt (for
-privileged actions). 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`).
+terminal work as they are, and the admin password (R8) is the only prompt,
+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
@@ -1203,7 +1238,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
@@ -1220,7 +1258,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)
@@ -1238,36 +1288,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
@@ -1301,6 +1426,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
@@ -1448,19 +1643,40 @@ port.
 `--workspace <ws>` and `--actor agent:<id>` (both or neither) scope the server
 to one workspace for one agent:
 
-- **Pinned.** A tool that takes a `workspace` gets `<ws>` when none is given.
-  A call naming another workspace is refused (`Refused: <tool>: this MCP
-server is scoped to workspace "<ws>" (agent:<id>; no grants); "<other>" is
-another workspace`; with grants, `grants: <a>, <b>`) before anything reaches the web server. A refused call is
-  recorded in the activity trail, read tools included.
+- **Pinned.** A tool that takes a `workspace` gets `<ws>`. The server
+  registers each workspace tool with "This workspace only" in its
+  description and without the `workspace` parameter (with grants it stays,
+  a name whose description lists `<ws>` and the granted ones; any other
+  name gets the refusal below, not a schema error). A call naming another
+  workspace is refused
+  (`Refused: <tool>: this MCP server is scoped to workspace "<ws>"
+(agent:<id>; no grants); "<other>" is another workspace`; with grants,
+  `grants: <a>, <b>`) before anything reaches the web server. The refusal
+  says how to get more: a person adds `<other>` to `agents.<id>.grants` in
+  the org config and restarts the agent; an agent can't grant itself one. A
+  refused call is recorded in the activity trail, read tools included.
+- **Says so.** Every scoped answer (`status`, `services`, `applications`,
+  `graph`, `stacks`, `workspaces`) carries a `scope` block: the workspace
+  shown, how many other workspaces there are and how much it leaves out,
+  for example `hidden: { repos: 6 }`, and a note pointing at `org_summary`.
+  A scoped `graph` is the workspace's own repos and the edges out of them
+  (`map: "workspace"`, with `outside` naming the repos they depend on
+  elsewhere). Unscoped with no `workspace` it is the org-wide map
+  (`map: "org-wide"`: every active workspace's graph merged, `workspaces`
+  naming them); with one, that workspace's (`map: "workspace"`).
 - **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
   take only `<ws>`'s services, `manifest_validate` takes only an absolute path
   inside one of its repos (or the content), and `workspace_sync` syncs `<ws>`.
   Tests run against the focused workspace, so `tests_available` and
   `run_tests` are refused unless `<ws>` is the focused one.
 - **Not workspace data**, served as unscoped: `environments`,
-  `security_latest`, `release_status` and `edge_status` (the org's and the
-  distribution's, not a workspace's).
+  `security_latest`, `release_status`, `edge_status` and `org_summary` (the
+  org's and the distribution's, not a workspace's).
+- **The org at a glance.** `org_summary` gives every agent every workspace
+  and repo with status counts, the graph, the edge and the environments
+  (see [Tools](#tools)). Detail and actions stay scoped: for workspaces
+  other than `<ws>` it carries names and counts only, never logs, env
+  values, commands, URLs, paths or check output.
 - **Stamped.** Every web API call carries `x-den-mcp-agent: agent:<id>` and
   `x-den-mcp-workspace: <ws>` beside the usual audit headers. The activity
   entry gains `agent` and `workspace`, and the log line reads `· by
@@ -1479,7 +1695,9 @@ agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
 - `<ws>` must exist in this distribution; until it does, every tool says so.
   The id is letters, digits, dots, dashes and underscores (at most 64). A bad
   or half-given scope is a usage error, exit 2. `--list` and `--call` take
-  the scope too.
+  the scope too: they list and validate against the pinned tools, as the
+  server registers them, and `--call` names its scope on stderr
+  (`acme mcp --call: scoped to <ws> as agent:<id>`).
 
 **It binds cooperating agents only.** The scope lives in the MCP server's
 process. The web server's HTTP API does not check it yet, so an agent that
@@ -1525,22 +1743,60 @@ guard off.
 
 Read tools (always registered):
 
-| Tool                | Web API                                    | What                                                                                                                                                                                |
-| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell, or `container <project>/<service>`); `ok` true up, false down, null not known (`pending: true` when a check has not answered) |
-| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                                                          |
-| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                                                                 |
-| `graph`             | `/api/graph`                               | The derived dependency graph and startup order                                                                                                                                      |
-| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                                                      |
-| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                                                                  |
-| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                                                                   |
-| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                                                              |
-| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                                                     |
-| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                                                                   |
-| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                                                                 |
-| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                                                              |
-| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health                                                                                                                             |
-| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names                                                                                                                                     |
+| Tool                | Web API                                    | What                                                                                                                                                                                                                                                                           |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `status`            | `/api/health`                              | Service health: `counts`, then each service's `state` (`up`, `down`, `redirect`, `pending`, `unknown`, `not-checked`) and, without a plain verdict, `why`; `url` (HTTP check) or `check` (shell, or `container <project>/<service>`); `ok` true up, false down, null not known |
+| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                                                                                                                                                     |
+| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                                                                                                                                                            |
+| `graph`             | `/api/graph`                               | The derived dependency graph (`map: "org-wide"`, every active workspace's; with `workspace`, that one's and its startup order; scoped, the workspace's own)                                                                                                                    |
+| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                                                                                                                                                 |
+| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                                                                                                                                                             |
+| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                                                                                                                                                              |
+| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                                                                                                                                                         |
+| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                                                                                                                                                |
+| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                                                                                                                                                              |
+| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                                                                                                                                                            |
+| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                                                                                                                                                         |
+| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health; an empty list says `why`                                                                                                                                                                                              |
+| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names; `https` (TLS strategy, who supplies the cert, whether HTTPS is serving)                                                                                                                                                       |
+| `org_summary`       | several (read only)                        | Every workspace and repo with status counts, the graph, the edge and the environments; scoped, `yours` adds your workspace's services                                                                                                                                          |
+
+**Health states.** A service with no verdict says why in `why`: no health
+check in the manifest for the env, remote with no check or `target.url`
+for its env, not deployed in the env (no commands and no check there), no
+manifest, or checked but no answer yet. A redirect (`302 → /login`) is
+`redirect` with its status and target (the query is dropped), not down:
+something answered. It is never green either, so an unexpected redirect
+(an ALB answering for a stopped service) is not taken for up; list the code
+in `target.expect` to count it as up. The web health row and `<cli> status`
+use the same rule: the web row shows a redirect muted (with `status` and `redirect`
+in `/api/health`), and `<cli> status` as `redirect 302 → /login`.
+
+**`org_summary`** reads `/api/workspaces`, `/api/health` (local, every
+active workspace), `/api/graph`, `/api/edge` and `/api/environments`:
+
+- `workspaces`: each workspace's name, whether it is active, focused or
+  yours, its state (`running`: every checked service answers; `partial`:
+  some are down; `stopped`: all checked ones are down; `unknown`: nothing
+  checked; `inactive`: not polled), its counts (up, down, redirect,
+  pending, not checked) and its repos, each with its rolled-up state.
+- `graph`: the org-wide map, every active workspace's repos merged (each
+  workspace's graph from the web server; `workspaces` names them, and
+  `unavailable` any whose graph failed), repo names and edge kinds only (no
+  evidence, paths or URLs).
+- `edge`: up, state, domains, the route count and `https`.
+- `environments`: the enabled names, never their values.
+- scoped, `yours`: your workspace's services as `status` gives them.
+
+**`edge_status.https`** says which TLS strategy is in use (`mkcert`,
+`files`, `none`), who supplies the cert (`den`, or `distribution` under
+`tls: files` and the legacy `issue_cert: false`) and whether HTTPS is
+serving: a TLS handshake on the edge's published https port (`serving`
+true or false, null when a proxy in front owns the port), with `detail`.
+`certIssuedByDen` replaces `certIssued`, which is kept for 0.4.4 with a
+note in `deprecated`: it said whether Den minted the cert, so it was
+`false` under `tls: files` while HTTPS worked. `edge status` prints the
+same `https` line.
 
 Action tools (only those named in `mcp.actions`): `service_up`,
 `service_down`, `service_restart` (through `/api/service/exec`),
@@ -1658,7 +1914,7 @@ server scoped to its workspace.
 <cli> agents stop <id> [-w <ws>]
 <cli> agents resume <id> [-w <ws>]
 <cli> agents personas [--json]
-<cli> agents doctor [--json]            # can each runtime run here, and why not
+<cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -1708,9 +1964,10 @@ started. The workspace header counts them ("2 agents").
 - The page and the CLI call the same operations and read the same agent
   records, so an agent started in one is listed in the other. A workspace
   lists its own agents only.
-- Start, Stop and Resume need the lock open (🔓, the same rule as a
-  service's Start), are capped by `agents.max_concurrent`, and are refused
-  for an agent (agents don't start agents from the page). Each one is in the
+- Start, Stop and Resume never ask for the admin password (it is for
+  sudo, and no agent action runs sudo), are capped by
+  `agents.max_concurrent`, and are refused for an agent (agents don't
+  start agents from the page). Each one is in the
   server log's activity, with you as its actor. The agent's environment is
   the one below, built from the web server's environment.
 - **Open in Agents →** (the section header) opens the Agents tab for the
@@ -1720,7 +1977,7 @@ The routes: `GET /api/workspaces/<ws>/agents`, `POST
 /api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
 /api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
 /api/personas` (personas and runtimes). Errors are the usual
-`{ ok: false, error, code, requestId }`: `locked` (423), `cap` (429),
+`{ ok: false, error, code, requestId }`: `cap` (429),
 `conflict` (409, e.g. already running, or no resume), `not_found` (404),
 `exited_at_once` (502, with the session's last lines).
 
@@ -1743,12 +2000,10 @@ agent of the workspaces in view, and their terminals in the browser.
   reload or Back reopens them.
 - **Close** (×) detaches, as leaving the page does: the session keeps
   running, and opening it again replays what you missed. **Stop** (an
-  agent only) is `agents stop`, behind the lock. **+ Start agent** (or
+  agent only) is `agents stop`. **+ Start agent** (or
   `/agents?start=1`) starts one and opens its pane; under All it asks for
   the workspace. It says before Start whether the runtime can run, as the
-  Workspaces page's form does. While the lock is closed, the dialog asks
-  for the admin password at its top, and Start unlocks, then starts, without
-  closing anything.
+  Workspaces page's form does. It never asks for the admin password.
 - ⌘K lists each as "Agents › <ws> / <name>", and "Start agent…".
 - Several browsers and `<cli> sessions attach` can attach to one session
   at once and each sees every byte; the terminal's size is the last
@@ -1813,8 +2068,9 @@ header (agent headers without the token are recorded as an unverified
 claim).
 
 An agent's token reaches only its own session's routes, and never a
-shell-grade route, `/api/web/*`, sign-in or sign-out, or the lock: it can't
-unlock, use the sudo password or start another agent (403
+shell-grade route, `/api/web/*`, sign-in or sign-out, or the admin
+password's routes: it can't set the admin password, use it for sudo or
+start another agent (403
 `agent_forbidden`). A person's credential never reaches a session:
 `DEN_PERSON_TOKEN`, a person token's value and a path to `web.secret` are
 always removed, and `sessions start --keep-env` of one is refused and logged.
@@ -1835,7 +2091,8 @@ it does not catch every spelling: a path relative to the agent's cwd
 (`cat ../.den/web.secret`, say), another program, a script or a copy under
 another name all get past it. The server's token rules (above)
 are the boundary: whatever an agent reads, its token reaches only its own
-session's routes, never a shell-grade route or the lock. OS-user isolation
+session's routes, never a shell-grade route or the admin password's.
+OS-user isolation
 (a separate user, a container, a sandbox) is not in 0.4.x. `web logout
 --all` revokes every agent's token (above, under Signing in).
 
@@ -1884,7 +2141,8 @@ are errors naming the file or the key.
 
 ### Runtimes
 
-`<cli> doctor` lists the runtime kind. Two are built in:
+`<cli> doctor` lists the runtime kind. Den knows the runtimes in its
+**catalog** (below); two are special:
 
 - **`den-claude`** (the default) runs Claude Code's `claude`, found as
   below; `<cli> doctor` reads its version from the install, without running
@@ -1899,14 +2157,64 @@ are errors naming the file or the key.
 - **`generic`** runs the persona's `argv` template. `{model}` is the agent's
   model (an error when the template uses it and there is none);
   `{mcp_config}` is the path of the agent's MCP config, written only when the
-  template references it. It declares no resume.
+  template references it. It declares no resume. It is startable only for
+  a persona that has an `argv`.
+
+**The runtime catalog.** Den ships, as data, every vendor CLI it knows how
+to find. Each entry was checked against the vendor's own docs or installer:
+
+| id           | Vendor    | CLI                   | Found in (after PATH)                                            | Source                                                                                             |
+| ------------ | --------- | --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `den-claude` | Anthropic | Claude Code, `claude` | `~/.local/bin`, `~/.claude/local`, system dirs                   | [setup](https://code.claude.com/docs/en/setup)                                                     |
+| `codex`      | OpenAI    | Codex CLI, `codex`    | `$CODEX_INSTALL_DIR`, `~/.local/bin`, system dirs                | [openai/codex](https://github.com/openai/codex), [installer](https://chatgpt.com/codex/install.sh) |
+| `gemini`     | Google    | Gemini CLI, `gemini`  | system dirs                                                      | [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)                            |
+| `grok`       | xAI       | Grok Build, `grok`    | `$GROK_BIN_DIR`, `~/.grok/bin`, `~/.local/bin`, `/usr/local/bin` | [Grok Build](https://docs.x.ai/build/overview), [installer](https://x.ai/cli/install.sh)           |
+
+"System dirs" are `/opt/homebrew/bin`, `/usr/local/bin` and npm's global
+bin. Each one's version is `<bin> --version`. Every vendor here publishes
+an official CLI, so none is left out; a vendor without one is left out
+rather than guessed at (community CLIs, such as third-party "grok" CLIs,
+are not xAI's and are not in the catalog).
+
+Claude Code runs as `den-claude` (above). Every other installed runtime
+runs its own interactive CLI (`codex`, `gemini`, `grok`) in the
+workspace's directory; Den's tools (MCP) and permission modes are coming
+for them, and lists tag them **Den tools: coming**. A runtime is offered
+as startable only when it can start here: installed (or, for `generic`,
+with the persona's `argv`).
+
+A distribution adds entries with `agents.runtime_catalog` in its config,
+and a person with the same key in `config/local/user.yml`. Both go
+through the validator the built-in entries pass; an entry can't reuse a
+catalog id (set a path instead, below):
+
+```yaml
+agents:
+  runtime_catalog:
+    - id: aider # lowercase, starts with a letter
+      vendor: Aider
+      name: Aider
+      bins: [aider] # executable names, no paths
+      version:
+        args: [--version]
+        identity: # at least one: how a path is known to be it
+          output: "aider" # a pattern its version output matches
+          # package: aider-chat        (the npm package it resolves into)
+          # realpath_under: [~/.aider] (where it really lives)
+      dirs: [~/.local/bin, $AIDER_DIR, "{system}"]
+      launch:
+        argv: ["{bin}"] # "{bin}" first: the path found
+```
 
 **Where a runtime's CLI is found.** As your terminal would find it, not
 only on the web server's own PATH (a launchd service's PATH leaves out
 `~/.local/bin`, where Claude Code's native installer puts `claude`). The
 first match wins:
 
-1. **`agents.runtimes.<id>.bin`** in `config/local/user.yml`: the absolute
+1. **A workspace's own path**, `<ws>.agents.runtimes.<id>.bin` in
+   `config/local/workspaces.yml`, for that workspace's agents. Checked the
+   same way as the next one.
+2. **`agents.runtimes.<id>.bin`** in `config/local/user.yml`: the absolute
    path of the runtime's CLI. Paths are per machine, so it is read from
    user.yml only, never from the distribution's config. A bad value (not
    absolute, missing, not an executable file) makes the runtime
@@ -1920,14 +2228,28 @@ first match wins:
          bin: /Users/me/.local/bin/claude
    ```
 
-2. **Your login shell's PATH**: the web server asks `$SHELL -lc` once at
+3. **Your login shell's PATH**: the web server asks `$SHELL -lc` once at
    start, in the background, under a 3-second timeout. On a timeout or
    any failure it is left out.
-3. **The server's own PATH.**
-4. **The runtime's install directories.** For den-claude: `~/.local/bin`,
-   `~/.claude/local`, `/opt/homebrew/bin`, `/usr/local/bin` and npm's
-   global bin (`$npm_config_prefix/bin`, and node's own directory). Den
-   never runs npm to find it.
+4. **The server's own PATH.**
+5. **The runtime's install directories** (its catalog entry's; for
+   den-claude: `~/.local/bin`, `~/.claude/local`, `/opt/homebrew/bin`,
+   `/usr/local/bin` and npm's global bin, `$npm_config_prefix/bin` and
+   node's own directory). Den never runs npm to find it.
+6. **Your interactive shell's PATH**, only while a catalog runtime is
+   still not found: `$SHELL -ilc` once (stdin closed, 3-second timeout,
+   the answer kept), for a PATH set only in an interactive startup file
+   such as `~/.zshrc`. Its source is `interactive-shell`.
+
+Paths are this machine's only: Den reads them from `config/local` files,
+never from the distribution's config. **Settings › Agents › Runtimes**
+shows each runtime's status, version, the path in use and its source.
+**Set path…** runs the runtime's version command and refuses a path that
+isn't that runtime (its output, npm package or install location must name
+it); **Clear** removes it. The **Paths for** selector switches between
+every workspace (`user.yml`) and one workspace (`workspaces.yml`). Only a
+person sets a path, never an agent (`POST /api/agents/runtimes/<id>/path`,
+audited).
 
 Sessions and agents Den starts get the same directories on their PATH
 (and a configured CLI's own directory), so the runtime's own tools are
@@ -1936,17 +2258,19 @@ diagnosis: `DEN_LOGIN_SHELL` (the shell to ask instead of `$SHELL`; `off`
 for none) and `DEN_RUNTIME_DIRS` (a PATH-style list that replaces every
 runtime's install directories; empty for none).
 
-**`<cli> agents doctor`** prints, for each runtime, its status, the CLI it
-runs and where that came from (the `agents.runtimes` setting, the login
-shell's PATH, PATH, or an install directory), its version (`claude
+**`<cli> agents doctor`** prints, for each runtime (installed first), its
+status, the CLI it runs and where that came from (the workspace's or the
+user.yml `agents.runtimes` setting, the login shell's PATH, PATH, an
+install directory, or the interactive shell's PATH), its version (`claude
 --version`, run once under a timeout), the directories it searched (names
 only, never an environment value), and the fix when it's missing. It
 resolves the login shell's PATH first, as the web server does. It exits 1
-when the default runtime is unavailable; `--json` prints what the Start
-dialog gets.
+when the default runtime is unavailable; `-w <ws>` uses that workspace's
+paths; `--json` prints what the Start dialog gets. A search list the same
+as the one above it prints once.
 
 ```
-den-claude (Claude Code)  [default]
+den-claude (Claude Code, Anthropic)  [default]
   status    ✗ unavailable: claude not found (searched 5 directories)
   searched  /usr/bin
             /bin
@@ -1955,9 +2279,12 @@ den-claude (Claude Code)  [default]
             then run `<cli> agents doctor` again
 ```
 
-`GET /api/personas` gives each runtime its `version`, `path`, `source`
-(`setting`, `login-shell`, `well-known` or `PATH`), `searched` and
-`setting` (the user.yml key), and `userConfig`, the user.yml to edit.
+`GET /api/personas` and `GET /api/agents/runtimes` (each with an optional
+`?workspace=<ws>`) give each runtime its `vendor`, `denTools`, `version`,
+`path`, `source` (`workspace`, `setting`, `login-shell`, `PATH`,
+`well-known` or `interactive-shell`), `searched`, `setting` (the user.yml
+key) and `workspaceSetting` (the workspaces.yml key), and `userConfig`,
+the user.yml to edit.
 
 ### Workspace scope and grants
 
@@ -1979,6 +2306,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