@monster-orange/den 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,1553 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.3.0] - 2026-11-06
+
+0.3.0-dev.31 and later include all of 0.2.7 (below).
+
+### Added
+
+- **R26a's 422 page: "Config is invalid"** (0.3.0-dev.40). A page
+  navigation with a config that fails validation gets the shell frame
+  with a table of each problem (file, key path, message), the command
+  that shows them in a terminal (`<cli> validate`), "Reload once fixed",
+  and links to Logs and Settings, in en, ja and es. The rail stays
+  usable: `/settings` and `/logs` load whatever the config holds, and so
+  do the routes the shell and those pages need (`/api/settings`,
+  `/api/themes`, `/api/scope`, `/api/workspaces/settings`,
+  `/api/sudo-password/status`, `/api/environments` (dev.41), besides `/api/server-info`,
+  `/api/server-log`, `/api/changelog` and `/api/web/restart`). Any other
+  page answers 422 with this page.
+  - Org config validation lists every problem, not the first: a
+    ConfigError carries `issues` (`{ file, key, message }`), its message is
+    one line per issue as each always read, and the 422 JSON body gains
+    `issues`.
+- **`up --dry-run` says what up will do about a pre-dev.37 record or a
+  held port** (0.3.0-dev.40, a consumer's dev.39 nit; it said only "Would
+  up"): "would adopt pid N (port P), nothing started", "would drop the
+  record (nothing running), then start it", or "port P held outside the
+  repo: would not start" (exit 1, as the real up). It signals nothing and
+  writes no record.
+- Everything in 0.2.8 (scoped MCP for agents, orgs that own their sources,
+  config validation that stops every command) is in 0.3.0.
+- **The UI in Japanese and Spanish** (0.3.0-dev.39, R19; R10's and R21's
+  Language).
+  - Catalogs for en, ja and es. en is shell.js's `MESSAGES.en`, the
+    fallback; ja and es are `public/i18n/<lang>.js`, which the server
+    loads before shell.js for a page in that language (with
+    `<html lang>`), so the first paint is already in it. Every lookup is
+    `t(key, vars)`; a `key.one` (any CLDR category) is the plural form
+    `Intl.PluralRules` picks for `n`, and numbers go through
+    `Intl.NumberFormat`.
+  - The language is a user pref, `language:` in `config/local/user.yml`
+    (absent: English), read and written by `/api/settings` (`ui_languages`
+    lists the choices; anything else is a 400). The user menu has a
+    Language section, each language named in itself, Settings → Appearance
+    a Language row, and ⌘K a "Language: …" command; a pick reloads the
+    page in it.
+  - The whole shell is converted: rail, top bar and scope menus, status
+    chip and drawer, ⌘K palette (its Settings rows too), Runs chip and
+    dock, lock popover, user menu, What's new, the stale-server pill and
+    restart overlay, the engine and network banners, the error toasts and
+    the 404 and 500 pages. The pages' own content (Workspaces, Graph,
+    Services, Logs, Tests, Environments, Releases, Edge and the Settings
+    page's rows) is still English: they move to `t()` page by page.
+  - Never translated: names (services, workspaces, repos, themes,
+    languages), logs, command output, run labels, and "Copy details"
+    (it is for a report, so it stays English).
+  - Guards: `i18n.test.ts` fails when any catalog lacks a key en has, has
+    one en doesn't, drops a placeholder, or uses a plural form its
+    language doesn't; when the code looks up a key en lacks; and when a
+    node-side `EN_FALLBACK` drifts from en. `i18n-shell.browser.test.ts`
+    draws the shell in a pseudo-locale with every overlay open and fails
+    on any word that skipped `t()`.
+  - English shows exactly what it did, apart from the new Language
+    controls.
+
+- **Errors people can see and act on** (0.3.0-dev.38, R26, Ward QA
+  2026-11-05: "we don't handle 500 or 404s from the den server with
+  anything remotely obvious ... just text").
+  - A page request that fails gets the shell frame (rail, top bar, status
+    chip) around an error page (`error.html`, `error-page.js`). 404 "Page
+    not found" shows the path, "Did you mean …" from the command palette's
+    own matcher (`rankCommands`), links to Workspaces and Search (⌘K) and
+    the list of pages; a path under `/plugins/<id>/` says which plugin it
+    belongs to and that it isn't installed. 500 "Something went wrong"
+    shows the method and route template (never query values), the time,
+    a request id, Retry and Copy details, and no stack: the server log
+    has it under the same request id (`✗ GET /route failed (req
+    <id>): …`). Assets and non-browser requests keep a plain 404.
+  - Every `/api/*` error is JSON, one shape:
+    `{ ok: false, error, code, requestId }` (`code`: `not_found`,
+    `bad_request`, `internal`, `method_not_allowed`, `engine_stale`, …). It
+    holds at the response for every route, whatever the route sends, and a
+    route's own fields (`runCmd`, …) are kept. Every response carries
+    `X-Request-Id`; a failed request's log line carries the id.
+  - `denShell.api(method, url, body?)`: the one client path for a call. It
+    resolves with the data or throws a typed error (`DenApiError`: status,
+    code, requestId, network); one no page catches becomes a toast with
+    the message, the request id, Retry and Copy details
+    (`denShell.errorToast`). The shell's own calls, the scope and focus
+    menus, Services' workspace panel, the Workspaces page's add, create,
+    delete, rename, auto-start, mode and open-in-editor/terminal actions,
+    Releases' config save and deploy start, and the log search use it.
+  - When fetches fail at the network level (the server stopped or is
+    restarting), a banner says "Den's server isn't responding — retrying",
+    retries with backoff (1 s doubling to 15 s, or Retry now), and clears
+    itself when the server answers; meanwhile the status chip reads
+    "Status unknown", never a stale green.
+- **A server older than the engine on disk says so** (0.3.0-dev.38, MD-2).
+  After a pin upgrades Den under a running web server, the server keeps the
+  old engine in memory while serving the new pages, so their new routes
+  404. The server records the engine's version and build id (a hash of its
+  package.json) at startup and compares them with the engine on disk on
+  page requests (cached for 3 s). On a mismatch every page leads with a
+  banner, "Den was updated to <new>. This server is still running <old>.
+  Restart it: `<cli> web restart` (or your service restart).", an unknown
+  route answers that message (`/api`: code `engine_stale` with `loaded`
+  and `onDisk`) instead of a 404, and a failed MCP tool call names both
+  versions and the restart. `/api/server-info` gains `loaded` and `onDisk`
+  (`{ version, buildId }`) and `engineStale`; its `version` is now the
+  engine the server runs.
+- **DOC-1: the README's screenshots, generated** (0.3.0-dev.40; `npm run docs:shots`,
+  `scripts/doc-shots.mjs`). Runs Den on a scratch copy of
+  `examples/distribution` with the `examples/demo` repos as its workspace (a
+  docker shim, a random localhost port, a throwaway HOME, and a server env
+  built from HOME, PATH and the DEN_* it needs, never the caller's), and
+  writes to `docs/images/<version>/` (package.json's version without the
+  prerelease suffix): `hero-dark.png` and `hero-light.png` (the Graph page,
+  2x), `social-preview.png`, `workspaces.png`, `graph.png`,
+  `status-drawer.png`, `edge.png`, `runs-dock.png`, the `make up`
+  animation (`up.gif` with ffmpeg, else `up.webp` with img2webp, else
+  skipped with a message) and `alt.json`, the alt text. Size budgets: hero
+  400 KB a theme, the rest 200 KB, the animation 5 MB; over budget, the run
+  fails. Nothing reaches the tree unless every shot passes.
+  - The capture guard (`scripts/doc-shots-guard.js`): before each shot, the
+    page's innerText, every title, alt, aria-label and placeholder, and SVG
+    text go through the org-name gate's own matcher, now shared
+    (`scripts/org-names.js`, used by `org-name-gate.mjs` too). A hit aborts
+    the run naming the shot and the term, never the text around it, and
+    writes no image; so does a path under the real HOME. Without
+    DEN_ORG_NAMES or DEN_ORG_NAMES_FILE the script refuses (exit 2);
+    `--unguarded` is for local layout work only.
+  - The images stay out of the npm package: `files` has `!docs/images/`,
+    and dist-smoke fails on any image in the tarball.
+- **`npm run docs:links`** (`scripts/docs-links.js`) checks that every
+  relative link in README.md and docs/ reaches a file and, with a
+  `#fragment`, a heading.
+
+- **`stack_namespace`: a workspace can choose its stacks' Compose
+  namespace** (0.3.0-dev.36, Ward 2026-11-05). By default nothing changes:
+  a stack runs as Compose project `<stack>-<workspace>` (`default`:
+  `<stack>-main`), and so do its containers, volumes and networks. A
+  workspace can opt out with `stack_namespace: <slug>`, which replaces that
+  suffix: several workspaces can then share one namespace, and a stack
+  keeps its data when its repo moves to another workspace.
+  - Where: `workspaces.<ws>.stack_namespace` in
+    `config/local/workspaces.yml`, or `stack_namespace` on a blueprint
+    workspace (`defaults.workspaces.<n>`, next to `org`). First match wins:
+    workspaces.yml, the blueprint, then the workspace's own name.
+    `workspace seed` carries the blueprint's value into the workspace it
+    seeds. workspaces.yml overriding a different blueprint value is a
+    warning naming both, as for `org`. The value is lowercase letters,
+    digits and dashes; anything else is a config error naming the key.
+  - One resolver: every stack path (`stack` commands, `/api/stacks`,
+    Den's in-process compose health checks, a stack service's container
+    lookup, `workspace deactivate`'s running-stacks note) turns a workspace
+    into its suffix through `resolveStackWorkspaces`.
+  - A shared namespace means a shared instance, keyed by checkout. Two
+    workspaces bringing up the same stack from the same checkout (repo
+    path and branch) share one project: `stack down` (and `down <repo>`)
+    from one while another active workspace in the namespace still holds
+    it detaches instead of stopping it; the last one stops it
+    (`stack down --force` stops it regardless). A workspace skipping the
+    stack as already healthy is recorded as an owner too. The owners are
+    kept in `owners.json` in the project's edge state directory, and
+    re-derived on every decision (active, same namespace, still holds the
+    stack), like Den's own service refcount. Bringing it up from a
+    different checkout or branch is refused (`ServiceConflictError`,
+    `identity_mismatch`), naming both checkouts and the namespace: Den
+    never swaps the containers under another workspace.
+  - Visible: `workspace list` gains a Stacks column when a workspace's
+    namespace is not its default; the Workspaces page header shows a
+    "stacks: <ns>" chip; `GET /api/workspaces` adds `stackNamespaces`, each
+    workspace's resolved `stack_namespace`, its `source` (`workspace`,
+    `blueprint` or `default`), its `default` and whether it `differs`.
+  - `DEN_STACK_WORKSPACE` still wins over all of it, for that one process:
+    a per-command override (it also bypasses the owner refcount), not a
+    migration tool. To move a workspace's stacks onto another namespace
+    for good, set `stack_namespace`.
+- **The graph's edges flow when a card is selected, and stay on top**
+  (0.3.0-dev.35, R22b, Ward's QA of dev.34). Selecting a card only
+  thickened its edges, and the edge layer painted under the group frames,
+  repo frames and cards, so an opaque frame hid an edge or an arrowhead
+  that crossed it (dev.34's routed cross-group edges too). The edge layer
+  now paints above the frames and cards, still taking no pointer events
+  (cards under an edge stay clickable). A highlighted edge carries a
+  marching-dash overlay, in its kind's colour, moving from the dependent
+  to its dependency (data-f to data-t) at about one cycle a second: a
+  selected card's dependencies flow out of it and its dependents flow in.
+  Under reduced motion nothing moves: a highlighted edge is drawn thicker
+  in the accent colour.
+- **Workspaces: Local Dev is an ops page** (0.3.0-dev.35, R24a–e, Ward
+  2026-11-05: "the UX is a bit of a kitchen sink"). One job: run your
+  workspaces.
+  - R24a: the rail item, the page title and its header read
+    **Workspaces** (same icon and place). `/` and `/local-dev` still serve
+    it; the palette finds it as "Local Dev" too. The nav label key is
+    `n.workspaces`.
+  - R24b: the "⚙ Settings" footer under the workspace list is gone; "+ new
+    workspace" stays.
+  - R24c: the selected workspace's header adds **Open in Graph →**
+    (`/graph?ws=<name>`) and a ⋯ menu: Workspace settings
+    (`/settings?ws=<name>#workspace`, the old "Settings ↗" tab), Rename,
+    Delete.
+  - R24d: **one repo table** replaces the Graph, Applications and Config
+    tabs. Per repo: the health dot and rollup ("2/2 healthy", or the
+    failing check), the branch, the mode with "use local / use managed",
+    the last run's result and time (from the runs dock), Start, Stop,
+    Restart, Logs (in the dock) and ⋯ (terminal, editor, auto-start,
+    clone, validate, remove). A repo with several services expands to a
+    sub-row each (keyboard: the ▸ button, `aria-expanded`). Problems sort
+    first, then the startup order, with the fix inline: the status
+    drawer's text and Start/Logs buttons, from one source
+    (`topbar.js problemFix`). **Group by** None, Application (as `den
+    apps`, each application's Up/Restart/Down in its row) or Org, a user
+    pref (`graph.groupBy`). **Find** uses the Graph page's matcher. "+ Add
+    repo" sits under the table; "Validate a manifest" folds under it. The
+    empty state is unchanged. A real `<table>` with `th scope`; every
+    action button is named with its repo or service.
+  - R24e: on Workspaces the runs dock shows the selected workspace's runs
+    (a run belongs to every workspace that has its repo; one with no repo,
+    such as Sync, always shows), with an **All runs** toggle in the bar.
+    `denShell.runs.scope({ ws })`, and `runs.add(…, { ws })` tags a run.
+  - Not changed: the Graph page, Services, Settings and every API; no
+    consumer config needs a change.
+
+- **The Graph page** (0.3.0-dev.32, R22, Ward 2026-11-05). Develop ›
+  Graph, after Local Dev, at `/graph`: the workspace graph alone, full
+  width under its page header, with the same toolbar, zoom, Maximize
+  (which now hides the page header too) and details panel as Local Dev's
+  Graph tab. It shows the workspace Local Dev would (`?ws=`, else the
+  view scope when it is one workspace, else the focus). Local Dev keeps
+  the workspace list, the workspace's actions and its tabs, Graph tab
+  included. Overview and Security stay out for now.
+- **A page header on every page** (0.3.0-dev.32, R20). The shell draws the
+  prototype's `.ph` on each page that has no header of its own: the page's
+  title (`600 22px/1.2`, its one h1, which used to be visually hidden) and
+  a 13px muted line with the scope, `org / workspace / env`, kept in step
+  with the top bar (Local Dev and Graph name the workspace they show). Pages
+  keep their content below it. `denShell.pageHeader()` gives a page the
+  header's `act` (the primary action, at the end) and `tabs` (`.ptabs`,
+  below it), and `setScope` / `setSub` for the line. Local Dev's workspace
+  tabs are page tabs now: real tabs (`role="tab"`, `aria-selected`) at the
+  prototype's sizes (8px 12px, 14px, a 2px accent rule under the selected
+  one).
+- **The stacks' routes on the Edge page and in `edge routes`**
+  (0.3.0-dev.32, from a consumer). The routers Den writes into
+  `edge/dynamic/stack-*.yml` when a stack comes up are neither Den's host
+  routes nor `edge include` files, so nothing listed them. They are listed
+  last, source "stack" with the file; `/api/edge` adds `stacks` and
+  `stackErrors` (a file that doesn't parse is named, never fatal).
+
+- **The runs dock** (0.3.0-dev.30, R16). One output dock for every page, at
+  the foot of the content column, ported from the shell prototype: a bar
+  with "Runs", the run tabs (12px mono, a dot that pulses while running,
+  red when the run failed) and Show/Hide runs; open, a 170px output. The
+  Runs chip (R7) shows and hides it and counts the running tabs; an empty
+  dock links to the page that ran the last run. The bar carries Copy and
+  Clear for the selected run, a tab closes with its × (or Delete), ←/→ move
+  between tabs, and the dock's top edge drags to resize it. Pages and
+  plugins use one path, `denShell.runs` (`start`, `append`, `finish`, `set`,
+  `select`, `clear`, `remove`, `show`/`hide`/`toggle`, `list`, `onChange`);
+  a run started there gets "✓ done in {s}s" when it finishes. Since R16a
+  (below) the dock starts collapsed and open/closed is a user pref.
+- **The Edge page** (0.3.0-dev.30, PL-SPEC §10). A built-in page in the
+  rail's Ship group, shown once `/api/edge` reports the edge configured
+  (`/api/edge?probe=1`, which asks no Docker). Read-only: the container and
+  its ports, the TLS strategy (`edge.tls`: none, mkcert or files) with
+  where it came from (set, mapped from the legacy keys, or implicit), CA
+  trust and the CA's directory, the cert and its names, the domains, and
+  every route: Den's own, then the routers in the included dynamic files
+  (`edge include`), each marked by its source file.
+- **Room for Local Dev's graph** (0.3.0-dev.30, R23, Ward QA 2026-11-05).
+  The workspace list, the output and two toolbar rows left the graph at 40%
+  Fit. The workspace list now collapses to a 40px strip (« in its header;
+  » brings it back), remembered per user (`graph.workspaces`: `open` or
+  `collapsed`, on the Settings page under Graph). A Maximize button in the
+  graph's zoom group, or `F` with focus outside a field, hides the list,
+  the workspace header, the action row and the tabs; Esc restores. Fit
+  measures the whole area, so its zoom rises once maximized.
+- **Included routers in `edge routes` and `/api/edge`** (0.3.0-dev.30,
+  PL-SPEC §10, from a consumer review). Routers defined in the distribution's
+  included dynamic files are served by Traefik but were never listed. Den
+  now reads their `http.routers` (read-only) and lists them after its own
+  routes with their source file; `/api/edge` adds `included`,
+  `includedErrors` (a file that doesn't parse is named, never fatal) and
+  `tls.from` / `tls.ca`. The rendered edge config is unchanged.
+
+- **`<cli> relocate <repo> <path>`** (0.3.0-dev.26, from a consumer). A
+  checkout moved on disk: every workspace's dev-managed entries for the repo
+  (bare and `<repo>/<svc>`) now point at the new path, keeping each entry's
+  other settings. Managed entries (Den's own clones) are left alone, and focus
+  and the active set never change. It refuses a missing path, one whose
+  manifest name or GitHub remote names a different repo, and a repo no
+  workspace has. Since 0.3.0-dev.27 (from a consumer's dev.26 run) it also
+  refuses a folder where nothing names the repo (an empty or unrelated
+  folder): the manifest name, or the GitHub remote against the catalog's
+  `gh` (or the repo name when the catalog has none), must match.
+  `--force` accepts such a folder. The refusal's `--force` hint keeps
+  `--dry-run` and `-w` when given (0.3.0-dev.28). `--dry-run` shows the changes without writing; `-w` limits it
+  to one workspace.
+- **`<cli> register <path> -w <workspace>`** (0.3.0-dev.26). `-w` writes that
+  workspace, active or not, and leaves focus alone. It used to fail with
+  "-w/--workspace is not valid with register". The no-TTY usage line names `-w` too
+  (0.3.0-dev.27).
+
+- **The "What's new" pop-up shows the newest release only** (0.3.0-dev.16).
+  A "Show all versions (N earlier)" button in its footer lists every
+  earlier version in the same pop-up, and "Show latest only" collapses it
+  again. It always opens collapsed, at the top.
+- **Themes (`den.theme/v1`).** The contract is `schemas/den.theme.v1.json`:
+  color tokens for dark and light, type, shape, a mark and self-hosted fonts.
+  `<cli> theme add <repo>[/<subpath>]@<tag|commit>` validates a theme and
+  vendors it into the distribution (`plugins/<id>/`, `plugins.lock.json`, shared with future plugin kinds). `theme add` never replaces a plugin dir it did not vendor (a local, unlocked plugin) or another kind's lock entry; `theme list` fails on a leftover 0.3.0-dev.0 `themes.lock.json`, naming it; `theme add` refuses a `file://` source (0.3.0-dev.7, below). A theme's and a font's `license` follow one rule: an SPDX expression, never UNLICENSED/NONE. `theme list` reports a theme that fails this Den's rules as "no longer valid" with the reasons, apart from "changed since it was added"; validate explains the license and CSS-value rules instead of printing "must NOT be valid". Local themes (the distribution's own, in `plugins/<id>/` with no lock entry) are listed as `local` and validated; `theme validate` with no argument checks every installed theme; `theme new <id>` starts a local theme from the built-in one;
+  `theme list` checks themes against the lock; `theme validate` and `theme
+  remove`. Contrast is checked per pair in both modes. A branch ref needs
+  `--track`. Den bundles its own theme, `den` 2.0.0. The public set and the
+  authoring guide: https://github.com/Monster-Orange/den-themes. See "Themes"
+  in `docs/distributions.md`.
+- **The web UI is themed (0.3.0-dev.5).** Every page draws its colors from
+  the active theme, in dark or light: the engineer's choice (user.yml
+  `appearance: { theme, mode }`, from the header's new Mode and Theme menus),
+  else the org config's `brand.theme`, else `den`; an unknown or invalid id falls
+  back with one server-log warning. The server serves `/theme.css`,
+  `/theme/<id>/<file>` (only the files the manifest names) and `/api/themes`.
+  Switching writes user.yml only (no edge, services or restart). No page,
+  stylesheet or UI script hard-codes a color any more (a test holds that).
+  The header's version pill shows the running build, prerelease suffix
+  included (`v0.3.0-dev.5`, not the changelog's `v0.3.0`).
+- **Plugins (`den.plugin/v1`, PL-1a and PL-2a, 0.3.0-dev.7).** The contract
+  is `schemas/den.plugin.v1.json`: `id`, `name`, `version`, `license` (the
+  theme schema's SPDX rule, by `$ref`), `den` (a version range, required),
+  `maintainer`, `readme`, `provides` (one entry per extension point: `theme`
+  with its `manifest`, `page` with its `entry` and `nav`, and the other kinds
+  by name) and `capabilities` (a closed vocabulary: `ui.nav`, `api.read`,
+  `api.actions:`, `secrets:`, `net:`, `exec:`, `send:`). A directory holding
+  only a `den-theme.json` is an implicit theme plugin, so every theme keeps
+  working. Every `plugins/<id>/` is a plugin: **local** when it has no lock
+  entry (the distribution's own, any kind; being present is its approval),
+  **added** when `plugin add` vendored it. A `plugins/<id>/` with neither
+  manifest is an error in `plugin list` and `plugin validate`, never
+  skipped, as are the id `den` and a directory name that is not an id.
+  - `<cli> plugin list`: every plugin with its version, kinds and `local`
+    or its source and ref; added ones are checked against the lock's hash
+    (as `theme list` does).
+  - `<cli> plugin validate [dir]`: every local and added plugin, or one dir
+    (a plugin, a distribution, or a repo of `themes/<id>/` and
+    `plugins/<id>/`). Admission rules: a `maintainer` (1); a browser- or
+    server-tier plugin's README names its tier and says what it must never
+    do (2; themes are exempt); an SPDX license and licensed fonts (3). A
+    local plugin that declares `api.actions`, `secrets`, `exec`, `net` or
+    `send` and has files git has not committed gets a warning (never an
+    error): committing it is its review.
+  - `<cli> plugin add <repo>[/<subpath>]@<tag|commit> [--track] [--yes]`,
+    `plugin update <id> @<ref>` and `plugin remove <id>`. The lock entry's
+    `kinds` and `approved_capabilities` come from the manifest; a plugin that
+    asks for capabilities needs `--yes`, and `update` asks again only when the
+    set grows. `remove` and `update` are for added plugins: a local one is
+    edited or deleted in git. A den-plugin.json plugin is vendored whole
+    (every file but dot-files); a theme still vendors only its named files,
+    so existing lock hashes still match.
+  - `add` and `update` refuse a `file://` source: "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". This replaces 0.3.0-dev.2's
+    warning.
+  - `plugins.allow` in `den.yml` lists the `<host>/<owner>` pairs (or bare
+    hosts) `add` may fetch from. Absent: any host. A malformed value is an
+    error.
+  - `theme add | list | validate | remove` are `plugin` filtered to kind
+    theme, with the same output and exit codes; `theme new` is unchanged.
+    The web UI also finds a theme a `den-plugin.json` provides.
+  See "Plugins" in `docs/distributions.md`.
+- **PL-SPEC draft-4 rulings (0.3.0-dev.8).**
+  - Rule 1 covers themes: a bare `den-theme.json`'s `author` is its
+    maintainer, and a theme plugin without one fails `plugin validate`.
+    `theme new` sets the author to the brand's name.
+  - The `den` range is checked (semver, prereleases included).
+    `plugin validate` and `theme validate` fail a plugin whose range
+    excludes the running Den, naming the range and the version. At load,
+    the web UI skips such a theme, whether the range is in its
+    `den-theme.json` or in the `den-plugin.json` that provides it, with one
+    server-log notice, and draws with the next choice (yours, then
+    `brand.theme`, then `den`). It never crashes. Den now depends on
+    `semver` (pinned).
+  - `plugin list` and `theme list` warn, never fail, about a lock entry
+    with a `file://` source (from 0.3.0-dev.2), and say how to fix it.
+- **`plugin validate <id>` and `theme validate <id>` mean `plugins/<id>/`**
+  (0.3.0-dev.8). An id that names a dir in `plugins/` or a lock entry is
+  never read as a cwd-relative path. A bare name that isn't an id (such as
+  `x`) means `plugins/x/` when no such path exists. Anything else is a path,
+  as before. `theme validate den` checks the built-in theme. `theme
+  validate <id>` of a plugin that isn't a theme gives one ✗.
+- **The theme reaches the type, the mark and links.** Every page draws text
+  in `var(--sans)` / `var(--mono)` / `var(--display)` (no page names a font
+  any more; a test holds that, like the color rule), so a theme's fonts
+  apply; `/theme.css` ends a theme's stack with Den's when it has no generic
+  family. The header shows the active theme's mark (SVG, `svg_dark` in dark
+  mode, or text in its `shape`) and redraws it on a live switch; favicon.ico
+  stays the favicon. Links in body content are underlined (subtly, in a tint
+  of their own color), so a red accent never makes a link read as an error.
+- **Back to the org default.** The Theme menu starts with "Org default
+  (<name>)", which stores `appearance.theme: null`, so you keep following
+  `brand.theme`. Picking a theme by name stores its id, even the theme that
+  is the org default today (0.3.0-dev.11; dev.8 stored null for it): that
+  is a pin, selected as itself and labelled "<name> (pinned)".
+  `/api/themes` gives `org_default`. The popover's controls are named
+  (Mode, Theme; the button is "Appearance" with `aria-expanded` and
+  `aria-controls`); Escape closes it and returns focus to the button.
+
+- **What fails `validate` never loads (0.3.0-dev.9).** The theme runtime's
+  verdict is now `plugin validate`'s for the whole plugin. That covers a bare
+  `den-theme.json`'s `author`, a `den-plugin.json`'s `maintainer`, README,
+  capabilities and `den` range, and the theme contract. A theme that fails
+  is left out of the Theme menu (even when it is your stored choice: you then
+  follow the org default) and is skipped at load with one server-log notice.
+  The fallback is the same as for the range: yours, then `brand.theme`, then
+  `den`. `/api/themes` still lists it, with `ok: false` and the problem.
+- **A prerelease Den explains a range without `-0` (0.3.0-dev.9).** When
+  the running Den is a prerelease and only that keeps the range from
+  matching, the refusal adds "prerelease builds need a -0 range, e.g.
+  >=0.3.0-0", built from the range's own lower bound.
+- **The left rail: grouped, pinnable, collapsible** (0.3.0-dev.17, R11,
+  R11a, R12, R13, R14). Pages sit under Develop (Local Dev, Services, Logs),
+  Verify (Tests) and Ship (Environments, Releases), with Settings at the
+  foot. Groups and items come from one registry in `shell.js`;
+  a distribution adds its own with `denShell.registerGroup({id, label,
+  order, tag})` and `denShell.registerNav({group, id, label, href, icon,
+  order, badge})`, and its labels with `denShell.addMessages(lang, {...})`.
+  - **Pinned**: ☆ on a Services card or in the graph's details pins a repo
+    or service to the top of the rail with its health dot ("Pinned shop");
+    × or Delete on the pinned row unpins it.
+  - **Badges**: Services shows how many services are down, live from the
+    health row; Logs how many log streams are open.
+  - **Collapse** (« at the foot) narrows the rail to its icons, 216 to 56px;
+    the headings and labels stay for screen readers. Under 720px the rail is
+    a drawer behind ☰.
+  - Pins and collapse are stored in user.yml `shell` (`GET`/`POST
+    /api/settings` `shell: {pins, collapsed}`); setting them changes nothing
+    else (the theme-switch isolation test covers it).
+- **The shell matches the prototype's sizes** (0.3.0-dev.17, R1, R2, R3,
+  R9, R10): one 48px top bar with the brand, the workspace pill and Env as
+  key + value buttons, the health row as a chip, "What's new" and the ◐ ▾
+  menu (now with "All settings"); the rail's type, spacing and current-page
+  bar. `scripts/shell-fidelity.mjs` measures the real pages against the
+  prototype at 1440 and 1024 (1px, 0.5px for type) and lists any allowed
+  difference with its reason.
+
+- **The scope breadcrumb is three menus** (0.3.0-dev.18, R4): `/ ORG
+  <org> ▾ / WORKSPACE <ws> ▾ / ENV <env> ▾`, each the prototype's `.ib`
+  button with a `.pop` menu (✓ on the current entry). The menus are ARIA
+  menus: ↓ or Enter opens one, ↑/↓, Home and End move, Enter picks,
+  Escape (or Tab) closes it and gives focus back to its button, and a
+  click outside closes it. They replace the workspace pill and its menu,
+  the env select, the interim View select and Services' own workspace
+  select. Below 860px the keys, separators and the org hide; below 720px
+  the scope does (the narrow layout, R11b, comes later).
+  - **Org:** one org is a static label with no ▾, as before (ORG-SPEC
+    C4). `denShell.setOrgs([{ id, title, workspaces? }], current,
+    onSelect?)` turns two or more into an Org ▾ menu; a pick calls
+    `onSelect(id)` and fires `den:org` on window. Nothing feeds it a list
+    yet: ORG-1b plugs `/api/orgs` in.
+  - **Workspace:** the view scope. "All active (N)" (with two or more
+    active) and each active workspace, the focused one tagged `focus`.
+    Picking one stores the view (user.yml `view`, `POST /api/scope`) and
+    reloads the page; it never moves the focus. A separate "Set <ws> as
+    focus" item (when the workspace in view isn't the focus) does Local
+    Dev's focus action, and "Manage workspaces…" opens Local Dev.
+  - **Env:** the same envs, value and browser storage as the select it
+    replaces; `#env-sel` stays (hidden) as the value pages read and the
+    `change` event they listen for.
+- **A view scope: all active workspaces, or one** (0.3.0-dev.18). The
+  health row covered every active workspace while Services, Tests, Logs
+  and `status` showed only the focused one, so the row above a page listed
+  repos the page didn't. One source now says which repos are in view
+  (`src/shared/environment-manager/scope.ts`), and the health row,
+  `/api/services` (every page's list) and `<cli> status` all read it.
+  - "All active" is the default: it is what the health row already showed,
+    and with one active workspace it is the same view. A scope that is no
+    longer active falls back to all, never to an empty page.
+  - **The view is not the focus.** The focus stays the default target for
+    commands; the view only filters what pages show. Switching it writes
+    user.yml `view` and nothing else: no edge route, container, daemon or
+    workspaces.yml change, and the server doesn't restart (the
+    theme-switch isolation test covers it). `GET`/`POST /api/scope`.
+  - **A shared service is listed once, with its owners**: a repo that two
+    workspaces in view define shows one card (`shop · ws-a, ws-b`) and one
+    health dot, its deps and auto-start from the first (focus first).
+    `/api/services` rows carry `inWorkspaces`, `/api/health` rows carry
+    `workspaces`.
+  - **`<cli> status`** shows the same view and says so ("Scope: all active
+    (a, b, c) · focus: a"). Use `--scope <workspace>` for one (`--all`
+    already means `--verbose` there); `-w <workspace>` still checks that
+    one workspace.
+  - Local Dev edits one workspace at a time: it opens on the view's
+    workspace when that is one, else the focus.
+- **A ready path for distribution scripts** (0.3.0-dev.18). A script that
+  loads before shell.js pushes functions onto `window.denShellQueue` (an
+  array); each runs with `denShell` once the shell exists, and a later push
+  runs at once. `den-shell:ready` fires on window when the shell is up.
+- **`den:pins`** (0.3.0-dev.18): any pin change fires it on window
+  (`detail.pins`), and every pin toggle on the page repaints from it.
+- **`org.title_source`** in `/api/<cli>/config` (0.3.0-dev.18; added beside
+  the existing fields, ORG-SPEC C3): `org.title`, `orgs`, or `id`.
+- **A Settings page** (0.3.0-dev.19, R21): `/settings`, in the shell,
+  with the prototype's page header, sections, rows, segmented buttons,
+  swatches and navigation list, applied to every setting Den has.
+  - **Categories** on the left (a nav; the current one `aria-current`),
+    their rows on the right: Appearance, Editor & terminal, Navigation,
+    Graph, Workspace, Command line, Distribution, then any a distribution
+    or plugin registers (tagged with its `from`).
+  - **Search** (`/` focuses it) filters rows by label, description and
+    keywords; a match stays under its category's heading, empty
+    categories hide, "No settings match" shows when nothing does, and the
+    count is announced. The URL keeps `#<category>` and `?q=`, so a
+    setting can be linked to; reload and back/forward work.
+  - **Every row shows its scope**: User (config/local/user.yml),
+    Workspace (that workspace in config/local/workspaces.yml) or
+    Distribution (read-only). The Workspace rows follow the Workspace you
+    view; with All active, the section asks which workspace.
+  - **Writes go only to per-user, gitignored state**, as before:
+    `POST /api/settings` (user.yml) and `POST /api/workspaces/settings`
+    (workspaces.yml), with the same keys. Nothing writes except an
+    explicit change: a control writes on its change (the per-workspace
+    editor on Save, as before) and says "✓ Saved". Loading, searching,
+    moving between categories and changing the hash or query write
+    nothing. The page never writes the distribution's config.
+  - **Distribution rows are read-only**: the product name, GitHub org, org
+    labels, web port, environments, edge domain and the org default theme,
+    each with "Set by the distribution in config/<file>.yml". Your own
+    override of the same thing (your theme) is a separate User row.
+    `GET /api/settings` gains `distribution` (read from the org config
+    only), `user_web_port`, `local_dev` and `cli_tabs` (read-only).
+  - **Today's settings moved in, unchanged in storage**: Default IDE,
+    Per-language IDE and Default terminal (Local Dev's ⚙ panel); mode and
+    theme (◐ ▾ stays as a shortcut, and both drive the same prefs and
+    repaint each other); the graph prefs; the per-workspace editor (Local
+    Dev's workspace Settings tab). `log_window_lines`, `local_dev`,
+    `cli_tabs` and your `web.port` show read-only with the command that
+    sets them.
+  - **Navigation** (new): hide or show each rail page and move it within
+    its group; reorder and unpin pins; collapse the rail. Stored in
+    user.yml `shell` as `hidden` and `order` (page ids), beside `pins` and
+    `collapsed`. A view preference only: no edge route, container, daemon,
+    pid or restart changes (the theme-switch isolation test covers it).
+  - **The old entry points land on the matching category**: Local Dev's
+    ⚙ (`#editor`), its workspace Settings tab (`#workspace`, that
+    workspace), `/local-dev?settings=1` (redirected to `#editor`), the
+    rail's Settings item and "All settings" in ◐ ▾ (`#appearance`). The
+    old panel is gone. Arriving at a category (a link, the hash,
+    back/forward) marks it current and puts focus on its heading.
+- **The SETTINGS registry** (0.3.0-dev.19, R21), beside NAV and GROUPS on
+  `window.denShell` (and through `window.denShellQueue`):
+  `registerSettingsCategory({ id, label, order, description?, from? })`
+  and `registerSetting({ id, category, label, description, keywords,
+  scope: user|workspace|distribution, control, read(ctx), write?(value,
+  ctx), keys? })`; `settings()`, `settingsCategories()`; `den:settings`
+  fires on any change. A distribution row with a `write` is refused.
+  Controls: `seg`, `radio`, `select`, `number`, `toggle`, `text`,
+  `readonly` and `custom` (`render(el, ctx, { value, save })`). Den's own
+  rows are in `public/settings-registry.js`; a test fails if a key
+  `POST /api/settings` accepts has no row.
+- **`denShell.setNavPrefs({ hidden?, order? })`, `setPins(ids)`,
+  `setCollapsed(bool)` and `orderedNav()`** (0.3.0-dev.19): the rail's
+  Navigation prefs, saved to `/api/settings` `shell`.
+- **The top bar's search, status, runs and lock** (0.3.0-dev.20, R5, R6,
+  R7, R8, R10, R15, R17, R18). It ships together with the Settings page
+  (dev.19, never released on its own): the palette finds every setting,
+  and the user menu's "All settings" opens it. The bar now reads ☰, brand, scope, search,
+  then the Status, Runs and lock chips, "What's new" and the ◐ ▾ menu, at
+  the prototype's sizes (`scripts/shell-fidelity.mjs` measures it). The
+  search field gives way first, so the scope's parts never run into each
+  other; below 960px the scope's keys hide (860px in the prototype, whose
+  chips are narrower), below 860px the chips keep only their dots and
+  icons, and below 720px the scope hides and the search field is an icon.
+  - **Search and the ⌘K palette.** "Search pages, services, actions…"
+    (⌘K or Ctrl+K anywhere, or a click) opens a palette: pages, apps,
+    services with their health dot, Restart and Logs for each service,
+    Appearance (System, Dark, Light) and every installed theme. It ranks a
+    label's prefix, then a word in it, then anywhere, then keywords and
+    the kind, then the letters in order; every word must match. ↑/↓ move,
+    Enter runs, Escape closes and gives focus back. It is a modal dialog
+    with a combobox and a listbox (`aria-activedescendant`).
+  - **`denShell.registerCommand({id, label, keywords, kind, run})`**
+    (also from `window.denShellQueue`) adds a palette row; `kind` is
+    `page`, `app`, `service`, `action` or `setting`. Every row of the
+    SETTINGS registry (Den's, a distribution's or a plugin's) is a
+    `setting` row on every page: "terminal" finds Default terminal, and
+    Enter opens `/settings?q=<label>#<category>`.
+    `unregisterCommand(id)` and `commands()` too. `denShell.openMenu(btn,
+    items)` opens a `.pop` menu any script can use.
+  - **The status chip** replaces the health dot row and its "+N" chip:
+    "All N healthy", or "ok/N healthy · k down" with a bad border, from the
+    same rollup as the rail's Services badge. It shows "Checking…" until
+    the first cycle is in and paints once: no partial red on a cold load.
+    A pending check is pending, never down.
+  - **The status drawer** (the chip opens it): a right-hand modal panel,
+    focus on ✕, Escape back to the chip. "Needs attention" has one card
+    per down service, with what was checked, the error and when, and
+    Start, Logs and Pin; "Everything" lists each application ok/N, each
+    service with its time in ms. What the row's tooltips said is in each
+    row's title.
+  - **The Runs chip** counts the runs this page started (service and
+    workspace commands, syncs, test runs, deploys; not log tails), with a
+    pulse while one runs. Until the output dock (dev.21) it shows the
+    page's own output pane (marked `data-den-output`), else links to the
+    page of the last run.
+  - **The lock chip** (🔒 Locked / 🔓 Unlocked) holds the admin-password
+    form that was Local Dev's sudo banner, with Save to 1Password, in a
+    popover: "Den asks once per session. Agents can't unlock." It is the
+    one unlock on every page; the banner is gone. Local Dev still asks
+    1Password for a stored password on load; other pages ask only when
+    the popover opens. Start and Restart from the drawer or the palette
+    follow the same lock rule, then run on Local Dev (which runs them on
+    arrival when you are on another page).
+  - **The user menu** (◐ ▾) is the prototype's `.pop`: Appearance, Theme
+    and "All settings" (`/settings#appearance`), and a hidden slot for
+    Language. Its ◐ ▾ glyphs are hidden from screen readers; its name is
+    "Appearance". Opening any of these overlays writes
+    nothing; switching appearance or theme from the menu or the palette
+    writes user.yml `appearance` only (the theme-switch isolation test
+    covers it).
+  - `header.js` exports `requireUnlock`, `isUnlocked`, `onLockChange`,
+    `setServiceRunner` and `takePendingAction` for pages.
+  - **One h1 per page**: the brand title in the bar is a span now, not an
+    h1, so a page's own heading is its one. A page with none (Services,
+    Logs, …) gets a visually hidden h1 named from its title.
+- **Raster theme marks** (0.3.0-dev.22): a mark can be a PNG or a WebP
+  (`png` / `png_dark`, `webp` / `webp_dark`), for a mark that exists only
+  as a raster. One image kind per mark (svg, png or webp): two fail
+  validate, naming both. `theme validate` and `theme add` check each file's
+  first bytes against its extension, a 64 KB cap and at least 44×44 px
+  (twice the bar's 22px mark), reading the PNG or WebP header itself.
+  `/theme/<id>/<file>` serves them as `image/png` and `image/webp`, still
+  only the files the manifest names. The top bar draws one as an image at
+  22px, clipped to the mark's `shape`, the dark file in dark mode. SVG and
+  text marks are unchanged.
+- **The browser tab shows the theme's icon** (0.3.0-dev.22): the theme's
+  new optional `favicon` (`.png`, `.svg` or `.ico`, magic-byte checked, at
+  most 64 KB), else its mark's file (the dark variant in dark mode), else
+  Den's own icon. The shell sets it on every page (no page links
+  `/favicon.ico` any more) and changes it with the theme and the mode,
+  System following the OS included. Its URL,
+  `/theme-favicon/<id>?mode=<mode>&v=<version>-<hash>`, changes with each,
+  so a switch is never answered from cache. The built-in `den` theme names
+  Den's icon as its `favicon`; `theme new` leaves it out, so a new theme's
+  tab shows its own mark.
+- **Secrets backends are registered strategies, and `none` is one**
+  (0.3.0-dev.23). Each built-in (`none`, `env`, `doppler`, `1password`)
+  registers through one registry (`src/shared/strategies/registry.ts`, kind
+  `secrets`) as `{ id, kind, detect(), capabilities }`: a factory, a label,
+  its CLI, which ref parts it needs, and optional `setup` and env
+  injection. `detect()` is a PATH check that never prompts or prints; a
+  backend whose CLI is missing reports "not available: The Doppler CLI
+  (doppler) is not on PATH" instead of failing a spawn. `secrets.provider:
+  none` resolves nothing and never runs a CLI. `den create` now scaffolds
+  `secrets: { provider: none }`, with the choices in a comment, so a new
+  distribution depends on no store. See "Secrets" in
+  `docs/distributions.md`.
+- **The edge's TLS is a registered strategy: `edge.tls`** (0.3.0-dev.25,
+  TLS-1a). `none`, `mkcert` and `files` register through the strategy
+  registry as kind `tls`, as the secrets backends do. `tls: none` serves
+  http only (no https entrypoint, no cert work, mkcert never run);
+  `{ strategy: mkcert }` issues the edge's wildcard cert from a local CA,
+  its own or `ca:` (an existing CA, never minted or uninstalled);
+  `{ strategy: files, include, mounts }` serves the certs your included
+  config holds (`ca:` optional, for health checks). An unknown strategy,
+  or a key a strategy does not take, is a validation error naming the
+  built-ins. mkcert's `detect()` is a PATH check: with it missing,
+  `validate`, `doctor`, `edge up` and `edge trust` say "mkcert is not
+  installed" instead of a spawn error. `edge trust` / `untrust` exist under
+  mkcert, and `edge trust` also under `files` with a `ca` (it installs that
+  existing CA, as `caroot` did); elsewhere they exit 1 ("edge trust needs
+  edge.tls.strategy: mkcert (or files with a ca)").
+  `den create` scaffolds `edge.tls: none`, with the mkcert and files forms
+  in a comment. `/api/edge` adds `tls: { strategy, implicit }`. See "The
+  edge and TLS" in `docs/distributions.md`.
+- **`<cli> doctor`** (0.3.0-dev.25): each strategy kind (secrets, tls),
+  the strategy selected, whether it was implicit, and its `detect()` with
+  the reason. Read-only: a PATH check, never a backend CLI, a prompt or a
+  secret value. Exit 1 when a strategy that will be used cannot work.
+
+### Changed
+
+- **`down` works under an invalid config** (0.3.0-dev.40): it is
+  config-free, so stopping is never stranded. With a config that fails
+  validation it says so ("Stopping anyway, without the config's org
+  data") and stops from the daemon records and compose projects; `down -a`
+  too. Every other command still stops first.
+- **Only up and restart detach by default** (0.3.0-dev.40, DOC-1). Every
+  string command but down and setup ran detached, so `preflight` run from
+  the Services page never finished. A command other than up and restart
+  now runs to completion unless it says `detachable: true`.
+- **English plurals** (0.3.0-dev.40): en has the `.one` forms (`org.n.one`
+  "{n} workspace", and the status, badge, drawer and changelog counts), so
+  the org menu no longer says "1 workspaces". The catalog test fails when a
+  count another catalog makes singular has no en `.one`.
+- **The graph's top-level groups wrap to the stage** (0.3.0-dev.34, a
+  consumer's dogfood finding: 31 services in 10 org groups). Top-down,
+  every org (or application) group sat in one row, so the whole graph
+  fitted only at 15–24%, where cards are hard to read. Each top-level
+  group is now laid out on its own by the same layered layout (a group's
+  inside is unchanged), and the groups wrap into rows (top-down) or
+  columns (left-right), choosing the wrap that fits the stage at the
+  highest zoom; the edges between groups are routed through the gaps
+  between rows. A 31-card, 10-org graph fits at 45% at 1440×900 (was
+  22%) and 33% at 1024×768 (was 14%).
+- **The automatic fit shows the whole graph** (0.3.0-dev.34). A graph
+  that needed less than 25% used to open on its top at 60%; the first
+  paint now fits it as Fit does (down to 10%).
+
+- **The Graph page follows the top bar's workspace scope** (0.3.0-dev.33,
+  a consumer's dogfood finding). With the top bar's Workspace on "All
+  active", `/graph` used to show (and name) the focused workspace only. It
+  now shows every active workspace in one graph, as the Services page
+  lists them: one card per service, a service several workspaces define
+  listed once with its owners (`demo-api · main, notes`). One workspace
+  picked shows that one, and `?ws=` still wins. The page header's line
+  names what is shown (`acme / All active / local`). A card's actions run
+  in the workspace that owns its repo (the first in view, focus first).
+  Local Dev keeps one workspace, the list's selection: its actions, its
+  Applications and Config tabs and its Graph tab are per workspace.
+- **Stack routes on the Edge page and in `edge routes`: scheme and
+  upstream** (0.3.0-dev.33, a consumer's dogfood finding). A stack
+  router's URL is shown with its scheme like Den's own rows: `https://`
+  when the router has TLS or is on the `websecure` entrypoint, else
+  `http://`. UPSTREAM shows the service's `loadBalancer` server URL when
+  the router's file defines it, else the Traefik service's name. The
+  routers in `/api/edge` (`included`, `stacks`) carry `secure` and
+  `upstream`; included routers get the same.
+- **Page tabs are WAI-ARIA tabs** (0.3.0-dev.33, a consumer's dogfood
+  finding: ArrowRight, Home and End left focus on Graph). Local Dev's
+  workspace tabs and any tabs `denShell.pageHeader().tabs(spec)` makes
+  share one helper, `denShell.wireTabs(tablist, opts)`: one tab stop (the
+  selected tab is `tabindex=0`, the rest `-1`), ←/→ move and wrap, Home and
+  End go to the ends, and a tab is selected as focus moves to it
+  (automatic activation). Each tab's `aria-controls` names its
+  `role="tabpanel"`, whose `aria-labelledby` names the tab, and the other
+  panels are hidden. Local Dev's "Settings ↗" link now sits beside the
+  tablist rather than in it. `pageHeader().tabs` is a function now: the
+  shell no longer adds a hidden, unlabelled, empty `.ptabs` tablist to
+  every page, only the one a page asks for.
+
+- **POST /api/settings: null clears a pref** (0.3.0-dev.32, from a
+  consumer). A key set to `null` (`{"graph":{"workspaces":null}}`, or in
+  `shell` or `appearance`) is removed from config/local/user.yml instead of
+  failing with 400, and a block left empty goes too; a whole block set to
+  `null` (`{"graph":null}`) removes it. `graph:` now keeps only the keys
+  someone set (it used to write every default), so setting a pref and
+  clearing it again leaves user.yml byte-identical.
+- **Edge page: the cert-names card under tls `files`** (0.3.0-dev.32, from a
+  consumer) reads "Names the included certs should cover": Den issues
+  nothing there. mkcert keeps "Certificate names (planned)".
+
+- **The pages' output panes are gone; their runs are tabs in the runs
+  dock** (0.3.0-dev.30, R16). Local Dev's output panel (one tab per
+  system, log tails, the dismissed tabs per workspace), Services' output
+  pane, Tests' output pane and its service command strip (Stop / Detach is
+  now a button in the dock's bar while the command runs), and Releases'
+  deploy log (each deploy session is a tab: selecting one attaches its
+  log, its × closes the session; the session chips are gone) all write to
+  the dock. The output lines are the same text with the same line classes;
+  k6's progress lines still update in place, Local Dev still keeps its
+  last 1000 lines per tab. Auto-scroll now pauses on every page when you
+  scroll up (Local Dev's rule).
+- **The runs dock starts collapsed, and stays as you leave it** (0.3.0-dev.30,
+  R16a, Ward QA 2026-11-05). A run starting never opens it: its tab
+  appears and the Runs chip pulses, and you open it (Show runs, the chip or
+  a tab). Only an action whose whole point is output opens it: Logs on a
+  service (Services) and a card's output in Local Dev's graph. Open or
+  closed and its height are user prefs (`shell.dock`, `shell.dockHeight`
+  in `/api/settings`, the Settings page's Navigation row "Open the runs
+  dock"), so they hold across pages, reloads and browsers; nothing is kept
+  per browser tab any more. Dragging its top edge stops at half the window.
+- **Settings: the search and the category list stay put** (0.3.0-dev.30,
+  R21a, Ward QA 2026-11-05). The page header with its search box and the
+  category list on the left are sticky while the rows scroll; a category
+  click scrolls its section to just below the header.
+
+- **Existing edge configs render exactly as before** (0.3.0-dev.25). The
+  legacy keys map to `edge.tls` (EXT-1 rule 6): `issue_cert: false` is
+  `files`, `caroot` is `mkcert` with `ca`, and an `edge:` block with
+  neither is `mkcert` with the edge's own CA. A test renders each shape
+  (and its explicit `edge.tls` form) and compares the Traefik dynamic and
+  compose files, cert names and paths, route URLs and the mkcert call
+  byte for byte with 0.3.0-dev.24's own output. Under `files` with no `ca`,
+  `edge trust` now refuses (it minted a CA that signs nothing the edge
+  serves); with a `ca` it installs that CA, as before.
+- **No built-in secret locations** (0.3.0-dev.23). Den no longer assumes a
+  vault, item, field, key or account of its own: the default 1Password
+  vault, developer-keys item and sudo field, the default account domain, and
+  the flat `<PREFIX>_LOCAL_ADMIN_PWD` key that doppler and env used for the
+  saved sudo password are gone. The saved sudo password and the journeys
+  agent key come only from `secrets.refs.sudo` and
+  `secrets.refs.journeys_agent_key`; without them each says "not configured:
+  set secrets.provider and secrets.refs.<name> in config/<cli>.yml" and
+  runs no CLI (the interactive unlock still works). A `1password`
+  distribution with no refs gets one warning in the web server's startup
+  log and in `validate`. The 1Password developer-keys setup writes to
+  `secrets.developer_keys: { vault, item }` (else the vault and item of
+  `refs.sudo`). See Migrations.
+- **`make up` / `make web` check secrets only when `secrets.required` is
+  set** (0.3.0-dev.23). Otherwise the gate passes silently, whatever the
+  provider, and never asks the backend. `make <cli>-setup-secrets` runs the
+  selected strategy's setup; with `none`, or no provider set, it says there
+  is nothing to set up and exits 0.
+- **`/api/sudo-password/vault-status` is backend-neutral** (0.3.0-dev.23):
+  `{ backend, label, configured, backendAvailable, reason?, hasStored }`,
+  and the unlock form says "Save to <backend>". `load-from-vault` answers
+  `{ ok: false, reason: "not-configured", message }` with no `refs.sudo`.
+- **A local-jwt signing key that is not found names its provider**
+  (0.3.0-dev.23): "... not found in env or the doppler secrets backend
+  (secrets.provider)". Its resolution is unchanged.
+
+### Deprecated
+
+- **The implicit mkcert default (set `edge.tls`)** (0.3.0-dev.25). An
+  `edge:` block with no `tls`, `caroot` or `issue_cert` still means mkcert
+  with a local CA, and warns once per run (`validate`, `doctor`, `edge up`,
+  `stack up`): "edge.tls is not set; defaulting to mkcert with a local CA.
+  Set edge.tls explicitly." `edge.caroot` and `edge.issue_cert` still work,
+  and `validate` and `doctor` name the `edge.tls` line that says the same.
+- **The implicit doppler default (set `secrets.provider`)** (0.3.0-dev.23).
+  An unset `secrets.provider` still means `doppler`, but only when something
+  actually resolves a secret; the first time it does, Den warns once:
+  "secrets.provider is not set; the implicit doppler default is deprecated
+  and will be removed in a later minor. Set it explicitly: doppler,
+  1password, env or none." A distribution that resolves no secret never
+  runs `doppler` and never sees the warning.
+- **`opAvailable` in `/api/sudo-password/vault-status`** (0.3.0-dev.23):
+  an alias of `backendAvailable`, removed in a later minor. Read
+  `backendAvailable` (and `backend`, `reason`).
+
+### Fixed
+
+- **`web up` under an invalid config reports the server ready**
+  (0.3.0-dev.42, a consumer's dev.41 finding). It waited for
+  `/api/health`, which answers 422 by design then, and exited 1 with
+  "web did not become ready" while the server ran. Readiness now asks
+  `/api/server-info` (answered under any config; `/api/health` for a
+  server too old for it), and the 422 "Config is invalid" page counts as
+  the shell serving.
+- **No page throws under an invalid config** (0.3.0-dev.41, a consumer's
+  dev.40 finding: "envs.map is not a function" on every page).
+  `/api/environments` is config-free (it already fell back to `local`),
+  the env picker and the Logs toolbar treat an error answer as an empty
+  list, and a test loads every page with an invalid config and expects
+  no uncaught error.
+- **A refused `edge down` says "not stopping it"**, not "not replacing
+  it"; `edge` rejects an unknown flag (a mistyped `--take-over` is never
+  ignored) (0.3.0-dev.41).
+- **A pre-dev.37 record whose port is held by another process** no
+  longer warns "nothing running is it" before saying what holds the port
+  (0.3.0-dev.41).
+- **Safety: an edge another state dir owns is never replaced**
+  (0.3.0-dev.40, P1). The edge's container and Compose project are named
+  by `edge.org`, so a scratch root with its own `DEN_EDGE_DIR` but the real
+  `edge.org` recreated the real edge with its scratch certs and routes
+  (`stack up` brings the edge up first). The edge container now carries
+  `den.edge.root=<realpath of its state dir>` and `den.edge.org=<org>`, and
+  `edge up`, `stack up`/`restart` (their implicit edge up) and `edge down`
+  touch an existing `<org>-edge` only when its `den.edge.root` is their own
+  state dir. Otherwise they refuse before writing or starting anything,
+  exit 1: "edge <org>-edge belongs to <its dir>; not replacing it". An
+  unlabelled (pre-dev.40) edge is adopted only from the default state dir,
+  never under a `DEN_EDGE_DIR` that overrides it (the refusal names its
+  mounts' dir when known). Under such an override a refusal also warns:
+  "Give this root a distinct edge.org." `edge up --take-over` is the only
+  override, and nothing implies it. The routes (the dynamic files) are
+  byte-identical. See "The edge and TLS" in docs/distributions.md.
+- **A recreated edge keeps running stacks routed** (0.3.0-dev.40, P1). A
+  new or restarted edge container starts on its own network only, so every
+  running stack's routes answered 502 until that stack's next `stack up`.
+  After `edge up` (and `stack up`/`restart`'s implicit edge up) the edge
+  now rejoins the routed networks of each stack that has its routes file
+  (`dynamic/stack-<project>.yml`) in this edge's state dir and whose
+  Compose project is running, with one line per network ("rejoined
+  <network> (<project>)"). Stacks that are down are skipped; a network the
+  edge is on already is left alone; a project with no routes file in this
+  state dir is never touched. `stack up` connects through the same helper.
+- **`validate` reports an org config error** (0.3.0-dev.40, a consumer's
+  0.2.8 nit): each problem with its file and key path, exit 1; the
+  manifests are still checked.
+- **The scoped `manifest_validate` refusal names the whole path**
+  (0.3.0-dev.40, a consumer's 0.2.8 nit): it was cut at 80 characters,
+  mid-filename. Up to 160 it is whole; a longer one keeps its start and its
+  filename and elides the middle with "…".
+- **A named `up <repo>/<svc>` whose port is held refuses before spawning**
+  (0.3.0-dev.40, a consumer's dev.39 finding): it started the server once,
+  which died on EADDRINUSE, before refusing. It now refuses as the
+  repo-level up does ("<repo>/<svc> not started"), with or without a
+  pre-dev.37 record. And a listener in the repo but in Den's own process
+  group is said as that ("in Den's own process group; not adopted"), not
+  as "outside <repoPath>".
+- **Graph cards** (0.3.0-dev.40, DOC-1): a service card's red "down"
+  border goes when it recovers (only repo cards toggled it); before the
+  first health round cards say "checking…", as the Workspaces table does,
+  not "no health check"; the details panel's Opens link follows the edge's
+  TLS (`http://` and the http port for `tls: none`; it always said
+  `https://`).
+- **Records from before 0.3.0-dev.37 reach adoption from the CLI**
+  (0.3.0-dev.39, a consumer's dev.38 finding). dev.38 decided right when
+  asked, but the CLI's paths never asked. Every up, down and healthy-skip
+  now reads a service's record through one accessor
+  (`settledDaemonRecord`) that settles a pre-dev.37 record first: adopted
+  (its group recorded) or dropped (said, nothing signalled).
+  - `up <repo>` on a healthy service attached to the old record and left
+    it without a group, so a later `down` could not stop it. It now adopts
+    the running process ("adopted pre-dev.37 process (pid …, port …)"),
+    starts nothing, and `down <repo>` stops it.
+  - `down <repo>/<svc>` of a service with an up of its own pointed at the
+    repo's down ("it is stopped by repox's down") and stopped nothing. Its
+    down is its own: the group its up recorded.
+  - A healthy service with no record whose port is held by a process in
+    its repo is adopted the same way; one held from outside the repo is
+    said ("port N is in use by pid … (cwd …), outside …: left alone"),
+    never claimed or signalled, and nothing is started on it (a named
+    target fails; a dependency warns).
+  - An up whose process exits non-zero during startup (a second server
+    that died on EADDRINUSE) keeps no record and no process group, so a
+    later `down` never signals a dead group while the real listener runs.
+  - The CLI prints what was adopted, dropped or found busy; before, those
+    lines only flashed in the spinner.
+  - `down -a` warns about records no active workspace reaches ("… is in no
+    active workspace: down -a left it alone") and leaves them alone, where
+    it skipped them silently.
+- **`restart` of a service with only an `up` works** (0.3.0-dev.39, a
+  consumer's dev.38 finding). `restart repox/web` failed with `command
+  "restart" not found` and left the old group running. With no restart or
+  down command, a restart stops the recorded group, then runs the up
+  detached, as `down` then `up` would.
+- **`down <repo>` and `down -a` stop a repo's per-service daemons**
+  (0.3.0-dev.38, a consumer's dev.37 finding). A repo with services of
+  their own (`up repox` started `repox/web` and `repox/api`, each with
+  its own process group) and no down of its own printed "down repox
+  (nothing to stop)" and left both running. A repo-level down with no
+  down command now stops every service record of the repo through the
+  per-record path (its refcount, its down command or its recorded group);
+  `down -a` does it for each repo of the workspace. The mirror of
+  dev.35's `up` multi-service fix.
+- **Records from before 0.3.0-dev.37 are adopted or dropped, never
+  trusted blindly** (0.3.0-dev.38, a consumer's dev.37 finding). A record
+  with no process group made `up` print "✔ up repox/api" while nothing ran,
+  and `down` give up on it. One rule now serves `up` and `down`: the
+  listener on the service's known port (its `port`, the port in its
+  health URL, or `--port`/`-p` in its up command) whose cwd is inside the
+  repo is adopted (its process group is recorded: "adopted pre-dev.37
+  process (pid N, port P)"); else a recorded pid whose group shows every
+  token of the up command (leading `VAR=value` and an `npx`/`npm exec`
+  prefix stripped) is adopted; else the record is stale: warned, dropped,
+  nothing signalled. `up` then reports an adopted service already running
+  and starts a stale one; `down` stops an adopted one through the
+  TERM→KILL group path. A port held by a process outside the repo is
+  named and left alone.
+- **A restart records only the up** (0.3.0-dev.38). A service with a down
+  and an up but no restart ran one detached `sh -c "<down> && <up>"`, so
+  its recorded process group held the down too. It is now the down step,
+  then a detached up step, and the group is the up's.
+
+- **Graph: a selected card's flowing edges are visible** (0.3.0-dev.37,
+  Ward QA of dev.35). The marching dashes were drawn in the same colour on
+  a full-strength line, so they barely showed. A lit edge's line is now a
+  faint track in its kind's colour and the dashes run wider on top of it;
+  under reduced motion the lit edge stays solid and thicker, as before.
+- **Test workers inherit no credentials** (0.3.0-dev.37). `tests/setup.ts`
+  strips credential-shaped variables (by name, family or token shape) from
+  the environment before any suite runs, so a failing assertion on a
+  spawn env can no longer print a developer's tokens.
+- **`down` stops what a detached `up` started** (0.3.0-dev.37, a
+  consumer's dogfood finding). `<cli> down <repo>` for a service with no
+  down command and no container printed ✔ and stopped nothing: daemon
+  records kept no process. A detached `up` now records its process group
+  (`pgid`, and the leader's start time as `pgidStartedAt`) in the daemon
+  record, and `down` sends the group SIGTERM, waits up to 3s
+  (`DEN_DOWN_GRACE_MS`), then SIGKILL. Before each signal it checks the
+  pid still belongs to the recorded process (same start time), so a
+  reused pid is never signalled: that service had already exited, and
+  `down` says so and leaves the process alone. After a declared down
+  succeeds, a recorded group still running is stopped too. When `down`
+  cannot stop what it knows is running (a record written before dev.37,
+  with no group; a group that survives SIGKILL), it warns, and an explicit
+  `down <repo>` exits non-zero (a workspace-wide `down` warns and goes
+  on). With nothing recorded, the CLI says "nothing to stop" instead of ✔.
+  `down --dry-run` lists a service with a recorded group as one it stops.
+- **A compose-stack repo's Start and Restart work on the Workspaces page**
+  (0.3.0-dev.37, a consumer's dev.35 finding). The repo row's buttons
+  were disabled, "has no up command", for a repo whose up is its compose
+  stack's. `/api/services` now gives each local service its effective
+  commands (a stack's synthesized up/down/restart included) and
+  `upTargets`: what `<cli> up <repo>` starts (`resolveUpTargets`), as the
+  table's addresses. The repo row's Start and Restart are enabled when it
+  is non-empty and run exactly those addresses.
+- **The Workspaces table says "checking…" until the first health round
+  lands** (0.3.0-dev.37). Before it, repo and service health cells read
+  "unknown (not checked)" or "no health check".
+- **Find shows only the sub-rows it matches** (0.3.0-dev.37). A Find that
+  matched one service of a repo opened every one of the repo's sub-rows;
+  now only the matching ones show under their repo (a match on the repo
+  itself still shows them all).
+
+- **`<cli> up <repo>` no longer fails fast on a multi-service dependency**
+  (0.3.0-dev.35; backported to 0.2.8). A dependency with no `up` of its
+  own but with per-service ups (two services, each with its `up`) was run
+  as the repo, `command "up" not found for service "<repo>"`, and the run
+  aborted before the repo you asked for. `up <repo>` and `up -a` now make
+  one decision (`resolveUpTargets`): a repo with its own `up` starts as
+  before; one with none but per-service ups starts its services (all of
+  them, or the ones its dependents name in `depends_on`); only one with
+  no `up` at all is skipped, said as `-a` says it ("Skipping (no local up
+  command): …"), and nothing waits on it. A dependency whose `up` fails
+  still fails fast.
+
+- **The graph fits on first paint** (0.3.0-dev.34, a consumer's dogfood
+  finding). With "All active", `/graph` opened at 60% with 17 of 31 cards
+  outside the stage at 1440×900 (23 at 1024×768) until Fit was clicked:
+  the org frames land after the first draw, the graph was drawn again,
+  and only the first draw was fitted (a render a newer one overtook could
+  also fit the stale layout). The view now fits once the final layout is
+  drawn, and again whenever the set of cards changes, unless you zoomed
+  or panned since. Local Dev's per-workspace graph likewise.
+- **The Workspace picker on `/graph` replaces `?ws=`** (0.3.0-dev.34, a
+  consumer's dogfood finding). On `/graph?ws=w2`, "All active" changed the
+  pill but the URL kept `?ws=w2`, which wins, so the header and the graph
+  stayed on w2, after a reload too. A choice there now drops `?ws=` (All
+  active) or sets it (a workspace), replacing the history entry, and the
+  pill shows the workspace a fresh `?ws=` names: the pill, URL, the
+  header's line and the graph agree.
+- **The runs dock is a tablist only while it holds tabs** (0.3.0-dev.34).
+  With no runs, `.den-runs-l` was a `role=tablist` holding a "No runs"
+  span and no tab; the role and its label come back with the first run.
+- **`theme-switch-isolation` is deterministic under load** (0.3.0-dev.34;
+  it failed 5/6 then 1/6 on a busy machine). Its file snapshot covered the
+  throwaway HOME, where a container runner's CLI that the health check
+  calls writes its own update hint on its own schedule; it now covers
+  Den's files (the distribution and `DEN_HOME`). The server gets a port
+  from the OS on localhost (not a random pick that could land on another
+  session's server), and readiness waits for the server whose
+  `/api/server-info` names this distribution's root.
+
+- **Stale daemon records are dropped** (0.3.0-dev.33, a consumer's
+  dogfood finding). A record whose repo had been relocated (no pid,
+  `containers: []`) was kept forever because its address still resolved,
+  and the Runs dock showed a permanent tab. The startup sweep and the
+  health reaper now drop a record of this root's, or an unstamped one,
+  whose `repoPath` is not on disk, or whose `repoPath` is no longer where
+  the service resolves and none of its candidate containers (captured,
+  or the dev-op's at its old path) is running; the relocated checkout's
+  own container, which carries the repo's name, does not count.
+  Another root's records are never touched, and a record that resolves
+  to its own checkout with nothing to verify is still kept (it may be a
+  live non-opctl process). Removals are logged with the sweep's and the
+  reaper's lines.
+- **Graph group boxes fit their content** (0.3.0-dev.33, a consumer's
+  dogfood finding). On `/graph` a repo box with one row of cards drew
+  about twice the height it needs: top-down, ELK reads a compound node's
+  minimum size in its own layout axes, so the repo box's minimum width
+  (386px) became its height. The minimum is passed in that order now; the
+  boxes are their padding plus their cards, and keep the header's width.
+- **Fit keeps the graph above the legend and the zoom group**
+  (0.3.0-dev.33, a consumer's dogfood finding). After Fit, a legend on
+  two lines covered the last group's bottom ~10px. Fit's height now leaves
+  out the overlays' measured height (and a gap), so no card or group
+  border sits under them.
+
+- **CA trust on a fronted edge reads "not needed: fronted"** (0.3.0-dev.32,
+  from a consumer). With `edge.publish: false` a proxy in front owns
+  browser trust (BOOT-1), so the Edge page's CA trust tile is neutral
+  instead of a red "not trusted", and `edge status` says the same.
+- **Fit follows the graph's size on maximize and restore** (0.3.0-dev.32,
+  R23, from a consumer). Fit stopped at 35%, so a big graph at 1440×900 read
+  35% maximized or not, and didn't fit either way. Fit now fits the whole
+  graph, by width and height, down to 10% (zooming out goes as far as
+  that), and a fitted view refits when the graph is maximized or restored.
+
+- **A seed without a terminal no longer resets a workspace that has
+  entries** (SEED-0, 0.3.0-dev.29; also 0.2.7). `<cli> init` and
+  `<cli> workspace seed` from a script or `make` replaced every entry of the
+  default (or blueprint) workspaces with managed clones, dev-managed
+  checkouts included, without asking. Without a TTY they now refuse (exit 1,
+  nothing written) and name `--reset`; on a TTY they still ask, default No.
+  `init --reset` and `workspace seed --reset` reset as before. A script that
+  relied on the silent reset must pass `--reset`.
+- **`<cli> init` in the distribution root seeds through a symlinked path**
+  (0.3.0-dev.29): it compared paths without resolving links and ran the
+  manifest scaffolder instead.
+
+- **`create`'s "Next:" hint names an absolute path** (0.3.0-dev.26) when the
+  new directory is not under the cwd, instead of `cd ../../../..`.
+
+- **A fresh distribution runs no gh for a placeholder org** (0.3.0-dev.25,
+  from a consumer's dev.24 run): `den create` wrote `github_org:
+  your-github-org`, and Local Dev then ran `gh repo list your-github-org`
+  on every load. The scaffold now leaves `github_org` commented out, with
+  an example. With `github_org` unset or still a placeholder
+  (`your-github-org`, `your-org`, `<your-org>`, `example-org`) GitHub is
+  "not configured": `/api/github/repos` is empty and runs no gh (no
+  fallback to catalog owners or a git remote), and `register`'s GitHub
+  list ignores a placeholder.
+- **The lock's not-configured note names your config file** (0.3.0-dev.25):
+  with no `secrets.refs.sudo`, the admin-password popover says "Saving the
+  password is off: set secrets.provider and secrets.refs.sudo in
+  config/acme.yml.", the distribution's real file, from the new
+  `configFile` field of `/api/sudo-password/vault-status`.
+- **`register` with no terminal exits cleanly** (0.3.0-dev.25): with stdin
+  closed or piped, the interactive `register` crashed with
+  ERR_USE_AFTER_CLOSE. It now exits 2 (a usage error, since 0.2.8's
+  check; it exited 1 before): "register needs a terminal (stdin is not a
+  TTY)", naming the non-interactive form, `register <path> [--name
+  <repo>] [--gh <owner/repo>]`.
+- **`bin/den` sets no backend account** (0.3.0-dev.24, from a consumer's
+  dev.23 run): the launcher exported `OP_ACCOUNT` with a placeholder
+  domain for every command, whatever the secrets backend, so it reached
+  the web server even under doppler. It now adds nothing; the 1password
+  strategy sets it from `secrets.onepassword.account`, or the caller's own
+  is kept.
+- **`backendAvailable` is true for a usable backend even with no sudo ref**
+  (0.3.0-dev.24): dev.23 reported false whenever `secrets.refs.sudo` was
+  unset, so the deprecated `opAvailable` alias changed meaning. With no
+  ref it now reflects detect() (a PATH check, nothing spawned) for an
+  explicitly chosen backend; `configured: false` says the ref is missing.
+  An unset provider and `none` still report false and are never probed.
+- **Raster marks are scaled to fit, never cropped** (0.3.0-dev.23).
+- **Den adds no 1Password account to anything it starts** (0.3.0-dev.23).
+  The web server daemon (`web up`, `web restart`) was always given
+  `OP_ACCOUNT`, with a built-in domain when unset, and `den.mk` exported
+  one to every recipe. Now only the `1password` strategy gives one, from
+  `secrets.onepassword.account` or your own `OP_ACCOUNT`; no other backend
+  gives any, and `den.mk` sets none.
+- **1Password make targets exist only when 1Password is selected**
+  (0.3.0-dev.23). `make <cli>-setup-1password` and `make auth-configure`
+  moved to `make/secrets-1password.mk`, which `den.mk` includes only when
+  `secrets.provider` (or `<PREFIX>_SECRETS_PROVIDER`) is `1password`; every
+  other distribution no longer has them.
+- **"Register a managed repo" never lists the engine's owner's repos**
+  (0.3.0-dev.23). With no `github_org`, the org fell back to the git remote
+  of the engine's own checkout, so a linked or git-installed engine listed
+  its owner's repos for an unrelated project. The fallback is now the
+  distribution's own checkout (only when it is the top of its own repo),
+  else the "set github_org" error. The 1Password setup scripts likewise
+  read `developer_keys.env_file` and write `admin-auth-<env>.json` under the
+  distribution root, not the engine's.
+- **Settings keeps your pick marked while it scrolls** (0.3.0-dev.22, SA's
+  dev.21 run): a click or Enter on a category no longer walks
+  `aria-current` through every category the smooth scroll passes. Your
+  pick holds until the scroll ends (`scrollend`, else once it is still,
+  within about a second); then the scroll-spy takes over again.
+- **Below 480px the top bar shows only the mark** (0.3.0-dev.22, SA's
+  dev.21 run): the product name is visually hidden there and stays the
+  brand link's accessible name; from 480px it truncates as in dev.21.
+- **0.2.6 is in the 0.3 line** (0.3.0-dev.21): `type: container` health
+  checks, the server identity check behind `web restart` and `web down`,
+  the MCP server's identity, and `service install --plan`. See 0.2.6 below.
+- **Settings marks the category you picked** (0.3.0-dev.21, SA's dev.20
+  run): `/settings#distribution`, or a click on the last short section,
+  marked the one before it as current, because the page could not scroll
+  far enough for the section to reach the top. At the end of the page,
+  your pick wins if it is in view.
+- **"IDE for this workspace" saves on change** (0.3.0-dev.21), like every
+  other row; its Save button is gone.
+- **The top bar fits at 400px** (0.3.0-dev.21): a long product name
+  truncates and the stale-server pill shows only its ⚠ (named "Stale
+  server: restart"), so the page no longer scrolls sideways.
+- **Status drawer rows are named by service, state and latency**
+  (0.3.0-dev.21), e.g. "shop/db, healthy, 9 ms". What the check ran is
+  the row's description and tooltip, not its name.
+- **The rail's Settings item opens Settings** (0.3.0-dev.19): in dev.18 it
+  went to `/local-dev?settings=1`, which nothing read, so it landed on
+  Local Dev. It now goes to `/settings`, and the old URL redirects there.
+  Plain `/settings` opens at the top, on the title and the search box; a
+  link that names a category (`/settings#editor`) scrolls to it and puts
+  focus on its heading.
+- **The rail's × keeps focus in the rail** (0.3.0-dev.19, SA's dev.18
+  run), as Delete does: the next pinned row, else the previous one, else
+  the first item (Enter on "Unpin <id>" dropped focus to the top of the
+  document). One function for both.
+- **The narrow rail is a modal drawer** (0.3.0-dev.19, SA's dev.18 run).
+  Below 720px, ☰ moves focus into the rail (the current page), makes the
+  top bar and the page `inert` behind a scrim, and keeps Tab inside;
+  Escape or a click on the scrim closes it, sets `aria-expanded` back and
+  returns focus to ☰ (Escape did nothing before).
+- **Names screen readers read** (0.3.0-dev.19, SA's dev.18 run): a rail
+  group is named by its label alone (`aria-labelledby` points at the label,
+  not the heading with its tag; Chrome read "XGlobex"); a tagged menu
+  row reads "default, focus", not "defaultfocus"; the ✓ on a checked menu
+  row is drawn with no alt text (`aria-checked` says it); ◐ ▾'s glyphs are
+  hidden from readers. A scope button's `aria-controls` names its menu
+  only while the menu is open.
+- **A page registered before its group no longer warns** (0.3.0-dev.19,
+  a consumer's dev.18 run). Queuing a page before its group is a legitimate
+  order; the warning now waits until the queue has drained and a tick has
+  passed after `den-shell:ready`, and fires only for a group that is still
+  missing (the same for a setting and its category).
+- **Opening a run's output no longer hides the lowest graph cards**
+  (0.3.0-dev.19, a consumer's dev.18 run). Automatic fits (first draw, layout
+  changes, and the re-fit as the output panel opens) now show the whole
+  graph whenever it fits at 35% zoom, the Fit button's limit; only a graph
+  too big for that starts at its top at 60%. The panel already had its
+  own room below the graph: stopping the fit at 60% cut the lowest cards
+  off at the graph's bottom edge, where the panel begins, so a click
+  landed on the panel.
+- **The ORG label is the org's name, not its id** (0.3.0-dev.18). With no
+  `org.title` in the org config, the label was the id (`edge.org`). It is
+  now `org.title`, then the `orgs:` label of `github_org` (the name the
+  Environments page shows), then the id.
+- **A pin toggle follows the rail** (0.3.0-dev.18). Unpinning from the rail
+  (× or Delete) left the Services card's ☆ and the graph panel's reading
+  "Unpin X" (`aria-pressed=true`) until a reload.
+- **Delete on a pinned row keeps focus in the rail** (0.3.0-dev.18): on the
+  next pinned row, else the previous one, else the first item (it fell to
+  the top of the document).
+- **A pinned row is named by its id** (0.3.0-dev.18), not "shop-web×":
+  the × is its own control, out of the tab order, named "Unpin
+  shop-web", its glyph hidden from screen readers; the row has
+  `aria-keyshortcuts="Delete"`.
+- **One main landmark per page** (0.3.0-dev.18). Every page's content is in
+  `<main id="den-content">` (the skip link's target); the four pages that
+  had a `<main>` of their own around part of it, and the two that had
+  none, now have exactly one.
+- **A distribution group is named once** (0.3.0-dev.18): its tag is hidden
+  from screen readers and read as the group's description ("from globex"),
+  not "Globex globex".
+- **Registration mistakes warn** (0.3.0-dev.18): a non-number `order`, or
+  a `registerNav` into a group not registered yet, logs a `console.warn`
+  naming the field. The page waits for its group instead of being lost.
+- **Local Dev's output panel no longer covers graph cards** (0.3.0-dev.18).
+  When the panel opened (a run's tab), the graph's viewport shrank but the
+  graph kept its fit, so the lower cards sat under the panel and couldn't
+  be clicked. A viewport that changes size re-fits the graph unless you
+  have panned or zoomed it yourself.
+
+- **An app is never painted down before its checks have answered**
+  (0.3.0-dev.17). One cold load in twenty painted an app red for ~100ms:
+  only its one down service had answered, and as the only row it read as
+  the entry service. A poll that overlapped the first one started from
+  nothing and drew what had landed. Until every check of a repo has
+  answered (a pending check has), the repo is unknown (neutral, "still
+  checking"); a repo the last complete cycle described keeps its earlier
+  answers meanwhile. The rail's Services badge and pinned dots read the same
+  rollup, so they count only completed downs.
+- **Shell accessibility** (0.3.0-dev.17): a "Skip to content" link comes
+  first on every page; the rail is one tab stop (the current page) with
+  ↑/↓, Home and End moving within it; the Logs link's name is "Logs" or
+  "Logs, 2 open", not "Logs0"; the Tests page's title is "<title> · Tests".
+- **"What's new" is a modal dialog, and reopens at the top** (0.3.0-dev.17).
+  A reopen after scrolling kept the old position: the scroll was reset
+  while the overlay was still hidden, where it doesn't stick; it is reset
+  once the dialog shows. The box is `role="dialog"` with `aria-modal` and
+  its heading as the label; it takes focus (the versions toggle, else Got
+  it), keeps Tab inside, and gives focus back on close (to the version pill
+  after a first-visit open). A browser test covers Escape, × and Got it,
+  collapsed and expanded; CI installs Playwright's chromium for it.
+- **One bar on Logs** (0.3.0-dev.17). The cols/rows toggle moved into the
+  Logs toolbar from a band of its own.
+- **One workspace control on Services** (0.3.0-dev.18). Services' own
+  workspace select (beside the top bar's) is gone: the top bar's Workspace
+  ▾ says what the page lists; its status moved to the Output bar.
+- The appearance control (◐) sits at the header's far right on every page
+  and never leaves the screen: the nav shrinks and scrolls and the health
+  dots give way first (the Tests page's top bar overflowed at 1440 and 1024).
+- Org colors from the config are no longer text: the graph's org frames and
+  the panel's breadcrumb label in `--text` with the color as a dot (they read
+  at 2.5:1 on a light ground), and the frame's ground is neutral. A test
+  bans a config color as `color:`.
+- The active workspace row in the Local Dev sidebar is a calm neutral tint
+  in both modes (it was a loud accent tint in light mode).
+- `plugin list` with broken dirs in `plugins/` (0.3.0-dev.8, reported by
+  consumers on dev.7) prints exactly one row for every directory there, every
+  time. Before, it crashed with no rows when `plugins.lock.json` couldn't be
+  parsed, skipped a symlink, and hid a dir whose lock entry named another
+  id. `plugin validate` reports each of these too. Nothing in a plugin dir
+  makes either command throw.
+- A dir name that isn't an id (such as `plugins/x/`) now gives the real
+  rule: "2–40 characters: lowercase letters, digits or dashes, starting with
+  a letter". A missing manifest is reported as well (0.3.0-dev.8).
+- A dir with no manifest reads "local (plugins/scratch): no den-plugin.json
+  or den-theme.json, so it isn't a plugin" in `plugin list`. "Not valid
+  under this <cli>: …" is now kept for a recognized plugin that fails
+  validation (0.3.0-dev.8).
+- `theme list` still shows themes only, and still exits 0 when other plugin
+  dirs are broken. It now adds one line, "N plugin dir(s) have errors: run
+  `<cli> plugin list`" (0.3.0-dev.8).
+
+- `theme list`'s footer counts every broken plugin dir, whether or not it
+  is a row above, and gets the plural right: "1 plugin dir has errors" /
+  "4 plugin dirs have errors: run `<cli> plugin list`" (0.3.0-dev.9; it
+  counted only the hidden ones, as "N plugin dir(s)").
+- `plugin validate` says the same as `plugin list` for a dir with no
+  manifest: "no den-plugin.json or den-theme.json, so it isn't a plugin",
+  from one constant. `plugin list`'s and `theme list`'s id column fits the
+  longest id, so rows stay aligned with ids up to 40 characters
+  (0.3.0-dev.9).
+- **The header's health row no longer cuts repos off** (0.3.0-dev.9, a
+  regression from the one-line header earlier in 0.3.0). The row was clipped
+  silently: whole repos were hidden, a name could be cut mid-word, and a
+  hidden repo that was down didn't show. It now:
+  - orders problems first: down, then degraded, then healthy, then unknown
+    (0.3.0-dev.11; dev.9 put unknown before healthy), within and across
+    application boxes;
+  - shows only items that fit whole;
+  - ends with a "+N" chip for the rest, named "N more repos" and saying
+    "+N · 1 down" when a hidden repo has a problem. The chip opens the full
+    list; Escape closes it and returns focus to the chip.
+  - fits again on resize, when fonts load, and when the rest of the header
+    squeezes it.
+
+  An interim fix until the slice-3 status chip. The new module is
+  `public/health-fit.js`.
+
+- **One repo health rule for the header, the chip, the graph and
+  `<cli> status`** (0.3.0-dev.10). The header row and `status` read only
+  the entry service, so a repo whose web answered but whose mailpit
+  container was gone read healthy. It sorted with the healthy repos and
+  never reached the chip's count, while the graph showed the down service.
+  All four now use one function, `public/health-rollup.js`, typed for
+  TypeScript in `src/shared/health/rollup.ts`. Only checked signals count:
+  - **down**: the entry service (the manifest `entrypoint`, else the
+    service named like the repo, else the only one) is down;
+  - **degraded**: another checked service is down;
+  - **ok**: at least one signal is checked and none fails;
+  - **unknown**: nothing is checked. It is neutral, never green, and sorts
+    last, after healthy (0.3.0-dev.11). A service not yet probed is
+    unknown. `status` keeps the graph's order.
+
+  A repo of 26 services with one probe is judged by that probe.
+  - `status` prints one row per repo with its rolled-up state and names
+    what is down, e.g. "degraded" with "mailpit down". It says "N not
+    checked" when services aren't probed. An entrypoint-less repo is
+    rolled up too, and `--verbose` still lists every service.
+  - The graph's repo card shows degraded in `--warn`.
+  - In the row, same-state repos sort the focused workspace's first, then
+    by name. `/api/health` rows carry `focused`.
+- **The health row no longer hides everything behind one big application
+  box** (0.3.0-dev.10).
+  - When the boxes don't all fit, the row shows repos one by one. It places
+    every down or degraded repo that fits first, and a problem that is too
+    wide never blocks a later one. Then it adds the rest, in order.
+  - The chip shows the richest text that fits ("+9 · 1 down, 1 degraded",
+    then "+9 · 1 down"). Its name and tooltip always carry the full count.
+  - The row now takes the header's free space. Before, it shrank to its
+    content, and the page's own spacer took half of what was left.
+- **The health row is never an empty box on a cold load** (0.3.0-dev.11).
+  Before the first health result (the application and editor lookups and
+  the stream come first) the row painted nothing, and since dev.10 it takes
+  the header's free space, so it read as a wide empty box with no refresh
+  button. It now shows a neutral "…" and the refresh button at once. A fit
+  that runs before the row or its items have a width keeps everything
+  boxed and runs again next frame (`fitPlan` in `public/health-fit.js`).
+  It fits again on the first data and when fonts load. The brand, version
+  badge and pills beside the row never shrink for it.
+- **The health row's fit, checked against a real 6+3 workspace**
+  (0.3.0-dev.11). Measured names of 71 to 182px: all nine flat need about
+  1070px, so a 1002px row shows 7 and "+2", and a 1282px row shows both
+  boxes whole. The fit was right; these numbers are now a test, with an
+  11-repo 7+3+1 case for the flat fallback.
+- **The "+N" chip names a hidden problem in its text** (0.3.0-dev.12).
+  With only room for the chip, a hidden degraded repo read "+11" with an
+  amber ring, and "1 degraded" was only in its accessible name. The ladder
+  is now "+11 · 1 down, 1 degraded", then the worst one alone ("+11 · 1
+  down"), then compact ("+11 · ⚠2", 0.3.0-dev.13), down and degraded named
+  the same way. Bare "+N" only when no
+  hidden repo has a problem. The fit keeps room for that text
+  (`fitPlan`'s `chipWidthOf`).
+- **Escape from the chip's list returns focus to the chip, even after a
+  re-fit** (0.3.0-dev.12). A health tick or a font load while the list was
+  open laid the row out again with a new chip node, so focus fell to the
+  page (the breadcrumb). The chip is now one node across re-fits, keeps its
+  focus, and stays the list's anchor; when a re-fit drops the chip, focus
+  moves to the row's refresh button.
+- **The health row settles once on a fresh load** (0.3.0-dev.13). It
+  reshuffled three or four times between 0.6s and 3.6s as streamed results
+  arrived. Now a first cycle (a page load, an environment switch) keeps the
+  "…" placeholder until the whole cycle is in (or 8s pass with a slow probe
+  still out), then fits once. Later data repaints are debounced by 300ms;
+  resize and font re-fits stay immediate (`paintGate` in
+  `public/health-fit.js`).
+- **The refresh button is never clipped** (0.3.0-dev.13). At 124px,
+  "+11 · 1 degraded" pushed ⟳ out of the row. The chip's ladder ends in a
+  compact form, "+11 · ⚠1" (every hidden problem counted), used before the
+  problem would be dropped; its name and tooltip keep the full text. If
+  even that doesn't fit, the chip's text gives way, not ⟳. The chip is
+  measured at its natural width.
+- **One shell for every page: a top bar and a left rail** (0.3.0-dev.14,
+  shell slice 2). Every page had its own copy of the header, nav and header
+  CSS (six copies; Environments loaded none of the header's behaviour).
+  `public/shell.js` now draws one frame on every page, and the pages keep
+  only their content:
+  - **Top bar** (48px): the theme's mark and the title in the theme's
+    display face (`var(--display)`; the pages had used the mono face), the
+    version pill, the health row and chip (unchanged), the workspace focus
+    pill, one env picker and ◐.
+  - **Rail**: Local Dev, Services, Environments, Releases, Logs, Tests, the
+    current page marked `aria-current="page"`. ↑/↓, Home and End move
+    between pages; it collapses to icons below 1100px (labels stay for
+    assistive tech). No horizontal page scroll at 1024.
+  - **One env picker for the whole shell.** Tests, Services and Logs each
+    had their own; the choice is now one control, remembered across pages.
+    Local Dev and Releases keep checking local health whatever it says
+    (`data-health-env`), and Releases' own selector is now labelled as the
+    deploy target it is.
+  - A page joins the shell with `<div id="den-shell" data-page="…">` and
+    `<script src="/shell.js">`; `header.js` drives it (`envReady()`,
+    `healthEnv()`).
+- **Header fixes** (0.3.0-dev.14): a long workspace name ends in an
+  ellipsis with the full name in its tooltip, and names in the bar never
+  wrap mid-word; the Tests page's "ENV" label no longer collides with its
+  select (the picker is the shell's).
+- **Environments groups services under their org again** (0.3.0-dev.14).
+  Every service showed under "no org": the page read each row's `org` from
+  `/api/health`, which never sends one. It now takes each repo's org from
+  `/api/orgs?repos=1`, like the graph.
+- **The first health paint waits for the whole cycle** (0.3.0-dev.14). A
+  stream that broke after its first results counted as a finished cycle,
+  so a cold load could paint a partial row. Only the server's `done` ends
+  a cycle now; a broken stream is completed from `/api/health` (or the 8s
+  cap paints what landed, and a check with no result is never shown as
+  down). `healthCycle` in `public/health-fit.js`.
+- **The Theme menu says when your theme isn't in use** (0.3.0-dev.10). A
+  stored theme that fails validation selects nothing, instead of looking
+  like "Org default". One line explains: "Your theme <id> isn't valid
+  (<first problem>), so <name> is in use", or "isn't installed". Picking
+  any option replaces the stored choice.
+
+### Migrations
+
+- 0.3.0-dev.40, the edge's owner labels: plan one `edge up`. The edge's
+  compose.yml gains `den.edge.root` and `den.edge.org` labels, so the first
+  `edge up` (or `stack up`) after upgrading recreates the edge once, from
+  its own state dir. Routes drop only while the container restarts, then
+  stay up: the edge rejoins running stacks' networks. Run it once, from
+  the edge's own dir, when a brief blip is acceptable. A scratch or test root that sets `DEN_EDGE_DIR` needs an
+  `edge.org` of its own; with the real one it is refused.
+- 0.3.0-dev.40, commands that detach: a command other than up and restart
+  that should keep running detached says `detachable: true`.
+- 0.3.0-dev.39, the UI language: nothing required. With no `language:`
+  in `user.yml` the UI is English, as before. A distribution or plugin
+  that adds its own words with `denShell.addMessages(lang, table)` can
+  add `ja` and `es` tables the same way.
+- 0.3.0-dev.39, pre-dev.37 records: nothing required. Their next `up`,
+  `down` or `restart` from the CLI or the web adopts or drops them (said).
+- 0.3.0-dev.38, the restart banner: **restart the web server once after
+  installing.** The first upgrade from a server older than dev.38 can't
+  show the "Den was updated" banner: the old server has no MD-2 code, so
+  it keeps serving the new pages from the old engine until it restarts
+  (`<cli> web restart`, or your service restart). From dev.38 on, the
+  banner says when a restart is needed.
+- 0.3.0-dev.38, `/api` error bodies: **they changed from text to JSON.**
+  Every `/api/*` error now answers `Content-Type: application/json` with
+  `{ ok: false, error, code, requestId }`, where some routes sent
+  `text/plain` (a message, or an empty body). A script that read the text
+  should read `.error`; a status check needs nothing. Den's own pages and
+  the MCP server read the new shape.
+- 0.3.0-dev.38, records from before dev.37: nothing required. A service
+  still running from such a record is adopted on its next `up` or `down`
+  (by its port, else its pid); one that can't be matched is dropped with a
+  warning and never signalled.
+- 0.3.0-dev.37, `down` and process groups: nothing required. A service
+  started by an older Den has no recorded group, so its first `down
+  <repo>` after the upgrade (for a service with no down command and no
+  container) warns, drops that record and exits non-zero: stop it
+  yourself once; its next `up` records the group.
+- 0.3.0-dev.36, `stack_namespace`: optional, no change required. Without it
+  every Compose project, container, volume and network keeps its name.
+  `stack_namespace` in a blueprint needs Den 0.3.0-dev.36 or later: an
+  older Den rejects the unknown key.
+- 0.3.0-dev.25, edge TLS. Nothing is required: every existing edge config
+  renders as before (only `edge trust` under `issue_cert: false` with no
+  `caroot` now refuses). To silence the warnings, say what your config already means,
+  in the org config (`config/<cli>.yml`):
+  - **No `tls`, `caroot` or `issue_cert`** (the implicit default):
+
+    ```yaml
+    edge:
+      tls: { strategy: mkcert }
+    ```
+
+    Or, if the edge needs no https, `tls: none`.
+  - **`caroot: <ca>`**: replace it with
+
+    ```yaml
+    edge:
+      tls: { strategy: mkcert, ca: <ca> }
+    ```
+
+  - **`issue_cert: false`** (with `include` and `mounts`): replace it with
+
+    ```yaml
+    edge:
+      tls:
+        strategy: files
+        include: edge/dynamic # was edge.include
+        mounts: { <host path>: <container path> } # was edge.mounts
+    ```
+
+    `include` and `mounts` may also stay where they were. With `caroot`
+    too, move it to `ca: <ca>` under `tls`.
+  - `edge.tls` beside `caroot` or `issue_cert` is an error: move them.
+  - `github_org: your-github-org` from an earlier `den create`: set your
+    real org, or delete the line.
+- 0.3.0-dev.23, secrets. Nothing is required of a distribution that uses
+  no secrets; the YAML below goes in the org config (`config/<cli>.yml`).
+  - **Relied on the old 1Password defaults** (the saved sudo password or
+    the journeys key in the developer-keys item): add the old layout as
+    your own refs. These are the exact former defaults; `<PREFIX>` is your
+    env prefix (`ACME` for `acme`, `DEN` for Den's own checkout).
+
+    ```yaml
+    secrets:
+      provider: 1password
+      onepassword:
+        account: example.1password.com # your account; Den injects none now
+      refs:
+        sudo:
+          { vault: Employee, item: Developer API Keys, field: <PREFIX>_LOCAL_ADMIN_PWD }
+        journeys_agent_key:
+          { vault: Employee, item: Developer API Keys, field: CURSOR_API_KEY }
+      developer_keys: { vault: Employee, item: Developer API Keys }
+    ```
+  - **Relied on doppler or env for the saved sudo password** (the flat
+    `<PREFIX>_LOCAL_ADMIN_PWD` key):
+
+    ```yaml
+    secrets:
+      provider: doppler # or env
+      refs:
+        sudo: { key: <PREFIX>_LOCAL_ADMIN_PWD }
+    ```
+
+  - **Relied on the implicit doppler default**: it still works. To silence
+    the deprecation warning, say so: `secrets: { provider: doppler }`. A
+    distribution that uses no secrets store can set `secrets: { provider:
+    none }`.
+  - A page or script that read `opAvailable` from
+    `/api/sudo-password/vault-status` reads `backendAvailable`.
+  - A `make auth-configure` or `make <cli>-setup-1password` in your own
+    scripts needs `secrets.provider: 1password`.
+- None. Optional: set `brand.theme: <id>` in the org config to give the
+  distribution's web UI its own default theme.
+- A `plugins/<id>/` with no `den-plugin.json` or `den-theme.json` now fails
+  `plugin list` and `plugin validate`: give it a manifest or move it out of
+  `plugins/`. A theme added from a `file://` path (0.3.0-dev.2 warned) stays
+  listed, but re-add it from its published URL before committing the lock.
+- 0.3.0-dev.20: the header's health row (`#health`) and Local Dev's
+  `#sudo-banner` are gone, and so are `planRow`, `fitPlan`, `moreChip`,
+  `mountMoreChip`, `openMoreList` and `closeMoreList` in
+  `public/health-fit.js`. A distribution page that read them reads the
+  `<cli>:health-update` event (unchanged) or the status chip (`#den-status`)
+  instead, and unlocks with `requireUnlock()` from `/header.js`.
+- 0.3.0-dev.8: a `den-theme.json` used as a plugin needs an `author`
+  (`theme new` sets one). A plugin's `den` range is now enforced: write
+  `>=0.3.0-0 <0.4.0` to admit Den's 0.3.0 prereleases, because `>=0.3.0`
+  excludes them.
 ## [0.2.8] - 2026-11-05
 
 ### Added