@devrouter/cli 0.0.22 → 0.0.24

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roland Schlaefli
+
+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

@@ -27,13 +27,12 @@ This is the only supported per-repo config for app routing/runtime definitions.
 
 Both are configured the same way (`.devrouter.yml`) and can be mixed in one repo.
 
-### 1. Front a devcontainer / existing process — `runtime: proxy` (preferred)
+### 1. Front a devcontainer / existing process: `runtime: proxy` (preferred)
 
-The recommended setup going forward. A **devcontainer** (DevPod, VS Code Dev
-Containers, `@devcontainers/cli`, Codespaces) owns the *environment* — toolchain,
-databases, auth mocks, the app process, seeding — and publishes the app on a local
-port. devrouter is a thin **routing layer**: it puts a stable `*.localhost` HTTPS
-host (shared `:443`, mkcert TLS) in front of that port and does nothing else.
+The recommended setup is devcontainer first. The devcontainer owns the toolchain,
+databases, auth mocks, app process, and seed data. devrouter owns only the local
+routes. In the best case the container joins `devnet` and exposes stable network
+aliases, so the app and database need no published host ports.
 
 ```yaml
 apps:
@@ -41,18 +40,20 @@ apps:
     host: myapp.localhost
     protocol: http
     runtime: proxy
-    upstream: 127.0.0.1:3000 # the port your devcontainer publishes
+    upstream: myapp-app:3000 # devnet alias inside the devcontainer compose
 ```
 
 ```bash
-dev up && dev tls install     # one-time
-dev app run app               # registers the route; the container owns start/stop
+devrouter setup --yes
+devpod up .
+devrouter repo devcontainer verify --live --yes --json
 ```
 
 Why prefer it: the environment is reproducible and runs anywhere the devcontainer
-spec runs (including remote/cloud via DevPod), devrouter never duplicates the
-DB/lifecycle/env work, and the two layers can't fight. See
-[`docs/DEVCONTAINER.md`](./docs/DEVCONTAINER.md) for the end-to-end walkthrough.
+spec runs, while devrouter gives it stable local HTTPS and database hostnames.
+Agents can add the scaffold with `devrouter repo inspect`, `devrouter repo devcontainer write`,
+and `devrouter repo devcontainer verify`, then include the JSON evidence in a PR. See
+[`docs/DEVCONTAINER.md`](./docs/DEVCONTAINER.md) for the full reference.
 
 ### 2. devrouter runs everything — `runtime: host` / `runtime: docker`
 
@@ -62,27 +63,38 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 
 ## Core commands
 
