@synap-core/workspace-templates 0.24.1 → 0.26.0

package/README.md

@@ -9,7 +9,7 @@ this folder, through one lib and one CLI. The live catalog is the Control Plane'
 > **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).
+> shim for one release. See [Coordinated rename](#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.
@@ -25,7 +25,8 @@ How installs, reconciles and tiers work is in the `synap-market` skill
 | `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). Headers decided by the founder on 2026-11-05: `bookmark-enrichment` and `routing-to-channels` public, `mapping-the-server` unlisted (private to the official owner); `reading-client-progress` and the parked `stellar-scf-grants-advisor` stay **staged** |
 | `views/<slug>.view.json` | `view` | Manifest; `spec.views` in the canonical shape the CP stores (`{slug, displayName, type, config, scopeProfileSlugs}`) | Category `view`. Three today (`bookmark-views-pack`, `event-views-pack`, `task-views-pack`), moved from the old CP pack fragments on 2026-11-05. CI on every push to main |
 | `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. Headers decided by the founder on 2026-11-05: `bookmark-enrichment` public; `url-bookmark-capture`, `github-pr-events` and the five `ship-a-change-*` unlisted. `mail-feed` stays **staged**: it carries two placeholders bridge-setup fills |
-| `schema/` | | Zod manifest schema: `header.ts`, plus one body per kind (`workspace`, `capability`, `skill`, `automation`, `playbook`) | |
+| `agents/<slug>.agent.yaml` | `agent` | Manifest. `spec` (`schema/agent.ts`) is what the pod reads as `definition.agent`: `harness` (the `agent_type` join key), `aliases`, `worker`, `tried`, `detect`, `wake` (data: `program` + `args` + `params`, never a shell line; required for a worker only), `practices.skills`. One per program of the backend harness registry, plus `hermes`. CP category `agent`, official vendor only, left out of browse lists (the catalog installs every official agent on every pod, founder decision D8) | **Not automatically.** `publish-official.mjs` leaves `agent` out when no `--kind` is given (`FIRST_PUBLISH_BY_HAND`), so main's publish skips it; the founder approves the first publish (`--kind agent`), after the CP that knows the category is deployed |
+| `schema/` | | Zod manifest schema: `header.ts`, plus one body per kind (`workspace`, `capability`, `skill`, `automation`, `view`, `agent`, `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 | |
@@ -260,10 +261,11 @@ start on it, and a person decides at the moments that commit the business. It ne
 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.
+(`synap-app/packages/workspace-templates/`, by kind); landing it on app-bases main publishes it (CI). 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 land it
+on main. A pod draft proposal mirrored into the catalog is a second copy: once the file lands, withdraw the
+proposal; the review is the catalog commit.
 
 | Field | Where | Rule |
 |---|---|---|
@@ -317,10 +319,16 @@ meta:
 
 ## 4. The ONE command set
 
+**Landing on app-bases `main` IS publishing.** Every push to `main` runs CI (below),
+which publishes every kind, tombstones included. Content that waits for the
+founder's review waits BEFORE it lands on `main`; once it lands it is live. Nobody
+runs a publish step after a merge: `synap catalog publish --official` is the same
+lib by hand, for an emergency republish when CI cannot run.
+
 ```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 catalog publish  --official [--kind k] [slug...] [--dry-run] [--yes] [--json]   # emergency republish only
 synap market publish   --official [slug...] [--dry-run]   # alias of: catalog publish --official --kind workspace
 ```
 
@@ -344,23 +352,19 @@ 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 EVERY kind live (no `--kind`), tombstones included, then npm publish, only if the `package.json` version is new on npm. |
+| Push to `main` (or manual) | `validate`, then job `publish` (environment `catalog-publish`): a read-only preview against the live CP, then publish EVERY kind live (no `--kind`), tombstones included, then npm publish, only if the `package.json` version is new on npm. A live run with no `SYNAP_CP_PUBLISH_TOKEN` exits 1: a `main` run that publishes nothing is red, never green with a warning. |
 
 Main publishes every kind (founder, 2026-11-05: "remove the blocker that only do
-workspace, we will do ALL"); the old `SYNAP_CATALOG_LIVE_KINDS` variable is not
-read. 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.
+workspace, we will do ALL"). Secrets, in the `catalog-publish` environment only:
+`SYNAP_CP_URL` and `SYNAP_CP_PUBLISH_TOKEN` (a CP PAT of the `synap-official`
+owner; humans use `synap login`). npm needs no secret: it publishes through npm
+Trusted Publishing (OIDC, the job's `id-token: write`).
+
+**The `catalog-publish` environment** (GitHub → app-bases → Settings →
+Environments; set up and live since 2026-11-06): deployment branches **`main`**
+only; environment secrets `SYNAP_CP_PUBLISH_TOKEN` and `SYNAP_CP_URL`; no
+repository-level copy of either, so no other job, and no workflow a branch pusher
+writes, can read them.
 
 **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
@@ -378,101 +382,34 @@ stay **local-only** (they skip when the CP is not a sibling checkout):
 `scripts/catalog-lib.columns.tripwire.test.ts` (the preview's columns and adoption
 rule ↔ the CP publish core); their CI-safe halves are snapshots.
 
-## 5. Founder runbook: deploy, publish, retire the copies
-
-Do these in order. The runbook only names the commands; it does not run anything.
+## 5. History, and an empty CP
+
+**How the catalog got here** (the by-hand runbook this section used to hold is done):
+- Until 2026-11-05 the founder published by hand, kind by kind, with
+  `synap catalog publish --official`, after deploying the CP that adopts the seeded
+  rows; the CP and the CLI each held a copy of catalog files.
+- 2026-11-05: `main` publishes every kind (founder: "remove the blocker that only
+  do workspace, we will do ALL"). The copies are deleted: the CP and the CLI read
+  the installed package (CP `2c755f8e`, synap-cli#91), guarded by their
+  `no-catalog-copy` tripwires.
+- 2026-11-06: control-plane-api #70 let the publish token reach every call the
+  publish makes; run 42141858556 printed "Published 116 catalog entries". Since
+  then landing on `main` publishes.
+
+**A brand-new, empty CP only:** seed it once, then let CI publish:
+```bash
+docker compose -f docker-compose.prod.yml run --rm control-plane pnpm seed:capabilities
+docker compose -f docker-compose.prod.yml run --rm control-plane pnpm seed:templates
+gh workflow run publish-official-templates.yml -R Synap-core/app-bases
+```
+Both seeders are insert-only; `seed:templates` seeds workspaces only (views reach
+an empty CP through the publish).
 
-### A. Turn on catalog-published capabilities
+**CI cannot run** (GitHub down, the environment broken): `synap catalog publish
+--official`, signed in as the `synap-official` owner, republishes `main`'s catalog
+through the same lib. Say so where you work: it is a recovery, not a step.
 
-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. **Views** (`views/`, 2026-11-05): `synap catalog diff bookmark-views-pack
-   event-views-pack task-views-pack` shows each `CHANGED`: a new content version
-   (the new listing description inside the definition), `displayName` and
-   `description` (the catalog's copy, which never reached the CP), `source:
-   "file-seed" → "api"` and `vendorId: null → synap-official` (the publish adopts
-   the unowned seeded row). The views themselves are byte-equal to the live rows.
-   CI publishes them with every other kind on the next push to main.
-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 publish (step 6). `seed:templates` seeds
-   workspaces only: views reach an empty CP through the publish.
-
-### 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/` (done 2026-11-05;
-     `seed-templates.ts` no longer seeds packs: views publish through the door);
-   - `synap bridge-setup` reads the skill and automation files from the installed
-     package (done, synap-cli#91).
-4. **Delete the copies and their tripwires in the same change:**
-   - CP: done 2026-11-05 (copies, listing and visibility literals, and both
-     tripwires deleted);
-   - CLI: done (synap-cli#91).
-
-### C. Coordinated rename (planned)
+### 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:

package/agents/chatgpt.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: chatgpt
+  name: "ChatGPT"
+  description: "OpenAI's ChatGPT. Connects to the pod through MCP; it does not run handed work."
+  tags: [chat]
+spec:
+  harness: chatgpt
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/claude-code.agent.yaml

@@ -0,0 +1,24 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: claude-code
+  name: "Claude Code"
+  description: "Anthropic's coding agent in the terminal. Connects to the pod with its own key and can run handed work headless as a worker."
+  tags: [coding, worker]
+spec:
+  harness: claude-code
+  worker: true
+  tried: true
+  detect:
+    bins: [claude]
+    homePaths: [.claude.json, .claude]
+  wake:
+    program: claude
+    args: ["-p", "{prompt}", "--output-format", "stream-json", "--verbose"]
+    params:
+      prompt: { type: text, required: true }
+      model: { type: model }
+    env:
+      strip: [ANTHROPIC_API_KEY]
+  practices:
+    skills: [synap]

package/agents/claude-desktop.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: claude-desktop
+  name: "Claude Desktop"
+  description: "Anthropic's desktop chat app. Connects to the pod through MCP; it does not run handed work."
+  tags: [chat]
+spec:
+  harness: claude-desktop
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/codex.agent.yaml

@@ -0,0 +1,21 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: codex
+  name: "Codex"
+  description: "OpenAI's coding agent in the terminal. Can run handed work headless (codex exec); that wake has not been run on a real computer yet."
+  tags: [coding, worker]
+spec:
+  harness: codex
+  worker: true
+  tried: false
+  detect:
+    bins: [codex]
+    homePaths: [.codex]
+  wake:
+    program: codex
+    args: ["exec", "{prompt}"]
+    params:
+      prompt: { type: text, required: true }
+  practices:
+    skills: [synap]

package/agents/cursor.agent.yaml

@@ -0,0 +1,15 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: cursor
+  name: "Cursor"
+  description: "The Cursor code editor and its agent. Connects to the pod through MCP; it does not run handed work."
+  tags: [coding, editor]
+spec:
+  harness: cursor
+  worker: false
+  tried: false
+  detect:
+    homePaths: [.cursor]
+  practices:
+    skills: [synap]

package/agents/discord.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: discord
+  name: "Discord"
+  description: "A Discord bot that holds a pod key. It does not run handed work."
+  tags: [chat]
+spec:
+  harness: discord
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/generic.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: generic
+  name: "Generic"
+  description: "Any other MCP client a person connects with a pod key. It does not run handed work."
+  tags: [mcp]
+spec:
+  harness: generic
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/goose.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: goose
+  name: "Goose"
+  description: "Block's Goose agent. Connects to the pod through MCP; it does not run handed work yet."
+  tags: [assistant]
+spec:
+  harness: goose
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/grok.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: grok
+  name: "Grok"
+  description: "xAI's Grok. Connects to the pod through MCP; it does not run handed work (a headless mode is not verified)."
+  tags: [chat]
+spec:
+  harness: grok
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/hermes.agent.yaml

@@ -0,0 +1,18 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: hermes
+  name: "Hermes Agent"
+  description: "Nous Research's Hermes Agent CLI. A stub: its wake (hermes chat -q) has never been run on a real computer, so treat it as untested."
+  tags: [assistant, worker]
+spec:
+  harness: hermes
+  worker: true
+  tried: false
+  wake:
+    program: hermes
+    args: ["chat", "-q", "{prompt}"]
+    params:
+      prompt: { type: text, required: true }
+  practices:
+    skills: [synap]

package/agents/opencode.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: opencode
+  name: "OpenCode"
+  description: "The OpenCode coding agent. Connects to the pod through MCP; it does not run handed work yet."
+  tags: [coding]
+spec:
+  harness: opencode
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/openwebui.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: openwebui
+  name: "Open WebUI"
+  description: "The self-hosted Open WebUI chat. Connects to the pod with its own key; it does not run handed work."
+  tags: [chat]
+spec:
+  harness: openwebui
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/proton-agent.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: proton-agent
+  name: "Proton"
+  description: "Proton's assistant holding a pod key. It does not run handed work."
+  tags: [assistant]
+spec:
+  harness: proton
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/raycast.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: raycast
+  name: "Raycast"
+  description: "Raycast's AI on the Mac. Connects to the pod through MCP; it does not run handed work."
+  tags: [assistant]
+spec:
+  harness: raycast
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/vscode.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: vscode
+  name: "VS Code"
+  description: "Visual Studio Code and its agent. Connects to the pod through MCP; it does not run handed work."
+  tags: [coding, editor]
+spec:
+  harness: vscode
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/windsurf.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: windsurf
+  name: "Windsurf"
+  description: "The Windsurf code editor and its agent. Connects to the pod through MCP; it does not run handed work."
+  tags: [coding, editor]
+spec:
+  harness: windsurf
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]

package/agents/zed.agent.yaml

@@ -0,0 +1,13 @@
+apiVersion: synap/v1
+kind: agent
+meta:
+  slug: zed
+  name: "Zed"
+  description: "The Zed code editor and its agent. Connects to the pod through MCP; it does not run handed work."
+  tags: [coding, editor]
+spec:
+  harness: zed
+  worker: false
+  tried: false
+  practices:
+    skills: [synap]