@synap-core/cli 1.10.0 → 1.12.2

package/skills/synap-market/author-and-publish.md

@@ -0,0 +1,212 @@
+# Author & publish — the ONE write door
+
+Every kind (workspace, capability, cell, view, …) publishes through the SAME door:
+`POST /api/packages` → `publishPackageCore`. `synap market <verb>` is the CLI front
+end (human, or an AI driving the CLI on the user's behalf — always say what you ran).
+
+**Two distinct AI paths — don't conflate them:**
+
+- **Publish to the MARKET (the shared catalog)** = human / CLI / browser only.
+  Publishing a template to the CP catalog needs the user's CP session; an agent
+  in the pod holds no CP credential (founder-gated trust boundary). So an agent
+  _authors + drives the CLI_, or the user publishes from the browser wizard.
+- **Author + PROPOSE an install** = agents CAN do this natively. The IS tool
+  **`propose_workspace_template`** authors a full workspace definition and routes it
+  through the pod's governed `/packages/apply` → a **reviewable proposal** carrying
+  the whole definition (the user sees a live preview and approves). This is NOT a
+  market publish — it installs the AI-authored template into the user's pod, governed.
+  Use it when the user wants a whole workspace set up as a reviewable proposal.
+
+**One space per domain:** A space is a domain, installed once (Content, Brand, CRM…). A project is a filter across spaces. To make something “for project X”: file it into X inside the domain's space (`file_into_project`), and link X to the space (`project_use_workspace`). Never create a space named after a project, a brand or a client.
+
+## The loop
+
+```bash
+synap market scaffold my-thing              # writes my-thing.template.yaml (refuses to overwrite)
+# ...edit the file...
+synap market validate my-thing.template.yaml
+synap market publish my-thing.template.yaml            # PRIVATE by default
+synap market publish my-thing.template.yaml --public    # opt in to sharing
+```
+
+### `scaffold <slug>`
+
+Writes a minimal valid `<slug>.template.yaml` — `meta` (slug/name/description/
+icon/color), `workspace` (name/description), and one starter profile. Refuses
+to clobber an existing file — create-then-configure, never silently overwrite
+an author's work.
+
+### `validate <file>`
+
+Runs the ONE shared validator (`validateTemplate` from
+`@synap-core/workspace-templates`) locally — fast feedback before any network
+call. Fix every reported error before publishing; the CP re-runs the same
+class of check server-side and will reject an invalid definition (400).
+
+### `publish [file]`
+
+```bash
+synap market publish [file] [--public|--private] [--from-workspace <id>] [--json]
+```
+
+- Validates first — a failing template is never published.
+- Default is **private**; pass `--public` to share. `--private` is accepted
+  explicitly if a script wants to state intent.
+- `--from-workspace <id>` serializes a LIVE, already-built workspace into a
+  template via the pod's own `POST /workspaces/:id/to-template` door, then
+  publishes that — the fastest way to turn something you already built into a
+  reusable package. It runs through the SAME validator as a hand-authored file.
+- Writes go to `POST /api/packages` (upsert by `(slug, authorId)`; version is
+  a content hash, so republishing identical content is a safe no-op — you'll
+  see `outcome: "no-op"` vs `"created"`/`"updated"`).
+- Slugs `foundation`, `crm`, `operations`, `content-os`, `enterprise-os`,
+  `research-base` are reserved bedrock templates — publishing under one of
+  those 403s; pick a different slug.
+
+### Standalone non-workspace kinds (`--kind`)
+
+A lone **cell** (a renderer — the code that draws an entity/widget) or **view** can
+be authored + published on its own, same door:
+
+```bash
+synap market scaffold --kind cell my-card   # → my-card.cell.json  {category, slug, displayName, definition}
+# edit the cell's code/definition
+synap market publish my-card.cell.json       # category:"cell", same publish client
+```
+
+`--kind view` works the same, and so does **`--kind skill`** — a skill ships as its
+own package now:
+
+```bash
+synap market scaffold --kind skill my-method   # → my-method.skill.json
+# definition.skill = { slug, name, kind: "instruction"|"code", body | code, … }
+synap market publish my-method.skill.json
+```
+
+Author a skill a template needs as its OWN package, never nested inside a
+capability (the nested form still exists for a capability's own verbs, but it is
+not how a space gets a skill). The `slug` is the skill's `load_skill` ref and
+**cannot start with `system/`** — that namespace is reserved for seeded skills.
+
+The door is category-gated: only `category:"workspace"` runs the WorkspaceYaml
+validator + lossless normalization; every other kind is stored pod-native as-is (a
+capability/cell/skill is NOT a WorkspaceYaml). A `category:"skill"` publish must
+carry a non-empty `definition.skill` with documentation or code — the pod refuses a
+bodiless skill at install, so the CP refuses it at publish.
+
+### Compose — ship a whole stack in one install
+
+A template declares `dependencies[]` (`{kind, relation: compose|require}`) so
+installing it installs its whole stack in one governed pass. The resolver
+materializes **workspace / capability / cell / skill** dependencies today;
+**view and workflow are accepted and composable but not yet installed
+standalone** (pending appliers) — so a space can ship its cells + capabilities +
+skills + a base workspace as ONE install. Compose, don't inline.
+
+Author these BOTTOM-UP: publish the skill/cell/capability first, then the template
+that requires it. `dependencies[]` is the INSTALL; the template's own `skills:`
+block is the LINK to the space (and its mode). A link with no matching dependency
+installs cleanly and links nothing — silently, because a missing dependency is
+non-fatal by design (`required-absent` in the resolver's report, which you should
+read rather than assume).
+
+### `unpublish <slug>`
+
+Flips a published package back to private (owner-only). ⚠️ Known gap: the CP's
+PATCH validator doesn't yet accept `isPublic` on every deploy — if it 400s,
+that's a server-side TODO, not something to work around; report it honestly.
+
+## Server-side validation scope (important honesty note)
+
+`POST /api/packages` validates **self-contained** templates (no `dependencies`
+declared) with the full referential-integrity check (dangling profile refs in
+views/entityLinks, missing view scope, entityLink predicates). A template that
+**declares `dependencies`** (compose/require another template) passes through
+this HTTP door **without** that validation — composition-aware server-side
+validation is not yet wired for ad-hoc publishes (official templates are
+validated corpus-wide from their YAML by the official publish
+(`synap market publish --official`) before it posts). Don't claim a composed publish was fully validated; say what actually ran.
+
+**Official templates — ONE catalog, ONE writer.** Every official template, of
+every kind, lives in ONE catalog package: `synap-app/packages/workspace-templates/`
+(npm `@synap-core/workspace-templates`; a rename to `packages/catalog` /
+`@synap-core/catalog` is planned, not done). By kind: workspaces in `src/*.yaml`,
+then `capabilities/`, `skills/`, `packs/`, `automations/`. Each file is one manifest
+`{apiVersion: synap/v1, kind, meta, spec, dependencies}`. Its `README.md` is the
+how-to. It has ONE writer: `synap catalog publish --official [--kind k] [slug...]`.
+That is the founder's command: its `synap login` session must own the
+`synap-official` vendor. It refuses a non-official account before the preview,
+validates the whole corpus, previews the diff against the live catalog, and asks
+before writing; `--dry-run` previews only. `synap market publish --official` is
+its alias for `--kind workspace`. Both go through the ONE lib
+`scripts/catalog-lib.mjs` → `POST /api/packages` (`publishPackageCore`).
+`synap catalog validate|diff` are the read-only verbs. `scripts/publish-official.mjs`
+is only the CI wrapper (`publish-official-templates.yml`): a read-only preview on
+PRs, and on main a live publish of the kinds in `SYNAP_CATALOG_LIVE_KINDS` (default
+`workspace`). The CP never reseeds on deploy, neither templates nor capabilities.
+`seed-templates.ts` and `seed-capability-templates.ts` are insert-only, by-hand
+bootstraps for an empty CP. A catalog change reaches pods only when that publish
+runs. A CP-door change ships CP-deploy first, then publish.
+`definition.sourcePackage` (the `mergeCatalog` winner signal) is official-only:
+the CP rejects it (403) from any other publisher, so never put it in an ad-hoc
+package. Official capability keys are reserved: an ad-hoc publish of a capability
+whose slug or `capability.key` matches an official one gets 409
+`OFFICIAL_CAPABILITY_KEY_RESERVED`. Pick your own key. Never pass the official
+`vendorId` to `market_publish` or publish an official slug ad-hoc — official
+content is authored in the catalog and published by the human with
+`synap catalog publish --official`.
+
+## 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 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).
+
+## What you're producing
+
+A `PackageDefinition`: `_meta` (slug/name/description/icon/color/tags),
+`workspaceName`, `description`, `profiles`, `views`, `entityLinks`, optional
+`dependencies`. The scaffolded YAML and `--from-workspace` both produce this
+shape — never hand-write JSON against the raw DB row shape.

package/skills/synap-market/discover-and-fetch.md

@@ -0,0 +1,59 @@
+# Discover & fetch
+
+Three doors reach the same catalog. Pick the one that matches where you're
+running.
+
+## CLI — `synap market`
+
+```bash
+synap market                              # browse/list (the default action)
+synap market --search "crm"               # filter by name/description/slug
+synap market --type capability            # filter by type: workspace|capability|skill|workflow|view|cell
+synap market --search "crm" --type workspace --json
+```
+
+`market` with no subcommand lists; `--list` is accepted explicitly too. It
+merges: your OWN packages (public + private, via `GET /api/packages/mine`)
+with the PUBLIC catalog (`GET /api/packages`) — logged out, you only see the
+public/bundled set.
+
+Companion commands:
+
+```bash
+synap market installed             # what's already installed on THIS pod (pure read)
+synap market installed --tree      # composition graph: package → templates → workspaces
+synap market update                # check installed packages for drift against the catalog
+```
+
+## Pod verb — `market.search` (MCP / agent / automation)
+
+The pod-native verb, run via MCP `run_capability` or
+`POST /api/hub/capabilities/execute` with `{ verbId: "market.search", parameters }`:
+
+```json
+{ "query": "crm", "kind": "template", "limit": 20 }
+```
+
+- `kind` ∈ `capability | automation | template | cell` (omit to search all).
+- Reads the pod-local `cp_catalog_cache` — fast, no live CP round-trip.
+- Returns `{ entries: [{ slug, kind, name, description, version, tier, installed }], count }`.
+- `installed` is `true`/`false` for capability/cell (cheap natural-key check);
+  `undefined` for automation/template — that's an HONEST unknown, not a bug,
+  never read it as "not installed."
+- Empty result → say so plainly ("nothing matched") — never fabricate a
+  package that doesn't exist. Offer to capture the gap as a note for later.
+
+This is the verb an agent should reach for first — it's read-only (auto-runs,
+no approval needed) and mirrors exactly what `synap market --search` shows a
+human.
+
+## Fetching one package's full definition
+
+- **CLI (authoring path):** `synap market publish --from-workspace <id>` reads
+  a LIVE workspace via the pod's own `to-template` serializer — see
+  `author-and-publish.md`.
+- **CP directly:** `GET /api/packages/:slug` returns the full row **with**
+  `definition` — the install payload. Auth is required to see a private
+  package (author-only). No auth → public only, and a private slug 404s.
+- **From an install:** you don't normally need the definition yourself —
+  `market.install` (see `install.md`) resolves and applies it for you.