-- `dev init [--repo <path>] [--entries-json <json>] [--json] [--write-agents] [--write-skill] [--with-linear]`
-- `dev -V [--repo <path>]` (installed CLI version, local repo version, next upgrade target)
-- `dev upgrade [version] [--repo <path>]`
-- `dev up`
-- `dev down`
-- `dev status [--repo <path>] [--json]`
-- `dev doctor|verify [--repo <path>] [--json]`
-- `dev ls [--json]`
-- `dev open <name>` (matches app name, then service/container/host)
-- `dev tls install`
-- `dev repo init [--repo <path>]`
-- `dev repo agents [--repo <path>] [--with-linear]`
-- `dev app add ...` (`--kind app|dependency`, default `app`)
-- `dev app ls [--repo <path>] [--json]`
-- `dev app run <name> [--repo <path>] [--yes] [--workspace <slug>]`
-- `dev app exec <name> [--repo <path>] [--yes] [--shell] [--env-map TARGET=SOURCE] [--workspace <slug>] -- <command>`
-- `dev app rm <name> [--repo <path>]`
-- `dev logs [-f]`
-- `dev workspace up <branch> [--path <dir>] [--no-devpod] [--open] [--repo <path>]`
-- `dev workspace ls [--repo <path>] [--json]`
-- `dev workspace down <workspace|branch> [--keep-worktree] [--keep-devpod] [--repo <path>]`
+- `devrouter init [--repo <path>] [--entries-json <json>] [--json] [--write-agents] [--write-skill] [--with-linear]`
+- `devrouter -V [--repo <path>]` (installed CLI version, local repo version, next upgrade target)
+- `devrouter upgrade [version] [--repo <path>]`
+- `devrouter setup --yes [--repo <path>] [--json]`
+- `devrouter up`
+- `devrouter down`
+- `devrouter status [--repo <path>] [--json]`
+- `devrouter doctor|verify [--repo <path>] [--json]`
+- `devrouter ls [--json]`
+- `devrouter open <name>` (matches app name, then service/container/host)
+- `devrouter tls install`
+- `devrouter repo init [--repo <path>]`
+- `devrouter repo inspect [--repo <path>] [--json]`
+- `devrouter repo devcontainer write [--repo <path>] [--dry-run] [--yes] [--json]`
+- `devrouter repo devcontainer verify [--repo <path>] [--live] [--yes] [--json]`
+- `devrouter repo agents [--repo <path>] [--with-linear]`
+- `devrouter app add ...` (`--kind app|dependency`, default `app`)
+- `devrouter app ls [--repo <path>] [--json]`
+- `devrouter app run <name> [--repo <path>] [--yes] [--workspace <slug>]`
+- `devrouter app exec <name> [--repo <path>] [--yes] [--shell] [--env <env>] [--workspace <slug>] -- <command>`
+- `devrouter app rm <name> [--repo <path>]`
+- `devrouter logs [-f]`
+- `devrouter workspace up <branch> [--path <dir>] [--no-devpod] [--open] [--repo <path>]`
+- `devrouter workspace ls [--repo <path>] [--json]`
+- `devrouter workspace down <workspace|branch> [--keep-worktree] [--keep-devpod] [--repo <path>]`
+
+The current `devrouter repo devcontainer write` scaffold is intentionally narrow:
+Node + pnpm + Postgres. Other package managers stop with a JSON diagnostic
+instead of writing files that would need manual repair.
+Use `devrouter repo devcontainer verify --json` for read-only PR evidence; add
+`--live --yes` only after the devcontainer is running and route probes should
+mutate local route state.
 
 ## Workspace isolation (parallel worktrees)
 
@@ -108,24 +120,29 @@ A **workspace token** lets several git worktrees of the same repo run side-by-si
 
 ```bash
 # Bring up a feature branch as an isolated workspace
-dev workspace up feat/my-feature
+devrouter workspace up feat/my-feature
 
 # List git worktrees with workspace tokens and route counts
-dev workspace ls
+devrouter workspace ls
 
 # Tear down a workspace (stop devpod, remove worktree, free routes)
-dev workspace down feat/my-feature
+devrouter workspace down feat/my-feature
 ```
 
 **devcontainer integration:** the devcontainer compose service exposes a devnet network alias `${WORKSPACE}-app` (defaulting to the project name in `devcontainer.env`); the proxy app uses `upstream: ${WORKSPACE}-app:<port>`. Workspace `feat-a` → alias `feat-a-app`, host `app.feat-a.localhost`.
 
 **Try it:** [`examples/workspace/`](examples/workspace/) is a runnable showcase — `./run.sh` brings up one app in two parallel worktrees (`wsdemo.localhost` and `wsdemo.feat-a.localhost`) served at once, then `./run.sh down` tears it down.
 
-**GC:** `dev doctor` check `routes.orphaned-workspace-routes` reclaims proxy routes whose worktree directory was removed without `dev workspace down`. Only orphaned workspace routes are reclaimed; primary-checkout routes are never touched.
+**DevPod example:** [`examples/devcontainer/`](examples/devcontainer/) is the
+agent-native devcontainer path end to end — `./run.sh` brings up a DevPod
+workspace, registers app/Postgres proxy routes, runs static/live verification,
+and prints the proof. `./run.sh down` tears it down.
+
+**Orphan detection:** `devrouter doctor` check `routes.orphaned-workspace-routes` reports proxy routes whose worktree directory was removed without `devrouter workspace down`. It does not mutate route state.
 
 ## Upgrade metadata and prompts
 
