@synap-core/cli 1.11.0 → 1.13.0

package/skills/synap-market/SKILL.md

@@ -13,7 +13,7 @@ description: >
   about the PACKAGE layer: finding, installing, and publishing reusable
   templates/capabilities/automations/cells to/from the Control Plane catalog.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: []
     optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID, SYNAP_HUB_API_KEY]
@@ -27,11 +27,79 @@ metadata:
 
 # Marketplace & templates on Synap
 
-The marketplace is Synap's **package layer**: workspace templates, capabilities,
-automations, and cells — anything that can be installed into a pod rather than
-hand-built. It lives in the Control Plane (CP) catalog and is discoverable and
-installable from any door: the `synap` CLI, MCP (`run_capability`), or the Hub
-REST API (`/api/hub/capabilities/execute`).
+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
 
@@ -67,7 +135,7 @@ REST API (`/api/hub/capabilities/execute`).
 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` (workspace ≡ template there). Match
+`capability|automation|template|cell` (`template` there means a workspace template). Match
 whichever surface you're calling.
 
 ## Visibility
@@ -149,7 +217,7 @@ human.
 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>           # tag seeded entities to a project (install stays pod-wide)
+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
@@ -157,6 +225,8 @@ Installs are **workspace-first**: a `workspace`/`template` package spins up
 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
@@ -180,6 +250,59 @@ never treat a non-"installed" response as failure:
 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
@@ -190,6 +313,29 @@ they can approve it — don't retry, don't report it as a failure. See
 - **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
@@ -201,11 +347,24 @@ retrying.
 
 # Author & publish — the ONE write door
 
-`synap market <verb>` is the only supported authoring path today (human or AI
-driving the CLI). There is no agent-native "publish a template" MCP verb —
-`market.install` only ever CONSUMES the catalog. Authoring is a human/CLI
-action; if you're an agent helping the user author one, drive the CLI on
-their behalf and always tell them what you ran.
+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
 
@@ -251,6 +410,53 @@ synap market publish [file] [--public|--private] [--from-workspace <id>] [--json
   `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
@@ -264,9 +470,86 @@ 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 (only the seeded flagship
-templates get validated at that level). Don't claim a composed publish was
-fully validated; say what actually ran.
+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
 
@@ -333,3 +616,10 @@ 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/_skill.yaml

@@ -12,7 +12,7 @@ description: >
   about the PACKAGE layer: finding, installing, and publishing reusable
   templates/capabilities/automations/cells to/from the Control Plane catalog.
 metadata:
-  openclaw:
+  synap:
     requires:
       env: []
     optional_env: [SYNAP_POD_URL, SYNAP_WORKSPACE_ID, SYNAP_HUB_API_KEY]

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

@@ -1,10 +1,23 @@
 # Author & publish — the ONE write door
 
-`synap market <verb>` is the only supported authoring path today (human or AI
-driving the CLI). There is no agent-native "publish a template" MCP verb —
-`market.install` only ever CONSUMES the catalog. Authoring is a human/CLI
-action; if you're an agent helping the user author one, drive the CLI on
-their behalf and always tell them what you ran.
+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
 
@@ -50,6 +63,53 @@ synap market publish [file] [--public|--private] [--from-workspace <id>] [--json
   `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
@@ -63,9 +123,86 @@ 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 (only the seeded flagship
-templates get validated at that level). Don't claim a composed publish was
-fully validated; say what actually ran.
+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
 

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

@@ -54,3 +54,10 @@ 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`.