@monster-orange/den 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,210 @@ 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.2.1] - 2026-11-04
+
+### Fixed
+
+- **MCP `service_restart` on a service with only `up` and `down`.**
+  `/api/service/exec` now runs `up`, `down` and `restart` (env local) through
+  the service runner, as `<cli> up|down|restart` do, instead of looking up
+  and executing the manifest's command itself. So, for the web UI's panel and
+  for MCP alike: `restart` with no declared `restart` is `down` then `up`;
+  `up` on a service that is already healthy starts nothing and says
+  `already up (healthy)`; `up` attaches to a running shared instance; `down`
+  honours workspace ownership. The panel offers Restart whenever a service has
+  `up` and `down`.
+- **A detached start says when it is ready.** `/api/service/exec` sends a
+  `ready` event once a detached `up` or `restart` is up: its health check
+  passes (`checked: true`; for a restart, only after the old instance went
+  down or 5s passed), or, with no health check, its launcher is still running
+  after 5s (`checked: false`). MCP `service_up` and `service_restart` return
+  at `ready` (`"ready": true` in the result) instead of waiting for a
+  launcher that runs in the foreground (a dev server) to exit, which ran
+  into the 180s timeout and reported a false failure. A restart of a running
+  shared instance now says `restarting the running instance`, not
+  `already running`, and the log path is printed once. An MCP action's
+  `ended` reads `ready` or `handed-off` for a detached start, never
+  `stopped`.
+- **MCP actions report failure.** `service_up|down|restart`, `run_tests` and
+  `workspace_sync` return `isError` with `"failed": true` in the result when
+  the command exits non-zero, a detached service's launcher exits non-zero,
+  or the call times out. They used to come back ok with `exitCode: 1` inside.
+- **`<cli> up|down|restart <remote service>` exits 1.** Naming a remote
+  service (or its repo) directly is a refused command. A remote service
+  reached through a workspace, `-a` or `-A <app>` run is still said and
+  skipped, exit 0.
+- **Refusals name the command.** `runs in dev (AWS); nothing to restart here`
+  (and `stop`, `start`, `run "<cmd>" on`), not `start` for everything.
+
+### Added
+
+- **`<cli> mcp connect`: register the MCP server with your agents.**
+  `mcp clients` lists the agents installed here (Claude Code, Codex, Cursor,
+  VS Code, Claude Desktop, Windsurf, Gemini CLI) and whether each is
+  connected. `mcp connect <client>...|--all` registers the distribution's
+  server at user scope through each client's own CLI or config file, and
+  `--project [dir]` writes a project's config instead. `--dry-run` shows the
+  change, `mcp disconnect` removes it, and `mcp config` prints JSON for any
+  other client. The registration pins `PATH` to the running node so GUI
+  agents can launch it. See "Connecting your agents" in
+  `docs/distributions.md`.
+- **Refused attempts are in the activity trail.** `/api/activity` entries may
+  carry `outcome: "refused"` and a `reason`: a refused or unresolvable
+  `/api/service/exec`, and any MCP action a guard refused before it reached
+  the web server. Agents report the latter to `POST /api/activity` (agent
+  audit header required; it appends one sanitised entry and nothing else).
+  The panel's Activity tab shows them as refused. An attempt that named only
+  the repo shows for the repo and for each of its services.
+- **`target.expect` in placement.** `/api/services` and `/api/health` rows'
+  `target` now carry `expect` (as declared) when the manifest's target has its
+  own `url`.
+
+### Migrations
+
+- None required. Two additive API changes a contract probe may see:
+  `target.expect` on `/api/services` and `/api/health` rows, and
+  `outcome`/`reason` on `/api/activity` entries.
+- Scripts that relied on `<cli> restart|down <remote service>` exiting 0
+  should expect 1.
+
+## [0.2.0] - 2026-11-04
+
+### Added
+
+- **Manifest overrides.** An optional `manifests/<repo>.override.yml` in the
+  distribution is deep-merged onto the repo's base manifest (its own, or the
+  held one): maps merge by key, lists and scalars replace, and an explicit
+  `null` deletes a key. An override may only name services and keys the base
+  has, and an override with no base is an error. See "Overriding a manifest"
+  in `docs/distributions.md`.
+- **Manifest layers are visible.** `/api/services` returns `manifestLayers`
+  per service (`["repo"]`, `["held", "override"]`, …) and the Services cards
+  show them; `GET /api/manifest/validate?path=<repo dir>` returns each layer's
+  result.
+- **`validate` checks each layer.** For a repo folder it validates the base
+  and the override separately, each error naming its file, then the merged
+  result.
+- **`<cli> mcp`: an MCP server over stdio** for agents, a thin client of the
+  running web server (it never starts it, and says how when it is down). Read
+  tools are always on, including the new `stacks` and `edge_status`; the
+  actions `service_up`, `service_down`, `service_restart`, `workspace_sync`
+  and `run_tests` are opt-in per org with `mcp.actions`. Guards: lifecycle
+  commands and env=local only, locally run services only, `run_tests` limited
+  to `mcp.run_tests.envs` (default `[local]`, never production), security runs
+  must pass the owned-host plan and `full` is local only, log tools read
+  local sources unless `mcp.logs.remote: true`, and all text returned is
+  secret-redacted. No deploy tool. Pinned `@modelcontextprotocol/sdk` 1.32.1.
+  See "MCP server" in `docs/distributions.md`.
+- **Agent audit trail.** Every service exec, test run and sync is recorded
+  with who asked: an agent's actions carry actor `agent`, the MCP client's
+  self-reported name and version, and the MCP pid and session id, and show as
+  `[agent]` lines in the web server log on the Logs page.
+- **Read-only status endpoints:** `/api/stacks` (what `stack ls/health` show),
+  `/api/edge` (what `edge status` shows) and `/api/security/plan` (the
+  security CLI's own dry run). `stack ls` and `edge status` now print from the
+  same code.
+- **Graph: cards and a details panel.** The Local Dev graph is laid out by
+  ELK (layered, compound org or application › repo › service, orthogonal
+  edges; elkjs vendored and served by Den, so it works offline). Cards are
+  full size (detailed or compact) on a canvas you pan and zoom; Fit zooms out
+  to 35%. A card shows status, name, repo, placement and health, and its main
+  actions on hover. Clicking a card or a repo opens a side panel: one primary
+  action (Start when down, Open when up, else Logs), two common ones, and More
+  (manifest commands, tools, and careful actions that confirm on a second
+  click); tabs Overview, Logs (live tail), Config and Activity (the audit
+  trail, yours and agents'). ⤢ pops the panel out as a dialog. Layout
+  direction, grouping, card density and panel width are remembered per user
+  (`/api/settings` `graph`). Find highlights and centres on matches. The
+  panel is built from registries (actions, tabs, sections) a distribution or
+  later release can add to.
+- `GET /api/activity`: the audit trail, filtered by service or repo.
+- **One secret redactor** (`src/shared/redact.ts`), shared by the journeys and
+  security pillars and the MCP server.
+- **Placement (R13): what runs here and what runs in the cloud.** A
+  manifest's service may say `runs: { local: remote, dev: remote }` (per env,
+  `local` or `remote`) and `target: { env, account?, url?, expect? }`.
+  Without `runs`, a service is local when it or any service of its repo has
+  local commands (or the repo is a compose stack), remote when it has only an
+  HTTP health URL and nothing in its repo runs here, and otherwise has no
+  placement. `/api/services`
+  and `/api/health` rows carry `runs` and `target`; `/api/applications`
+  carries `placements` per service address, and per application `placement`
+  (`local | remote | hybrid | none`) and a `summary`
+  (`shop-frontend local · shop-core remote (dev)`). `<cli> status`,
+  `services` and `apps` suffix remote services `☁ remote (dev)`, and
+  `<cli> graph` marks remote and hybrid nodes. See "Placement" in
+  `docs/distributions.md`.
+- **Remote health.** A remote service is checked by the health declared for
+  its `target.env`; only when there is none does Den GET `target.url`, up when
+  the status is one of `target.expect` (a code or a list, 100–599; default
+  any 2xx). Its health row's label names the target (`dev · AWS`).
+- **`production_envs`** in the org config: the envs that count as production
+  (default `[prod, production]`).
+
+### Changed
+
+- **`/api/health` rows: `url` is only ever a URL.** A shell health check's
+  command (a compose stack's `<cli> stack health …`, or any declared shell
+  check) is now in a new `check` field and `url` is null; the UI shows the
+  same tooltips as before. Clients that read the command from `url` should
+  read `check`.
+- `/api/server-info` returns Den's `version`.
+- **Nothing runs a command on a remote service.** `/api/service/exec`,
+  `<cli> up|down|restart`, workspace up and down, and `<cli> up`'s plan refuse
+  it (`runs in dev (AWS); nothing to start here`; a `down` succeeds with
+  nothing to stop). The MCP guard `runsLocally()` reads `runs`. Security
+  `auto_targets` excludes remote services explicitly, a remote service is
+  never scanned as if it were local, and one whose `target.env` counts as
+  production is never scanned at all.
+- **Overrides may add placement.** `runs` and `target` are the one thing a
+  `manifests/<repo>.override.yml` may add to a service its base has.
+- `validate` checks env names: a `runs` key or `target.env` that is not one of
+  the org's `environments` is an error.
+- `<cli> status` keeps a hybrid repo's remote service as its own row instead
+  of rolling it into the entrypoint.
+
+### Fixed
+
+- **Logs of compose-stack services.** The live tail (`/api/service/taillog`,
+  so the UI's log view and `logs_tail`), log history and search
+  (`logs_search`) and `<cli> logs` now find a stack service's container,
+  `<stack>-<workspace>-<service>-1`, through the stacks naming helpers. They
+  looked only for opctl containers, so they fell back to the startup log
+  ("container log unavailable") or found nothing.
+- **`<cli> mcp` against an older web server.** A tool whose route the web
+  server predates (`stacks`, `edge_status`, a security `run_tests`) now says
+  `web server is Den <x>; <tool> needs >= <y>: run <cli> web restart`
+  instead of a bare 404; other 404s name the tool and the route.
+- Sync never touches a dev-managed checkout: a managed entry whose path is,
+  holds or sits inside one is refused with the reason, and naming a
+  dev-managed repo says so instead of doing nothing.
+- The What's new dialog showed every changelog bullet cut off mid-sentence.
+- With nothing run yet, the empty output pane no longer takes 200px from the
+  Local Dev page.
+- A security run's mode chosen on the Tests page (`api`, `full`) now reaches
+  the scan; it always ran `baseline` before.
+
+### Security
+
+- Dependency advisories: `npm audit fix` plus `@cursor/sdk` 1.0.23 → 1.0.40
+  (drops its `undici` 5 / `zod` 3 tree) clear every critical and high
+  advisory. Left: a `minimatch` ReDoS under `openapi-typescript` (only fix is
+  a downgrade to 6.x; it matches local config globs only) and dev-only
+  tooling (jest, eslint) moderates.
+
+### Migrations
+
+- None required: with no override files, manifests resolve as in 0.1.0.
+- To let agents act through `<cli> mcp`, add `mcp.actions` to the org config.
+- Placement needs no change: without `runs`, services keep working as
+  before. A service with an HTTP health URL, no commands, and nothing else
+  in its repo that runs here now shows as remote; add `runs: { local: local }`
+  if it is really on this machine. To
+  mark more envs as production than `prod` and `production`, set
+  `production_envs`.
+
+
 ## [0.1.0] - 2026-11-04
 
 The first Den release: one engine for local development, tests and releases

package/README.md

@@ -9,7 +9,7 @@ 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).
+> **Status: 0.2.0**: `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
 

package/bin/den

@@ -40,6 +40,14 @@ if [ "${1:-}" = "create" ]; then
   entry="src/ui/cli/create-main.ts"
   built="dist/src/ui/cli/create-main.js"
 fi
+# `mcp` speaks the MCP protocol on stdout: its own entry point, so nothing
+# the full CLI prints can reach the protocol stream. Its setup subcommands
+# (connect, disconnect, clients, config) are ordinary CLI commands.
+if [ "${1:-}" = "mcp" ] && ! case "${2:-}" in connect|disconnect|clients|config) true ;; *) false ;; esac; then
+  shift
+  entry="src/ui/cli/mcp-main.ts"
+  built="dist/src/ui/cli/mcp-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

package/docs/distributions.md

@@ -49,18 +49,152 @@ 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                                      |
+| 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, and overrides ([below](#overriding-a-manifest)) |
+| `tests/pillars/<pillar>/` | Your own suites, e.g. `tests/pillars/perf/<module>/test.js`                                      |
+| `reports/`, `results/`    | Test output; gitignored                                                                          |
+
+## Overriding a manifest
+
+A repo's manifest comes from one base: the repo's own file (`.acme.yml`, or
+its `.json` twin) or, when the repo has none, the one the distribution holds
+at `manifests/<repo>.acme.yml`. On top of that base, an optional
+`manifests/<repo>.override.yml` changes what this distribution needs to
+differ, without a commit to the repo. The override file is named with
+`.override` plus the manifest's extension, and `<repo>` is matched exactly as
+for a held manifest: the checkout's `origin` repo name, then the managed-clone
+name, then the folder name.
+
+```yaml
+# manifests/shop.override.yml, merged onto shop's own .acme.yml
+services:
+  web:
+    commands:
+      local:
+        up: make up-fast # replaces up; the base's other commands stay
+    depends_on: [] # lists replace whole: web no longer waits on api
+    urls: null # null deletes the key
+```
+
+Merge rules:
+
+- Maps merge by key, recursively.
+- Lists and scalars replace the base value whole.
+- An explicit `null` deletes the key from the result.
+
+An override only changes or deletes what the base has. A service or key the
+base lacks is an error, even inside a map whose keys are free-form (a new
+command, a new environment): put new entries in the base. An override with no
+base is an error, never a manifest on its own.
+
+`<cli> validate <repo-dir>` checks each layer against the schema on its own,
+naming the file each error is in, then checks the merged result:
+
+```
+  ✓  /src/shop/.acme.yml  (repo, v1, no issues)
+  ✗  /dist/manifests/shop.override.yml  (override, v1, 1 error)
+  ERROR   services.api.commands.local.down  unknown key "down": not in the base manifest
+```
+
+The web UI's Services cards show the layers each manifest was built from
+(`manifest: repo + override`), and `/api/services` returns them per service as
+`manifestLayers`, e.g. `["held", "override"]`. `DEN_MANIFESTS_DIR` points the
+held and override lookup at another directory (tests use it).
+
+## Placement
+
+Each service says where it runs, per environment: `local` (on this machine,
+started by Den) or `remote` (deployed elsewhere). A remote service still
+shows in the graph, the health row and the applications, marked ☁, but Den
+never starts, stops, scans or execs it. The common case is a hybrid
+application: its frontend runs here and calls the team's dev deployment of
+its backend.
+
+```yaml
+# .acme.yml of shop-core
+services:
+  core:
+    runs: { local: remote, dev: remote } # per env: local | remote
+    target:
+      env: dev # one of the org's environments
+      account: AWS # a label for where it is deployed
+      url: https://api.dev.acme.example/admin/manifest
+      expect: 401 # the API answers 401 when it is up (behind a JWT authorizer)
+```
+
+When `runs` says nothing for the env being viewed:
+
+- `local` if the service has commands there. Locally that also covers every
+  service of a repo that runs here: a compose stack, or a repo where any
+  service has `commands.local` (one repo-level `up` starts the others). A
+  remote service inside such a repo says `runs: { local: remote }`;
+- `remote` if it has an HTTP health URL there and nothing in its repo runs
+  there;
+- otherwise `none`: Den knows no runtime for it, and shows no placement.
+
+`target` names where a remote service runs: `env`, an optional `account`
+label, an optional `url`, and `expect`, a status code or a list of codes that
+count as up when Den probes `url` (default: any 2xx). Codes are integers
+100–599. A service with `runs.local: remote` must have a `target`.
+
+**Health.** A remote service is checked by the health declared for its
+`target.env` (`health.dev` above), the same check Den runs when you view that
+env. Only when there is none does Den GET `target.url` and compare the status
+with `expect`. The health row's label names the target, `dev · AWS`, followed
+by the status or response time.
+
+**Validation.** `<cli> validate` rejects an env name in `runs`, or a
+`target.env`, that is not one of the org's `environments`, an unknown key in
+`target`, and `expect` codes outside 100–599. Placement is the one thing an
+[override](#overriding-a-manifest) may add to a service its base has, so a
+distribution can place a repo's service remote without a commit to the repo:
+
+```yaml
+# manifests/shop-core.override.yml
+services:
+  core:
+    runs: { local: remote }
+    target: { env: dev, account: AWS, url: https://api.dev.acme.example/health }
+```
+
+**Where it shows.** `/api/services` and `/api/health` rows carry `runs`
+(`local`, `remote` or `none`, for the env asked about) and `target`
+(`{ env, account?, url? }`, or null unless remote). `/api/applications`
+carries each service's placement in `placements` (keyed by address), and per
+application `placement` (`local`, `remote`, `hybrid` or `none`) with a
+`summary` such as `shop-frontend local · shop-core remote (dev)`.
+`<cli> status` and `<cli> services` suffix remote services with
+`☁ remote (dev)`; `<cli> apps` marks hybrid and remote applications and
+repos; `<cli> graph` marks remote nodes (dashed in `--format dot`) and hybrid
+ones (`⇄ hybrid`).
+
+**Guards.**
+
+- Service exec (`/api/service/exec`, `<cli> up|down|restart`, workspace-wide
+  up and down, `<cli> up`'s plan) refuses every command on a remote service:
+  `shop/core runs in dev (AWS); nothing to start here`. A `down` stops
+  nothing and succeeds, so a workspace down is not failed by it.
+- MCP: `runsLocally()` reads the served `runs`, so agents cannot start, stop
+  or restart a remote service.
+- Security: `auto_targets` never adds a remote service, even one with local
+  commands. A declared target of a remote service is not scanned in `local`,
+  only in other envs.
+- **Production.** A remote service whose `target.env` counts as production is
+  never scanned, in any env, and never acted on. Production is an attribute of
+  an env in the org config, never a name check:
+
+  ```yaml
+  # config/acme.yml
+  production_envs: [prod] # default: [prod, production]
+  ```
 
 ## den.yml: the product profile
 
@@ -215,6 +349,143 @@ 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.
 
+## MCP server
+
+`./bin/acme mcp` runs an [MCP](https://modelcontextprotocol.io) server over
+stdio, so an agent (an MCP client such as an editor or a coding agent) can
+read and, where the org allows it, act on the same local environment the web
+UI shows. It is a thin client of the running web server
+(`http://localhost:<web.port>`): agents and the UI share one state and one
+set of guards. It never starts the web server; if it is not running, every
+tool answers with the command that starts it (`./bin/acme web up`). stdout
+carries only the protocol; diagnostics go to stderr.
+
+The web server keeps running the Den it started with until it is restarted,
+so after an upgrade it can be older than the MCP server. When a tool's route
+answers 404, the MCP server reads the web server's version from
+`/api/server-info` and, if it predates the route, says so:
+`web server is Den 0.1.0; stacks needs >= 0.2.0: run acme web restart`. Any
+other 404 is reported as it is.
+
+### Connecting your agents
+
+`<cli> mcp connect` registers the server with the agents you use, so nobody
+edits an MCP config by hand:
+
+```sh
+./bin/acme mcp clients                 # which agents are installed, which are connected
+./bin/acme mcp connect --all           # every installed agent, user scope
+./bin/acme mcp connect claude-code     # one (or several) by id
+./bin/acme mcp connect cursor --project ../shop   # a project's config instead
+./bin/acme mcp connect --all --dry-run # show what it would write or run
+./bin/acme mcp disconnect cursor
+./bin/acme mcp config                  # JSON for any other MCP client
+```
+
+| Client           | User scope                            | Project scope (`--project [dir]`) |
+| ---------------- | ------------------------------------- | --------------------------------- |
+| `claude-code`    | `claude mcp add --scope user`         | `<dir>/.mcp.json`                 |
+| `codex`          | `codex mcp add`                       | –                                 |
+| `cursor`         | `~/.cursor/mcp.json`                  | `<dir>/.cursor/mcp.json`          |
+| `vscode`         | `code --add-mcp`                      | `<dir>/.vscode/mcp.json`          |
+| `claude-desktop` | its `claude_desktop_config.json`      | –                                 |
+| `windsurf`       | `~/.codeium/windsurf/mcp_config.json` | –                                 |
+| `gemini`         | `~/.gemini/settings.json`             | `<dir>/.gemini/settings.json`     |
+
+The server is registered under the CLI's name (`acme`) as the distribution's
+`bin/<cli>` by absolute path, with `PATH` set to the directory of the `node`
+that ran `connect` plus the system dirs. GUI agents start without your login
+shell's PATH (so without nvm's node) and would otherwise fail to launch it.
+After upgrading or switching node, run `connect` again. For a JSON config,
+`connect` changes only its own entry, keeps the previous file as `.bak`, and
+refuses to rewrite a file it cannot parse. Connecting again replaces the entry.
+Restart the agent, or start a new session, to load it.
+
+Project-scope files hold absolute paths on your machine: commit them only if
+everyone's checkout is in the same place.
+
+`--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
+port.
+
+### Config
+
+Without an `mcp:` block in the org config (`config/<name>.yml`) only the read
+tools are registered. Actions are opt-in, by name:
+
+```yaml
+mcp:
+  actions:
+    [service_up, service_down, service_restart, workspace_sync, run_tests]
+  run_tests:
+    envs: [local] # the default; production is refused even if listed
+  logs:
+    remote: false # the default; true lets the log tools read non-local sources
+```
+
+An unknown action or environment name is an error, so a typo never turns a
+guard off.
+
+### Tools
+
+Read tools (always registered):
+
+| Tool                | Web API                                    | What                                                       |
+| ------------------- | ------------------------------------------ | ---------------------------------------------------------- |
+| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell)      |
+| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands |
+| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                        |
+| `graph`             | `/api/graph`                               | The derived dependency graph and startup order             |
+| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                             |
+| `environments`      | `/api/environments`                        | The enabled environment names (never their values)         |
+| `logs_search`       | `/api/logs/search`                         | Search services' full log history                          |
+| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)     |
+| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from            |
+| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                          |
+| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table        |
+| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                     |
+| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health    |
+| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names            |
+
+Action tools (only those named in `mcp.actions`): `service_up`,
+`service_down`, `service_restart` (through `/api/service/exec`),
+`workspace_sync` (`/api/workspace/sync`) and `run_tests` (`/api/run`). There
+is no deploy tool.
+
+### Guards
+
+- **Lifecycle only, local only.** The service tools run a manifest's `up`,
+  `down` or `restart` and nothing else, with `env=local`, and only for a
+  service run locally: its placement is `local` and it has a local `up`
+  command (see [Placement](#placement)).
+- **Sync touches managed clones only.** It never pulls, resets or switches
+  branches in a dev-managed checkout (your own). The web server enforces
+  this for the UI's Sync too: a managed entry whose path is, holds or sits
+  inside a dev-managed checkout is refused, out loud.
+- **Tests:** `run_tests` targets only `mcp.run_tests.envs` (default
+  `[local]`) and never production. A security run must first pass the
+  security CLI's own plan (`/api/security/plan`, a dry run): every target
+  host in `security.owned_hosts` and the mode within the env's ceiling.
+  `full` (active attacks) is local only.
+- **Logs** read local sources only, unless `mcp.logs.remote: true`. All text
+  the tools return is scrubbed of secret-shaped values: bearer tokens, JWTs,
+  AWS keys, credentials in URLs and DSNs, `key=value` secrets, private-key
+  blocks.
+- **Never exposed:** sudo passwords, AWS login, opening a terminal or editor,
+  workspace-wide exec, any other service command, settings writes, workspace
+  create, rename or mode changes, the server log, and anything that returns
+  environment values. The MCP server's HTTP client cannot reach any other
+  route.
+
+### Audit
+
+Every action is recorded with actor `agent`, the MCP client's name and
+version (as the client reports them at initialize: a label, never used to
+authorise anything), and the MCP server's pid and session id. They travel as
+`x-den-*` headers on each web API call. The web server writes each action
+(and each UI one) as a lifecycle line in its log; on the Logs page, the
+`acme/server` stream shows an agent's actions as `[agent]`, ending
+`· by agent <client> <version> (mcp pid <pid>, session <id>)`.
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -53,7 +53,8 @@
   "author": "Monster Orange",
   "license": "MIT",
   "dependencies": {
-    "@cursor/sdk": "1.0.23",
+    "@cursor/sdk": "1.0.40",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@playwright/test": "^1.61.1",
     "@slack/webhook": "^7.0.2",
     "ajv": "^8.12.0",
@@ -62,6 +63,7 @@
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.3",
     "dotenv": "^16.4.1",
+    "elkjs": "0.12.0",
     "inquirer": "^9.2.14",
     "jsonwebtoken": "^9.0.2",
     "openapi-typescript": "^7.13.0",

package/src/pillars/journeys/sandbox.ts

@@ -48,6 +48,7 @@ import type { JourneyPersonaRole } from "./spec/schema.js";
 import { product } from "../../shared/product.js";
 import { enginePath } from "../../shared/engine.js";
 import { getDistRoot } from "../../shared/paths.js";
+import { containsValue } from "../../shared/redact.js";
 // ── Layer 1: captureSecrets ──────────────────────────────────────────────────
 
 /** 1Password field label holding the Cursor API key (= env var name). */
@@ -375,11 +376,7 @@ export class TranscriptScrubber {
 
   /** Throws SecretLeakError when `text` contains any live secret value. */
   assertClean(text: string): void {
-    for (const secret of this.secrets) {
-      if (text.includes(secret)) {
-        throw new SecretLeakError();
-      }
-    }
+    if (containsValue(text, this.secrets)) throw new SecretLeakError();
   }
 }
 

package/src/pillars/security/discover.ts

@@ -11,6 +11,10 @@
 import { discoverRepos } from "../smoke/discover.js";
 import { effectiveLocalCommands } from "../../shared/stacks/manifest-commands.js";
 import type { WorkspaceService } from "../../shared/manifest/workspace-manifests.js";
+import {
+  servicePlacement,
+  type Placement,
+} from "../../shared/manifest/placement.js";
 import type {
   DiscoveredRepo,
   SecurityServiceConfig,
@@ -27,6 +31,12 @@ export interface DiscoveredSecurityTarget {
   config: SecurityServiceConfig;
   /** Derived by `security.auto_targets` from a health URL, not declared. */
   auto?: true;
+  /**
+   * Where the service runs from this machine (R13). A remote one is never
+   * scanned as if it were local, and never at all when its target env counts
+   * as production (see run.ts).
+   */
+  placement?: Placement;
 }
 
 /** Repo-qualified name used by --service and the module picker. */
@@ -61,6 +71,7 @@ export function discoverSecurityTargets(
         repoPath: repo.repoPath,
         serviceName,
         config,
+        placement: servicePlacement(repo.manifest, serviceName, "local"),
       });
     }
   }
@@ -73,7 +84,8 @@ export function discoverSecurityTargets(
  * local commands or compose) with an HTTP health URL, scanned at that URL's
  * origin in each env that has one. Never a service its manifest marks
  * `security.skip`, one already declared under `security:`, or one with no
- * local runtime (a remote or shell-checked service). Host policy is applied
+ * local runtime (a remote or shell-checked service). A service whose
+ * placement is remote is excluded explicitly, whatever commands it has. Host policy is applied
  * later as for any target: every URL must be on the owned-host allowlist.
  */
 export function autoSecurityTargets(
@@ -85,6 +97,10 @@ export function autoSecurityTargets(
   for (const s of services) {
     const id = securityTargetId({ repoName: s.repo, serviceName: s.service });
     if (taken.has(id) || s.config?.security?.skip) continue;
+    // Explicitly: a service placed remote (R13) is never an automatic
+    // target, even when it also has local commands.
+    if (servicePlacement(s.manifest, s.service, "local").runs !== "local")
+      continue;
     const runsLocally =
       Object.keys(effectiveLocalCommands(s.manifest, s.service, s.repo, "auto"))
         .length > 0;