@monster-orange/den 0.2.8 → 0.4.0

package/docs/distributions.md

@@ -307,6 +307,102 @@ ones (`⇄ hybrid`).
   production_envs: [prod] # default: [prod, production]
   ```
 
+## Secrets
+
+A distribution needs no secrets store. Den has no store, vault, item,
+field, key or account of its own that a distribution is assumed to share.
+Where a distribution keeps its secrets, if anywhere, is its own config.
+
+### Choosing a backend
+
+The backend is a strategy, chosen with `secrets.provider` in the org config
+(per engineer in `config/local/user.yml`, per shell with
+`<PREFIX>_SECRETS_PROVIDER`):
+
+| `secrets.provider` | What it is                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `none`             | No store. Nothing is resolved, no CLI is run; `den create` scaffolds this                |
+| `env`              | Plain environment variables of the process running Den                                   |
+| `doppler`          | The `doppler` CLI (`secrets.doppler: { project, config }` for a default scope)           |
+| `1password`        | The `op` CLI (`secrets.onepassword.account` for the account, else your own `OP_ACCOUNT`) |
+
+```yaml
+# config/acme.yml
+secrets:
+  provider: none # or env | doppler | 1password
+```
+
+When `secrets.provider` is not set at all, Den falls back to `doppler`,
+but only at the moment something actually resolves a secret: a
+distribution with no refs, no `secret_env` and no `required` never runs
+`doppler` and never sees a warning. The first time an unset provider does
+resolve a secret, Den prints, once, that the implicit default is deprecated.
+Set the provider explicitly to silence it.
+
+Each backend is registered as a strategy (`src/shared/secrets/strategies.ts`,
+through the generic registry in `src/shared/strategies/registry.ts`) with a
+`detect()`: a file check that never prompts. A backend whose CLI is not on
+PATH reports "not available: The Doppler CLI (doppler) is not on PATH"
+instead of failing a spawn.
+
+### Refs: where Den's own features find their secrets
+
+Two Den features can use a secret, and only when the distribution says
+where it is, under `secrets.refs`:
+
+| Ref                  | Feature                                                      |
+| -------------------- | ------------------------------------------------------------ |
+| `sudo`               | The saved local-dev sudo password (auto-unlock, "Save to …") |
+| `journeys_agent_key` | The journeys agent's API key, when `CURSOR_API_KEY` is unset |
+
+```yaml
+secrets:
+  provider: 1password
+  onepassword: { account: example.1password.com }
+  refs:
+    sudo: { vault: Private, item: Dev Keys, field: ACME_LOCAL_ADMIN_PWD }
+    journeys_agent_key:
+      { vault: Private, item: Dev Keys, field: CURSOR_API_KEY }
+```
+
+```yaml
+secrets:
+  provider: doppler # or env
+  refs:
+    sudo: { key: ACME_LOCAL_ADMIN_PWD }
+    journeys_agent_key: { key: CURSOR_API_KEY }
+```
+
+`1password` needs an `item` and a `field` (`vault` is optional); `doppler`
+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
+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).
+
+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.
+
+### Setup targets
+
+`make <cli>-setup-secrets` runs the selected backend's setup: `doppler
+login` and `doppler setup`, the 1Password developer-keys setup, or a note
+for `env`. With `none`, or no provider set, it says there is nothing to set
+up and exits 0.
+
+Backend-only make targets come from `make/secrets-<provider>.mk` and exist
+only when that backend is selected: with `secrets.provider: 1password`,
+`make <cli>-setup-1password` (the developer-keys item at
+`secrets.developer_keys: { vault, item }`, else the vault and item of
+`refs.sudo`) and `make auth-configure env=<env>` (your own admin account
+for staging and production). Any other distribution has neither.
+
+`make up` and `make web` check the backend only when `secrets.required:
+true`; otherwise the check passes silently, whatever the provider.
+
 ## Secrets in a target's env
 
 `secret_env` puts secrets from the configured secrets provider
@@ -358,6 +454,98 @@ OPENAI_API_KEY (names only; not resolved in a dry run)`.
   (`[A-Za-z_][A-Za-z0-9_]*`). A `stacks:` entry in the org config takes
   `secret_env` too.
 