-`dev upgrade` and `dev -V` read local upgrade metadata from `.devrouter.yml` in the target repo (`devrouter.version`):
+`devrouter upgrade` and `devrouter -V` read local upgrade metadata from `.devrouter.yml` in the target repo (`devrouter.version`):
 
 ```yaml
 version: 1
@@ -136,18 +153,18 @@ apps: []
 
 Quick checks:
 
-- `dev -V` shows installed CLI version, local repo version, and next available upgrade target.
-- `dev upgrade` lists all upgrade targets newer than the local repo version and marks the next one.
-- `dev upgrade <version>` prints that target release's Agent Adaptation Prompt and then shows if a further version is available.
+- `devrouter -V` shows installed CLI version, local repo version, and next available upgrade target.
+- `devrouter upgrade` lists all upgrade targets newer than the local repo version and marks the next one.
+- `devrouter upgrade <version>` prints that target release's Agent Adaptation Prompt and then shows if a further version is available.
 - Upgrade prompts are sourced from `upgrade-prompts/<version>.md`.
-- `dev repo init` initializes `devrouter.version` to the installed CLI version.
+- `devrouter repo init` initializes `devrouter.version` to the installed CLI version.
 
 ## AI-native onboarding prompt
 
 Generate a ready-to-copy onboarding prompt for an AI agent:
 
 ```bash
-dev init --repo /absolute/path/to/repo
+devrouter init --repo /absolute/path/to/repo
 ```
 
 By default, this command is non-mutating (it prints prompt text only).
@@ -155,47 +172,48 @@ By default, this command is non-mutating (it prints prompt text only).
 Optional: embed target app entries as JSON:
 
 ```bash
-dev init --repo /absolute/path/to/repo --entries-json '[{"name":"web","host":"web.localhost","protocol":"http","runtime":"host"}]'
+devrouter init --repo /absolute/path/to/repo --entries-json '[{"name":"web","host":"web.localhost","protocol":"http","runtime":"host"}]'
 ```
 
 JSON mode for machine consumption:
 
 ```bash
-dev init --repo /absolute/path/to/repo --json
+devrouter init --repo /absolute/path/to/repo --json
 ```
 
 Optional repo artifact writes are explicit:
 
 ```bash
-dev init --repo /absolute/path/to/repo --write-agents --write-skill
+devrouter init --repo /absolute/path/to/repo --write-agents --write-skill
 ```
 
 Optional: also bootstrap Linear workflow skill/templates and AGENTS section:
 
 ```bash
-dev init --repo /absolute/path/to/repo --with-linear --write-agents --write-skill
+devrouter init --repo /absolute/path/to/repo --with-linear --write-agents --write-skill
 ```
 
 When `--with-linear` is combined with AGENTS writes, devrouter captures minimal Linear mapping (workspace, team, project). In non-interactive mode it writes placeholders and prints a warning so values can be filled in later.
 
 ## Health diagnostics
 
-Run deep checks for global router state and repo configuration:
+Run check-only diagnostics for global router state, machine prerequisites, route state, and repo configuration:
 
 ```bash
-dev doctor --repo /absolute/path/to/repo
+devrouter doctor --repo /absolute/path/to/repo
 ```
 
 Machine-friendly output:
 
 ```bash
