@dragonmastery/tamer 0.1.2 → 0.28.0

package/README.md

@@ -1,20 +1,32 @@
 # @dragonmastery/tamer
 
-TypeScript types for Cloudflare Wrangler configuration. Generated from the official wrangler config schema. Supports Tamer and other CF CICD tooling.
+**Tamer tooling monorepo** — Cloudflare Workers infrastructure CLI (sync, apply, deploy, migrate, destroy), Wrangler-oriented TypeScript types (generated from the official Wrangler config schema), reference fixtures, and tests for the published **`@dragonmastery/tamer`** npm package.
 
-> **Note:** This package provides types only. The full Tamer CLI (sync, apply, dev, deploy) is in development.
+**Using Tamer in a downstream repo?** Install from npm and follow **[Consumer quickstart](docs/consumer-quickstart.md)**. The rest of this README is for contributors hacking Tamer and for CLI/config reference.
 
 ## Installation
 
+**Contributors** (this repo):
+
+```bash
+bun install
+```
+
+Requires [Bun](https://bun.sh) and Node.js **22+** (`engines.node`). Run the CLI with **`bun run tamer -- …`** or **`bun src/cli/index.ts …`** (see [Developing](#developing)).
+
+**Published package** (downstream repos):
+
 ```bash
-npm install @dragonmastery/tamer
-# or
-bun add @dragonmastery/tamer
+npm install -D @dragonmastery/tamer wrangler
 ```
 
-Requires `wrangler` (peer dependency) and Node.js 22+.
+Also requires the **`wrangler`** peer (`>=4.0.0`). Install, scripts, stack layout, and first deploy: **[Consumer quickstart](docs/consumer-quickstart.md)**.
+
+## Consumers (downstream repos)
+
+Install from npm and walk through bootstrap → apply → deploy in **[docs/consumer-quickstart.md](docs/consumer-quickstart.md)**. Resource kinds, `${tamer:import:…}`, outputs, and CLI flags remain documented below for reference.
 
-## Usage
+## Types usage
 
 ```ts
 import type {
@@ -29,21 +41,560 @@ const config: WranglerConfig = {
   name: "my-worker",
   main: "src/index.ts",
   compatibility_date: "2025-01-01",
-  d1_databases: [
-    { binding: "DB", database_id: "xxx" },
-  ],
+  d1_databases: [{ binding: "DB", database_id: "xxx" }],
 };
 ```
 
-## Exports
+| Type                  | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `WranglerConfig`      | Full wrangler config (alias: `RawConfig`)   |
+| `WranglerEnvironment` | Environment block (alias: `RawEnvironment`) |
+| `WranglerD1Database`  | D1 binding entry                            |
+| `WranglerR2Bucket`    | R2 binding entry                            |
+| `WranglerKVNamespace` | KV binding entry                            |
+
+## CLI
+
+```
+tamer bootstrap  Create per-env Tamer metadata: `tamer-state-<env>` (D1) and `tamer-artifacts-<env>` (R2)
+tamer sync       Sync local state from Cloudflare (no writes)
+tamer apply      Provision missing D1 / R2 / KV / Queues / Hyperdrive / Vectorize / AI Gateways / Pipelines / Workflows / Secrets Stores / DNS records / dispatch namespaces
+tamer migrate    Run D1 migrations per worker
+tamer deploy     wrangler deploy per worker (after sync), then apply zone-name `tamerRoutes` via Workers Routes API
+tamer dev        wrangler dev (use --all for every worker)
+tamer status     Show config vs state (optional `--tenant product:workspace`)
+tamer drift      Compare state vs Cloudflare and report differences (read-only)
+tamer plan       CloudFormation-style preview: what `apply`+`deploy` would create (read-only)
+tamer import     Register an existing Cloudflare resource into state by logical name
+tamer doctor     Verify `CLOUDFLARE_*` credentials against the account API (`--json` supported)
+tamer provision-tenant  Runtime: create tenant D1 + upload dispatch script (`--main` or `--artifact-key`)
+tamer destroy-tenant    Runtime: remove tenant script + D1 + state (shared envs: `--confirm-tenant`)
+tamer destroy    Remove workers + storage + namespaces for an env
+tamer wfp put    Upload a single-module Worker to a dispatch namespace
+tamer wfp delete Delete a Worker from a dispatch namespace
+```
+
+Common flags: `--env <name>` (required for every command; `tamer deploy --env <name>` no longer silently defaults to `prod`), `--worker <name>`, `--config <path>`, `--force`, `--confirm-env <name>` (destroy: required for any env in `tenant.protectedEnvs` from `tamer.config.ts` — defaults to `["prod","production"]` when unset; pass `protectedEnvs: ["prod","production","production-eu","qa"]` etc. to widen the gate, or `[]` to opt out — unless `--force`), `--confirm-tenant <workspace>` (destroy-tenant: same rule, sourced from `tenant.protectedEnvs`), `--skip-workers` (destroy), `--wipe-metadata` (destroy: delete shared `tamer-state-<env>` D1 **and** `tamer-artifacts-<env>` R2; use on the last stack in a multi-stack teardown), `--dispatch-namespace <name>` (deploy), `--json` (drift / plan: emit machine-readable JSON), `--detailed-exitcode` (plan: exit `2` instead of `0` when there are pending changes — Terraform-style CI gate), `--destroy` (plan: preview deletions instead of creates/updates — read-only `tamer destroy` dry-run).
+
+`tamer import` flags: `--kind d1|r2|kv|queue|hyperdrive|vectorize|ai_gateway|pipeline|workflow|secret_store|dns_record|dispatch_namespace|worker_route`, `--logical <name>` (logical name from `tamer.config.ts`, or worker key for `worker_route`), `--cf-id <id>` (D1 uuid, KV id, R2 bucket name, queue id, hyperdrive config id, vectorize index name, AI gateway id, pipeline id, workflow id, secrets store id, DNS record id, or dispatch namespace name), `--shard-date <YYYY-MM-DD>` (sharded D1 only), `--created-date <YYYY-MM-DD>` (R2: optional, defaults to extracting from name), `--route-id <id>` and `--zone-name <z>` (worker_route).
+
+### Environment variables
+
+Tamer uses the same env vars as Wrangler — see [system environment variables](https://developers.cloudflare.com/workers/wrangler/system-environment-variables/):
+
+- `CLOUDFLARE_ACCOUNT_ID`
+- `CLOUDFLARE_API_TOKEN`
+- `R2_ACCESS_KEY_ID` / `R2_SECRET_ACCESS_KEY` (optional) — [R2 S3 API](https://developers.cloudflare.com/r2/api/s3/tokens/) credentials. When both are set, `tamer destroy` empties managed R2 buckets (delete all objects, abort incomplete multipart uploads) before removing the bucket. Not the same as `CLOUDFLARE_API_TOKEN`.
+- `TAMER_DEV_BASE_PORT` (default `8787`, used by `dev --all`)
+
+Bun loads `.env` from the **current working directory** automatically when you run `bun src/cli/index.ts ...`, so you can keep credentials in a per-project `.env` (gitignored) instead of exporting them.
+
+### API token scopes
+
+Custom token, **scoped to the account** you target. Names match Cloudflare’s [API token permissions reference](https://developers.cloudflare.com/fundamentals/api/reference/permissions/):
+
+| Permission                | Scope   | Used by                                                                  |
+| ------------------------- | ------- | ------------------------------------------------------------------------ |
+| **Workers Scripts: Edit** | Account | `deploy`, `destroy` (worker delete), `wfp put`, dispatch-namespace ops   |
+| **Workers KV Storage: Edit** | Account | KV `apply` / `destroy` / `sync`                                       |
+| **Workers R2 Storage: Edit** | Account | R2 `apply` / `destroy` / `sync`                                       |
+| **D1: Edit**              | Account | D1 `apply` / `destroy` / `migrate` / `sync`                              |
+| **Queues: Edit**          | Account | Queues `apply` / `destroy` / `sync` / `drift` / `import`                |
+| **Hyperdrive: Edit**      | Account | Hyperdrive `apply` / `destroy` / `sync` / `drift` / `import`            |
+| **Vectorize: Edit**       | Account | Vectorize `apply` / `destroy` / `sync` / `drift` / `import`             |
+| **AI Gateway: Edit**      | Account | AI Gateway `apply` / `destroy` / `sync` / `drift` / `import`            |
+| **Pipelines: Edit**       | Account | Pipelines `apply` / `destroy` / `sync` / `drift` / `import`             |
+| **Workflows: Edit**       | Account | Workflows `apply` / `destroy` / `sync` / `drift` / `import`             |
+| **Secrets Store: Edit**   | Account | Secrets Store `apply` / `destroy` / `sync` / `drift` / `import`         |
+| **DNS: Edit**             | Zone    | DNS records `apply` / `destroy` / `sync` / `drift` / `import` (zones declared in `dnsRecords[]`) |
+| **Logs: Edit** (or **Logpush: Edit**) | Account | `logpushJobs` in `tamer.config.ts`: create/delete Workers trace Logpush jobs ([Workers Logpush](https://developers.cloudflare.com/workers/observability/logs/logpush/)) |
+| **Workers R2 Data Catalog: Edit** | Account | **`pipelinesAuto` (apply token):** calls `POST …/r2-catalog/{bucket}/enable` and `…/credential` on your **CLOUDFLARE_API_TOKEN** — *not* the minted “catalog+sink” sub-token. With **Workers R2 Storage: Edit** on the catalog bucket for Pipelines. |
+| **API Tokens: Edit** (or equivalent) | Account | **`pipelinesAuto` (apply token):** [list permission groups](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/subresources/permission_groups/methods/list/) and [create / delete](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/) the two **account** sub-tokens only. |
+| **Account Settings: Read** | Account | Account-scoped reads (and required by Wrangler subprocesses)            |
+| **Workers Tail: Read**    | Account | Optional, only for `wrangler tail`                                       |
+| **Workers Routes: Edit**  | Zone    | Zone-name `tamerRoutes`: list/create/delete routes (`deploy`, `sync`, `destroy`, `drift`). Skip if you only use wrangler-native `routes` or custom-domain `tamerRoutes`. |
+| **Zone: Read**            | Zone    | Resolving `zone_name` → zone id for those routes (same zones as above). |
+
+The dashboard template **“Edit Cloudflare Workers”** covers most of these; **add D1: Edit** manually.
+
+**Workers trace → Pipelines → Iceberg (`pipelinesAuto`):** On **`tamer apply`**, Tamer [mints](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/create/) two **account** sub-tokens, in line with the dashboard: **Workers R2 Data Catalog** (Edit/Write) only for the stored **catalog** credential and the `r2_data_catalog` sink, and [Workers Pipelines **Send**](https://developers.cloudflare.com/pipelines/streams/writing-to-streams/) only for Logpush stream ingest. **Values are stored in the `logpush_pipelines` state entry**; treat that state as sensitive. Your **`CLOUDFLARE_API_TOKEN`** must *also* be allowed to call the **R2 Data Catalog** account HTTP API (`/accounts/.../r2-catalog/...` for enable + credential) on its own — that uses the apply token, not the sub-tokens. The same apply token also needs the account Token API, Logpush, Pipelines, etc. (table [above](#api-token-scopes), [Account Token API](https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/)). If sink creation fails with **HTTP 422 / code 1012** (*existing catalog table*), change **`pipelinesAuto.tableName`** and/or **`namespace`** to a name that does not already exist in that catalog bucket.
+
+For read-only flows (`status`, dry runs), use the **Read** variants instead.
+
+### Resource kinds
+
+Tamer-managed resources are declared on a worker under `resources`. Each kind expands to a Wrangler binding plus a state row keyed by derived name.
+
+```ts
+defineWorker({
+  resources: {
+    d1: [{ logicalName: "settings", type: "single" }],
+    r2: [{ logicalName: "assets" }],
+    kv: [{ logicalName: "cache" }],
+    queues: [
+      { logicalName: "events" },               // producer binding emitted
+      { logicalName: "audit", consumerOnly: true }, // queue created, no producer binding
+    ],
+    hyperdrive: [
+      {
+        logicalName: "primary",
+        origin: {
+          scheme: "postgres",
+          host: "db.example.com",
+          port: 5432,
+          database: "app",
+          user: "app",
+          password: { fromEnv: "PG_PW" },        // never persisted in state
+        },
+        localConnectionString: "postgres://localhost/app",
+      },
+    ],
+    vectorize: [
+      { logicalName: "embeddings", dimensions: 768, metric: "cosine" },
+    ],
+    aiGateway: [
+      {
+        logicalName: "openai",
+        cacheTtl: 60,           // seconds; 0 = caching off (default)
+        authentication: true,   // require Authorization header on gateway endpoint
+        rateLimitingInterval: 60,
+        rateLimitingLimit: 100,
+      },
+    ],
+    pipelines: [
+      {
+        logicalName: "events",
+        // Arroyo SQL — `events_stream` and `events_sink` must already exist on Cloudflare.
+        sql: "insert into events_sink select * from events_stream;",
+      },
+    ],
+    workflows: [
+      {
+        logicalName: "billing",
+        className: "BillingWorkflow",  // class exported from this worker's entrypoint
+        // scriptName defaults to the owning worker's deployed script — pin it
+        // here only to bind to a different worker's exported class.
+        limits: { steps: 50 },         // optional — tracked in state for drift
+      },
+    ],
+    secretsStores: [
+      // Tamer manages the *store* (account-scoped container). Secret values
+      // inside it are written out-of-band via wrangler / dashboard / CI.
+      { logicalName: "apiKeys" },
+    ],
+    secretsStoreSecrets: [
+      // Wire one previously-uploaded secret into this worker. The wrangler
+      // generator resolves `store: "apiKeys"` to the live store_id from state.
+      { binding: "STRIPE_KEY", store: "apiKeys", secretName: "stripe_key" },
+    ],
+  },
+  vars: {
+    // No wrangler binding for AI Gateway — pull the derived id into env vars instead.
+    AI_GATEWAY_ID: "${tamer:ai_gateway:openai.name}",
+  },
+});
+```
+
+Notes:
+
+- **Queues**: Tamer creates the queue itself on `apply` and emits `queues.producers[]` in the generated wrangler config. Consumer subscriptions stay wrangler-side — set them on the worker config under `queues.consumers` (passed through verbatim).
+- **Hyperdrive**: the origin connection (including `password` and optional `access_client_secret`) is sent to Cloudflare on `apply` and discarded — Tamer's state only records the resulting config id, scheme, host and database name. Use `{ fromEnv: "VAR" }` to source secrets from the shell environment so they never enter `tamer.config.ts`. `localConnectionString` is written to the generated wrangler config for `wrangler dev` only.
+- **Vectorize**: `dimensions` and `metric` (`cosine` | `euclidean` | `dot-product`) are immutable once the index is created. To change them, run `tamer destroy --resource <logicalName>` (or scope to the kind) and re-apply. The generated wrangler config emits `vectorize[]` bindings using the derived index name.
+- **AI Gateway**: gateways are account-scoped and have **no Wrangler binding kind** — Workers reference them per-request via `env.AI.run(model, opts, { gateway: { id } })` (or by URL on the OpenAI-compatible endpoint). Tamer therefore emits no wrangler fragment for AI Gateway; use the cross-resource ref `${tamer:ai_gateway:<logical>.name}` (or `.id`) in worker `vars` to inject the derived gateway id. Derived id pattern: `aigw-{logical}-t-{tenantId}-{env}`. All listed `cacheTtl` / `rateLimiting*` / `authentication` / `cacheInvalidateOnUpdate` / `collectLogs` fields are optional with sensible defaults (caching off, rate limiting off, logs on, fixed-window).
+- **Pipelines (V1, SQL)**: Tamer creates the pipeline against `/accounts/{id}/pipelines/v1/pipelines` and emits `pipelines[]` in the generated wrangler config. The `sql` field is mandatory and references streams (sources) and sinks (destinations) **by name** — those upstream/downstream resources are not Tamer-managed in this iteration; create them via the Cloudflare dashboard or Wrangler before applying, otherwise the pipeline will exist in non-running status. Pipeline SQL changes on existing pipelines require `tamer destroy --resource <logicalName>` followed by re-apply (Cloudflare V1 has no PATCH endpoint today). Derived name pattern: `pipe-{logical}-t-{tenantId}-{env}`. Default binding key: `PIPE_{LOGICAL}_T_{TENANT}` (override with `binding`).
+- **Workflows**: Tamer registers the workflow with Cloudflare via `PUT /accounts/{id}/workflows/{name}` and emits `workflows[]` in the generated wrangler config. `className` is the exported class on the owning worker; `script_name` defaults to that worker's deployed script (env-suffixed for shared envs), so workflow classes co-located with their owning worker need no extra config. Set `scriptName` explicitly to bind to a different worker. Optional `limits.steps` (positive integer) is tracked in state and reapplied on drift. Derived name pattern: `wf-{logical}-t-{tenantId}-{env}`. Default binding key: `WF_{LOGICAL}_T_{TENANT}` (override with `binding`). Workflow registrations are immutable in shape but mutable in target — class-name or script-name changes are issued as in-place PUTs; deletes go through `DELETE /accounts/{id}/workflows/{name}` and `tamer destroy` removes them transactionally.
+- **DNS records**: declared at the **stack root** (not per worker), since the same record shouldn't be redeclared by every worker that happens to live behind it. Add `dnsRecords[]` directly on the `defineConfig({ ... })` document. Tamer creates each record via `POST /zones/{zoneId}/dns_records` and stamps a stable attribution comment (`tamer:<tenantId>:<env>:<logicalName>`) so subsequent `sync` / `apply` runs can re-adopt the record from a Cloudflare listing even after state loss. Mutable-field drift (`content`, `ttl`, `proxied`, `priority`, `comment`) is patched in place via `PATCH /zones/{zoneId}/dns_records/{recordId}`; `type` changes follow Cloudflare's delete-and-recreate convention. State key `dns_record:{zoneId}:{type}:{name}`. The `local` env is always implicitly skipped (DNS is a real-world side effect — `wrangler dev` does not own real DNS); use `skipEnvs` to opt out of additional envs. Set `preserveOnDestroy: true` on a record to keep it on Cloudflare past `tamer destroy` (the state row is dropped either way for clean teardown). Requires the **DNS: Edit** zone-scoped permission for every zone referenced in `dnsRecords[]`.
+- **Secrets Store**: Tamer manages account-scoped **stores** (containers) — never the secret values inside them. On `apply`, each declared `secretsStores[]` entry is created via `POST /accounts/{id}/secrets_store/stores` (idempotent — a matching name in `secretsStoreListAll` short-circuits to the existing `id`) and the assigned id is recorded in state. To wire a stored secret into a worker, declare a `secretsStoreSecrets[]` entry referencing the store by its logical name (`store: "apiKeys"`); the wrangler generator resolves it to the live `store_id` and emits a `secrets_store_secrets[]` row with `{ binding, store_id, secret_name }`. The named secret itself must already exist in the store — create it out-of-band via `wrangler secrets-store secret create` (or the dashboard) so secret material never enters `tamer.config.ts` or `tamer-state-*`. Derived store name: `sec-{logical}-t-{tenantId}-{env}`. Cross-resource refs supported (`${tamer:secret_store:<logical>.name|id|binding}`). `tamer destroy` removes managed stores transactionally — Cloudflare cascades the deletion to all contained secrets, so make sure no live worker still binds into the store first.
+
+### Stack-scoped DNS records (`dnsRecords`)
+
+Declared once on the `defineConfig({ ... })` root, not per worker. Each entry pins the zone (`zoneId`), the record `type`, the DNS `name`, and the `content`; everything else is optional.
+
+```ts
+import { defineConfig } from "@dragonmastery/tamer";
+
+export default defineConfig({
+  workers: { /* ... */ },
+  dnsRecords: [
+    {
+      logicalName: "apex",
+      zoneId: "0123456789abcdef0123456789abcdef",
+      type: "A",
+      name: "todo.com",
+      content: "192.0.2.1",
+      proxied: true,
+    },
+    {
+      logicalName: "www",
+      zoneId: "0123456789abcdef0123456789abcdef",
+      type: "CNAME",
+      name: "www.todo.com",
+      content: "todo.com",
+      proxied: true,
+    },
+    {
+      logicalName: "spf",
+      zoneId: "0123456789abcdef0123456789abcdef",
+      type: "TXT",
+      name: "todo.com",
+      content: "v=spf1 -all",
+      ttl: 3600,
+      comment: "anti-spoofing baseline",     // appended after Tamer's attribution comment
+    },
+    {
+      logicalName: "mailRouting",
+      zoneId: "0123456789abcdef0123456789abcdef",
+      type: "MX",
+      name: "todo.com",
+      content: "mail.todo.com",
+      priority: 10,
+      preserveOnDestroy: true,                // survive `tamer destroy`
+    },
+    {
+      logicalName: "stagingApex",
+      zoneId: "0123456789abcdef0123456789abcdef",
+      type: "A",
+      name: "todo.com",
+      content: "192.0.2.2",
+      skipEnvs: ["dev", "prod"],              // only created in `staging`
+    },
+  ],
+});
+```
+
+### Cross-resource references (`${tamer:...}`)
+
+CloudFormation `!Ref` / `!GetAtt` analogue. Embed `${tamer:<kind>:<logicalName>.<field>}` in worker `vars` or in `tamerRoutes[].host` / `tamerRoutes[].zone` to interpolate values from already-applied state at wrangler-config generation time.
+
+| Kind                  | `name` (default)              | `id`                              | `binding`              |
+| --------------------- | ----------------------------- | --------------------------------- | ---------------------- |
+| `d1`                  | derived database name         | D1 UUID                           | wrangler binding key   |
+| `r2`                  | derived bucket name           | *(unsupported — buckets use name)*| wrangler binding key   |
+| `kv`                  | derived namespace title       | KV namespace id                   | wrangler binding key   |
+| `queue`               | derived queue name            | queue id                          | wrangler binding key   |
+| `hyperdrive`          | derived config name           | hyperdrive config id              | wrangler binding key   |
+| `vectorize`           | derived index name            | vectorize index id                | wrangler binding key   |
+| `ai_gateway`          | derived gateway id            | derived gateway id                | stable cross-ref key (no wrangler binding) |
+| `pipeline`            | derived pipeline name         | server-assigned pipeline id       | wrangler binding key   |
+| `workflow`            | derived workflow name         | server-assigned workflow id       | wrangler binding key   |
+| `secret_store`        | derived store name            | server-assigned store id          | stable cross-ref key (no wrangler binding) |
+| `dispatch_namespace`  | resolved per-env namespace    | namespace name                    | —                      |
+| `worker`              | env-suffixed deployed script  | —                                 | —                      |
+
+Examples:
+
+```ts
+defineWorker({
+  resources: { r2: [{ logicalName: "assets" }], queues: [{ logicalName: "events" }] },
+  vars: {
+    ASSETS_BUCKET: "${tamer:r2:assets.name}",
+    EVENTS_QUEUE: "${tamer:queue:events.name}",
+    INTERPOLATED: "queue=${tamer:queue:events.name};kv=${tamer:kv:cache.id}",
+  },
+  tamerRoutes: [
+    // hosts/zones can also embed references resolved against state
+    { host: "api-${tamer:worker:edge.name}.todo.com", zone: "todo.com" },
+  ],
+});
+```
+
+Resolution behavior:
+
+- **Strict mode** (`apply`, `deploy`, `destroy`): unresolved references throw `TamerReferenceError` with the field path (e.g. `worker[default].vars.ASSETS_BUCKET`) and a "run apply first" hint, so a typo in `<logicalName>` or a forgotten apply fails fast.
+- **Tolerant mode** (`plan`, `drift`, `status`, `sync`): unresolved references are left in place as their original `${tamer:...}` placeholder, so read-only commands work on a fresh checkout before the first apply.
+
+### Stack outputs (`outputs`)
+
+CloudFormation `Outputs` analogue: declare named values your stack publishes after a successful `apply`. Each value is a Tamer reference string (`${tamer:<kind>:<logical>.<field>}`) — full-string OR interpolated — resolved against the just-completed state and persisted under `CfiState.stackOutputs` so it survives across runs and is visible to `tamer status` (and to sibling stacks via `${tamer:import:<stack>.<output>}`, shipping next).
+
+```ts
+export default defineConfig({
+  tenant: { id: "platform", name: "Platform", slug: "ext" },
+  worker: { main: "src/index.ts", resources: { d1: [{ logicalName: "users", type: "single" }] } },
+  outputs: {
+    usersDbId:    "${tamer:d1:users.id}",
+    eventsQueue:  "${tamer:queue:events.name}",
+    adminUrl:     "https://admin.example.com/?db=${tamer:d1:users.id}",
+    pinnedLiteral: "v1.0.0",
+  },
+});
+```
+
+Behavior:
+
+- Output **names** must match `^[a-zA-Z][a-zA-Z0-9_-]*$` (CloudFormation-style identifier — keeps them safe in env-var exports, filenames, and the `${tamer:import:…}` parser). Validated at config-load time.
+- Resolution runs at the **end** of a successful `apply`, after every resource is in state. A typo in any output (unknown logical name, unknown field, unknown kind) fails the apply with `TamerReferenceError` tagged `outputs.<name>` and rolls back when `--rollback-on-failure` is set.
+- Persisted entry shape: `{ value, source, resolvedAt }` — keeps both the resolved literal and the original `${tamer:...}` source so `status` can flag drift.
+- `tamer status` prints a per-output row tagged `resolved` (declared source matches persisted source), `pending` (declared but never applied), `stale` (config edit since last apply — re-run apply), or `orphan` (persisted but no longer declared in config).
+- `tamer destroy` clears `stackOutputs` after teardown so a future `status` doesn't surface refs to deleted resources.
+- Re-applies are structurally idempotent: when value + source are unchanged, `resolvedAt` is updated in memory but state isn't dirtied (no gratuitous `revision` bump).
+
+### Cross-stack imports (`${tamer:import:<stack>.<output>}`)
+
+CloudFormation `Fn::ImportValue` analogue. One stack publishes named values via `outputs:` (above); a sibling stack consumes them by referencing `${tamer:import:<stack>.<output>}` anywhere a regular `${tamer:...}` reference is allowed (worker `vars`, `tamerRoutes[].host` / `.zone`, **`services[].service`**, **`dispatch_namespaces[].namespace`**, even another stack's `outputs`). Multiple stacks now coexist in the same `tamer-state-<env>` D1 by namespacing the state row as `cfi_state:{stackName}`, so the consumer just reads the producer's row and looks up the named output.
+
+```ts
+// fixtures/network/tamer.config.ts (the "producer")
+export default defineConfig({
+  stack: { name: "net", description: "Network plane: shared edge router + queue" },
+  tenant: { id: "platform", name: "Platform", slug: "net" },
+  worker: { main: "src/edge.ts", resources: { queues: [{ logicalName: "events" }] } },
+  outputs: {
+    edgeQueue: "${tamer:queue:events.name}",
+    region:    "iad",
+  },
+});
+
+// fixtures/app/tamer.config.ts (the "consumer")
+export default defineConfig({
+  stack: { name: "app" },
+  tenant: { id: "platform", name: "Platform", slug: "app" },
+  worker: {
+    main: "src/index.ts",
+    vars: {
+      EDGE_QUEUE: "${tamer:import:net.edgeQueue}",
+      REGION:     "${tamer:import:net.region}",
+      QUEUE_URL:  "https://${tamer:import:net.region}.example.com/q/${tamer:import:net.edgeQueue}",
+    },
+    tamerRoutes: [{ host: "${tamer:import:net.region}.app.example.com", zone: "example.com" }],
+  },
+  outputs: {
+    region: "${tamer:import:net.region}", // republish a sibling's value
+  },
+});
+```
+
+Behavior:
+
+- **Stack identity.** `stack: { name?, description? }` pins the producer's row key; `name` defaults to `tenant.slug`, so existing single-stack configs keep working unchanged. Output names match `^[a-zA-Z][a-zA-Z0-9_-]*$` (same as `outputs:`).
+- **Pre-fetch once per command.** At command start (`apply`, `deploy`, `dev`, `migrate`, `types`, `plan`, `drift`, `sync`, `status`) Tamer scans the config for `${tamer:import:…}` sites, hydrates a read-only `StateManager` per referenced sibling, and flattens every `stackOutputs.<output>.value` into an in-memory `imports` map. Subsequent reference resolution is a pure map lookup — no D1 round-trips mid-build, no partial-failure modes.
+- **Strict at write time** (`apply`, `deploy`): a typo, a sibling that hasn't been applied yet, or an output the sibling never published all fail with `TamerReferenceError` tagged with the field path (e.g. `worker[default].vars.EDGE_QUEUE`) and an `Available outputs on stack "<name>": …` hint. **Tolerant at read time** (`plan`, `drift`, `status`, `sync`): unresolved import refs stay in place as their literal `${tamer:import:…}` placeholder so a fresh checkout works before the first apply.
+- **Self-imports are filtered.** A stack that mistakenly references its own name in `${tamer:import:…}` is dropped at scan time so the typo doesn't silently resolve via the row apply is about to write — it surfaces as the same "no imported stack available" error a missing sibling would produce.
+- **`tamer status` shows imports.** A new "Inbound imports" panel lists every `${tamer:import:…}` site grouped by source stack, with the resolved value (or `(missing — run \`tamer apply\` on that stack)`) and a per-output `resolved` / `unresolved` tag — the operator-facing equivalent of CloudFormation's stack-export view.
+- **Greenfield row key.** No compat alias for the legacy literal `cfi_state` row key — first run on an env D1 created by an older `bootstrap` will see no state and rebuild from `sync`.
+- `local` env skips import pre-fetch entirely (no shared state DB exists), so cross-stack composition is a non-`local` deployment concern.
+
+### Adding a new resource kind (resource registry)
+
+Every Tamer-managed Cloudflare resource (D1, R2, KV, Queues, Hyperdrive, Vectorize, ...) is wired through a single registry at `src/core/registry/registry.ts`. The CLI commands (`apply`, `sync`, `drift`, `destroy`, `status`, `import`) and the wrangler generator iterate `resourceModules` — none of them special-case any kind.
+
+To add a new kind (e.g. Pipelines, Workflows, Pages):
+
+1. Add the config + state types to `src/types.ts` (`<Kind>ResourceConfig`, `<Kind>StateEntry`, append to `WorkerResources` and `StateEntry`).
+2. Implement the per-feature module under `src/features/<kind>/` (`<kind>.apply.ts`, `<kind>.sync.ts`, `<kind>.drift.ts`, `<kind>.destroy.ts`, `<kind>.status.ts`, `<kind>.generate.ts`).
+3. Author `src/features/<kind>/<kind>.module.ts` exporting a `ResourceModule` (see `src/core/registry/types.ts`); it wires the per-feature functions into the generic `apply` / `sync` / `drift` / `destroy` / `status` / `generate` / `importOne` / `pickResources` / `fetchAll` shape and declares its `kind`, `label`, `configKey`, and `stateEntryType`.
+4. Append the module to `resourceModules` in `src/core/registry/registry.ts`.
+
+That's it — every command picks the kind up automatically and `tamer status`, `tamer drift`, `tamer plan`, `tamer import --kind <kind>`, and the generated `wrangler.json` will all include it.
+
+### Routes (`tamerRoutes`)
+
+Workers can declare HTTP routes that Tamer expands per env per [handoff §6](docs/handoff.md):
+
+- **prod / production** → bare apex (`todo.com`, `admin.platform.com`).
+- **other shared envs** (`dev`, `staging`, …) → `{env}.{apex}` (`dev.todo.com`).
+- **ephemeral envs** (any env matching `tenant.ephemeralEnvPattern` in `tamer.config.ts` — e.g. `"^pr-"` for `pr-1234`) → `{env}.{apex}` (`pr-1234.todo.com`).
+- **local** → no route.
+
+```ts
+defineWorker({
+  scriptName: "portal-ui",
+  tamerRoutes: [
+    { host: "portal.todo.com" },                  // → {env}.portal.todo.com/* (zone_name=portal.todo.com)
+    { host: "api.todo.com", zone: "todo.com" },   // explicit parent zone
+    { host: "todo.com", customDomain: true },     // CustomDomainRoute
+  ],
+});
+```
+
+How routes land in Wrangler vs the Cloudflare API:
+
+- **Zone-name routes** (`zone_name` + `pattern`, including default `tamerRoutes` expansion) are **not** written into generated `wrangler.json`. They are tracked as `worker_route` entries in `tamer-state-{env}` and applied with the [Workers Routes API](https://developers.cloudflare.com/api/resources/workers/subresources/routes/) **after** a successful `wrangler deploy` for that script (so the worker exists before the route binds). `tamer sync` reconciles listings into state; `tamer destroy` removes API routes before deleting workers; `tamer drift` reports mismatches for these routes.
+- **Custom-domain `tamerRoutes`** (`customDomain: true`) and any **static `routes`** you declare in worker config are still merged into generated `wrangler.json` and deployed by Wrangler only.
+
+To opt out per env, set `skipEnvs` (default `["local"]`) or `prodEnvs` (default `["prod", "production"]`). Tamer never strips or rewrites the wrangler-native `routes` field — declare both if you need static escape-hatch routes alongside `tamerRoutes`.
+
+### Workspace tenants (runtime)
+
+`CfiState` (D1 `tamer-state-{env}`) includes a `tenants` map keyed `product:workspace` for signup-time resources **not** declared in `tamer.config.ts`.
+
+- `tamer provision-tenant --env dev --product todo --workspace acme --main ./worker.js` — for every role declared in `tenant.d1Shards` in `tamer.config.ts`, creates the per-tenant D1 (`db_{role}_{w}_{p}_t_{tid}_{env}`); then uploads the dispatch script to the first configured dispatch namespace and records `TenantStateEntry` as `ready`. Tamer ships **no built-in shard layout** — the engine is opinion-free, so a Dragoncore-style product picks `d1Shards: ["system", "app", "history"]`, a single-DB tenant picks `["main"]`, a billing/content split picks `["billing", "content"]`, and a tenant that needs no per-tenant DB at all simply omits `d1Shards` and gets the dispatch script alone. Use `--artifact-key <path/in/tamer-artifacts-{env}>` instead of `--main` to deploy from R2. Pass `--shards a,b` to **trim** the configured layout to a subset for ephemeral previews; the CLI flag cannot extend the configured set (config is the source of truth — typos surface with the configured roles in the error message). Re-runs are idempotent: existing shards are adopted, missing shards are added in place, so editing `tenant.d1Shards` to add a new role and re-running picks up the new shard without disturbing the others. Pass `--json` for a single trailing JSON line on stdout `{ status: "ready"|"noop"|"failed", tenantKey, scriptName, dispatchNamespaceName, shards: [{role, derivedName, cfId}] }` — designed for the Cloudflare Container caller (`provision-workflow`, see [container invocation contract](#container-invocation-contract)).
+- `tamer destroy-tenant --env dev --product todo --workspace acme --confirm-tenant acme` — deletes the dispatch script, every tenant D1 shard recorded in state, and removes the tenant record (shared envs require confirmation or `--force`). Pass `--json` for `{ status: "destroyed"|"noop"|"failed", removed: { scriptName, dispatchNamespaceName, shards }, errors }`.
+- `tamer status --env dev --tenant todo:acme` — shows provisioning status and bound resources.
+
+#### Container invocation contract
+
+The tenant runtime commands are designed to be invoked by a Cloudflare Container (`provision-workflow` per [`docs/handoff.md`](docs/handoff.md) §7) — same image CI uses (`Dockerfile`). Build and run:
+
+```bash
+docker build -t tamer .
+docker run --rm \
+  -e CLOUDFLARE_ACCOUNT_ID -e CLOUDFLARE_API_TOKEN \
+  -v "$PWD":/work -w /work \
+  tamer provision-tenant --env dev --product todo --workspace acme \
+    --artifact-key todo/worker.js --json
+```
+
+Contract:
+
+- **Exit code is the source of truth.** `0` on success or no-op, non-zero on failure. `provision-workflow` should branch on this, not on log scraping.
+- **Stdout's last line is a JSON envelope** when `--json` is passed (other lines remain human-readable). Failure path also emits an envelope (`status: "failed"`, `error: <message>`) before the non-zero exit.
+- **No interactive prompts.** Shared-env safety still applies — destroy callers must pass `--confirm-tenant <workspace>` (or `--force`) explicitly.
+- **Idempotent.** Workflow retries are safe: re-invoking `provision-tenant` with the same args produces `status: "noop"` once the tenant is `ready`; partial-failure resumes pick up from the last persisted shard.
+
+If two writers update state concurrently, `persist` throws `StateConflictError` and the CLI exits with code **3**; re-run after refreshing state.
+
+### Plan (`tamer plan`)
+
+CloudFormation-style preview of `apply` + `deploy`. Reads only — never mutates state or Cloudflare. Shows every D1 / R2 / KV / dispatch namespace / Workers zone route declared in `tamer.config.ts` that isn't yet on Cloudflare, plus declared **global Worker scripts** that have no deployment (queried directly via `GET /accounts/.../workers/scripts/{name}`; dispatch-namespace tenant scripts are skipped — those belong to `provision-tenant` / WFP).
+
+```bash
+tamer plan --env dev                    # human-readable summary, exit 0
+tamer plan --env dev --json             # machine-readable for CI
+tamer plan --env dev --detailed-exitcode
+# ↑ exit 0 if no changes, 2 if changes pending (Terraform convention),
+#   non-zero on errors as usual
+
+tamer plan --env dev --out plan.json    # also persist a verifiable plan file
+
+tamer plan --env dev --destroy          # preview what `tamer destroy` would remove
+tamer plan --env dev --destroy --json --detailed-exitcode
+# ↑ exit 2 when there is anything to delete (CI gate before stack teardown)
+```
+
+**Scoped plan / apply (`--target`)** — Limit preview or provisioning to a single declared resource: `--target <kind>:<logicalName>` (e.g. `d1:settings`, `r2:assets`, `dispatch_namespace:workspace`, `dns_record:apex_txt`). Uses the same kind strings as `tamer import --kind`. A scoped **`tamer apply`** still runs sync, still regenerates **every** worker’s `wrangler.json`, and still resolves the full `outputs:` block at the end so state stays coherent. **`--target` is incompatible with `apply --plan` and `plan --out`** — saved plan files attest the whole stack. `worker_route` and `worker_script` are not supported here (zone routes apply after **`tamer deploy`**; scripts are deployed by wrangler).
+
+The plan reuses the `drift` engine for "would create" detection, so the rules are the same: drift filters by current-stack `logicalName`s in shared-state setups, and `local` envs only show storage that would be created in-memory.
+
+For tracked resources whose recorded state has drifted from the declared config, `tamer plan` also emits `update` and `replace` items with terraform-style attribute change detail:
+
+```text
+DNS records (1):
+  ~ apex -> A todo.com (content: 192.0.2.1 -> 192.0.2.99, proxied: false -> true)
+Vectorize (1):
+  ± embeddings -> vec-embeddings-t-acme-dev (dimensions: 768 -> 1536, metric: cosine -> euclidean)
+
+Summary: 0 to create, 1 to update, 1 to replace.
+```
+
+`+` is `create`, `~` is `update` (in-place PATCH on apply), `±` is `replace` (Cloudflare's API rejects PATCH on the changed field, so apply must delete + recreate — DNS record `type` change, Vectorize `dimensions` / `metric`, Pipelines V1 `sql`), `-` is `delete` (destroy plan only). `--json` includes the same diffs as `items[].changes[]: { field, from, to, kind: "mutable" | "immutable" }`. Today the `update` / `replace` engine covers DNS records, Workflows, Vectorize, and Pipelines; other kinds emit only `create` / `delete`.
+
+#### Destroy preview (`tamer plan --destroy`)
+
+Mutually exclusive with the forward plan. Walks `tamer-state-{env}`, filters to entries owned by the current `tamer.config.ts` stack (same scoping as `tamer destroy` / `tamer drift`), and emits a `delete` `PlanItem` per managed kind — D1, R2, KV, Queues, Hyperdrive, Vectorize, AI Gateway, Pipelines, Workflows, Secrets Stores, dispatch namespaces, DNS records, and zone `tamerRoutes`. Declared global Worker scripts that currently exist on Cloudflare also appear as `worker_script` deletes. Dispatch-namespace tenant scripts are intentionally excluded — those are managed via `provision-tenant` / `destroy-tenant`. Read-only: never mutates state or Cloudflare.
+
+`--out destroy.json` writes the destroy plan with the same `(config, state, cloudflare)` attestation as forward plans (`report.mode: "destroy"`); `tamer destroy --plan destroy.json` then recomputes the three hashes and refuses to proceed unless they all match (override with `--allow-stale`). Mode mismatch is **non-overridable**: `apply --plan` rejects destroy plans and `destroy --plan` rejects forward plans regardless of `--allow-stale`, so a saved plan can only ever execute the operation the operator reviewed.
+
+```bash
+tamer plan --env dev --destroy --out destroy.json
+git diff destroy.json && code review ...
+tamer destroy --env dev --confirm-env dev --plan destroy.json
+# Refuses with one of:
+#   "config has changed since plan was generated; ..."
+#   "recorded state has changed since plan was generated; ..."
+#   "Cloudflare-side resources drifted since plan was generated (out-of-band create/delete); ..."
+tamer destroy --env dev --confirm-env dev --plan destroy.json --allow-stale
+```
+
+#### Saved plans + transactional apply
+
+`--out plan.json` writes a `tamer-plan/v1` document containing the plan report and an **attestation**: SHA-256 hashes of (a) the parsed config, (b) the recorded state's resources/tenants/stack (timestamps and revision counters are excluded so legitimate noise doesn't trigger false mismatches), and (c) the **live Cloudflare snapshot** at plan time — the per-kind `fetchAll` + `sync` result against a fresh in-memory state, with timestamps stripped. `cloudflareHash` is omitted for `env: local` and for legacy plans written before drift-aware refresh.
+
+`tamer apply --plan plan.json` recomputes all three hashes against the current `(config, state, live Cloudflare)` triple and refuses to proceed if any drifted, mirroring `terraform apply <planfile>` plus `terraform refresh`. Out-of-band creates or deletes on Cloudflare between plan and apply are caught here; the recorded state alone wouldn't notice. Pass `--allow-stale` only when you've reviewed the diff and want to override:
+
+```bash
+tamer plan --env dev --out plan.json
+git diff plan.json && code review ...
+tamer apply --env dev --plan plan.json
+# Refuses with one of:
+#   "config has changed since plan was generated; ..."
+#   "recorded state has changed since plan was generated; ..."
+#   "Cloudflare-side resources drifted since plan was generated (out-of-band create/delete); ..."
+tamer apply --env dev --plan plan.json --allow-stale     # opt-in override
+```
+
+`tamer apply --rollback-on-failure` snapshots state-entry keys at start and, on any failure, walks every key created during the run in reverse insertion order and asks the owning module's `destroyOne` to delete the underlying Cloudflare resource (best-effort; failures log a warning and never mask the original error). Use it in CI to keep your account clean when an apply fails halfway:
+
+```bash
+tamer apply --env dev --plan plan.json --rollback-on-failure
+```
+
+### Import (`tamer import`)
+
+CloudFormation `import_resources` analogue. When state is missing one specific resource that already exists on Cloudflare (created out-of-band, or after a partial restore), `import` registers it under its logical name without touching the resource itself. Verifies the Cloudflare object exists and that the cf-side name matches Tamer's derived name for `--logical` before writing the state entry.
+
+```bash
+tamer import --env dev --kind d1 --logical settings --cf-id <d1-uuid>
+tamer import --env dev --kind d1 --logical events --shard-date 2026-01-15 --cf-id <d1-uuid>
+tamer import --env dev --kind r2 --logical assets --cf-id r2-assets-t-acme-dev
+tamer import --env dev --kind kv  --logical cache --cf-id <kv-namespace-id>
+tamer import --env dev --kind queue --logical events --cf-id <queue-id>
+tamer import --env dev --kind hyperdrive --logical primary --cf-id <hyperdrive-config-id>
+tamer import --env dev --kind dispatch_namespace --logical workspace-workers --cf-id workspace-workers-dev
+tamer import --env dev --kind worker_route --logical portal_ui --route-id <route-id> --zone-name portal.todo.com
+tamer import --env dev --kind dns_record --logical apex --cf-id <dns-record-id>
+```
+
+Use `tamer sync` for bulk discovery instead. `import` refuses to overwrite an existing state row that points at a different Cloudflare id.
+
+### Drift (`tamer drift`)
+
+Read-only diff between Tamer state, Cloudflare reality, and the current `tamer.config.ts`. Useful for CI guards and pre-deploy sanity checks; never writes to state or to Cloudflare.
+
+For each managed resource kind (D1, R2, KV, **Queues**, **Hyperdrive**, dispatch namespaces, **HTTP routes** when you use zone-name `tamerRoutes`, and **Worker scripts** for declared global workers) the report lists three buckets:
+
+- **`missingFromCloudflare`** — state references a resource that no longer exists on Cloudflare (deleted out-of-band; consider rerunning `apply` or pruning state).
+- **`unrecordedInState`** — Cloudflare has a resource that matches a declared logical name in this stack's config, but no state entry tracks it (run `tamer sync`).
+- **`undeployed`** — declared in this stack's config, present in neither state nor Cloudflare (run `tamer apply`).
+
+```bash
+tamer drift --env dev          # human-readable; non-zero exit when drift
+tamer drift --env dev --json   # machine-readable for CI
+```
+
+Drift filters by the current config's `logicalName`s, so multi-stack environments sharing one `tamer-state-<env>` only report on resources owned by the current stack. Zone-name `tamerRoutes` appear under **HTTP routes (Workers Routes API)**; custom-domain and wrangler-only `routes` are not checked here (Wrangler remains their source of truth). The **Worker scripts** section only emits `undeployed` (declared but missing on Cloudflare) since global script ids aren't tracked in state today.
+
+### State and artifacts
+
+For non-`local` envs, `tamer bootstrap --env <env>` provisions two pieces of per-env metadata Tamer owns directly:
+
+- **`tamer-state-<env>` (D1):** stores deployment state as JSON (logical resources mapped to Cloudflare IDs — D1 UUIDs, KV IDs, dispatch namespaces, Workers zone route ids for API-managed `tamerRoutes`, etc.) plus optional CloudFormation-style **stack metadata** (`stack.name`, `stack.owner`) and a **last operation marker** (`lastOperation`: command name, `in_progress` / `succeeded` / `failed`, timestamps, error message) updated by `bootstrap` / `apply` / `deploy` / `destroy` / `import`. Each successful or failed run also appends a snapshot to **operationHistory** (newest first, capped at 50 entries) so operators can review recent changes. **`tamer events`** (read-only) prints that timeline, optional **`--limit N`**, and **`--json`** for automation. `sync` merges API listings into this document; Cloudflare remains the source of truth for what exists. State schema is on **v4** (auto-migrates v2/v3 in place on read). Each stack's document lives at row key `cfi_state:{stackName}` (where `stackName` comes from `stack: { name? }` in `tamer.config.ts`, defaulting to `tenant.slug`), so multiple stacks can share the same `tamer-state-<env>` D1 without overwriting each other — required by `${tamer:import:<stack>.<output>}` cross-stack references.
+- **`tamer-artifacts-<env>` (R2):** holds Tamer-managed bundles keyed by `{resource-type}/{name}/{version}/...`. Used by future runtime provisioning paths (read-only at deploy time today).
+
+Multi-stack flows (`fixtures/platform`, `fixtures/portal`, and `fixtures/internal`) share one `tamer-state-<env>` and one `tamer-artifacts-<env>` per account when you use the normal bring-up scripts; `tamer:down` passes `--wipe-metadata` only on the **platform** destroy (`fixtures/platform`) so the metadata DB and artifacts bucket are removed once at the end. The bucket delete is best-effort — if it still has objects, the operator must clean them and re-run `--wipe-metadata`.
+
+See **[Runbook](docs/runbook.md)** for the **platform + portal + internal** fixtures (spin-up, tear-down, flags).
+
+## Developing
+
+From the repo root after **`bun install`**:
+
+- **CLI:** **`bun run tamer -- <command>`** (root `package.json` → `bun src/cli/index.ts`) or invoke **`bun src/cli/index.ts`** directly.
+- **Fixtures:** reference stacks under **`fixtures/platform`**, **`fixtures/portal`**, and **`fixtures/internal`**. Bring up / tear down with **`bun run tamer:up`** / **`bun run tamer:down`** — see **[Runbook](docs/runbook.md)**.
+- **Tests:** **`bun run typecheck`** and **`bun run test`**. CI uses **`bun run test:report`** (JUnit → **`reports/junit.xml`**, dots output). Coverage: **`bun run test:coverage`** → **`coverage/lcov.info`**. Details: **[Testing](docs/testing.md)**.
+- **CI:** **[`.github/workflows/ci.yaml`](.github/workflows/ci.yaml)** — typecheck + unit tests on pushes and PRs to **`main`** / **`apex`**.
+- **Publish:** npm releases via **[`.github/workflows/publish-npm.yaml`](.github/workflows/publish-npm.yaml)** (Trusted Publishing / OIDC). Packaging: **[npm-cli-packaging-strategy.md](docs/npm-cli-packaging-strategy.md)**. Cross-repo contracts: **[publish.md](docs/publish.md)**.
+
+Fixture smoke test (requires **`.env`** under each fixture directory):
+
+```bash
+bun run tamer:up -- --env dev
+# …
+bun run tamer:down -- --env dev --confirm-env dev
+```
+
+## Documentation
+
+| Doc | Audience |
+| --- | --- |
+| **[Consumer quickstart](docs/consumer-quickstart.md)** | Downstream repos — install from npm, first deploy, version pinning |
+| **[Testing](docs/testing.md)** | Contributors — test runners, JUnit, coverage |
+| **[Publish / integration requirements](docs/publish.md)** | Maintainers — cross-repo contracts for DragonMastery stacks |
+| **[npm CLI packaging strategy](docs/npm-cli-packaging-strategy.md)** | Maintainers — npm package build and release layout |
+| **[Runbook](docs/runbook.md)** | Contributors — platform + portal + internal fixture walkthrough |
+| **[Platform architecture](docs/platform-arch.md)** | Platform owners — repos, stacks, runtime model, rollout |
 
-| Type                 | Description                    |
-| -------------------- | ------------------------------ |
-| `WranglerConfig`     | Full wrangler config (alias: `RawConfig`) |
-| `WranglerEnvironment`| Environment block (alias: `RawEnvironment`) |
-| `WranglerD1Database` | D1 binding entry               |
-| `WranglerR2Bucket`   | R2 binding entry               |
-| `WranglerKVNamespace`| KV binding entry              |
+Other material lives under [`docs/`](docs/).
 
 ## License