@monster-orange/den 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+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.1.0] - 2026-11-04
+
+The first Den release: one engine for local development, tests and releases
+across an organisation's repos, shipped as `@monster-orange/den` and used
+through thin distributions that pin an exact version.
+
+### Added
+
+- **`den create <name> [dir]`** (also `npx @monster-orange/den create`)
+  scaffolds a distribution: `den.yml`, a `package.json` pinning this exact
+  Den, a `bin/<cli>` shim, a Makefile including `make/den.mk`, an org config
+  with a brand, and empty `manifests/` and `tests/pillars/`.
+  `examples/distribution/` is its output for `acme`. See
+  `docs/distributions.md`.
+- **Den runs as an installed package.** Den's own files resolve from the
+  engine root (`node_modules/@monster-orange/den`), the distribution's from
+  its root; scripts run with Den's tsx, never through `npx` or the current
+  directory. The package ships `src/` and runs it with tsx (a dependency
+  now); CI proves it with `scripts/dist-smoke.sh`.
+- **Org > Application > Repo > Services.** Declared applications (config
+  `applications:` or a manifest's `application:`) group repos; the Local Dev
+  graph boxes each one inside its org's frame, next to the connected groups of
+  repos that are their own application.
+- **Security scans keep a latest record.** Every run writes
+  `reports/security/<env>/latest-<mode>.json`; the Tests page shows it, with
+  findings marked new since the previous run.
+- **Repo suites** (`tests:` in a manifest) run from the Tests page and CLI.
+- **Edge opt-ins**: a project CA and route certificates are opt-in; with none
+  set, the rendered edge is unchanged.
+
+- **launchd service from a distribution.** `service/install.sh` ships in the
+  package and runs from `DEN_ROOT`; `DEN_SERVICE_LABEL` and `DEN_SERVICE_LOGS`
+  keep an existing label and log folder; `print` shows the plist.
+
+### Migrations
+
+From the engine this release was generalised from:
+
+- Run Den from the package: a `bin/<cli>` shim that sets `DEN_ROOT` to the
+  distribution and execs `node_modules/@monster-orange/den/bin/den`, and a
+  Makefile that does `include node_modules/@monster-orange/den/make/den.mk`
+  (`den create` writes both; `docs/distributions.md` shows them).
+- Add `den.yml` at the distribution root with `product: { name: <your name> }`.
+  Env vars, the config and manifest file names, the state, managed-clone and
+  workspace directories all derive from that name, so an existing install
+  keeps every on-disk and env name by naming itself as before.
+- Workspace mode `<name>-managed` is now `managed`. Old values are still
+  read, and rewritten on the next save.
+- The CLI command `use-<name>` is now `use-managed`.
+- `github_org` has no default: set it in the org config.
+- The shared local-infra repo is configuration: `graph.infra: { repo,
+  signals }`. Without it no infra edges are derived. The default-workspace
+  entry repo is `defaults.workspace.entry`.
+- Perf suites come from the distribution (`tests/pillars/perf/<module>/test.js`)
+  or from repo manifests; Den ships none.
+- Service and setup make targets are `<prefix>-up`, `-status`, … where the
+  prefix is `DEN_TARGET_PREFIX` (set before including `make/den.mk`; `den
+  create` sets it to the CLI name, so `make <name>-up` keeps working).
+- `service_env` has no built-in entries: a shared-infra secrets file is
+  configured as `service_env: { <KEY>: "{repo:<infra repo>}/<path>" }`.
+- The smoke and browser make targets have no default repo: pass `repo=<repo>`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monster Orange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# Den
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Den is a config-driven local development appliance. It starts the repos you
+work on in dependency order, puts them behind a local HTTPS edge, gives you a
+web UI and a CLI over all of it, and runs smoke, browser, API, journey,
+security and performance suites against the environments you declare.
+
+Den knows nothing about any particular organisation. Everything specific to
+yours — product name, repos, environments, hosts, secrets backend, test
+accounts — lives in **your distribution**, not in Den.
+
+> **Status: 0.1.0**, the first release: `npm install @monster-orange/den`. Den is pre-1.0; each release lists the changes a distribution makes under **Migrations** in [CHANGELOG.md](CHANGELOG.md).
+
+## Make it your own
+
+1. **Create** a distribution named after your product:
+
+   ```sh
+   npx @monster-orange/den create acme      # → ./acme
+   cd acme && npm install
+   ```
+
+2. **Name** it: `den.yml` holds `product: { name: acme }`, so the CLI is
+   `./bin/acme`, env vars are `ACME_*`, state lives in `~/.acme`. Pass
+   `--cli`, `--env-prefix` or `--title` to `create`, or edit `den.yml`.
+3. **Brand** it: `brand:` in `config/acme.yml` sets the name, tagline and
+   banner people see in the CLI and web UI.
+4. **Point it at your repos**: set `github_org` in `config/acme.yml`, then
+   `./bin/acme register ../shop-api` (or add a manifest per repo under
+   `manifests/`).
+5. **Run** it: `./bin/acme up`, `./bin/acme web`, `make test`.
+
+Every field, the bin shim, the make fragment and upgrading are in
+[docs/distributions.md](docs/distributions.md);
+[examples/distribution/](examples/distribution) is what `create acme` writes.
+
+## Distributions
+
+You run Den through a small repo of your own (a _distribution_):
+
+```
+my-dev/
+├── den.yml               # who this distribution is (below)
+├── package.json          # pins an exact @monster-orange/den version
+├── config/<name>.yml     # your org config
+├── config/environments/  # one <env>.json per environment
+├── manifests/            # manifests for repos that don't carry their own
+├── tests/pillars/<pillar>/   # your own suites (e.g. tests/pillars/perf/<module>/test.js)
+├── bin/<cli>             # shim: DEN_ROOT=<this dir> exec node_modules/@monster-orange/den/bin/den
+└── Makefile              # include node_modules/@monster-orange/den/make/den.mk
+```
+
+`den.yml` names the product. Every runtime name derives from it:
+
+```yaml
+product:
+  name:
+    acme # CLI "acme", env vars ACME_*, config/acme.yml,
+    # manifests .acme.yml, state ~/.acme,
+    # managed clones .acme-services/, workspaces acme-workspaces/
+  # Override any of them: cli, env_prefix, config, manifest, state_dir,
+  # services_dir, workspaces_dir
+```
+
+Den's own checkout is a distribution named `den`, so in this repo the CLI is
+`./bin/den`, the config is `config/den.yml`, and env vars are `DEN_*`.
+
+## Repos opt in with a manifest
+
+A repo joins by carrying a manifest at its root (`.<name>.yml`, e.g.
+`.den.yml`) whose commands delegate to the repo's own targets. Den never
+reaches inside a repo beyond that. When a repo has no manifest, the
+distribution can hold one for it in `manifests/<repo>.<name>.yml`; the repo's
+own manifest always wins.
+
+```yaml
+# demo-api: a self-contained service. Nothing it calls, so it starts alone.
+version: 1
+name: demo-api
+application: shop # the application this repo belongs to (den apps)
+compose:
+  files: [docker-compose.yml]
+  routes:
+    api: api:8080 # https://api.demo-api.<edge domain>
+services:
+  demo-api:
+    commands:
+      local:
+        setup: make setup
+        preflight: make test
+# OWASP ZAP target for the security pillar (`make test-sec-api env=local`).
+security:
+  api:
+    hosts:
+      local: ["https://api.demo-api.globex.localhost"]
+```
+
+That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
+[`examples/demo/`](examples/demo/).
+
+## What it does
+
+- **Workspaces.** A workspace is a set of repos. Each is either
+  _dev-managed_ (your checkout, your branch) or _managed_ (cloned by Den and
+  kept on a tracking branch).
+- **Derived dependency graph.** Start and stop order comes from real signals in
+  each repo — SDK imports, `*_URL` env vars, IaC references, event rules,
+  readiness probes — tuned in config with `graph.aliases`, `graph.edges` and
+  an optional shared local-infra repo (`graph.infra`).
+- **Local HTTPS edge.** One local proxy routes `https://<route>.<domain>` to
+  each service, with an optional project CA.
+- **Test pillars.** `smoke`, `browser` (synthetic Playwright), `api`,
+  `journeys` (agent-driven), `perf` (k6), `security` (OWASP ZAP against hosts
+  you own) and `suites` (a repo's own commands).
+- **Releases.** A release view over the repos and deploy workflows your config
+  lists.
+- **Web UI and CLI** over the same state.
+
+## Strategies
+
+Concerns that vary by org are strategies selected in config, never hard-wired:
+
+| Concern          | Built-in choices                        | Chosen in                                                                                                            |
+| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Secrets backend  | `env`, `doppler`, `1password`           | `secrets.provider` in the org config; per engineer in `config/local/user.yml`; per shell `<PREFIX>_SECRETS_PROVIDER` |
+| Test-user tokens | `local-jwt`, `cognito`, `auth0`, `none` | `auth.provider` in `config/environments/<env>.json`                                                                  |
+
+A new secrets backend implements `SecretsProvider`
+(`src/shared/secrets/types.ts`); a new identity provider implements a token
+provider in `src/shared/auth/token-providers/`.
+
+## CLI
+
+```bash
+den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
+den down [repo]        # stop it cleanly
+den status             # service health for the active workspace
+den apps               # Org > Application > Repo > Services
+den graph [repo]       # the derived dependency graph
+den logs [repo]        # tail a repo's local logs
+den use-local [repo]   # use your checkout · use-managed [repo] to switch back
+den workspace list     # workspaces (activate · deactivate · use · create · delete)
+den run                # run test suites (interactive, or with options)
+den web                # the web UI
+den --help             # everything else
+```
+
+In a distribution the command is that distribution's `cli` name.
+
+## Developing Den
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+DEN_ORG_NAMES_FILE=<patterns file> node scripts/org-name-gate.mjs
+```
+
+CI runs the same gates. The org-name gate fails the build when any file names
+an organisation, product, host or account; its patterns are kept out of this
+repo (a CI secret) so the list itself is never published. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

package/bin/den

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Two roots (see src/shared/paths.ts):
+#   DEN_ENGINE_ROOT  Den's own package: this script's parent directory, which
+#                    in a distribution is node_modules/@monster-orange/den.
+#   DEN_ROOT         the distribution: the directory holding den.yml. A
+#                    distribution's bin/<cli> shim sets it; in Den's own
+#                    checkout (where the engine dir holds den.yml) it is set
+#                    here. Otherwise it is left unset and Den walks up from
+#                    the entry script to find den.yml.
+DEN_ENGINE_ROOT="$(cd "$(dirname "$(realpath "$0")")/.." && pwd)"
+export DEN_ENGINE_ROOT
+if [ -z "${DEN_ROOT:-}" ] && [ -f "$DEN_ENGINE_ROOT/den.yml" ]; then
+  DEN_ROOT="$DEN_ENGINE_ROOT"
+  export DEN_ROOT
+fi
+export DEN_INVOKE_CWD="$PWD"
+export OP_ACCOUNT="${OP_ACCOUNT:-example.1password.com}"
+
+# tsx: Den's own (a checkout) or hoisted into the distribution's node_modules.
+find_tsx() {
+  local dir="$DEN_ENGINE_ROOT"
+  while :; do
+    if [ -x "$dir/node_modules/.bin/tsx" ]; then
+      printf '%s\n' "$dir/node_modules/.bin/tsx"
+      return 0
+    fi
+    [ "$dir" = "/" ] && return 1
+    dir="$(dirname "$dir")"
+  done
+}
+
+# `create` scaffolds a new distribution: it needs no den.yml, so it runs on
+# its own entry point rather than the full CLI.
+entry="src/ui/cli/index.ts"
+built="dist/src/ui/cli/index.js"
+if [ "${1:-}" = "create" ]; then
+  shift
+  entry="src/ui/cli/create-main.ts"
+  built="dist/src/ui/cli/create-main.js"
+fi
+
+# Escape hatch: force the compiled build (e.g. to test the prod artifact).
+if [ "${DEN_USE_DIST:-}" = "1" ] && [ -f "$DEN_ENGINE_ROOT/$built" ]; then
+  exec node "$DEN_ENGINE_ROOT/$built" "$@"
+fi
+
+# Prefer live TypeScript source (the package ships src/ and runs it with tsx).
+# A built dist/ is gitignored and only refreshed by `npm run build`, so
+# preferring it would silently shadow local source edits with a stale build.
+if tsx="$(find_tsx)"; then
+  exec "$tsx" "$DEN_ENGINE_ROOT/$entry" "$@"
+fi
+
+if [ -f "$DEN_ENGINE_ROOT/$built" ]; then
+  exec node "$DEN_ENGINE_ROOT/$built" "$@"
+fi
+
+echo "den: no runnable entrypoint: run 'npm install'" >&2
+exit 1

package/docs/distributions.md

@@ -0,0 +1,256 @@
+# Distributions
+
+Den is one engine, `@monster-orange/den`. You run it through a small repo of
+your own, a **distribution**, that installs Den as a package and holds
+everything that makes it yours: its name, brand, config, manifests and tests.
+Den's own checkout is itself a distribution, named `den`.
+
+- [Create one](#create-one)
+- [Layout](#layout)
+- [den.yml: the product profile](#denyml-the-product-profile)
+- [Brand](#brand)
+- [The bin shim](#the-bin-shim)
+- [make: den.mk](#make-denmk)
+- [Two roots](#two-roots)
+- [Pinning and upgrading](#pinning-and-upgrading)
+- [Developing Den against a distribution](#developing-den-against-a-distribution)
+
+## Create one
+
+```sh
+npx @monster-orange/den create acme          # writes ./acme
+npx @monster-orange/den create acme ~/src/acme-dev --title "Acme Dev"
+```
+
+From a Den checkout, `./bin/den create acme ../acme` does the same.
+
+| Option                  | Default             | What                                  |
+| ----------------------- | ------------------- | ------------------------------------- |
+| `<name>`                | (required)          | Product name: `[a-z][a-z0-9-]*`       |
+| `[dir]`                 | `./<name>`          | A new or empty directory              |
+| `--title <title>`       | `<Name>` Title Case | Brand name shown to people            |
+| `--cli <cli>`           | `<name>`            | The command people type               |
+| `--env-prefix <PREFIX>` | `<NAME>`            | Env-var prefix (`ACME` → `ACME_HOME`) |
+
+`create` refuses a directory that is not empty and never overwrites a file.
+[`examples/distribution/`](../examples/distribution) is exactly the output of
+`den create acme`; a unit test regenerates it, so the two never drift
+(`npm run example:regen` after changing the scaffolder).
+
+Then:
+
+```sh
+cd acme
+npm install
+./bin/acme --help
+./bin/acme web          # the web UI, branded "Acme"
+make help
+```
+
+## Layout
+
+| Path                      | What                                                         |
+| ------------------------- | ------------------------------------------------------------ |
+| `den.yml`                 | The product profile ([below](#denyml-the-product-profile))   |
+| `package.json`            | Pins an exact `@monster-orange/den` version                  |
+| `bin/<cli>`               | The shim people run ([below](#the-bin-shim))                 |
+| `Makefile`                | Includes Den's targets ([below](#make-denmk))                |
+| `config/<name>.yml`       | Org config: brand, `github_org`, `secrets`, `edge`, …        |
+| `config/environments/`    | One `<env>.json` per environment (base URLs, auth, timeouts) |
+| `config/local/`           | Per-engineer overrides (`user.yml`); gitignored              |
+| `manifests/`              | Manifests for repos that do not carry their own              |
+| `tests/pillars/<pillar>/` | Your own suites, e.g. `tests/pillars/perf/<module>/test.js`  |
+| `reports/`, `results/`    | Test output; gitignored                                      |
+
+## den.yml: the product profile
+
+Every runtime name derives from `product.name`. Set only what you want to
+differ.
+
+```yaml
+product:
+  name: acme
+  # cli: acme
+  # env_prefix: ACME
+  # config: config/acme.yml
+  # manifest: .acme.yml
+  # state_dir: ~/.acme
+  # services_dir: .acme-services
+  # workspaces_dir: acme-workspaces
+```
+
+| Field            | Default              | What it names                                                     |
+| ---------------- | -------------------- | ----------------------------------------------------------------- |
+| `name`           | `den`                | The product; `[a-z][a-z0-9-]*`. Everything below derives from it  |
+| `cli`            | `<name>`             | The command shown in help, hints and the web UI                   |
+| `env_prefix`     | `<NAME>` (`-` → `_`) | Env vars: `<PREFIX>_ROOT`, `<PREFIX>_HOME`, `<PREFIX>_INVOKE_CWD` |
+| `config`         | `config/<name>.yml`  | The org config, relative to the distribution root                 |
+| `manifest`       | `.<name>.yml`        | The manifest file a repo carries; the `.json` twin is also read   |
+| `state_dir`      | `~/.<name>`          | Per-user state: web server, daemons, logs, history                |
+| `services_dir`   | `.<name>-services`   | Managed clones, relative to the distribution root                 |
+| `workspaces_dir` | `<name>-workspaces`  | Workspace checkouts, relative to the distribution root            |
+
+Env vars, with `ACME` as the prefix:
+
+| Variable          | What                                                               |
+| ----------------- | ------------------------------------------------------------------ |
+| `ACME_ROOT`       | The distribution root, if Den cannot find it from the entry script |
+| `ACME_HOME`       | Overrides `state_dir` (two instances on one machine stay apart)    |
+| `DEN_ROOT`        | The same as `<PREFIX>_ROOT`; the shim sets it                      |
+| `DEN_ENGINE_ROOT` | Den's package directory; `bin/den` sets it                         |
+| `DEN_PROFILE`     | Read another profile file instead of `<root>/den.yml` (tests)      |
+
+## Brand
+
+What people see: the CLI banner and help header, web page titles and the
+edge's web route. Read from `brand:` in the org config; every field is
+optional.
+
+```yaml
+brand:
+  name: Acme # default: the product name, first letter upper-cased
+  tagline: Acme local dev and E2E harness # default: "Local dev and E2E harness"
+  banner: # optional ASCII-art lines; default: the name spelled out
+    - "  ┌───────────┐"
+    - "  │  A C M E  │"
+    - "  └───────────┘"
+```
+
+| Field     | Used for                                                                     |
+| --------- | ---------------------------------------------------------------------------- |
+| `name`    | Web page `<title>`s, the banner fallback, the web route on the edge (`acme`) |
+| `tagline` | The line under the banner                                                    |
+| `banner`  | The CLI and web server startup banner                                        |
+
+Runtime names (env vars, files, directories) always come from `den.yml`,
+never from the brand.
+
+## The bin shim
+
+`bin/<cli>` is three lines of sh: it names the distribution root and runs
+Den from `node_modules`.
+
+```sh
+#!/bin/sh
+DEN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export DEN_ROOT; exec "$DEN_ROOT/node_modules/@monster-orange/den/bin/den" "$@"
+```
+
+`package.json` also lists it under `bin`, so `npm link` (or a global
+install of the distribution) puts `acme` on your PATH.
+
+Den's own `bin/den` sets `DEN_ENGINE_ROOT` to its own package directory and
+sets `DEN_ROOT` only when it is unset and the engine directory holds a
+`den.yml` (Den's own checkout). An installed Den ships no `den.yml`, so the
+engine directory is never taken for a distribution. `DEN_USE_DIST=1` still
+runs a compiled `dist/` build when one exists.
+
+## make: den.mk
+
+A distribution's `Makefile` includes Den's targets from the package:
+
+```make
+DEN_TARGET_PREFIX := acme
+include node_modules/@monster-orange/den/make/den.mk
+```
+
+`DEN_TARGET_PREFIX` names the service and setup targets: `make acme-up`,
+`acme-down`, `acme-status`, `acme-logs`, `acme-graph`, `acme-workspace`,
+`acme-setup` and the rest (default `den`). `den create` sets it to the CLI
+name.
+
+`den.mk` defines:
+
+| Variable         | What                                                                  |
+| ---------------- | --------------------------------------------------------------------- |
+| `DEN_ENGINE`     | Den's package directory (the directory above `den.mk`)                |
+| `DEN_TSX`        | The tsx binary: Den's own, or the one npm hoisted into `node_modules` |
+| `DEN_PLAYWRIGHT` | The playwright binary, found the same way                             |
+| `DEN_BIN`        | `$(DEN_ENGINE)/bin/den`                                               |
+| `DEN_ROOT`       | Exported: the directory make runs in (`$(CURDIR)`)                    |
+
+and includes `make/test.mk`, `local_dev.mk`, `journeys.mk`, `security.mk` and
+`demo.mk`: `make test`, `make web`, `make <prefix>-up`, `make test-syn-all
+repo=<repo>`, `make test-smk-all repo=<repo>`, `make test-perf
+module=<module>`, `make test-jrn-all`, `make test-sec-all` and the rest.
+Recipes run from the distribution root (reports and staged tests land there)
+and reach Den's files through `$(DEN_ENGINE)`. `make help` lists the main
+targets; define your own `help` by setting `DEN_OWN_HELP := 1` before the
+include. Add your own targets below it.
+
+## Two roots
+
+Den resolves two directories (`src/shared/paths.ts`, `src/shared/engine.ts`):
+
+- the **engine root** (`getEngineRoot()`, `enginePath()`): Den's own files,
+  `src/`, `make/`, `scripts/`; `node_modules/@monster-orange/den` in a
+  distribution;
+- the **distribution root** (`getDistRoot()`, `distPath()`): `den.yml`,
+  config, manifests, `tests/pillars/`, reports, results, staged tests.
+
+Den's scripts run with the engine's tsx (`tsxCommand()`), never through `npx`
+or a path relative to the current directory. In Den's own checkout both roots
+are the same directory.
+
+## Running the web UI as a service (macOS)
+
+Den ships a launchd installer that runs the web UI at login and restarts it if
+it exits. From the distribution root:
+
+```bash
+DEN_ROOT="$PWD" DEN_SERVICE_LABEL=local.acme.web \
+  node_modules/@monster-orange/den/service/install.sh            # install or refresh
+node_modules/@monster-orange/den/service/install.sh status      # with the same env
+node_modules/@monster-orange/den/service/install.sh uninstall
+node_modules/@monster-orange/den/service/install.sh print       # the plist only
+```
+
+| Variable            | Default                                  |
+| ------------------- | ---------------------------------------- |
+| `DEN_ROOT`          | required in a distribution               |
+| `DEN_SERVICE_LABEL` | `local.<distribution dir name>.web`      |
+| `DEN_SERVICE_LOGS`  | `~/Library/Logs/<distribution dir name>` |
+
+The service runs the engine's server with the `node` on your `PATH` at install
+time, from the distribution root; re-run `install` after changing node versions
+or upgrading Den. Keep the label stable: it is how launchd knows the service.
+
+## Pinning and upgrading
+
+`package.json` pins an exact Den version (`create` writes the version that
+ran it). Den is pre-1.0: read the **Migrations** section of
+[CHANGELOG.md](../CHANGELOG.md) for every version between yours and the
+target, make the config and manifest changes it lists, then:
+
+```sh
+npm install @monster-orange/den@<version> --save-exact
+./bin/acme --version
+```
+
+Installing from a tarball (`npm pack` of a Den checkout, before a version is
+on npm): every tarball Den hands out has its own prerelease number
+(`0.1.0-dev.1`, `-dev.2`, …). npm caches a tarball by version and
+integrity, so a repacked tarball with an unchanged version reinstalls the
+old copy; if you ever repack one yourself without bumping, remove
+`node_modules/@monster-orange/den` and its `package-lock.json` entry first.
+
+## Developing Den against a distribution
+
+To try a Den change in a distribution, install your checkout instead of the
+published package:
+
+```sh
+cd acme
+npm install ../den        # node_modules/@monster-orange/den → your checkout
+./bin/acme status
+```
+
+npm links the directory, so edits to Den's `src/` take effect on the next
+run (Den runs its TypeScript with tsx; there is no build step). Den's
+checkout has its own `den.yml`, but the shim's `DEN_ROOT` wins, so the CLI
+still runs as the distribution. Put the pinned version back with `npm
+install @monster-orange/den@<version> --save-exact` before committing.
+
+To check a change the way CI does, run `scripts/dist-smoke.sh` in Den's
+checkout: it packs Den, scaffolds `acme` from the tarball, installs the
+tarball into it, and checks the CLI, make targets and web server.

package/make/demo.mk

@@ -0,0 +1,82 @@
+# make/demo.mk — end-to-end proof of the repo flow on three demo repos
+#
+#   examples/demo/demo-api     standalone API
+#   examples/demo/demo-web     calls demo-api  (.den.yml compose.uses)
+#   examples/demo/demo-notes   unrelated, standalone
+#
+# Each repo carries its own Makefile (run it alone) and .den.yml (how
+# den runs it: compose behind the HTTPS edge, no host ports).
+#
+#   make demo           register + up + check + restart + down, then clean up
+#   make demo-register  workspace "demo" with the three repos
+#   make demo-apps      den apps: "shop" (declared by the repos) + demo-notes (its own)
+#   make demo-up        den up -A shop (demo-api first), then demo-notes
+#   make demo-check     HTTPS through the edge (retries ~10s while the edge
+#                       picks up new routes); demo-web shows demo-api's answer
+#   make demo-status    den status
+#   make demo-restart   den restart -A shop
+#   make demo-down      den down, every demo repo
+#   make demo-clean     down, drop the demo workspace + catalog entries, refocus
+
+.PHONY: demo demo-apps demo-register demo-up demo-check demo-status demo-graph demo-restart demo-down demo-clean
+
+DEMO_WS     := demo
+DEMO_REPOS  := demo-api demo-web demo-notes
+DEMO_DIR    := $(DEN_ENGINE)/examples/demo
+DEMO_PREV   := $(HOME)/.den/demo-prev-focus
+DEMO_DOMAIN  = $(shell $(DEN_TSX) -e 'import("$(DEN_ENGINE)/src/shared/edge/config.ts").then(m=>console.log(m.readEdgeConfig().domain))' 2>/dev/null)
+DEN_CLI     := $(DEN_BIN)
+
+# Steps run in sequence (a prerequisite list would run demo-check only once).
+demo:
+	@for t in demo-register demo-apps demo-graph demo-up demo-check demo-restart demo-check demo-status demo-clean; do \
+	  echo "\n── make $$t"; $(MAKE) --no-print-directory $$t || { $(MAKE) --no-print-directory demo-clean; exit 1; }; \
+	done
+	@echo "\n✓ demo passed"
+
+demo-register:
+	@mkdir -p $(dir $(DEMO_PREV))
+	@[ -f $(DEMO_PREV) ] || $(DEN_TSX) -e 'import("$(DEN_ENGINE)/src/shared/environment-manager/workspaces.ts").then(m=>console.log(m.getFocusedWorkspaceName()??"default"))' > $(DEMO_PREV)
+	@$(DEN_CLI) workspace create $(DEMO_WS) >/dev/null
+	@$(DEN_CLI) workspace use $(DEMO_WS) >/dev/null
+	@for r in $(DEMO_REPOS); do $(DEN_CLI) register $(DEMO_DIR)/$$r; done
+	@$(DEN_CLI) workspace list
+
+demo-apps:
+	@$(DEN_CLI) apps
+
+demo-graph:
+	@$(DEN_CLI) up -A shop --dry-run
+
+demo-up:
+	@$(DEN_CLI) up -A shop
+	@$(DEN_CLI) up demo-notes
+
+demo-check:
+	@set -e; for u in api.demo-api app.demo-web app.demo-notes; do \
+	  for i in 1 2 3 4 5 6 7 8 9 10; do \
+	    code=$$(curl -sk -o /dev/null -w '%{http_code}' https://$$u.$(DEMO_DOMAIN)/healthz); \
+	    [ "$$code" = 200 ] && break; sleep 1; \
+	  done; \
+	  echo "$$code https://$$u.$(DEMO_DOMAIN)/healthz"; [ "$$code" = 200 ] || exit 1; \
+	done
+	@curl -sk https://app.demo-web.$(DEMO_DOMAIN)/ | grep -q '"service": "demo-api"' \
+	  && echo "✓ demo-web reached demo-api over the link network" \
+	  || { echo "✗ demo-web did not reach demo-api"; exit 1; }
+
+demo-status:
+	@$(DEN_CLI) status
+
+demo-restart:
+	@$(DEN_CLI) restart -A shop
+
+demo-down:
+	@$(DEN_CLI) down -A shop
+	@$(DEN_CLI) down demo-notes
+
+demo-clean: demo-down
+	@$(DEN_CLI) workspace use $$(cat $(DEMO_PREV) 2>/dev/null || echo default) >/dev/null
+	@$(DEN_CLI) workspace delete $(DEMO_WS) --yes >/dev/null
+	@$(DEN_TSX) -e 'import("$(DEN_ENGINE)/src/shared/environment-manager/catalog.ts").then(m=>{for(const r of process.argv.slice(1))m.removeCatalogEntry(r)})' $(DEMO_REPOS)
+	@echo "✓ demo workspace removed; focus back on $$(cat $(DEMO_PREV) 2>/dev/null || echo default)"
+	@rm -f $(DEMO_PREV)