-dev doctor --repo /absolute/path/to/repo --json
+devrouter doctor --repo /absolute/path/to/repo --json
 ```
 
-`dev status` now includes readiness hints and next-step commands.
-For host apps that depend on postgres, `dev doctor` also checks host command wrapper precedence and warns with `repo.host-command-env-precedence` when `DATABASE_URI`/`DATABASE_URL` is assigned before a `run --` wrapper boundary.
-When TLS is enabled, `dev doctor` also checks TLS host coverage and warns with `repo.tls-host-coverage` if configured `.localhost` hosts are not covered by the current cert SANs.
-`dev doctor` also reclaims orphaned workspace proxy routes (`routes.orphaned-workspace-routes`) whose worktree directory was removed without `dev workspace down`.
+`devrouter status` now includes readiness hints and next-step commands.
+For host apps that depend on postgres, `devrouter doctor` also checks host command wrapper precedence and warns with `repo.host-command-env-precedence` when `DATABASE_URI`/`DATABASE_URL` is assigned before a `run --` wrapper boundary.
+When TLS is enabled, `devrouter doctor` also checks TLS host coverage and warns with `repo.tls-host-coverage` if configured `.localhost` hosts are not covered by the current cert SANs.
+When `.devcontainer/` exists, `devrouter doctor` checks devnet aliases, published host ports, and proxy upstream alias matches.
+`devrouter doctor` reports stale host routes and orphaned workspace proxy routes without mutating route state.
 
 ## `.devrouter.yml` example
 
@@ -254,61 +272,69 @@ apps:
 Notes:
 
 - `kind` defaults to routed app behavior. Use `kind: dependency` for non-routed Docker dependencies.
-- `runtime: proxy` registers an HTTP route to an externally-managed `upstream` (`host:port`) and does nothing else — use it to put a stable `*.localhost` HTTPS host in front of a devcontainer or any process you start yourself. Loopback upstreams (`localhost`/`127.0.0.1`/`0.0.0.0`) are rewritten to `host.docker.internal` so Traefik (in Docker) can reach the host. The route persists until `dev app rm`.
-- TCP mode currently supports PostgreSQL first (`tcpProtocol: postgres`).
-- Multi-DB hostname routing on shared `:5432` requires TLS/SNI.
-- Plaintext Postgres is not supported for multiplexed hostname routing.
+- `runtime: proxy` registers an HTTP route to an externally-managed `upstream` (`host:port`) and does nothing else — use it to put a stable `*.localhost` HTTPS host in front of a devcontainer or any process you start yourself. Loopback upstreams (`localhost`/`127.0.0.1`/`0.0.0.0`) are rewritten to `host.docker.internal` so Traefik (in Docker) can reach the host. The route persists until `devrouter app rm`.
+- TCP routing supports `tcpProtocol: postgres`, `redis`, `mariadb`, and `mysql` on shared protocol ports with TLS/SNI.
+- Plaintext TCP is not supported for multiplexed hostname routing.
 - Multi-segment `.localhost` hosts are supported (for example `elearning.klicker.localhost`).
 
 ## Runtime behavior
 
-`dev app run <name>`:
+`devrouter app run <name>`:
 
 - reads `.devrouter.yml`
 - prompts to start declared dependencies (or use `--yes`)
 - starts docker target services for `runtime: docker` apps, plus declared docker dependencies
-- for `runtime: proxy` apps: registers the route to `upstream` and returns immediately (no process started, no dependencies); re-running is an idempotent upsert and the route persists until `dev app rm`
+- for `runtime: proxy` apps: registers the route to `upstream` and returns immediately (no process started, no dependencies); re-running is an idempotent upsert and the route persists until `devrouter app rm`
 - fails fast if host-runtime dependencies are configured (start those manually)
 - waits for Docker dependencies to become healthy (`--wait`) before proceeding
-- automatically stops Docker dependencies when a host app exits; docker app services remain running until explicit cleanup (`docker compose down`, `dev down`, or equivalent)
+- automatically stops Docker dependencies when a host app exits; docker app services remain running until explicit cleanup (`docker compose down`, `devrouter down`, or equivalent)
 - prints recent dependency logs (last 20 lines) after deps start
-- `kind=dependency` apps are dependency-only: they do not create routes and cannot be direct targets for `dev app run`, `dev app exec`, or `dev open`
+- `kind=dependency` apps are dependency-only: they do not create routes and cannot be direct targets for `devrouter app run`, `devrouter app exec`, or `devrouter open`
 - `kind=dependency` services start as declared in compose (no Traefik labels, no random published ports, no injected env vars)
-- for TCP deps of host apps: publishes a random host port and injects `<NAME>_HOST`/`<NAME>_PORT` env vars into the host process; for postgres deps also injects `DATABASE_URL` and `SHADOW_DATABASE_URL` (fixed credentials `prisma:prisma`, databases `prisma`/`shadow`)
-- for one-shot commands, `dev app exec` starts declared docker deps as needed and only stops deps it started in that invocation (already-running deps stay running)
-- if `dev app exec` cannot determine pre-existing running services, it leaves selected deps running to avoid stopping non-owned services
-- when TLS is enabled, `dev app run` / `dev app exec` auto-refresh cert SAN coverage for configured repo hosts before startup (fails fast with `Run: dev tls install` guidance if refresh fails)
-- for one-shot commands, `dev app exec` preserves argv semantics by default (`shell: false`) to avoid nested quoting issues
-- `dev app exec --shell` is explicit and requires one command string after `--`
-- `dev app exec --env-map TARGET=SOURCE` (repeatable) maps aliases after dependency env resolution (for example `DATABASE_URI=DATABASE_URL`)
+- for TCP deps of host apps: publishes a random host port and injects per-dependency `<NAME>_HOST`/`<NAME>_PORT`/`<NAME>_URL` env vars into the host process; for postgres deps also injects `<NAME>_SHADOW_URL` (fixed credentials `prisma:prisma`, databases `prisma`/`shadow`)
+- for one-shot commands, `devrouter app exec` starts declared docker deps as needed and only stops deps it started in that invocation (already-running deps stay running)
+- if `devrouter app exec` cannot determine pre-existing running services, it leaves selected deps running to avoid stopping non-owned services
+- when TLS is enabled, `devrouter app run` / `devrouter app exec` auto-refresh cert SAN coverage for configured repo hosts before startup (fails fast with `Run: devrouter tls install` guidance if refresh fails)
+- for one-shot commands, `devrouter app exec` preserves argv semantics by default (`shell: false`) to avoid nested quoting issues
+- `devrouter app exec --shell` is explicit and requires one command string after `--`
+- config-level `envMap` on dependency references maps aliases after dependency env resolution (for example `DATABASE_URL: DB_URL`)
 - starts host app command for host runtime apps
 - generates docker overlay in `~/.config/devrouter/cache/...` for docker runtime apps
 
 Secret manager interop (Infisical/Doppler):
 
-- dependency env injection from devrouter includes `<NAME>_HOST`, `<NAME>_PORT`, `DATABASE_URL`, and `SHADOW_DATABASE_URL`
+- dependency env injection from devrouter includes `<NAME>_HOST`, `<NAME>_PORT`, `<NAME>_URL`, and postgres-only `<NAME>_SHADOW_URL`
 - do not assume secret-manager precedence when DB vars overlap; validate effective env before migrate/seed
 - avoid pre-wrapper DB assignments such as `DATABASE_URI=... <wrapper> run -- ...`; wrapper-managed env may override those values
-- safe host-run override pattern when wrapper also defines `DATABASE_URI`: `infisical run --projectId <id> --env=<env> -- env DATABASE_URI=${DATABASE_URL:?missing DATABASE_URL} pnpm dev`
-- non-Prisma mapping example: `dev app exec web --yes --env-map DATABASE_URI=DATABASE_URL -- infisical run --projectId <id> --env=<env> -- pnpm payload migrate`
-- env probe example: `dev app exec web --yes --env-map DATABASE_URI=DATABASE_URL -- printenv DATABASE_URL DATABASE_URI DB_HOST DB_PORT SHADOW_DATABASE_URL`
-- run `dev doctor --repo <path>` to surface risky wrapper precedence (`repo.host-command-env-precedence`) before migrations or app startup
-
-`dev ls` output includes both configured app identity (`APP`) and runtime service identity (`SERVICE`).
+- map app-specific names in `.devrouter.yml`:
+  ```yaml
+  dependencies:
+    - app: db
+      envMap:
+        DATABASE_URL: DB_URL
+        DIRECT_URL: DB_URL
+        SHADOW_DATABASE_URL: DB_SHADOW_URL
+  ```
+- safe host-run override pattern when wrapper also defines `DATABASE_URI`: `infisical run --projectId <id> --env=<env> -- env DATABASE_URI=${DB_URL:?missing DB_URL} pnpm dev`
+- non-Prisma mapping example: `devrouter app exec web --yes -- infisical run --projectId <id> --env=<env> -- pnpm payload migrate`
+- env probe example: `devrouter app exec web --yes -- printenv DB_URL DATABASE_URL DB_HOST DB_PORT DB_SHADOW_URL SHADOW_DATABASE_URL`
+- run `devrouter doctor --repo <path>` to surface risky wrapper precedence (`repo.host-command-env-precedence`) before migrations or app startup
+
+`devrouter ls` output includes both configured app identity (`APP`) and runtime service identity (`SERVICE`).
 
 ## First onboarding quick path
 
 In a repo that has a host app and a Docker Postgres service:
 
 ```bash