+## The edge and TLS
+
+The edge is one Traefik per org that routes `<name>.<edge.domain>` (and
+every `edge.aliases` domain) to local services. It exists only when the
+org config has an `edge:` block, which needs `org` and `domain`; Den has
+no default domain. How it gets certificates is a strategy, `edge.tls`:
+
+```yaml
+# config/acme.yml
+edge:
+  org: acme
+  domain: acme.localhost
+  tls: none # http only: no https entrypoint, no cert work, no mkcert
+  # tls: { strategy: mkcert }                  # a local CA, minted per machine
+  # tls: { strategy: mkcert, ca: ~/path/to/ca } # an existing mkcert CA
+  # tls:                                       # your own certs
+  #   strategy: files
+  #   include: edge/dynamic                    # Traefik dynamic config holding them
+  #   mounts: { edge/certs: /etc/traefik/dynamic/certs }
+  #   ca: ~/path/to/ca                         # optional: the CA that signed them
+```
+
+| Strategy | What the edge does                                                                                                                                                                                     |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `none`   | Serves http on `edge.http_port` (80) only. Route URLs are `http://`. No cert, no CA, mkcert is never run.                                                                                              |
+| `mkcert` | Issues its own wildcard cert for every domain, workspace and stack zone. Its CA is its own under the state dir (`~/.local/share/<org>/edge/ca`), or `ca`, an existing CA it never mints or uninstalls. |
+| `files`  | Issues nothing: the `include` directory (copied beside the generated config) and `mounts` hold the certs. `ca` only tells health checks which CA to trust.                                             |
+
+`tls: <id>` is short for `tls: { strategy: <id> }`. `config/local/user.yml`'s
+`edge.tls` replaces the team's whole. An unknown strategy, or a key the
+strategy does not take, is an error naming the built-ins (`none`, `mkcert`,
+`files`). `secret` (cert and key from the secrets strategy) and `acme` are
+later plugins.
+
+- **mkcert is checked before it is used.** It is run from PATH, never
+  bundled. With it missing, `validate`, `doctor`, `edge up` and `edge trust`
+  say "mkcert is not installed" instead of failing a spawn.
+- **`<cli> edge trust` and `untrust` exist under mkcert.** `edge trust` also
+  works under `files` with a `ca` (it installs that existing CA). Elsewhere
+  they exit 1: "edge trust needs edge.tls.strategy: mkcert (or files with a
+  ca)". `untrust` is
+  refused for a shared CA (`ca:`), whose trust other devices rely on.
+- **`<cli> create`** scaffolds `tls: none`, with the other forms in a
+  comment: one line opts into https.
+- **Legacy keys** still work, mapped to a strategy, with no change to what
+  the edge renders: `issue_cert: false` is `files`, `caroot: <ca>` is
+  `mkcert` with `ca`, and an `edge:` block with neither is `mkcert` with
+  its own CA, warned once per run ("edge.tls is not set; defaulting to
+  mkcert with a local CA. Set edge.tls explicitly.") by `validate`,
+  `doctor`, `edge up` and `stack up`. `edge.tls` beside a legacy key is an
+  error. See the 0.3.0 Migrations in the changelog.
+- **One edge per `edge.org` per machine.** The edge's container and Compose
+  project are named after `edge.org` (`<org>-edge`), whatever its state dir
+  (`DEN_EDGE_DIR`). Give a scratch or test root that points `DEN_EDGE_DIR`
+  (and `DEN_HOME`) elsewhere an `edge.org` of its own: the name comes from
+  the org, so nothing else keeps it apart. The edge container is labelled
+  with the state dir that owns it (`den.edge.root`). Edge up, edge down and
+  stack up (which brings the edge up first) refuse to touch an `<org>-edge`
+  another state dir owns. They start nothing and exit non-zero: "edge
+  acme-edge belongs to <its dir>; not replacing it". An unlabelled edge
+  (from before 0.3.0-dev.40) is adopted only from the default state dir,
+  never under an overriding `DEN_EDGE_DIR`. The only override is
+  `edge up --take-over`. (0.3.0-dev.40.)
+- **A recreated edge keeps its routes.** After edge up creates, recreates
+  or starts the edge, it rejoins the routed networks of every running stack
+  whose routes file (`dynamic/stack-<project>.yml`) is in its state dir,
+  one line per network. Stacks that are down, and projects with no routes
+  file there, are left alone. (0.3.0-dev.40.)
+
+## doctor
+
+`<cli> doctor` lists every strategy kind in the registry (secrets, tls,
+session-backend): the one this distribution selects, whether nothing chose
+it (implicit), and whether it can work on this machine, with the reason.
+It only checks PATH (and, for session-backend, whether the PTY module
+loads): it never runs a backend CLI, prompts, or prints a secret. It exits
+1 when a strategy that will be used cannot work (an implicit secrets
+default is used only when a secret is asked for, so it never fails
+doctor).
+
+```
+Acme doctor: strategies
+
+  secrets          none                 ✓ available: no secrets backend configured
+  tls              mkcert (implicit)    ✗ unavailable: mkcert is not installed
+    ⚠ edge.tls is not set; defaulting to mkcert with a local CA. Set edge.tls explicitly.
+  session-backend  den-pty (implicit)   ✓ available: PTY module loaded
+```
+
+`session-backend` is never a doctor failure: nothing needs a session until
+one is started (see Sessions).
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -421,6 +609,257 @@ brand:
 Runtime names (env vars, files, directories) always come from `den.yml`,
 never from the brand.
 
+## Plugins
+
+A plugin adds to Den without changing it: a theme, a page in the web UI, and
+later other kinds. Its manifest is a `den-plugin.json` that follows the
+[`den.plugin/v1` schema](../schemas/den.plugin.v1.json); a theme can also be a
+bare `den-theme.json`, which Den reads as a plugin that provides one theme
+and asks for nothing.
+
+```jsonc
+{
+  "schema": "den.plugin/v1",
+  "id": "runbook",
+  "name": "Team runbook",
+  "version": "1.0.0",
+  "license": "MIT", // an SPDX expression, the same rule as a theme's
+  "den": ">=0.3.0-0 <0.4.0", // required: the Den versions it runs on
+  "maintainer": "platform team",
+  "provides": [
+    {
+      "kind": "page",
+      "entry": "page/index.js",
+      "nav": { "group": "verify", "label": "nav.runbook" },
+    },
+  ],
+  "capabilities": ["ui.nav", "api.read"],
+}
+```
+
+Every plugin lives in `plugins/<id>/` in the distribution, and gets there in
+one of two ways:
+
+|              | Local                                                 | Added                                                     |
+| ------------ | ----------------------------------------------------- | --------------------------------------------------------- |
+| What it is   | the distribution's own (its theme, a team page)       | someone else's published plugin                           |
+| How          | put it in `plugins/<id>/` and commit it               | `<cli> plugin add <repo>[/<subpath>]@<tag\|commit>`       |
+| Lock entry   | none                                                  | `plugins.lock.json`: source, ref, commit, hash, approvals |
+| Integrity    | the distribution's own git history and review         | `plugin list` fails when its bytes differ from the lock   |
+| Capabilities | present is approved: what it declares is what it gets | approved at `add` (`--yes`), kept in the lock             |
+| Removing it  | delete it in git                                      | `<cli> plugin remove <id>`                                |
+
+```sh
+<cli> plugin list                 # every plugin: version, kinds, local or source@ref, lock check
+<cli> plugin validate             # every local and added plugin
+<cli> plugin validate runbook     # plugins/runbook/ (an id is never a cwd path)
+<cli> plugin validate path/to/dir # one plugin, a distribution, or a repo of them
+<cli> plugin add github.com/acme/den-plugins/runbook@runbook/v1.0.0 --yes
+<cli> plugin update runbook @runbook/v1.1.0
+<cli> plugin remove runbook
+```
+
+- **Every `plugins/<id>/` needs a manifest.** A directory with neither
+  `den-plugin.json` nor `den-theme.json` is an error in `list` and
+  `validate` ("no den-plugin.json or den-theme.json, so it isn't a
+  plugin"), so an id can never collide unseen. So is a directory named
+  `den` (the built-in theme's id), a name that is not an id (2–40
+  characters: lowercase letters, digits or dashes, starting with a letter),
+  and a symlink. `plugin list` prints exactly one row for every directory
+  in `plugins/`, even when `plugins.lock.json` can't be read. `theme list`
+  shows themes only and doesn't fail on other plugins, but counts the
+  plugin dirs with errors and points at `plugin list`.
+- **`den` is the range of Den versions the plugin runs on**, as a semver
+  range. Prereleases count, so a range meant to include Den's dev builds
+  starts at `-0`: `>=0.3.0-0 <0.4.0` admits 0.3.0-dev.8, while `>=0.3.0`
+  does not. `validate` fails a plugin whose range excludes the running Den
+  and names both, and on a prerelease Den says when only the `-0` is
+  missing.
+- **Load agrees with `validate`.** A theme that fails `validate` for any
+  reason (its range, a missing `author` or `maintainer`, a README, a
+  capability, contrast) is never offered in the Theme menu and never loads.
+  The web UI skips it with one server-log notice and draws with the next
+  choice (yours, then `brand.theme`, then `den`); it never fails to start.
+- **What `validate` checks:** the schema; each kind with its own validator
+  (a theme as `theme validate` does, a page's entry module on disk); and the
+  admission rules: a `maintainer` (for a bare `den-theme.json`, its
+  `author`; `theme new` sets it to the brand's name); for a page or server plugin, a README
+  (`readme`, default `README.md`) that names its tier and says what it may
+  touch and what it must never do (themes are exempt); an SPDX `license`,
+  with every bundled font licensed.
+- **Capabilities** come from a closed list: `ui.nav`, `api.read`,
+  `api.actions:<id,...>`, `secrets:<ref,...>`, `net:<host,...>`,
+  `exec:<binary,...>` and `send:<channel>`. Anything else fails validation.
+- **Commit a local plugin before you trust it.** Den loads what is on disk,
+  so it can't tell committed from uncommitted. When a local plugin declares
+  `api.actions`, `secrets`, `exec`, `net` or `send` and has files git has not
+  committed, `validate` warns, so the change goes through the same review as
+  the rest of the distribution. Themes and read-only plugins never warn.
+- **`add`** takes an exact ref: a tag or a full commit SHA (a branch only
+  with `--track`, recorded as tracking). It validates the plugin, vendors it
+  into `plugins/<id>/` and writes its lock entry, with `kinds` and
+  `approved_capabilities` from the manifest. A plugin that asks for
+  capabilities needs `--yes`. `add` never replaces a local plugin, and a
+  plugin already added from another source must be removed first.
+- **`update <id> @<ref>`** fetches an added plugin again from its locked
+  source, and asks again (`--yes`) only when it wants more capabilities than
+  were approved. A tracking plugin can be updated without a ref.
+- **A `file://` source is refused.** A path on one machine must never reach
+  a committed lock: for your own plugin, put it in `plugins/<id>/` as a local
+  plugin; to try a published one before tagging, push a branch and use
+  `--track`.
+
+### Where plugins may come from
+
+`add` fetches from any git host unless `den.yml` (the product profile at the
+distribution root) lists the ones it allows:
+
+```yaml
+# den.yml
+product:
+  name: acme
+plugins:
+  allow:
+    - github.com/acme # <host>/<owner>
+    - git.acme.example # a bare host: every owner there
+```
+
+A source outside the list is refused before anything is fetched, and a value
+that is not a list of strings is an error rather than "allow everything".
+
+## Themes
+
+A theme is the web UI's look and feel: color tokens for dark and light, type,
+shape and a mark, in a `den-theme.json` that follows the
+[`den.theme/v1` schema](../schemas/den.theme.v1.json). Den ships its own theme
+(`den`). Others live in git repos; Monster-Orange/den-themes is the public set
+and the guide to making your own
+(<https://github.com/Monster-Orange/den-themes>).
+
+```sh
+<cli> theme add github.com/Monster-Orange/den-themes/themes/paper@paper/v1.0.0
+<cli> theme list
+<cli> theme validate path/to/my-theme
+<cli> theme remove paper
+```
+
+- `add` takes an exact ref: a tag or a full commit SHA. A branch is refused
+  unless `--track` (for theme authors), which the lock records as tracking.
+- It validates the theme (schema, contrast in both modes, files) and copies it
+  into the distribution's `plugins/<id>/`, with an entry in `plugins.lock.json`
+  (kinds `["theme"]`, source, ref, commit, content hash). A theme is a
+  plugin, so `theme add | list | validate | remove` are `plugin` filtered to
+  kind theme (see [Plugins](#plugins)): the same lock and directory, the
+  `file://` refusal and `plugins.allow`. Commit both: a fresh clone has the
+  theme offline, and theme changes show up as reviewable diffs.
+- `list` checks every theme against its lock and fails if one has changed.
+- A distribution can also keep its own theme in the repo: `<cli> theme new
+<id>` copies the built-in theme into `plugins/<id>/` to edit (or put one
+  there by hand), and committing it gives everyone on the repo the theme.
+  It is a local plugin: publishing it to a themes repo is only for sharing
+  it with other teams. `list` shows it as `local` and `validate` with no
+  argument checks it along with the added ones; `add` never replaces it.
+- Contrast: every text token (`text`, `muted`, `faint`, `accent-text`, and
+  the status colors) at 4.5:1 on every ground (`bg`, `surface`, `raised`,
+  `sunken`); `accent` and `border-strong` at 3:1; `on-accent` on
+  `accent-fill` at 4.5:1. `accent` is never text: Den draws links and accent
+  text in `accent-text`.
+- The mark is one image or text: `svg` (with `svg_dark`), `png` (with
+  `png_dark`) or `webp` (with `webp_dark`), or `text` (up to 3 characters).
+  A mark that gives two image kinds fails validate, naming both. Use a
+  raster only for a mark that exists only as one (one that must not be
+  vectorised): `validate` checks that the file is what its extension says
+  (the PNG signature, or `RIFF….WEBP`), is at most 64 KB, and is at least
+  44×44 px (twice the 22px mark in the top bar). An SVG mark may reference
+  nothing outside itself (every `href` and `url()` starts with `#`).
+- `favicon` (optional): the browser-tab icon, a `.png`, `.svg` or `.ico`
+  file in the theme, at most 64 KB, its format checked by its first bytes.
+
+```json
+"mark": { "png": "mark.png", "png_dark": "mark-dark.png", "shape": "circle" },
+"favicon": "favicon.png"
+```
+
+### The active theme
+
+The web UI draws every color, font and radius from the active theme. Which
+one is active:
+
+1. the engineer's own choice (`appearance.theme` in `config/local/user.yml`,
+   set from the header's theme menu);
+2. else the distribution's default, `brand.theme` in the org config;
+3. else `den`.
+
+```yaml
+# config/<name>.yml
+brand:
+  theme: paper # an id in plugins/<id>/ (locked or local), or den
+```
+
+An id that is not installed, or no longer validates under this Den, is
+skipped for the next choice, ending at `den`, with one warning in the server
+log; the UI never fails over a theme.
+
+Appearance is a per-engineer preference, stored with the other settings
+(`/api/settings`, `appearance`):
+
+```yaml
+# config/local/user.yml (gitignored)
+appearance:
+  theme: paper # omit to follow the distribution
+  mode: light # system (default) | dark | light
+```
+
+The Theme menu's first entry is "Org default (<name>)": it stores no theme
+(`appearance.theme` null, the same as omitting it), so you follow
+`brand.theme`, and a later `brand.theme` change reaches you. Picking a theme
+by name stores its id, even the theme that is the org default today: that
+pins it, and the menu shows it as "<name> (pinned)" rather than "Org
+default".
+
+`system` follows the OS (`prefers-color-scheme`), and the theme's
+`default_mode` when the OS gives none. The header's Mode and Theme menus save
+here and apply at once, without a reload. Changing either writes only that
+block: no edge route, edge config, service or the web service process is
+touched.
+
+What the server serves:
+
+- `/theme.css`: the active theme as CSS custom properties
+  (`:root[data-mode="dark"] { --bg: …; }` and the light block, plus `--sans`,
+  `--mono`, `--display`, `--ja`, `--radius`, `--radius-button` and
+  `@font-face` for the theme's fonts). Only a validated manifest is rendered.
+- `/theme/<id>/<file>`: only the files the manifest names (the mark's
+  `.svg`, `.png` or `.webp`, the favicon, the `.woff2` fonts), from that
+  theme's directory, each with its own type (`image/svg+xml`, `image/png`,
+  `image/webp`, `image/x-icon`, `font/woff2`).
+- `/theme-favicon/<id>?mode=light|dark&v=<version>-<hash>`: the theme's
+  browser-tab icon in that mode: its `favicon` in both modes, else its
+  mark's file (the dark variant in dark mode, if it has one, else the base
+  file), else (a text mark) Den's own icon. `/theme-favicon` with no id is
+  the active theme's, never cached.
+- `/api/themes`: every installed theme (id, name, version, `built-in` |
+  `locked` | `local`, ok), the active one (with its `mark` and its
+  `favicon` URL for each mode) and `org_default` (the theme no choice
+  draws: `brand.theme`, else den).
+
+Each page sets `data-mode` on `<html>` before first paint, and its styles use
+only the tokens: a page or plugin that draws in the UI uses `var(--token)`,
+never a color literal (`accent` is never text: `accent-text` is), and only
+`var(--sans)`, `var(--mono)` or `var(--display)` for a font (the fallbacks
+are in `/theme.css`: a stack with no generic family gets Den's after it).
+The header shows the active theme's mark: its SVG, PNG or WebP (the dark
+variant in dark mode, if it has one) as an image at 22px, a raster clipped
+to the mark's `shape`, or its `text` drawn by Den in `shape` on
+`accent-fill`. The browser tab shows the theme's icon for the mode the page
+draws in: the shell sets it (no page links one) and changes it with the
+theme or the mode, System following the OS included. Each URL carries the
+theme's id, version, mode and a hash of the file, so a switch is never
+answered from cache.
+A color from the org config (`orgs.<id>.color`) is only ever a swatch,
+border or dot, never text or a ground: labels are `--text` or `--muted`.
+Links in body content are underlined, so a link never reads by color alone.
+
 ## Workspace blueprint
 
 The workspaces a new machine starts with. Read from `defaults:` in the org
@@ -452,7 +891,8 @@ defaults:
       focus: true
 ```
 
-Each entry takes `repos`, `branch`, `autostart_off` and `org`, the same
+Each entry takes `repos`, `branch`, `autostart_off`, `org` and
+`stack_namespace` (see [Stack namespaces](#stack-namespaces)), the same
 fields as `defaults.workspace`, plus `focus`. Seeding creates every named workspace
 with its repos, activates them all, and focuses the one with `focus: true`
 (else the first). Set `defaults.workspace` or `defaults.workspaces`, not both:
@@ -592,10 +1032,78 @@ source and an org with no `sources` of that name), is an error naming both
 keys. Such an error stops every command that touches orgs, the catalog,
 clones or releases (exit 1, before any git call or write), and every web
 API route that reads the config answers it as 422 `{ "ok": false, "error":
-"<message>", "code": "config_invalid" }`. Without the new keys nothing
+"<message>", "code": "config_invalid", "requestId": "<id>" }` (0.3: with
+the `X-Request-Id` header; a page request gets the error page). Without the new keys nothing
 changes: `/api/orgs` is byte for byte what 0.2.7 answered. They need Den
 0.2.8 or later.
 
+## Stack namespaces
+
+A repo's compose stack runs as the Compose project `<stack>-<workspace>`,
+and its containers, volumes and networks are named from it. The `default`
+workspace uses `main` (`shop-main`), so its data predates workspaces. That
+is the default and needs no config.
+
+A workspace can opt out with `stack_namespace`, which replaces the suffix:
+
+```yaml
+# config/local/workspaces.yml (this machine)
+workspaces:
+  storefront:
+    stack_namespace: main # shop runs as shop-main, with default's data
+    services: { shop: { mode: dev-managed, path: ~/src/shop } }
+```
+
+```yaml
+# org config: on a blueprint workspace, next to org
+defaults:
+  workspaces:
+    storefront:
+      repos: [shop-web, shop]
+      stack_namespace: main
+```
+
+A workspace's namespace is the first of `stack_namespace` in
+workspaces.yml, `stack_namespace` on the blueprint workspace of the same
+name, and its own name (`default`: `main`). `acme workspace seed` writes
+the blueprint's value into the workspace it seeds. workspaces.yml
+overriding a different blueprint value is a warning naming both. The value
+is lowercase letters, digits and dashes; anything else is a config error
+that names the key.
+
+Workspaces with the same namespace share their stacks' projects, and so
+their data; a stack keeps its data when its repo moves between them. A
+shared project is one instance, keyed by checkout:
+
+- Two workspaces bringing up the same stack from the same checkout (repo
+  path and branch) share it. `acme down <repo>` or `acme stack down
+<stack>` from one, while another active workspace in the namespace still
+  holds it, detaches and leaves it running; the last one stops it.
+  `stack down --force` stops it regardless. A workspace that skips the
+  stack as already healthy counts as holding it too.
+- Bringing it up from a different checkout or branch is refused
+  (`identity_mismatch`), naming both checkouts and the namespace. Stop it
+  where it runs first, or give the workspace its own `stack_namespace`.
+
+A shared stack's identity is its checkout path, plus the branch only when
+the workspace entry pins one. Den does not read the checkout's HEAD, so a
+`git switch` in that checkout does not refuse its co-owners.
+
+`acme workspace list` adds a Stacks column when a workspace's namespace is
+not its default, the Workspaces page shows a "stacks: <ns>" chip in the
+workspace's header, and `GET /api/workspaces` gives `stackNamespaces`:
+each workspace's `stack_namespace`, its `source` (`workspace`, `blueprint`
+or `default`), its `default` and whether it `differs`.
+
+`DEN_STACK_WORKSPACE=<suffix>` overrides the suffix for one command
+(`DEN_STACK_WORKSPACE=pr-12 acme stack up shop` runs `shop-pr-12`). It wins
+over `stack_namespace` and bypasses the shared-project bookkeeping. It is a
+per-command override, not a migration tool: to keep a workspace on another
+namespace, set `stack_namespace`.
+
+`stack_namespace` in the blueprint needs Den 0.3.0-dev.36 or later: an
+older Den rejects the unknown key.
+
 ## Releases
 
 The Release page dispatches each repo's CD workflow on GitHub. A repo's
@@ -812,7 +1320,7 @@ port.
 ### Scoped to one workspace
 
 ```sh
-./bin/acme mcp --workspace smb --actor agent:planner
+./bin/acme mcp --workspace north --actor agent:planner
 ```
 
 `--workspace <ws>` and `--actor agent:<id>` (both or neither) scope the server
@@ -820,8 +1328,8 @@ 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>); "<other>" is another
-workspace`) before anything reaches the web server. A refused call is
+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.
 - **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
   take only `<ws>`'s services, `manifest_validate` takes only an absolute path
@@ -836,6 +1344,16 @@ workspace`) before anything reaches the web server. A refused call is
   entry gains `agent` and `workspace`, and the log line reads `· by
 agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
 <id>)` for every exec, run and sync.
+- **Granted.** `--grant <other>` (repeatable) also serves `<other>`, but only
+  when the org config's `agents.<id>.grants` lists it; otherwise the server
+  exits 2 (an agent can't grant itself one). A call naming a granted
+  workspace is reported to the web server before it runs, and its activity
+  entry names both (`workspace` and `targetWorkspace`; the log line reads
+  `▶ <tool> in workspace <other>, under a grant to agent:<id> of workspace
+<ws>`). `GET /api/activity?address=workspace:<ws>` lists these entries
+  under either workspace. `workspaces` lists `<ws>` and its grants, and tests run when either
+  is focused. Logs and `manifest_validate` stay on `<ws>`'s own services.
+  `agents start` passes an agent's grants for you (see [Agents](#agents)).
 - `<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
@@ -847,7 +1365,7 @@ calls the API itself (curl, a browser) is not held to its workspace. Enforcing
 the scope in the HTTP server is WS-3a, planned for 0.4. `mcp connect` still
 registers the unscoped server; to hand one agent a scoped server, add it to
 that agent's config yourself, for example in a project's `.mcp.json`:
-`"args": ["mcp", "--workspace", "smb", "--actor", "agent:planner"]`.
+`"args": ["mcp", "--workspace", "north", "--actor", "agent:planner"]`.
 
 ### One call from a shell
 
@@ -942,6 +1460,212 @@ authorise anything), and the MCP server's pid and session id. They travel as
 `acme/server` stream shows an agent's actions as `[agent]`, ending
 `· by agent <client> <version> (mcp pid <pid>, session <id>)`.
 
+## Sessions
+
+A session is a terminal that keeps running when the web server restarts:
+an argv in a PTY, owned by the distribution's **session host**. The host
+is one small detached process (`<cli> sessions host`) that the first
+client starts on demand; it serves `<stateDir>/sessions.sock` (mode 0600)
+and logs to `<stateDir>/logs/<cli>/sessions-host.log`. The state dir is
+the profile's `state_dir` (`~/.<name>`), or `<PREFIX>_HOME`.
+
+```
+<cli> sessions start --workspace <ws> --name <n> [--cwd <dir>] [--keep-env NAME…] -- <argv…>
+<cli> sessions list [-w <ws>] [--json]
+<cli> sessions attach <name|id>          # ctrl-] detaches; the session keeps running
+<cli> sessions kill <name|id> [--signal INT|TERM|KILL]
+<cli> sessions host [--stop]
+<cli> agents list -w <ws> [--json]
+```
+
+- A session is named `<dist>-<ws>:<n>`. `list -w <ws>` and `agents list
+-w <ws>` show that workspace's sessions only. Elsewhere a session can be
+  named in full, as `<ws>:<n>`, as a bare `<n>` only one session has, or by
+  its id.
+- It runs in `--cwd` (default: where you ran the command). Its environment
+  starts empty and gets only `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`,
+  `TERM` (default `xterm-256color`), `COLORTERM`, `LANG`, `LC_*`, `TZ` and
+  `TMPDIR` from yours; `start` names the variables it left out (names, never
+  values). `--keep-env NAME` adds one more: one exact name per flag,
+  repeatable, no globs. It is audited: the session host's log
+  (`<stateDir>/logs/<cli>/sessions-host.log`) gets a line naming each kept
+  variable and who asked, never its value, and says `credential-shaped` when
+  the value or name looks like a credential (it is still passed: you named
+  it). An agent can't use it: `agents start` has no `--keep-env`, and
+  `sessions start` refuses it when run by an agent (`DEN_AGENT` is set).
+  Every runtime's `scrubEnv` (den-claude: `CLAUDECODE`, `CLAUDE_CODE_*`) is
+  removed last, even a name you kept.
+- Every attachment gets all of its output; attaching prints `[attached to
+<name>]`, then replays the scrollback (2 MB per session, kept in
+  `<stateDir>/sessions/<id>.log`).
+- Stopping the host (`sessions host --stop`, or a reboot) ends its
+  sessions. They stay listed as exited, with their scrollback, until
+  `sessions kill` removes them.
+- `agents.max_concurrent` caps the sessions running at once (default 4):
+
+  ```yaml
+  agents:
+    max_concurrent: 4
+  ```
+
+- A PTY needs a native module, `@lydell/node-pty`, which Den lists as an
+  optional dependency (prebuilt binaries for macOS, Linux and Windows,
+  nothing downloaded at install). Without it (`npm install
+--omit=optional`, another platform) everything else works, and `sessions
+start` and `<cli> doctor` say why den-pty is unavailable.
+- A state dir whose socket path would pass 103 bytes (the unix socket
+  limit) is refused with that reason; point `<PREFIX>_HOME` somewhere
+  shorter.
+
+## Agents
+
+An agent is a **persona** (who) in a **workspace** (where), run by a
+**runtime** (which CLI) in a [session](#sessions), acting through Den's MCP
+server scoped to its workspace.
+
+```
+<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]
+<cli> agents list -w <ws> [--json]
+<cli> agents stop <id> [-w <ws>]
+<cli> agents resume <id> [-w <ws>]
+<cli> agents personas [--json]
+<cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
+```
+
+- `start` runs the agent as session `<dist>-<ws>:<id>` in the workspace's
+  checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
+  `agents.max_concurrent`. The id defaults to the persona's id; an id is
+  unique in the distribution, so a second workspace's planner gets
+  `planner-<ws>` unless you give `--id`.
+- The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
+  persona, runtime, model, workspace, cwd, session and times. It never holds
+  the environment or the command line. `list` reads it for persona, runtime
+  and model; a record whose session has gone is listed as `stopped` (after
+  `stop`) or `ended`.
+- `list` shows agents only: sessions with an agent record. A session from
+  `sessions start` is not an agent; `sessions list` shows it.
+- `stop` sends its session TERM and marks it stopped. `resume` works only
+  when the runtime declares resume and the session is not running: it starts
+  a new session in the same cwd that continues the last conversation. A
+  session that never got a prompt (no input with a line end) has no
+  conversation, so `resume` starts it fresh under the same conversation id
+  and says so.
+- After `start` or `resume`, Den watches the session for up to 3 s. If it
+  exits non-zero, Den prints the exit code and its last lines (at most 10,
+  secret-shaped values redacted) and exits 1.
+
+### An agent's environment
+
+An agent's environment starts empty and gets, in order:
+
+1. `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TERM` (default
+   `xterm-256color`), `COLORTERM`, `LANG`, `LC_*`, `TZ` and `TMPDIR` from
+   yours;
+2. the variables its runtime names (`envPassthrough`; den-claude:
+   `CLAUDE_CONFIG_DIR`);
+3. the runtime's launch env;
+4. `DEN_AGENT=agent:<id>`.
+
+Then every runtime's `scrubEnv` is removed (den-claude: `CLAUDECODE` and
+`CLAUDE_CODE_*`), whatever put it there. Nothing else of yours reaches it:
+not your tokens, not your shell's other variables, and not the Claude Code
+session you started it from (its session id, messaging socket and token,
+and the child-session marker that turns transcripts off). The agent record
+still holds no env. The agent's MCP server gets the distribution's location
+(`DEN_ROOT`, `<PREFIX>_ROOT`, `<PREFIX>_HOME`, when set) in its own config,
+so it reaches the same distribution.
+
+`<cli> doctor --probe` checks this through the real session host: it runs a
+short probe session for a plain session and for each available runtime's
+agent env (built as `agents start` builds it, running the probe instead of
+the runtime's CLI). The probe prints key names and whether each is
+credential-shaped, never values. Doctor exits 1, one row per finding, when a
+runtime's `scrubEnv` name or a credential-shaped variable reaches either.
+Without the PTY module it says the probe is unavailable; that is not a
+failure. Plain `doctor` never spawns anything; when agents are configured it
+adds a note to run `<cli> doctor --probe`.
+
+**What the scope does not do.** An agent's MCP scope binds cooperating
+agents only. A runtime with a shell can still run `<cli>` itself, outside
+the scoped MCP server, and reach other workspaces; WS-3a and SEC-1 close
+that later. And the user's own Claude Code settings and hooks
+(`~/.claude/settings.json`, its hooks, a project's `.claude/`) load in a
+den-claude agent, as in any `claude` you start.
+
+### Personas
+
+A persona is a markdown file: YAML front matter, then the role prompt. It is
+a Claude Code agent file, read as it is, plus a few keys of Den's own:
+
+```markdown
+---
+name: planner # the id (or `id:`; default: the file name)
+description: Writes stories and their acceptance criteria. # or `role:`
+model: some-model # optional; `inherit` means none
+tools: Read, Grep # hints for the runtime; Den restricts nothing with them
+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`
+argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
+---
+
+You are the planner. …
+```
+
+Den ships a default pack: `planner` and `orchestrator` (standing), `fe-dev`,
+`be-dev`, `devops`, `reviewer` and `ux-designer`. Add your own packs, read in
+order after Den's; a persona with the same id replaces the earlier one:
+
+```yaml
+agents:
+  persona_packs: [personas, ../some-plugin] # relative to the distribution root
+```
+
+A pack is a directory of persona files. A pack with an `agents/` directory
+inside (a Claude Code plugin) is read from there, so a plugin's agents are
+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.
+
+### Runtimes
+
+`<cli> doctor` lists the runtime kind. Two are built in:
+
+- **`den-claude`** (the default) needs `claude` on PATH; doctor reads its
+  version from the install, without running it. It runs `claude --session-id
+<id> --mcp-config <file> --strict-mcp-config [--model <m>]
+--append-system-prompt <role prompt>`, so Den's MCP server is the agent's
+  only one, and resumes with `claude --resume <id>`. Permission prompts stay
+  in the agent's terminal: it passes `--permission-mode default` unless the
+  persona's `permission_mode` sets one of `default`, `acceptEdits`, `plan` or
+  `bypassPermissions` (anything else is an error naming the key).
+  `bypassPermissions` prints a one-line warning at every start.
+- **`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.
+
+### Workspace scope and grants
+
+An agent's MCP config, `<stateDir>/agent-files/<id>/mcp.json` (0600), runs
+`<cli> mcp --workspace <ws> --actor agent:<id>`: the agent sees and acts on
+its own workspace only, and every action is recorded as `agent:<id>` (see
+[Scoped to one workspace](#scoped-to-one-workspace)). A grant widens one
+agent's scope. It is config in git, reviewed like code; an agent can't give
+itself one:
+
+```yaml
+agents:
+  planner:
+    grants: [other-workspace]
+```
+
+`start` then adds `--grant other-workspace`, and each call into it is audited
+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.
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that