@monster-orange/den 0.2.7 → 0.3.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,93 @@ 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):
+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: 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.
+```
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -421,6 +604,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 +886,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:
@@ -473,8 +908,14 @@ To see what a setup would clone before it clones anything, run
 `acme setup --plan`: each repo with its org and clone URL, and whether it
 is cloned yet. On a fresh machine it plans the blueprint (every workspace
 `acme workspace seed` would create); once seeded, the focused workspace.
-`acme up --plan` lists the same lines for the repos it would start. Both
-are read-only: nothing is cloned, seeded or written.
+`-w <workspace>` (repeatable) plans those workspaces instead, active or not,
+and `--all-active` every active one; on a fresh machine `-w` narrows the
+blueprint's plan. Repos that only workspaces outside the plan hold are named
+in a closing hint. A dev-managed repo shows the branch its checkout has out
+(read from its `.git/HEAD`), not a configured one. `acme up --plan` lists
+the same lines for the repos it would start, and exits 1 when nothing
+resolves (a name no workspace has, an empty workspace). Both are read-only:
+nothing is cloned, seeded or written.
 
 ## Orgs
 
@@ -523,6 +964,141 @@ its workspace's org is a warning in both lists, never an error.
 `org:` in the blueprint needs Den 0.2.7 or later: an older Den rejects the
 unknown key. Pin 0.2.7 before you commit it.
 
+### Sources and repos (0.2.8)
+
+An org is Den's own: its id is any key of `orgs:`, and it needs no git
+host. Two optional keys bind it to where its repos live:
+
+```yaml
+github_org: acme
+orgs:
+  acme-group: # one org, two GitHub owners
+    label: Acme Group
+    sources:
+      - { host: github, owner: acme }
+      - { host: github, owner: acme-labs }
+  globex-billing: # one owner split across two orgs
+    repos: [globex-invoices]
+  globex:
+    sources: [{ host: github, owner: globex }]
+  initech: # no git host at all
+    sources: []
+    repos: [widget]
+```
+
+- `orgs.<id>.sources` is a list of `{host, owner}` (or `{host, group}`). A
+  source claims that owner's repos for the org. `host: github` is built
+  in; any other host id (`gitlab`, …) claims repos whose `remote:` is on
+  `<host>.com` or a `<host>.` hostname, and clones them from that remote.
+- `orgs.<id>.repos` lists repos that belong to the org whatever their
+  owner.
+- An entry with neither key is what it was before 0.2.8: the GitHub owner
+  of its own name.
+
+The catalog (`config/local/service-catalog.yml`) takes a `remote:` for any
+host, beside `gh: owner/repo`, which stays as the GitHub shorthand:
+
+```yaml
+widget: { remote: git@git.initech.example:tools/widget.git }
+```
+
+A repo's org is the org whose `repos` lists it, else the org with a source
+that claims its owner, else its GitHub owner as before. That org is what
+`/api/orgs?repos=1` maps the repo to and what infers a workspace's org (step
+3 above). A claimed owner is not listed as an org of its own, and a
+`github_org` that names one makes the claiming org the default. Service rows
+(`/api/services`, `/api/health`) keep `org` as the repo's GitHub owner.
+
+A repo clones from its source: a GitHub source gives
+`https://github.com/<owner>/<repo>.git` with your `gh` as credential helper.
+A repo with no source that claims it clones and pulls from its `remote:`
+through plain git, with your own git credential helper; Den never hands it
+`gh` or any credential of its own. A remote must be `https://`, `ssh://`,
+`git://`, `file://`, `user@host:path` or an absolute path. `setup --plan`
+shows it as the clone URL, with any user info masked.
+
+An org with no GitHub source has no repo discovery (`register` lists
+nothing for it) and its repos are left off the Release page.
+
+These keys are checked when den.yml is read, and a bad value is an error
+that names its key (`orgs.initech.sources[0].owner must be …`). A repo
+listed by two orgs, or an owner claimed by two orgs' sources (or by a
+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", "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
@@ -736,6 +1312,46 @@ everyone's checkout is in the same place.
 `--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
 port.
 
+### Scoped to one workspace
+
+```sh
+./bin/acme mcp --workspace north --actor agent:planner
+```
+
+`--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>); "<other>" is another
+workspace`) 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
+  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).
+- **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
+agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
+<id>)` for every exec, run and sync.
+- `<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.
+
+**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
+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", "north", "--actor", "agent:planner"]`.
+
 ### One call from a shell
 
 ```sh