package/skills/synap-market/governance-and-catalog.md

@@ -0,0 +1,63 @@
+# Governance & the one-catalog principle
+
+## Writes are governed — "proposed" is success
+
+Every mutating marketplace action an AGENT takes (`market.install` above all)
+can come back `{ status: "proposed", proposalId, reviewUrl }` instead of
+`{ status: "installed" }`. That is the write queued for the pod owner's
+review — like opening a PR, not a failure and not an error to retry. Always:
+
+- Surface `reviewUrl` to the user.
+- Don't retry the same install hoping for "installed" — it won't change the
+  outcome and may create a duplicate proposal.
+- Remember an unreviewed proposal isn't live yet: `market.search`'s
+  `installed` flag and any downstream read won't reflect it until approved.
+
+An OPERATOR-driven install (the pod owner themself, via CLI with their own
+credentials, no agent identity) executes directly — no proposal. The
+distinction is WHO is acting, not which door they used.
+
+## One catalog — never fork it
+
+- The catalog is `synapPackages` in the Control Plane, reached through
+  `GET/POST/PATCH /api/packages*`. `cp_catalog_cache` on the pod is a
+  **read-through cache** of it (populated by sync), not a second source of
+  truth — never write to it directly, and never treat a cache miss as "the
+  package doesn't exist" without falling back to a live CP fetch (which
+  `market.install` already does for automation/template kinds).
+- Discovery happens on the CP (`market.search`, `synap market`); apply
+  happens on the pod (`market.install`, workspace creation). Don't invent a
+  parallel "known templates" list anywhere else in a workflow you're
+  building — always search the real catalog.
+- Publishing to anywhere other than `POST /api/packages` (e.g. hand-writing a
+  file and calling it "published," or registering a template only in a local
+  config) is NOT publishing — it produces something invisible to
+  `market.search` and every other consumer.
+
+## Visibility model
+
+- **Public** (`isPublic: true`) — visible to everyone via `GET /api/packages`.
+- **Private** (`isPublic: false`, the default) — visible only to its
+  `authorId` (and, for non-workspace categories, active members of an
+  `podId`-owned team). A private **workspace template** is stricter:
+  owner-only, full stop, even for pod teammates.
+- A private package a caller can't see **404s, never 403s** — this is
+  deliberate (don't leak existence). If you get a 404 fetching a package by
+  slug, don't assume it never existed — it may just be private to someone
+  else.
+
+## Tier gating
+
+A public package can declare `requiredTier`. `GET /api/packages/available`
+tells an authed caller which tiered slugs their subscription actually
+unlocks; a slug missing from that list but present in the browse catalog is
+locked for them — `market.install` pre-checks this and fails before touching
+governance, so surface the tier requirement rather than treating it as a
+generic install error.
+
+The **server pre-check is the authoritative floor** (`assertPackageTierAccess`,
+wired at every install site). The browser UI is **display-only**: it threads
+`requiredTier` through to a "requires <tier>" badge but does NOT hard-block, and
+its lock/upgrade CTA only engages once a host wires a billing destination — so
+don't add a UI-side gate expecting it to enforce anything, and don't rebuild the
+badge thread (it exists). Full current-state: repo `TEMPLATE-DEV-GUIDE.md`.

package/skills/synap-market/install.md

@@ -0,0 +1,133 @@
+# Install
+
+## CLI — `synap market install <slug>`
+
+```bash
+synap market install crm                        # install as a new workspace
+synap market install crm --dry-run               # preview: would-create / reuse / conflicts, writes nothing
+synap market install crm --onto <workspaceId>     # reconcile ONTO an existing workspace (additive)
+synap market install crm --project <id>           # link the installed workspace(s) to an EXISTING project (id only)
+```
+
+Installs are **workspace-first**: a `workspace`/`template` package spins up
+(or reconciles onto) a workspace directly. Other package types (capability,
+automation, cell) route you to the right surface (`synap capability add`,
+etc.) rather than being force-fit into a workspace install.
+
+**One space per domain:** A space is a domain, installed once (Content, Brand, CRM…). A project is a filter across spaces. To make something “for project X”: file it into X inside the domain's space (`file_into_project`), and link X to the space (`project_use_workspace`). Never create a space named after a project, a brand or a client. Reinstalling reuses the live space. A template is installed **once per pod**, and a space name is held by **one** active space — whoever owns it, human or agent alike: a second copy is refused (`409` — `status: "exists"` + the space to use, or `WORKSPACE_IDENTITY_CONFLICT` naming the space that holds it). There are no named copies: `--as <name>` / `instanceName` answers `400`, and a package with no `_meta.slug` (and no `--onto` target) answers `400` instead of minting a second space.
+
+## Pod verb — `market.install` (MCP / agent / automation)
+
+```json
+{ "slug": "crm", "kind": "template", "version": "optional", "params": {} }
+```
+
+`kind` ∈ `capability | automation | template | cell` — required, unlike
+`market.search`.
+
+**This verb ALWAYS mutates**, so it goes through the full permission gate —
+never treat a non-"installed" response as failure:
+
+- **Operator call** (no agent identity — e.g. you're driving the CLI as the
+  pod owner): executes directly → `{ status: "installed", result }`.
+- **Agent call** (any MCP/automation/agent-key caller): ALWAYS proposes,
+  regardless of any standing grant on `market.install` itself — a grant on
+  the verb governs _invoking_ it, not the provisioning it performs. Response:
+  `{ status: "proposed", proposalId, reviewUrl }`.
+
+**`"proposed"` is success, not an error.** Surface `reviewUrl` to the user so
+they can approve it — don't retry, don't report it as a failure. See
+`governance-and-catalog.md`.
+
+## Project packs — a suite of workspaces, linked to a project
+
+A **project** is a cross-cutting lens over workspaces, not a package kind. A
+"project pack" is a **suite**: an ordinary `workspace`-category package tagged
+`suite`, whose `dependencies[]` **`require`** each constituent workspace package
+(never `compose` — re-applying must not duplicate workspaces). Installing a
+suite installs every constituent workspace (idempotent: reused if present).
+
+**Author one from a live project** — never hand-write the suite:
+
+```bash
+synap market publish --from-project <projectId>   # publishes the constituents first, then the thin suite
+```
+
+(Agent door: `export_project_pack` returns `{ definition, constituents }` —
+publish the constituents before the suite so every `require` resolves.)
+
+**Install onto a project.** The install never needs to know why the project
+exists — it installs the workspaces and LINKS them (a `project --uses-->
+workspace` edge per workspace, plus seeded entities filed into the project):
+
+```bash
+synap market install <suite-slug> --project <projectId>   # EXISTING project id only; errors if not found
+```
+
+The CLI has no flag that creates a project. Create the project first:
+
+- **A human**: in the app, or by passing `projectName` on the Hub door
+  `POST /api/hub/packages/apply` (mints or reuses by exact name).
+- **An agent**: `create_project` requires `evidenceEntityIds` — at least 5
+  existing entities that belong to it — or it is REJECTED (not proposed).
+  Without that evidence, ask the human to create the project, then install with
+  its id.
+- **An agent calling `market.install` with `projectName`**: the install becomes
+  a proposal that carries the name, and when a human approves it the project is
+  minted. The approval is the consent — say so when you propose it.
+
+Two packs on one project = install each with the same `--project <id>`. Each
+lands its own workspaces; both link to the project. Only ONE `compose`
+dependency is allowed per package, at every level.
+
+**The brief comes with the workspaces.** A workspace package's `onboarding` is
+the space's BRIEF — steady state (`purpose`, `framing`, `expertise`, `anchors`,
+`fetch`) plus its onboarding mode (`goal`, `collect`, `openingQuestions`,
+`doneWhen`) — stored on that workspace's `settings.onboarding`; the package's
+top-level `rules[]` install as the space's rules. A template update reaches an
+installed space without overwriting what its owner edited (conflicts are
+reported), and `synap_update_space_brief` proposes a change. The `onboard` skill runs the
+interview when a lens is empty; for a project spanning several workspaces it
+sets up one workspace's slice at a time, each entity filed into the project.
+There is no project-level recipe — the recipe always lives on a workspace. A
+journey completes by itself once the lens holds real data.
+
+## Idempotency by kind
+
+- **capability** — natural key is `(name, workspaceId)`; installing twice
+  converges, doesn't duplicate.
+- **template/workspace** — keyed by `packageSlug`/`proposalId` (both set to
+  the catalog slug); re-installing the same template for the same user
+  converges to the existing workspace rather than creating a second one.
+- **automation** — pre-checked by `(name, workspace)` before creating.
+- **cell** — keyed by `(typeKey, workspaceId)`.
+
+## Template updates — where a space stands, and whose step it is
+
+Read it with MCP `synap_template_health` (or `synap templates` in a terminal).
+Each space's row says what is left to do; act on these fields, not on
+`drifted` alone (`drifted: true` means "there is a step", not "apply now"):
+
+| Field | Means | Your move |
+|---|---|---|
+| `state: "active"`, `drifted: true` | a newer version is out | the update path below |
+| `state: "awaiting-approval"` + `awaitingApproval: [ids]` | the last update filed proposals | point the person to them; **do not re-apply** |
+| `state: "partial"` / `"layer-2-not-run"` / `"failed"` | the last update did not finish | `synap templates update <slug>` finishes it |
+| `pendingDataChanges: {count, sentences, needsPodAdmin}` | the update changes existing data and waits for a **person** to agree | tell them the sentences; they run `synap templates update <slug>` themselves (a pod owner/admin when `needsPodAdmin`) |
+| `updateProposal: {id}` | an update of this space is already proposed | point the person to that proposal; **never file another** |
+| `applyWarning` | the pod's one sentence for what is left | relay it as is |
+
+The update path is `synap templates update <slug>` (the person's door). Run
+with an agent key it becomes a proposal the person approves. **Agreeing to data
+changes is never an agent's**: the door answers `409
+DATA_CHANGES_NEED_CONSENT` with `needsPerson: true` for any agent, whatever it
+lists in `acceptDataChanges`. The version stamp (`settings.template.version`) is
+written only when an update converged, so a space never reads "up to date" over
+an update that did not land.
+
+## Locked / tier-gated packages
+
+A package can declare a `requiredTier`. Installing one your account's plan
+doesn't cover fails a pre-check (`assertPackageTierAccess`) BEFORE any
+proposal or provisioning — tell the user which tier is required rather than
+retrying.

package/skills/synap-market/overview.md

@@ -0,0 +1,119 @@
+# Marketplace & templates on Synap
+
+Synap is **configuration-first**: a feature is _stored, user-editable config_
+published to one catalog and installed through shared substrate — not hardcoded in
+the pod backend. The marketplace is that **package layer**, and the catalog
+(`synap_packages`) is **kind-agnostic** — one door serves every kind:
+
+| Kind                      | Configures                                                       | Standalone install (via `applyMarketInstall`)      |
+| ------------------------- | ---------------------------------------------------------------- | -------------------------------------------------- |
+| **workspace**             | a whole domain (profiles + views + bento + its caps/automations) | ✅ `createWorkspaceFromDefinitionIdempotent`       |
+| **capability**            | a credentialed tool pack (+ embedded skills/playbooks)           | ✅ `createCapabilityFromDefinition`                |
+| **cell**                  | a renderer — the code that draws an entity/widget                | ✅ `installCellFromDefinition` (needs a cache row) |
+| **view**                  | a saved view/layout                                              | ✅ `viewsRouter.create` (needs a `workspaceId`)    |
+| **skill**                 | agent know-how                                                   | ✅ `skillsRouter.create` (pod-wide if no ws)       |
+| **workflow / automation** | a WHEN→ACTION flow                                               | ✅ `automationsRouter.create` into acting ws       |
+
+**All six kinds install standalone today** through the ONE apply core
+`applyMarketInstall` (`services/capabilities/marketplace-install.ts`) — the same
+governed door `market.install` and the `capability.install` proposal executor share,
+each reusing the kind's _governed_ router caller (zero duplicated insert logic). The
+remaining gaps are NOT install: (1) **private-package sync is unauthenticated**, so a
+private package can't reach a pod yet (see `governance-and-catalog.md` / RC4); (2)
+standalone **view / skill / automation stamp no source-link**, so they don't self-heal
+via reconcile the way workspace/capability do. (Subscription-`tier` gating is a
+separate axis — see `governance-and-catalog.md`.)
+
+**Words** (template, pack, workspace/work/track/rule template) are defined once
+in the `synap` skill's `concepts` topic. In short: a template's kind is DERIVED
+from its content (a playbook with `scope: "project"` is a track template, the
+default `scope: "session"` a work template), never declared.
+
+**A pack is not a seventh kind.** Today it ships as a **suite**: a `workspace`
+package tagged `suite` that `require`s its constituent workspaces, built from a
+live project with `synap market publish --from-project <id>`, and installed
+with `--project <id>` to link every workspace to that project. See
+`install.md` → "Project packs". The model it is moving to: a pack lists the
+workspace templates it depends on and installs the missing ones, and never
+creates a workspace of its own.
+
+It lives in the Control Plane (CP) catalog and is discoverable and installable from
+any door: the `synap` CLI, MCP (`market_search` / `run_capability`), or the Hub REST
+API. **Everything that is config, not code, can be a template** — workspaces, entity
+profiles/views, renderers (cells), capabilities, skills, automations.
+
+## The authoring order — bottom-up, ALWAYS
+
+Everything installable is a **standalone package**, and packages form a graph: a
+bigger one **declares `dependencies[]`** on smaller ones, and the pod installs the
+missing ones in the same governed pass. So author from the SMALLEST piece up:
+
+1. **Basic objects** — entity types (profiles), **skills**, capabilities, cells,
+   views, workflow/automations. Each is publishable on its OWN and is useful before
+   any container exists. A skill package is one skill: its documentation or code.
+2. **Containers** — a **space** (a `workspace` template) that declares
+   `dependencies[]` on the basic objects it needs, and activates its skills with a
+   `skills:` block.
+3. **Compositions** — a **project / suite** ("truck") that `require`s the spaces.
+
+Publish the small pieces FIRST, then the space, then install. Nothing in the chain
+waits on a container.
+
+**The two verbs are different, and confusing them is the classic mistake:**
+
+- `dependencies[]` = what gets **INSTALLED** — the pod materialises the package if
+  it is not already there (idempotent; a second pass reports `found`).
+- `skills:` inside a template = what gets **LINKED** to that space, and in which
+  mode (`always` / `on-demand`). It names a skill some `dependencies[]` entry —
+  usually its own — already installed. Declaring the link without the dependency
+  installs cleanly and links NOTHING.
+
+**Never inline what is already a package.** Copying a skill's text into a template,
+or re-declaring a profile set that ships as a dependency, forks the thing and stops
+it converging. Depend on it; let the install bring it. And **never** seed a skill
+into the backend (`skills/synap/…`) to make a template resolve — that directory is
+not the marketplace. Publish it as a package.
+
+## The two reflexes
+
+1. **DISCOVER before you invent.** Before scaffolding a new template or
+   capability, search the catalog — `synap market --search "<query>"` or the
+   `market.search` verb. Someone may have already published what you need.
+   Reinventing a workspace that already exists as a template is wasted work
+   AND fragments the catalog.
+2. **One catalog, never a second one.** Every package — public or private —
+   lives in the CP's `synapPackages` table, reached through
+   `GET/POST /api/packages`. There is no side channel: don't write a
+   template to a random file and call it "published," and don't stand up a
+   local list of "known templates" — search the real catalog every time.
+
+## The four things this skill teaches
+
+| Task                                                      | Doc                         |
+| --------------------------------------------------------- | --------------------------- |
+| Search/browse/fetch a package (any kind)                  | `discover-and-fetch.md`     |
+| Install a package into a pod                              | `install.md`                |
+| Author a new template and publish it (the ONE write door) | `author-and-publish.md`     |
+| Governance rules + the one-catalog principle              | `governance-and-catalog.md` |
+
+## Package kinds
+
+- **workspace / template** — a full workspace definition (profiles, views,
+  entity links) you can spin up as a new workspace, or reconcile onto an
+  existing one.
+- **capability** — a tool + skill bundle (an integration or verb pack).
+- **automation** — a trigger + action definition.
+- **cell** — a custom UI renderer.
+
+The CLI's browse filter (`market --type`) uses
+`workspace|capability|skill|workflow|view|cell`; the pod-native install verb
+(`market.install`) and its catalog use the narrower
+`capability|automation|template|cell` (`template` there means a workspace template). Match
+whichever surface you're calling.
+
+## Visibility
+
+Every package is **public** or **private** (owner-only). Default on publish is
+**private** — you opt in to sharing with `--public`. A private package 404s
+(not 403) to anyone who isn't its author or an active member of its owning pod
+— see `governance-and-catalog.md`.