-dev repo init
-dev app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd .
-dev app add --name db --host db.localhost --protocol tcp --runtime docker --tcp-protocol postgres --service db --port 5432 --compose-file docker-compose.yml
-dev app add --name redis --kind dependency --service redis --compose-file docker-compose.yml
-dev app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd . --depends-on db --depends-on redis
-dev tls install
-dev app run web --yes
-dev ls
+devrouter repo init
+devrouter app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd .
+devrouter app add --name db --host db.localhost --protocol tcp --runtime docker --tcp-protocol postgres --service db --port 5432 --compose-file docker-compose.yml
+devrouter app add --name redis --kind dependency --service redis --compose-file docker-compose.yml
+devrouter app add --name web --host web.localhost --protocol http --runtime host --command "pnpm dev" --cwd . --depends-on db --depends-on redis
+devrouter tls install
+devrouter app run web --yes
+devrouter ls
 ```
 
 Expected endpoints:
@@ -316,11 +342,11 @@ Expected endpoints:
 - `https://web.localhost`
 - `postgres://db.localhost:5432 (tls required)`
 
-## Demo workspace (in this repo)
+## Routing example (without devcontainers)
 
-A complete sample repository is included at:
+A complete no-devcontainer sample repository is included at:
 
-- [`./demo`](./demo)
+- [`./examples/routing`](./examples/routing)
 
 It contains:
 
