@synap-core/workspace-templates 0.12.0 → 0.23.0

package/README.md

@@ -0,0 +1,483 @@
+# The Synap catalog
+
+ONE home for every official installable template: workspaces, capabilities, skills,
+packs and automations. The team sees, edits, validates and publishes them all from
+this folder, through one lib and one CLI. The live catalog is the Control Plane's
+`synap_packages` table, and it has one write door: `POST /api/packages` →
+`publishPackageCore`.
+
+> **Name today:** `synap-app/packages/workspace-templates/`, npm
+> `@synap-core/workspace-templates`. **Planned, not done:** a rename to
+> `packages/catalog/`, `@synap-core/catalog`, with the old name kept as a re-export
+> shim for one release. See [Coordinated rename](#5-coordinated-rename-planned).
+
+How installs, reconciles and tiers work is in the `synap-market` skill
+(`synap-backend/skills/synap-market/`), which is also the agent door.
+
+---
+
+## 1. What lives here, by kind
+
+| Dir | Kind | Format | Published today? |
+|---|---|---|---|
+| `src/*.yaml` | `workspace` (and `pack`, for a suite) | Legacy workspace YAML (`meta:` plus body). A thin adapter reads it as `{kind: workspace, meta, spec}` | Yes. 31 entries, CI on every push to main |
+| `capabilities/<key>.capability.json` | `capability` | Manifest (below). `meta` carries the listing and visibility; `spec` is the CapabilityDefinition | Yes, by hand. CI also publishes it once `SYNAP_CATALOG_LIVE_KINDS` includes `capability` (§3) |
+| `skills/<slug>/` | `skill` | Either a manifest `<slug>.skill.json` (`creative-director`), or an Agent-Skills folder (`SKILL.md` plus references) with a header `skills/<slug>.catalog.json` beside it | The manifest: yes. A folder: only with its header, and only when it holds no reference files (a skill package carries no documents). Today one folder has a header (`designing-with-real-components`); the five moved folders have none and are **staged** |
+| `packs/*.json` | `pack` (CP profile/view fragment) | CP `_meta` fragment | **Staged** (founder decision pending: what `pack` means). The CP's insert-only `seed-templates.ts` still owns them |
+| `automations/<slug>.automation.json` | `automation` | bridge-setup `flowDefinition` form, plus a header `automations/<slug>.catalog.json` beside it | Only with its header, and only without apply-time placeholders. Today none has a header, so all three are **staged** (`mail-feed` also carries two placeholders bridge-setup fills) |
+| `schema/` | | Zod manifest schema: `header.ts`, plus one body per kind (`workspace`, `capability`, `skill`, `automation`, `playbook`) | |
+| `standards/*.standard.yaml` | | Quality standard per workspace (`pnpm eval`) | |
+| `scripts/catalog-lib.mjs` | | **The ONE lib**: `loadCatalog` → `validateCatalog` → `diffCatalog` → `publishCatalog` | |
+| `src/*.ts` | | The typed bundle (`dist/`) that clients ship as the zero-network fallback | |
+
+A staged file is read, validated and counted, and the problem list carries a
+`staged` warning for it. It cannot reach `POST /api/packages`. Today the
+whole-catalog validate prints `✓ 73 catalog entries validated (selected: 31
+workspace · 41 capability · 1 skill · 0 pack · 0 automation)` (41 = 35 seeded on
+the CP + 6 authored here first).
+
+**What stays elsewhere:**
+- **System skills** (`system/*`) stay in `synap-backend/skills/`. They are the pod's
+  teaching substrate, seeded at boot, and are not marketplace items. Catalog files
+  may reference `system/*` slugs; the validator checks those exist when the
+  sibling repo is checked out, and says it skipped when it is not.
+- **CLI runtime skills** (`authoring-*`, `coordinating-*`) stay in `synap-cli/templates/skills/`.
+
+## 2. The one manifest shape
+
+```jsonc
+{
+  "apiVersion": "synap/v1",
+  "kind": "capability",            // workspace | capability | skill | pack | automation
+  "meta": {                        // the header: same limits as the CP publishSchema
+    "slug": "apify",               // kebab-case; dots only for a capability whose slug === spec.key
+    "name": "Apify — Web Scraping",
+    "description": "Find and run any Apify actor to collect data from public web pages and social posts. …",
+    "tags": ["capability"], "isPublic": true, "syncByDefault": true
+    // also: icon, color, domain, requiredTier, version?, owner ("template-owner" ⇔ private)
+  },
+  "spec": { "key": "apify", "skills": [ … ] },      // the per-kind body
+  "dependencies": []                                // { kind, slug } — what an install pulls in
+}
+```
+
+One pure compiler, `toPublishBody(manifest)`, turns a manifest into today's
+`POST /api/packages` body. The CP door and its `PACKAGE_TYPES` are unchanged. A
+workspace publishes as category `workspace`, a capability as `capability`, a skill
+as `skill`, an automation as `workflow`.
+
+Playbook goals use `{name}` placeholders. `@{arg:}` is refused at authoring; the
+runtime still reads it.
+
+## 3. Add or update, per kind
+
+**Workspace.** Edit or add `src/<slug>.yaml`, along with its `*.template.test.ts`
+when the template has one. Then run `pnpm --filter @synap-core/workspace-templates build`.
+That regenerates `src/templates.ts` and `dist/`. The publish refuses a stale
+`dist/`. **Bump `package.json` `version` whenever content changes**: the official
+publish stamps `definition.sourcePackage.version`, and clients let a remote row win
+only when it is strictly newer than their bundle.
+
+**Capability.** Edit `capabilities/<key>.capability.json`. The listing and
+visibility go in `meta`; the definition goes in `spec`.
+- **Transition:** an **existing** capability also has a CP copy,
+  `synap-control-plane-api/src/seeds/capability-templates/<key>.capability.json`,
+  whose content must equal `spec`. Its header lives in `capability-listings.ts` and
+  `CAPABILITY_VISIBILITY` in the seeder, and must equal `meta`. Change both sides.
+  The CP tripwire `catalog-mirror.tripwire.test.ts` turns red otherwise.
+- A **new** capability is authored here only: catalog-only files are allowed.
+- **A reader** is an ordinary verb that reads one link: `intent: "read_webpage"`, `metadata.readOnly: true`,
+  a required `url` parameter, and `urls: [...]` declaring the links it handles (`host[/path]`, `*.host`,
+  or `"*"`; the grammar lives in `@synap-core/types/url-read`). The pod's one read door routes by those
+  patterns; nothing else names a vendor. It returns a `UrlRead` (`status`, `text`, `media`, ...), saves
+  nothing, and an account-billed one runs only on the person's tap. Reference: `apify`'s
+  `capture_social_post`. `synap catalog validate` enforces it (`skill-urls`). The agents' own door to
+  reading a link is the pod's built-in `web.read` verb (Synap Core), not a catalog capability: the old
+  `web.read` pack is retired.
+
+**Skill.** Either a manifest `skills/<slug>/<slug>.skill.json` (`kind: skill`,
+`spec` = the CP's `definition.skill`), or an Agent-Skills folder
+`skills/<slug>/SKILL.md`. A folder stays in the shape `synap bridge-setup` reads; to
+publish it, add a header BESIDE it (never inside: bridge-setup imports every file in
+the folder as a document):
+
+```jsonc
+// skills/<slug>.catalog.json — a manifest without spec
+{ "apiVersion": "synap/v1", "kind": "skill",
+  "meta": { "slug": "<slug>", "name": "Display name", "description": "listing copy", "tags": [], "isPublic": true },
+  "dependencies": [] }
+```
+
+It compiles to `definition.skill = { slug: <frontmatter name>, name: meta.name,
+description: <frontmatter description>, kind: "instruction", scope: "pod", body }`,
+the same slug/description/body bridge-setup imports. Refused: reference files in the
+folder (`skill-documents`), `metadata.auto_load: true` (`skill-auto-load`), a
+frontmatter name that is not `meta.slug` (`skill-slug`). Without a header the folder
+is staged. Deciding which folders get a header (their listing and visibility) is a
+content decision; `reading-client-progress` and `stellar-scf-grants-advisor` are
+client-specific.
+- **Transition:** the five moved folders (`bookmark-enrichment`,
+  `mapping-the-server`, `reading-client-progress`, `routing-to-channels`,
+  `stellar-scf-grants-advisor`) must stay byte-identical to
+  `synap-cli/templates/skills/<slug>/`, because `bridge-setup` still reads them
+  there. The guard is the CLI's `test/catalog-mirror.tripwire.test.ts`.
+
+**Pack.** `packs/*.json` must stay byte-identical to the CP's `templates/packs/`
+(CP tripwire).
+
+**Automation.** Either a manifest (`kind: automation`, `spec` in the authoring
+`flow` form), or a raw `automations/<slug>.automation.json` in the `flowDefinition`
+form bridge-setup reads, published once a header `automations/<slug>.catalog.json`
+(`kind: "automation"`, no `spec`) sits beside it. It publishes as category
+`workflow`: `definition = { profiles: [], automations: [{ key: <slug>, name,
+description?, triggerType, triggerConfig, flowDefinition, status }] }`, i.e. the raw
+file minus its `metadata` notes. Refused: an apply-time placeholder
+(`apply-time-placeholder`: an empty or `<…>` connection id, a `<…>` output channel,
+a skill node without `skillId`) and any raw key a package cannot carry (`state`).
+Transition: the three raw files must stay byte-identical to
+`synap-cli/templates/automations/` (CLI tripwire).
+
+**Every kind.** Run the gate before you push:
+
+```bash
+cd synap-app
+node_modules/.bin/vitest run packages/workspace-templates        # schema, parity, lifecycle, goal grammar
+pnpm --filter @synap-core/workspace-templates type-check:catalog # schema/ + scripts/
+synap catalog validate                                           # the whole corpus, offline
+```
+
+The lib needs Node ≥ 22.18, because it imports `schema/*.ts` through native type
+stripping. An older Node refuses with `unsupported-runtime`.
+
+## Retiring a template
+
+A template that leaves the catalog is **not** just deleted: it gets a tombstone in
+`retired.yaml` (schema `schema/retired.ts`), so a pod can tell "retired, replaced by
+X" from "never heard of it" and offer the person a safe move to X.
+
+1. Delete the file (`src/<slug>.yaml`, `capabilities/<key>.capability.json`, …).
+2. Add an entry to `retired.yaml`:
+   ```yaml
+   - slug: radar
+     kind: workspace            # default; capability · skill · pack · automation
+     replacedBy: ecosystem      # a LIVE slug of the same kind, or omit when nothing replaces it
+     reason: Radar was merged into Ecosystem, which tracks competitors and trends in one place.
+     since: "2026-07-16"
+   ```
+3. `synap catalog validate`: `replacedBy` must be live and not retired, no slug may be
+   both live and retired **in the same category** (the CP keys rows on slug + category,
+   so a retired workspace `posthog-analytics` beside a live capability of that slug is
+   fine), and the reason must be one plain sentence a person reads.
+4. Publish as usual. `publishCatalog` sends each tombstone of the selected kinds to
+   `POST /api/packages/retire` through the catalog door, **after** the live publishes
+   (a replacement published in the same run exists by then; a tombstone whose
+   replacement failed is not sent). The preview prints `retire radar → ecosystem` with
+   its status: `new` (no CP row, a tombstone row is created), `changed` (the live row is
+   retired, or its retirement updated), `unchanged` (not sent). A CP without the endpoint
+   is reported as such, never skipped silently.
+
+Removing an entry from `retired.yaml` does not un-retire the CP row. The evidence
+behind each seeded entry is in the pod file `00c1b2fe-ef98-41fa-86cf-801dfab12cd1` ("Template lifecycle: decisions wave + lane catalog").
+
+## Removing a kind from a live template
+
+`retired.yaml` tombstones a whole template, not a kind inside one. There is no
+kind-level tombstone: remove the `profiles:` entry and everything that names it
+(views, relations, entity bento, onboarding `collect`, standards), bump the
+`package.json` version (minor for a removed kind), and republish. A pod that already
+installed the template keeps its profile and entities (profiles are never removed from
+an installed pod); only new installs lose the kind. The kinds removed this way are
+listed in `src/retired-goal-kinds.test.ts`, which fails if a template declares one again
+(Life OS `goal`, Enterprise OS `objective`, Project Management `okr`: "Goal" is the
+pod's track, decision D2, 2026-10-23).
+
+## Writing a process (a playbook that follows a kind's lifecycle)
+
+The status belongs to the **kind or role**, never to a playbook. Its profile declares the lifecycle ONCE, in its
+template:
+
+```yaml
+lifecycle:
+  property: post-status
+  options:
+    - { key: Idea, category: open }
+    - { key: Published, category: done }
+    - { key: Archived, category: lost, humanOnly: true }
+```
+
+Every option has one category (`open · active · paused · done · lost`); rules read the category, names stay free.
+`humanOnly` marks an option no agent sets; an agent's move into `done` or `lost` proposes. Every move goes through
+the one status door (`moveStatus`; an agent sends `update_entity` with `expectedStatus`).
+
+A step that can still move may also say when it is late and what it waits on, by the pod's own rules
+(`lifecycleOptionWaitsProblems` in `src/validate.ts`; never on a done or lost option):
+
+```yaml
+    - key: sent
+      category: active
+      dateBinding: dueDate                      # late once this date passes while it stands here
+      waits: { on: external, waitKind: payment, refFrom: clientId, dateBinding: dueDate }
+```
+
+`dateBinding` and `waits.refFrom` / `waits.dateBinding` are property slugs. `waits.on` is a hold's `on` (person ·
+agent · external · thing · decision · date · nobody); `waitKind` one of the pod's `WAIT_KINDS`.
+
+A new lifecycle should adopt one of the ten bases (`src/lifecycle-presets.ts`: work-item, run, decision, asset,
+publication, agreement, pipeline, relationship, offering, initiative) and say only how it differs:
+
+```yaml
+lifecycle:
+  property: reference-status
+  adopts: asset
+  rename: { in-review: studied, deprecated: archived }  # base key → this kind's key
+  drop: []                                               # base keys this kind does not use
+  add: []                                                # { key, category, after | before }
+  humanOnly: {}                                          # per step; false removes a base's mark
+  stuckAfterDays: {}                                     # per step
+  dateBinding: {}                                        # per step: { sent: dueDate }
+  waits: {}                                              # per step: { sent: { on: external } }
+```
+
+The build compiles it into the flat `options` above and writes the select's `enumValues` when the YAML leaves them
+out; nothing new reaches the pod. A lifecycle whose order the bases cannot express stays flat.
+
+A playbook that works that lifecycle is a **process**: it FOLLOWS it. Its stages name options of it, its workers
+start on it, and a person decides at the moments that commit the business. It never keeps a second status field.
+The reference is Content OS "Produce Content" (`synap-app/packages/workspace-templates/src/content-os.yaml`).
+
+**Official vs pod-local.** An official template or capability lives ONLY in the catalog
+(`synap-app/packages/workspace-templates/`, by kind) and is published with
+`synap catalog publish --official` (CI on main). A playbook, kind or automation an agent creates on a pod
+(`synap_create_playbook`, `synap_define_kind`, …) is **pod-local**: it never reaches the catalog. To make it
+official, write it into the catalog file and publish.
+
+| Field | Where | Rule |
+|---|---|---|
+| `subjectProfile.profileSlug` | playbook | The kind or role the process works. |
+| `subjectProfile.statusProperty` | playbook | Omit it: the pod follows the profile's declared lifecycle. If you name it, name that same property. A status worker on a role with no declared lifecycle is refused. |
+| `stages[].subjectStatus` | stage | Entering the stage moves the subject to this option, through the door. Must be an **existing option** of the lifecycle — never invent one. |
+| `stages[].gate` | stage | `{kind: human}` at every commitment: send to a client, sign, pay, publish, won/lost, anything irreversible. `{kind: check}` only where the stage's own criteria can be verified. A gated stage writes its status only when the gate passes. A check gate judges the stage being LEFT, so never use it to guard an irreversible status. |
+| `stages[].onFail` | stage | `{toStage: <key>}` — where a rejected gate sends the run (rework loop). |
+| `stages[].criteria` | stage | 2–5 binary statements; `check.kind` evidence (cheapest) · capability · judge · human. |
+| `expectedOutputs[]` | stage or playbook | What the step must produce: `kind` + `label` + `relationToSubject` (an existing relation slug, or `none`). The UI shows what was produced from this. |
+| `activators[]` (workers) | playbook | `on`: `created` · `enters_status` (+ `status`) · `count` (+ `status`, `min` ≥ 2) · `schedule` (+ `cron`, UTC) · `manual`. `size`: `per_thing` (default) · `per_moment` (count and schedule always are). `mode`: `propose` (default) · `run` only when cheap and safe. `maxPendingApprovals` (default 20) throttles. Compiled to a governed rule the owner can pause; it fires once per thing per transition. |
+| `humanOnlyStatuses` | playbook | Legacy: the options no stage owns. Mark a person-only option `humanOnly` on the lifecycle instead; while `statusProperty` is set, `synap catalog validate` still checks that stages and this list cover every option. |
+| `goalTemplate` | playbook | Placeholders are `{paramName}`. Never `@{arg:…}` (read-only legacy). |
+| `params` | playbook | The subject is a `type: entity` param. A required param left unanswered becomes a question owed by the person, not an empty string. |
+
+Human moments use an `ask` on an owed slot: `confirm` / `choose` (one `recommended`) / `form` / `act` / `provide`
+(connection, file or secret through the vault). Never ask for a secret in a form.
+
+Validation: `synap catalog validate` (process contract, goal grammar, lifecycle coverage ratchet — the count of
+lifecycle kinds with no process may only go down).
+
+## Intent: what a space produces
+
+A space is named by its PURPOSE first ("Product · Dev", "Sales · CRM") and is read through the THINGS it makes.
+The template that owns the space says both, in `meta.intent`:
+
+```yaml
+meta:
+  intent:
+    label: Product            # the purpose word, ≤ 24 characters
+    produces:                 # ordered; kinds or roles
+      - profile: devplane_feature
+      - profile: devplane_story
+      - profile: ui-design
+```
+
+- **Several kinds, never one only.** List what a person would come to the space to see move, in the order a home
+  shows them.
+- **No `produces` (or `[]`) = a library.** Brand, Strategy, Ecosystem, Knowledge… are read, not moved: they carry
+  a label only.
+- **Each produced profile declares a lifecycle** — a home counts things by lifecycle category, so a kind without
+  one cannot be counted (`intent-no-lifecycle`, naming it). Declare the lifecycle first (see "Writing a process").
+- **Each produced profile is the template's own or one it depends on** (`require`/`compose` closure), e.g. CRM
+  produces the `lead` and `client` roles whose lifecycles `foundation` declares (`intent-profile-unknown`).
+- **Only a template that owns a space declares it.** An overlay (`compose`) layers onto its base's space and a
+  pack (`suite`) owns none, so neither carries an intent (`intent-no-workspace`); `base` carries none either
+  (it is seeded into every space).
+- **On the pod.** Both install doors forward it as a top-level `intent` (never in `_meta`, which the CP rebuilds
+  on serve); the pod keeps it in `workspaces.settings.intent`. A space with no declared intent gets one inferred at
+  read time (the profiles there that declare a lifecycle and hold things), never stored.
+
+## 4. The ONE command set
+
+```bash
+synap catalog validate [--kind k] [slug...]           # offline: per-kind schema, cross-kind refs, goal grammar, duplicates
+synap catalog diff     [--kind k] [slug...]           # vs the live CP: new / changed / unchanged (+ warnings)
+synap catalog publish  --official [--kind k] [slug...] [--dry-run] [--yes] [--json]
+synap market publish   --official [slug...] [--dry-run]   # alias of: catalog publish --official --kind workspace
+```
+
+- `publish` requires `--official` and a `synap login` session that owns the
+  `synap-official` vendor. The CLI checks the publisher (`checkPublisher`) **before**
+  it shows the diff. A non-official account is refused up front. A failed read is
+  reported as `cp-unreachable`, never as "not official". `diff` warns instead of
+  refusing.
+- `publish` validates the **whole corpus** and stops on any error. It then shows the
+  diff, asks y/N, and writes only after you confirm. `--dry-run` stops after the
+  preview. Warnings never block.
+- A selection (`--kind`, slugs) narrows what gets planned and published. Validation
+  always covers the whole corpus, so a workspace's `dependencies` still resolve.
+- The CLI finds the checkout by package name (`@synap-core/catalog` first, then
+  `@synap-core/workspace-templates`), or by `--catalog-dir`. Every error code maps
+  to a single next step (`hint` in `--json`).
+
+**CI** (`synap-app/.github/workflows/publish-official-templates.yml`, through the
+wrapper `scripts/publish-official.mjs`, which uses the same lib):
+
+| Event | What runs |
+|---|---|
+| PR touching the catalog | Job `validate` only: build, validate every kind, print the **offline** preview (each entry and the version the CP will derive, where knowable offline). It holds **no secret and no `id-token`**: a PR runs its own lockfile and scripts. Guarded by `scripts/publish-workflow.guard.test.ts`. |
+| Push to `main` (or manual) | `validate`, then job `publish` (environment `catalog-publish`): a read-only preview against the live CP, then publish live `--kind ${SYNAP_CATALOG_LIVE_KINDS:-workspace}`, then npm publish, only if the `package.json` version is new on npm. |
+
+`SYNAP_CATALOG_LIVE_KINDS` is a repository **variable**. While it is unset, main
+publishes workspaces only: every kind is still validated and previewed, but only
+workspaces are written. Set it to `workspace,capability,skill,pack,automation`
+only after runbook §5 A. Secrets: `SYNAP_CP_URL`, `SYNAP_CP_PUBLISH_TOKEN`
+(a CP PAT of the `synap-official` owner; humans use `synap login`), `NPM_TOKEN`.
+
+**One-time setup of the `catalog-publish` environment** (GitHub → synap-app →
+Settings → Environments):
+1. Create the environment `catalog-publish`.
+2. Deployment branches and tags: **Selected branches → `main`** only.
+3. Add the environment secrets `SYNAP_CP_PUBLISH_TOKEN` and `SYNAP_CP_URL`.
+4. **Delete** the repository-level `SYNAP_CP_PUBLISH_TOKEN` (and `SYNAP_CP_URL`)
+   secrets, so no other job, and no workflow a branch pusher writes, can read them.
+   `NPM_TOKEN` may stay a repository secret (it is read only by the same job).
+Until step 3 is done, the `publish` job has no token: it validates and leaves a
+`::warning::`, it never publishes.
+
+**The CP never reseeds on deploy.** `deploy.sh`, `update.sh` and ops `apply` no
+longer run `seed:capabilities` or `seed:templates`. Both seeders are **insert-only
+bootstraps** for an empty CP, run by hand: they skip any slug that already has a
+row. A tripwire (`no-template-reseed-on-deploy-tripwire.test.ts`) guards this.
+**Official capability keys are reserved:** a non-official publish of an official
+key gets 409 `OFFICIAL_CAPABILITY_KEY_RESERVED`, and the CP serves the official row
+first for a key.
+
+**Transition mirrors** (each retires in the same change that deletes its copies; see §5).
+These guards are **local-only**: each skips when the sibling repo is not checked out,
+and every repo's CI checks out itself alone, so CI does not enforce them. Run them
+on a full monorepo checkout before merging a change to either side. The same holds
+for `schema/header.mirror.tripwire.test.ts` (header limits ↔ the CP `publishSchema`)
+and `scripts/catalog-lib.columns.tripwire.test.ts` (the preview's columns and
+adoption rule ↔ the CP publish core); their CI-safe halves are snapshots.
+
+| Copy | Guard | Retires when |
+|---|---|---|
+| CP `src/seeds/capability-templates/*.capability.json` + listings/visibility | CP `src/seeds/catalog-mirror.tripwire.test.ts` (spec- and meta-equal) | the CP pin is bumped and the seeder reads the package |
+| CP `templates/packs/*.json` | same file (byte-equal) | same |
+| CLI `templates/skills/<5 moved>/`, `templates/automations/*.automation.json` | CLI `test/catalog-mirror.tripwire.test.ts` (byte-equal, both directions) | the CLI's pin admits a package release that ships them: `bridge-setup` already reads the installed package first, and the CLI's retirement test fails while both exist |
+
+## 5. Founder runbook: deploy, publish, retire the copies
+
+Do these in order. The runbook only names the commands; it does not run anything.
+
+### A. Turn on catalog-published capabilities
+
+1. **Pre-flight on the prod CP DB.** Both queries must return 0 rows. If either
+   does not, resolve the duplicates first.
+   ```sql
+   SELECT lower(definition->'capability'->>'key') k, count(*)
+     FROM packages WHERE category = 'capability' GROUP BY 1 HAVING count(*) > 1;
+   SELECT slug, count(*)
+     FROM packages WHERE category = 'capability' GROUP BY 1 HAVING count(*) > 1;
+   ```
+2. **Deploy the backend first:** `26638d5e` ("an unanswered optional declared param
+   renders empty") must be live on the pods before any playbook goal written as
+   `{name}` reaches them; otherwise a literal `{programName}` lands in agent prompts.
+   Order: **backend → CP → dry run → publish.**
+3. **Deploy the CP** with all of these commits in that one deploy:
+   - `b669f90a`: posthog listing.
+   - `7ff44bf9`: capabilities publish onto their seeded row (official adoption, `syncByDefault`, dotted slug, description up to 10,000, full-column compare).
+   - `dac1da23`: reserved official keys, official-first read.
+   - `fe56bdf6`: reseed retired, seeder is insert-only.
+   - `d7a3f401`: ops drift is a human step.
+   - `0b0be3c8`: a capability key's owner is resolved before visibility; a key is a string equal to its slug.
+   - `a1401509`: an official publish adopts by the adoption rule, never a row of another kind.
+   - `6417b9f9`: `GET /api/packages/:slug?category=` serves the row a publish writes (the preview reads it).
+
+   Never ship `fe56bdf6` without `7ff44bf9` and `dac1da23`: on the old door, a catalog
+   publish forks every seeded row. This deploy no longer reseeds, so the rows stay
+   as the last reseed left them.
+4. **Dry run**, signed in as the official publisher (a private row is invisible to
+   an anonymous read): `synap catalog publish --official --kind capability --dry-run`.
+   The preview compares each body with the row the publish WRITES (the CP's adoption
+   rule) on the content version AND every column the CP writes, and prints a
+   content change as `~ definition: new content version` and each changed column
+   as `~ column: before → after`.
+5. **Read the diff.** Expected, and NOT a reason to stop:
+   - The **seeded capabilities** each show `CHANGED` with the same `h-` version and
+     only `~ source: "file-seed" → "api"`: the first publish writes each row once.
+   - **arch-client-intelligence** and **proton** show `CHANGED` with a new version (3 playbooks: Propose Grant Submission, Call Prep Brief, Draft Reply):
+     their playbook goals moved to the `{name}` grammar (`84363910`), which the
+     retired reseed never shipped.
+   - **posthog-analytics** shows `CHANGED` on its listing columns (`b669f90a`).
+   - **canva, dropbox, notion, slack, vercel** show `CHANGED` with a new version:
+     they have been official rows since 2026-10-01 (published from the old root
+     copies), and the catalog copy is newer (a derived `provides`, `72dd8d66`, and
+     reconciled descriptions). Their `~ tags` line shows only the AUTHORED tags
+     (`["capability"]`): the CP appends the search tokens it derives from the
+     definition, so the row keeps its search words and gains `capability` first.
+   - **content-idea-to-production** shows `CHANGED` on its definition and
+     description: the "Retired" listing the reseed never shipped.
+   - **claude-code-routines** is `NEW`. Publish it early: until an official row
+     exists, its key can be claimed by anyone.
+   - Any other `changed` row, or a warning that the CP ignores `?category=` (an
+     older CP): **STOP** and look.
+6. **Publish:** `synap catalog publish --official --kind capability`. Confirm at the
+   prompt.
+7. **Widen CI:** set the repo variable
+   `SYNAP_CATALOG_LIVE_KINDS=workspace,capability,skill,automation`. A skill folder
+   or raw automation publishes only once it has a header; `pack` stays out until
+   its meaning is decided.
+8. On a **brand-new, empty** CP only: run
+   `docker compose -f docker-compose.prod.yml run --rm control-plane pnpm seed:capabilities`
+   (and `seed:templates`) once, then step 6.
+
+### B. Publish the package and retire the mirrors
+
+1. **Publish the package to npm.** Merge a version bump to main, and CI publishes
+   it. Local is `0.13.0` and npm has `0.12.0`, so `check-publish-freshness` is red
+   until then. Never run `npm publish` by hand.
+2. **Bump the pins** and refresh each repo's own lockfile:
+   - **CP:** `^0.12.0` → `>=0.13.0 <1.0.0`. The caret excludes 0.13. Do this only
+     once the CP `pnpm-lock.yaml` is no longer peer-dirty.
+   - **CLI:** `>=0.12.0 <1.0.0`, which already admits 0.13. Refresh with
+     `pnpm install --lockfile-only --ignore-workspace` so the root lockfile is not
+     touched.
+   - **Backend:** `packages/api` **and** `apps/api` (`>=0.11.0 <1.0.0`). Move the
+     floor up only if a consumer needs the new content.
+3. **Point the readers at the package:**
+   - the CP seeder and capability resolver (`capability-template-dir.ts`) read
+     `node_modules/@synap-core/workspace-templates/capabilities/`, plus `packs/` for
+     `seed-templates.ts`;
+   - `synap bridge-setup` installs the published skill and automation entries
+     through the pod instead of reading `templates/`.
+4. **Delete the copies and their tripwires in the same change:**
+   - CP: `src/seeds/capability-templates/`, `templates/packs/`, the listing and
+     visibility literals, and `catalog-mirror.tripwire.test.ts`;
+   - CLI: the five moved skill folders, `templates/automations/`, and
+     `test/catalog-mirror.tripwire.test.ts`.
+
+### C. Coordinated rename (planned)
+
+Rename `packages/workspace-templates` to `packages/catalog` (`@synap-core/catalog`)
+in one change, at a quiet moment, because every tree's `node_modules` links move:
+
+1. `git mv synap-app/packages/workspace-templates synap-app/packages/catalog`.
+2. Update **both** workspace files: the root `pnpm-workspace.yaml`
+   (`synap-app/packages/workspace-templates`) and `synap-app/pnpm-workspace.yaml`
+   (`packages/workspace-templates`).
+3. Change the `package.json` `name` to `@synap-core/catalog`. Ship a thin
+   `@synap-core/workspace-templates` shim that re-exports it for one release. The
+   backend pins `>=0.11 <1`, the CP `^0.12`, the CLI `>=0.12 <1`, and the
+   synap-app/browser consumers use `workspace:*`.
+4. Update the workflow paths and `--filter` in `publish-official-templates.yml`,
+   and the `ci.yml` freshness step.
+5. Run `pnpm install` in each tree: the monorepo root, `synap-app/`, and each
+   sibling that installs on its own. Then run every consumer's typecheck.
+6. The CLI and both tripwires already resolve `packages/catalog` first. Remove the
+   `workspace-templates` fallback once the shim is retired.