@@ -329,24 +355,33 @@ It contains:
 - Postgres in Docker (`db`)
 - ready-to-use `.devrouter.yml`
 
-Run the end-to-end smoke demo:
+Run the bundled routing smoke:
+
+```bash
+pnpm routing:smoke
+```
+
+Run the live DevPod/devcontainer smoke when Docker, DevPod, and mkcert are
+available:
 
 ```bash
-pnpm demo:smoke
+pnpm devcontainer:smoke
+pnpm devcontainer:smoke down
 ```
 
 See details:
 
-- [`./demo/README.md`](./demo/README.md)
+- [`./examples/routing/README.md`](./examples/routing/README.md)
+- [`./examples/devcontainer/README.md`](./examples/devcontainer/README.md)
 
 ## AI agent discoverability
 
-`dev repo agents` writes a devrouter section into the repo's `AGENTS.md` and installs a skill file at `.agents/skills/devrouter/SKILL.md`. The skill content is embedded in the CLI bundle so it stays in sync across repos.
+`devrouter repo agents` writes a devrouter section into the repo's `AGENTS.md` and installs a skill file at `.agents/skills/devrouter/SKILL.md`. The skill content is embedded in the CLI bundle so it stays in sync across repos.
 
 If you also want Linear workflow assets and repository mapping metadata, run:
 
 ```bash
-dev repo agents --with-linear
+devrouter repo agents --with-linear
 ```
 
 This additionally installs:
@@ -380,8 +415,8 @@ Required Linear execution hygiene:
 
 - Host-runtime dependencies are not auto-started; only Docker dependencies are auto-started.
 - `kind=dependency` apps are not direct run/exec/open targets (must be started via a routed app dependency graph).
-- TCP routing currently supports PostgreSQL only (`tcpProtocol: postgres`).
-- Shared `:5432` hostname multiplexing requires TLS/SNI (`sslmode=require` or stronger).
+- TCP routing supports `tcpProtocol: postgres`, `redis`, `mariadb`, and `mysql`.
+- Shared TCP hostname multiplexing requires TLS/SNI (`sslmode=require` or protocol-equivalent client SNI).
 
 ## Router state
 
@@ -400,6 +435,6 @@ Global managed artifacts remain under:
 - Setup and bootstrapping: [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
 - Onboarding repositories and AI prompt: [`docs/REPO_ONBOARDING.md`](./docs/REPO_ONBOARDING.md)
 - Agent contributor guide: [`AGENTS.md`](./AGENTS.md)
-- Demo workspace: [`./demo/README.md`](./demo/README.md)
+- Routing example: [`./examples/routing/README.md`](./examples/routing/README.md)
 - Roadmap: [`docs/PLAN.md`](./docs/PLAN.md)
 - Release and adaptation history: [`CHANGELOG.md`](./CHANGELOG.md) and [`upgrade-prompts/`](./upgrade-prompts/)