@elevasis/sdk 1.33.0 → 1.34.0

package/reference/claude-config/skills/project/SKILL.md

@@ -115,9 +115,11 @@ Agents that need to pass structured JSON to `request:submit` or `exec` should wr
    pnpm elevasis-sdk exec my-workflow -f tmp/exec-payload.json --cleanup-input
    ```
 
-3. The `--cleanup-input` flag deletes the file automatically after a successful command. On failure the file is left intact for inspection.
+3. The `--cleanup-input` flag deletes request/exec input files automatically after a successful command. On failure the file is left intact for inspection.
 
-**Safety guard:** `--cleanup-input` only deletes files that are under `<projectRoot>/tmp/`. If the resolved path is outside `tmp/`, the CLI prints a warning to stderr and leaves the file untouched. Files passed via `--input <json>` (inline JSON, no file) are never affected.
+**Safety guard:** `--cleanup-input` only deletes files that are under `<projectRoot>/tmp/`. If the resolved path is outside `tmp/`, the CLI prints a warning to stderr and leaves the file untouched. Files passed via inline JSON flags are never affected.
+
+Checklist commands in the currently published SDK use inline `--checklist` JSON only. In Windows PowerShell 5.1, inline JSON is not reliable; use bash/PowerShell 7 for those updates, or update the checklist through the UI.
 
 ---
 
@@ -298,11 +300,11 @@ Both `prj_milestones.checklist` and `prj_tasks.checklist` store a JSONB array of
 ]
 ```
 
-The CLI `--checklist` flag on both `project:milestone:update` and `project:task:update` performs a **full replace** — the entire array is replaced with the JSON you supply. There are no item-level add/toggle/remove flags. To mutate a single item:
+The CLI `--checklist` flag on `project:task:create`, `project:task:update`, and `project:milestone:update` performs a **full replace** where the command accepts checklist data. The entire array is replaced with the JSON you supply. There are no item-level add/toggle/remove flags. In Windows PowerShell 5.1, inline JSON is not reliable; use bash/PowerShell 7 for checklist CLI updates, or update the checklist through the UI. To mutate a single item:
 
 1. Read the current checklist (via psql or `project:task:get` / `project:milestone:list`)
 2. Mutate the array in memory (append, flip `completed`, filter out)
-3. Write the entire array back via `--checklist '<json>'`
+3. Write the entire array back via `--checklist '<json-array>'`
 
 To clear a checklist: `--checklist '[]'`.
 
@@ -668,7 +670,7 @@ pnpm elevasis-sdk project:milestone:update <milestone-id> --status completed
 
 # Update checklist (full replace)
 pnpm elevasis-sdk project:milestone:update <milestone-id> \
-  --checklist '[{"id":"uuid","label":"Item label","completed":false}]'
+  --checklist '[{"id":"1","label":"Review scope doc","completed":false}]'
 ```
 
 If status changes to `completed`, the API auto-sets `completed_at`.
@@ -679,7 +681,7 @@ If status changes to `completed`, the API auto-sets `completed_at`.
 
 1. Read the current checklist via psql or `project:milestone:list`
 2. Mutate the array in memory
-3. Write back the full array via `--checklist '<json>'`
+3. Write back the full array via `--checklist '<json-array>'`
 
 ### `checklist <client> "<milestone>"` — View Checklist
 
@@ -741,7 +743,7 @@ pnpm elevasis-sdk project:task:create \
 pnpm elevasis-sdk project:task:create \
   --project <project-id> \
   --title "<name>" \
-  --checklist '[{"id":"1","label":"Step one","completed":false}]'
+  --checklist '[{"id":"1","label":"Review scope doc","completed":false}]'
 ```
 
 ### `task update <client> "<task>" [options]` — Update Task
@@ -757,7 +759,7 @@ pnpm elevasis-sdk project:task:update <task-id> --status <status>
 
 # Update checklist (full replace)
 pnpm elevasis-sdk project:task:update <task-id> \
-  --checklist '[{"id":"uuid","label":"Step","completed":false}]'
+  --checklist '[{"id":"1","label":"Review scope doc","completed":false}]'
 
 # Clear checklist
 pnpm elevasis-sdk project:task:update <task-id> --checklist '[]'
@@ -773,7 +775,7 @@ If status changes to `approved`, the API auto-sets `completed_at`.
 
 1. Read the current task via `project:task:get <task-id>`
 2. Mutate the checklist array in memory
-3. Write back the full array via `project:task:update <task-id> --checklist '<json>'`
+3. Write back the full array via `project:task:update <task-id> --checklist '<json-array>'`
 
 ### `note <client> "<content>" [options]` — Add Note
 
@@ -964,15 +966,15 @@ When args don't match any command pattern, infer intent from natural language:
 | "what's overdue?"                                              | List milestones where `due_date < now() AND status != 'completed'`                                                                                    |
 | "block acme, waiting on client credentials"                    | `update acme --status blocked`                                                                                                                        |
 | "show checklist for phase 2"                                   | Read and display checklist for milestone "phase 2" via psql or `project:milestone:list`                                                               |
-| "add 'deploy staging' to task X's checklist"                   | Read task X's checklist → append `{id: uuid, label: "deploy staging", completed: false}` → `project:task:update <id> --checklist '<json>'`            |
-| "mark 'deploy staging' done on task X"                         | Read task X's checklist → flip `completed` on matching item → `project:task:update <id> --checklist '<json>'`                                         |
+| "add 'deploy staging' to task X's checklist"                   | Read task X's checklist → append `{id: uuid, label: "deploy staging", completed: false}` → `project:task:update <id> --checklist '<json-array>'` |
+| "mark 'deploy staging' done on task X"                         | Read task X's checklist → flip `completed` on matching item → `project:task:update <id> --checklist '<json-array>'`                              |
 | "clear the checklist on task X"                                | `project:task:update <task-id> --checklist '[]'`                                                                                                      |
-| "add checklist item to onboarding milestone: review scope doc" | Read milestone checklist → append item → `project:milestone:update <id> --checklist '<json>'`                                                         |
+| "add checklist item to onboarding milestone: review scope doc" | Read milestone checklist → append item → `project:milestone:update <id> --checklist '<json-array>'`                                      |
 | "I'm done" / "task complete" / "done with this"                | Resolve active task → confirm → `project:task:update <task-id> --status completed`                                                                    |
 | "save: Apify actor X rate-limits at 20rps"                     | Resolve active project/task → `project:note:create --project <id> --type agent_learning --task <task-id> "Apify actor X rate-limits at 20rps"`        |
 | "remember: client requires ISO dates, not timestamps"          | Resolve active project/task → `project:note:create --project <id> --type agent_learning --task <task-id> "client requires ISO dates, not timestamps"` |
 
-**Checklist note:** all checklist mutations use the read-modify-write pattern. The CLI has no item-level flags (`--add-item`, `--toggle`, `--remove-item` do not exist). Always read the current state, mutate the array, then write the full array back.
+**Checklist note:** all checklist mutations use the read-modify-write pattern. The CLI has no item-level flags (`--add-item`, `--toggle`, `--remove-item` do not exist). Always read the current state, mutate the array, then write the full array back. Use bash/PowerShell 7 for generated checklist JSON; Windows PowerShell 5.1 native argument passing is not reliable for inline JSON.
 
 ---
 
@@ -1078,7 +1080,7 @@ The full `client:*` surface (list, get, status, resolve) is available via `eleva
 6. **Template project assumption** — the template is a single-organization project. All
    `/project` operations operate within the organization scoped by `ELEVASIS_PLATFORM_KEY`.
    There is no cross-org capability.
-7. **Checklist full-replace** — the `--checklist` flag replaces the entire array. Always read
+7. **Checklist full-replace** — `--checklist` replaces the entire array. Always read
    the current checklist before writing to avoid losing existing items.
 8. **Confirm task completion** — always ask once before marking a task `completed` via "I'm done"
    recognition. This status is semantically significant and warrants a confirmation step.

package/reference/claude-config/sync-notes/2026-06-04-scaffold-registry-lane-severity.md

@@ -0,0 +1,34 @@
+# Scaffold registry lane severity annotations
+
+## Why this note exists
+
+This train adds `sync_lane_severity` annotations to the scaffold registry schema and moves external sync lane-severity ownership from hardcoded script sets into registry metadata.
+
+The change is intended to keep project sync behavior the same while making the registry the single edit point for paths that need critical manual-merge handling or optional-feature-selection treatment.
+
+## Applies to
+
+- Template-derived projects that use `/external sync` or `pnpm sync:apply` from the Elevasis monorepo.
+- Projects that receive `@elevasis/core` package-baseline updates through `core/package.json` or `operations/package.json`.
+- Operators reviewing external-sync plans that mention critical manual-merge or optional-feature-selection paths.
+
+## Required actions
+
+1. Run the prepared external sync from the release train so this note reaches derived projects.
+2. After the `@elevasis/core` publish stage, install the prepared core package baseline in template-derived project package files.
+3. Review any sync plan lane labels against the registry entry metadata before widening a manifest or applying catch-up work.
+
+No project-authored Organization Model content should be overwritten for this train.
+
+## Verification
+
+```bash
+pnpm sync:verify
+pnpm exec tsx scripts/external/sync-apply.ts --all --dry-run --manifest apps/docs/content/docs/in-progress/active-development/sdk-changes/ship/_external-sync-prep.json --strict-manifest
+```
+
+The strict manifest dry-run should authorize only the prepared sync note and the core package-baseline cascades.
+
+## Not handled by /git-sync
+
+`/git-sync` can deliver committed file changes, but it does not publish `@elevasis/core`, install package baselines, validate scaffold registry metadata, or enforce manifest-scoped external-sync write authorization.

package/reference/claude-config/sync-notes/2026-06-05-appearance-app-mode-decouple.md

@@ -0,0 +1,29 @@
+# Appearance Page Decoupled From App-Mode
+
+## Why this note exists
+
+The Settings → Appearance page used to be hard-coupled to `dev-centric` app-mode: scaffold removed it under `--client-centric`, every `/external sync` actively deleted it (planner `delete` special-case), and verify forbade it for `client-centric` projects. That made the page silently vanish on every sync for client-centric tenants.
+
+This train decouples Appearance from app-mode. Appearance is now an optional standalone page available in any mode. The only remaining app-mode difference is the `OrganizationSwitcher` in the topbar.
+
+No npm publish is involved: the page renders the already-published `@elevasis/ui@2.46.0` `AppearanceSettings` component. The substrate changes (`scripts/external/*`) and the `_template` route are monorepo-internal and propagate through `/external sync`.
+
+## Applies to
+
+- All template-derived projects under `external/` that lack `ui/src/routes/settings/appearance.tsx`.
+- Confirmed pending at prep time: `nirvana-marketing` (sync planner `writes=1` for the appearance route). `contemplative-records` already restored it; `ZentaraHQ` shows no pending write.
+
+## Required actions
+
+1. The new template route `ui/src/routes/settings/appearance.tsx` propagates automatically via `/external sync` (registry entry `external-sync-feature-route-baseline`, `sync-preservation`). No manual file copy needed — running the prepared sync applies it.
+2. **Per-tenant nav entry is NOT propagated.** `core/config/organization-model/navigation.ts` is project-owned (sync-preservation). For any tenant that should surface Appearance in its sidebar, manually add a `settings-appearance` entry to `navigation.sidebar.bottom.settings.children` (order `50`, after `settings-webhooks`), pointing at the appearance route.
+
+## Verification
+
+- After sync: `pnpm -C external/<project>/ui check-types` passes with the new route present.
+- `pnpm sync:verify` reports `writes=0` for the synced project's `sync-plan`.
+- The Appearance entry renders in the Settings sidebar only after the per-tenant `navigation.ts` entry is added (step 2).
+
+## Not handled by /git-sync
+
+`/git-sync` does not author the per-tenant `navigation.ts` nav entry — it is project-owned business content and must be added by hand per tenant. `/git-sync` also will not retroactively restore the route for tenants that were previously stripped by the old delete special-case; run the prepared `/external sync --all` to apply the new non-deleting baseline.

package/reference/claude-config/sync-notes/2026-06-05-ontology-endpoint-rename-and-knowledge-browser-ui.md

@@ -0,0 +1,86 @@
+# Ontology `surface` → `endpoint` rename + Knowledge Browser UI upgrades
+
+## Why this note exists
+
+This release bumps **both** `@elevasis/core` and `@elevasis/ui`. Two distinct changes ride it:
+
+1. **Breaking OM contract rename (`@elevasis/core`).** The ontology kind `surface` was renamed to
+   `endpoint` to stop colliding with **navigation surfaces** (shell sidebar routes). The published
+   contract changed: the `OntologyKind` enum member `'surface'` is now `'endpoint'`, the ontology ID
+   namespace `…:surface/…` is now `…:endpoint/…`, `ontology.surfaces` is now `ontology.endpoints`,
+   and the exported `OntologySurfaceType` / `OntologySurfaceTypeSchema` are now
+   `OntologyEndpointType` / `OntologyEndpointTypeSchema`. **There is no back-compat alias** (hard
+   rename — the kind was near-dormant). Any tenant OM that still declares a `:surface/` **ontology**
+   ID will fail validation once it installs the new `@elevasis/core`.
+
+2. **Knowledge Browser UI upgrades (`@elevasis/ui`).** Three additive, platform-substrate
+   enhancements that tenants get purely on the `@elevasis/ui` bump — no authoring change required:
+   full `ClientProfile` detail rendering in the Clients panel, clickable group child cards
+   (Profile → Identity/Branding navigate like the tree), and explanatory hover tooltips on
+   platform-vocabulary badges/edge labels. The ontology tree row + its tooltip now read
+   **"Endpoints"** instead of "Surfaces", consistent with change #1.
+
+## Applies to
+
+- **Change #1 (ontology rename):** every tenant whose `core/config/organization-model/` declares any
+  ontology ID with a `:surface/` segment (i.e. an entry under a System's `ontology.surfaces`).
+  **Confirmed in this train: ZERO live tenants carry any `:surface/` ontology ID** (verified by a
+  repo-wide grep across all of `external/` — only `_template` carried one, migrated in this train).
+  The 3 live derived projects (ZentaraHQ, nirvana-marketing, contemplative-records) inherit
+  `endpoint/` cleanly. Run the verification below anyway before installing the new `@elevasis/core`.
+- **Change #2 (UI upgrades):** every template-derived project — they render on the `@elevasis/ui`
+  bump with no further action.
+
+## Required actions
+
+`/git-sync` / `/external sync` delivers the new `@elevasis/core` + `@elevasis/ui` dependency
+baselines and this note. The dependency bumps install automatically; the ontology-ID rewrite (only if
+your project authored any) is project-owned OM content and is **not** auto-applied.
+
+1. **Install the baselines together.** Bump `@elevasis/core` and `@elevasis/ui` in the same change
+   (the baseline write from sync covers `core/package.json`, `operations/package.json`, and
+   `ui/package.json`). Do not install the new `@elevasis/core` while your OM still has any `:surface/`
+   **ontology** ID.
+2. **Rename any ontology `surface/` IDs (only if present).** In `core/config/organization-model/`,
+   change every ontology ID `…:surface/<name>` to `…:endpoint/<name>`, and the containing
+   `ontology: { surfaces: { … } }` key to `ontology: { endpoints: { … } }`. Update every
+   cross-reference (`ownerSystemId`, `route`, links, etc.). Most tenants have nothing to change here.
+3. **Do NOT touch navigation surfaces.** This is the critical disambiguation. The rename is
+   ontology-only. Leave `system.surfaces`, `ui.surfaces`, sidebar `SidebarSurfaceNode`s, the
+   `surfaceType` route field, the graph node kind `surface`, and `SurfaceDescribeView` **unchanged** —
+   those legitimately own the word "surface" for shell routing and are orthogonal to the ontology kind.
+4. **Update tests.** If your `core/config/organization-model.test.ts` or contract tests assert
+   `compiled.ontology.surfaces` or a `:surface/` ontology ID, rename them to `.endpoints` /
+   `:endpoint/`. Leave any `ui.surfaces` / navigation-surface assertions alone.
+5. **Verify, then boot.** Run the verification block, then `pnpm -C core test` and
+   `pnpm -C ui check-types` before booting the app.
+
+## Verification
+
+```bash
+# 1. Find any remaining ontology surface/ IDs (navigation surfaces are fine — see discriminator)
+grep -rn ":surface/\|ontology.surfaces\|OntologySurfaceType" core/config/organization-model
+
+# Discriminator while reading hits:
+#   ontology (RENAME)  -> a ":surface/" ID segment, "ontology: { surfaces: ... }", OntologySurface*
+#   navigation (KEEP)  -> bare system.surfaces / ui.surfaces, SidebarSurface*, surfaceType
+
+# 2. Template-family coherence
+pnpm -C core test
+pnpm -C ui check-types
+pnpm -C ui test:contracts
+
+# 3. Boot must not throw OM validation (no unknown OntologyKind)
+```
+
+`OntologyKindSchema` must accept `endpoint` and reject `surface`; no `:surface/` ontology ID may
+remain. Navigation surfaces must still resolve and render in the sidebar.
+
+## Not handled by /git-sync
+
+- `/git-sync` and `/external sync` deliver the `@elevasis/core` + `@elevasis/ui` dependency baselines
+  and this note, but they do **not** edit your `core/config/organization-model/` — tenant OM content
+  is project-owned (`sync-preservation`). The `surface/` → `endpoint/` ontology-ID rewrite in steps
+  2–4 is manual per tenant (a no-op for every current live tenant, which carries none).
+- The Knowledge Browser UI upgrades (change #2) require **no** action — they are entirely inside
+  `@elevasis/ui` and appear on the bump.

package/reference/claude-config/sync-notes/2026-06-06-om-item-copy-references.md

@@ -0,0 +1,50 @@
+# Knowledge Browser item copy-references now resolve via `om:describe item:<domain>:<id>`
+
+## Why this note exists
+
+The Knowledge Browser used to copy an unresolvable `graph:<kind>:<uuid>` shorthand for
+domain items (clients, roles, policies, customers, offerings, goals). Pasting that to an
+agent led to dead ends — the OM resolver had no mount for it and `om:describe` rejected the
+id. This train (published `@elevasis/core`, `@elevasis/sdk`, `@elevasis/ui` + the bundled
+`om` skill) standardizes domain-item copy references on `item:<domain>:<id>`, which resolves
+to the rich profile plus its location and governing knowledge. The `om` skill's read-folder
+table and CLI invocation guidance changed, so derived projects must pick up the new skill
+text and package baselines.
+
+## Applies to
+
+- All template-derived projects that ship the `om` skill (`.claude/skills/om/SKILL.md`).
+- Any project whose Knowledge Browser surfaces domain items (clients, roles, policies,
+  customers, offerings, goals).
+- Agents that consume copied Knowledge Browser references.
+
+## Required actions
+
+1. Pull template changes and bump the published package baselines to the versions shipped by
+   this train: `@elevasis/core`, `@elevasis/sdk`, `@elevasis/ui` (run `pnpm install` after the
+   baseline bump so the new SDK CLI and UI copy behavior are present).
+2. Adopt the refreshed `.claude/skills/om/SKILL.md` read-folder table. It now documents
+   `item:<domain>:<id>` (resolves via `om:describe item:<domain>:<id>`), the `/by-domain/<domain>`
+   and `/by-item/<domain>/<id>` `om:ls` mounts, `group:` / `domain:` / `folder:` as
+   browser-overview references, and a legacy `graph:client:<uuid>` bridge note pointing to
+   `om:describe item:clients:<uuid>`.
+3. Use the corrected SDK CLI invocation at a project root: `pnpm elevasis-sdk om:describe …`
+   (root script alias) or `pnpm -C operations exec elevasis-sdk om:describe …`. The old
+   `pnpm exec elevasis-sdk …` at the project root fails in a multi-package tenant — replace it.
+
+## Verification
+
+- `pnpm elevasis-sdk om:describe item:clients:<id>` returns the client profile, its location
+  (domain + graph id + `contains` parentage), and any governing knowledge — no dead ends.
+- A bare/legacy `om:describe client:<uuid>` still resolves (back-compat for already-copied
+  references).
+- `pnpm sync:verify -- <project>` shows the `.claude/skills/om/SKILL.md` write applied and no
+  remaining `om`-skill drift.
+
+## Not handled by /git-sync
+
+- The published-package baseline bumps (`@elevasis/core` / `@elevasis/sdk` / `@elevasis/ui`)
+  and the subsequent `pnpm install` are manual — `/git-sync` does not bump dependencies.
+- Any project-local documentation that hand-copied the old `pnpm exec elevasis-sdk` root
+  invocation or the old `graph:<kind>:<uuid>` copy vocabulary must be corrected by the
+  maintainer; `/git-sync` stops before touching project-owned surfaces.

package/reference/scaffold/core/organization-graph.mdx

@@ -46,17 +46,18 @@ Edge kinds:
 
 - `contains`
 - `references`
-- `maps_to`
-- `uses`
-- `governs`
-- `governed-by`
-- `links`
-- `affects`
-- `emits`
+- `maps_to`
+- `uses`
+- `governs`
+- `links`
+- `affects`
+- `emits`
 - `originates_from`
 - `triggers`
 - `applies_to`
-- `effects`
+- `effects`
+
+`governed-by` is a Knowledge Graph route verb for traversing incoming `governs` edges; it is not an Organization Graph edge kind.
 
 System nodes come from the id-keyed `OrganizationModel.systems` map. Their graph IDs use `system:<id>`, such as `system:sales.crm`.
 

package/reference/scaffold/operations/propagation-pipeline.md

@@ -31,15 +31,19 @@ Layer 3: Sync Verification (pnpm sync:verify)
 
 ## Layer 1: Source Generation
 
-`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains three sub-scripts:
-
-| Script                                  | Input                                                                                                                                         | Output                                                              |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| `generate-scaffold-contracts.js`        | `packages/core/src/organization-model/types.ts`, `packages/ui/src/features/registry/types.ts`, `packages/core/src/platform/registry/types.ts` | `packages/core/src/reference/_generated/contracts.md`               |
-| `generate-scaffold-feature-registry.js` | `packages/ui/src/features/registry/manifests.ts`, `packages/ui/src/features/*/manifest.ts`                                                    | `packages/ui/src/scaffold/_generated/feature-registry.md`           |
-| `generate-reference-artifacts.js`       | SDK manifest, navigation sources                                                                                                              | `packages/sdk/reference/_reference-manifest.json`, `_navigation.md` |
-
-After generation, `validate-reference-artifacts.js` checks that the outputs are consistent. Exit 1 if drifted.
+`pnpm scaffold:sync` is the meta-script that regenerates all derived documentation and validates the output. It chains seven sub-scripts:
+
+| Script                 | Input                                                                                                                 | Output                                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `scaffold:generate`    | Scaffold contract and feature-registry sources                                                                        | `packages/core/src/reference/_generated/**`, `packages/ui/src/scaffold/_generated/feature-registry.md`     |
+| `knowledge:generate`   | Elevasis core knowledge nodes and UI knowledge body sources                                                           | Generated knowledge nodes and UI knowledge bodies                                                          |
+| `gen:sdk-catalog`      | SDK catalog source definitions                                                                                         | SDK catalog artifacts                                                                                      |
+| `gen:sdk-adapters`     | SDK adapter definitions                                                                                                | SDK adapter artifacts                                                                                      |
+| `copy-docs`            | SDK docs, package-owned reference docs, scaffold docs, and `_template/.claude` config                                  | `packages/sdk/reference/**` copied docs and scaffold reference bundle                                       |
+| `sdk-ref:generate`     | SDK manifest and navigation sources                                                                                    | `packages/sdk/reference/_reference-manifest.json`, `packages/sdk/reference/_navigation.md`                  |
+| `sdk-ref:check`        | Generated SDK reference artifacts                                                                                      | Freshness validation for `packages/sdk/reference/_reference-manifest.json` and `_navigation.md`             |
+
+The final `sdk-ref:check` step validates that the reference artifacts are consistent. Exit 1 if drifted.
 
 ### Trigger Points
 

package/reference/scaffold/operations/scaffold-maintenance.md

@@ -99,13 +99,14 @@ Generated files should never be edited manually. If the output is wrong, fix the
 
 ## SDK Build Pipeline (Reference Copy)
 
-`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has three phases:
-
-1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
-2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
-3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map
-
-The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `node_modules/@elevasis/sdk/reference/`.
+`packages/sdk/scripts/copy-reference-docs.mjs` runs during `pnpm --filter @elevasis/sdk build` and has four phases:
+
+1. **Phase 1:** Copies SDK public docs from `apps/docs/content/docs/sdk/` with link rewriting and MDX escape stripping
+2. **Phase 2:** Copies package-owned reference docs declared in reference manifests
+3. **Phase 3:** Copies scaffold docs from co-located package sources using the `SCAFFOLD_COPIES` map
+4. **Phase 4:** Copies `external/_template/.claude` into `packages/sdk/reference/claude-config` for tenant-facing agent configuration
+
+The output lands in `packages/sdk/reference/` which is included in the npm package's `files` array. External projects access it via `node_modules/@elevasis/sdk/reference/`.
 
 ---
 

package/reference/sdk/cli-management.mdx

@@ -1,12 +1,28 @@
 ---
 title: CLI Management Commands
-description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, and ui subcommand families
+description: elevasis-sdk management commands -- project, note, acquisition, client, agent, session, queue, schedule, om, ui, and skill subcommand families
 ---
 
 This page covers the domain management commands for `elevasis-sdk`. For core SDK commands (check, deploy, exec, resources, executions, describe, creds, rename), see [CLI Reference](cli.mdx).
 
 ---
 
+## JSON-valued options
+
+Any option that expects JSON can take inline JSON or a file reference:
+
+```bash
+elevasis-sdk queue:select <id> --action-id approve --payload @json:tmp/queue-payload.json
+elevasis-sdk schedule:create --name "Weekly report" --target-resource-type workflow --target-resource-id weekly-report --schedule-config @json:tmp/schedule-config.json
+elevasis-sdk project:task:save <id> --current-state "Updated" --files-modified @json:tmp/files-modified.json
+```
+
+`@json:<path>` is expanded before command parsing, so existing command handlers receive the same JSON string they would receive from an inline argument. Relative paths resolve against the Elevasis project root when the current directory is inside a project; otherwise they resolve against the current working directory. The referenced file must contain valid JSON.
+
+Use `@json:<path>` for generated payloads, nested objects, arrays, or Windows shells. Inline JSON remains supported for small values.
+
+---
+
 ## elevasis-sdk project:\*
 
 `elevasis-sdk project:*` is the canonical project-management surface. Use it for project, milestone, task, and note operations whether the caller is a human, a scripted workflow, or a slash-command router like `/project`.
@@ -42,18 +58,23 @@ elevasis-sdk project:milestone:list --project <id>
 elevasis-sdk project:milestone:create --project <id> --name "Phase 1"
 elevasis-sdk project:milestone:update <id> --status completed
 elevasis-sdk project:milestone:update <id> --description "Updated scope description"
+elevasis-sdk project:milestone:update <id> --checklist @json:tmp/milestone-checklist.json
 elevasis-sdk project:milestone:delete <id>
 ```
 
 `project:milestone:update` accepts `--description` to set or clear the milestone description. Passing an empty string clears the field, matching `project:task:update --description` semantics.
 
+Checklist updates are full replacements. Use `--checklist <json>` for small inline arrays, or `--checklist @json:<path>` for generated JSON. `--checklist-file <path>` is also supported for checklist-specific file input.
+
 ### Tasks
 
 ```bash
 elevasis-sdk project:task:list --project <id>
 elevasis-sdk project:task:get <id>
 elevasis-sdk project:task:create --project <id> --title "Implement API"
+elevasis-sdk project:task:create --project <id> --title "Implement API" --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:update <id> --status in_progress
+elevasis-sdk project:task:update <id> --checklist @json:tmp/task-checklist.json
 elevasis-sdk project:task:delete <id>
 ```
 
@@ -68,6 +89,8 @@ elevasis-sdk project:task:save <id> --current-state <text> [--files-modified <js
 - `project:task:save <id>` -- merges fields into `resume_context`; `--current-state` is required; all other flags are optional JSON arrays or plain text
 - these commands are the CLI counterpart to `/work resume` and `/work save` style flows
 
+Task checklist flags are also full replacements. `project:task:create`, `project:task:update`, and `project:milestone:update` support `--checklist <json>`, `--checklist @json:<path>`, and `--checklist-file <path>`. Prefer `@json:<path>` for non-trivial JSON and Windows shells because it works across JSON-valued options, not only checklist commands.
+
 **`project:task:save` flags:**
 
 | Flag                        | Description                               |
@@ -373,7 +396,7 @@ JWT-gated routes at the original unprefixed paths remain for the Command Center.
 
 Full CRUD management for client records. The `client:*` family covers create, read, update, and delete operations at `/api/external/clients`.
 
-For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/clients).
+For complete field definitions, filter options, and relationship semantics, see the [Clients feature documentation](/technical/features/operations/clients).
 
 **Quick reference:**
 
@@ -650,6 +673,24 @@ Both commands install after rewriting `package.json`. The `external/_template` r
 
 ---
 
+## elevasis-sdk skill:\*
+
+Developer-facing skill tooling keeps the template `.claude/skills/` surface aligned with the live CLI catalog.
+
+```bash
+elevasis-sdk skill:scaffold <domain>
+elevasis-sdk skill:check-coverage
+```
+
+- `skill:scaffold <domain>` prints a `SKILL.md` stub built from `elevasis-sdk cli --format json` for that domain. Author the curated skill at `external/_template/.claude/skills/<domain>/SKILL.md`; do not edit generated SDK reference copies directly.
+- `skill:check-coverage` compares live CLI domains against `.claude/registries/skill-coverage.json`. Domains must be owned by a skill or explicitly waived.
+
+The same coverage gate runs inside `elevasis-sdk check` when the coverage registry exists in the project root.
+
+**Implementation:** `packages/sdk/src/cli/commands/skill/`
+
+---
+
 ## Appendix: Domain Status
 
 Current status of all SDK CLI domains. Domains marked `deferred` have no CLI commands yet.
@@ -669,6 +710,7 @@ Current status of all SDK CLI domains. Domains marked `deferred` have no CLI com
 | session     | `session:list`, `session:get`, `session:end`                              | `/api/external/sessions*`                                  | implemented management scope |
 | queue       | `queue:list`, `queue:get`, `queue:select`, `queue:expire`, `queue:status` | `/api/external/command-queue*`                             | implemented                  |
 | schedule    | `schedule:list`, `schedule:get`, `schedule:create`, `schedule:update`     | `/api/external/task-scheduler/schedules*`                  | implemented                  |
+| skill       | `skill:scaffold`, `skill:check-coverage`                                  | local CLI catalog and `.claude/registries/skill-coverage.json` | implemented developer tooling |
 | content     | none                                                                      | not scoped here                                            | deferred                     |
 | seo         | none                                                                      | not scoped here                                            | deferred                     |
 | monitoring  | none                                                                      | not scoped here                                            | deferred                     |

package/reference/sdk/cli.mdx

@@ -13,7 +13,7 @@ pnpm add @elevasis/sdk
 
 After installation, the `elevasis-sdk` binary is available in your project's `node_modules/.bin/`. Most commands require `ELEVASIS_PLATFORM_KEY` to be set in your environment or a `.env` file.
 
-For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*), see [CLI Management](cli-management.mdx).
+For management commands (project:\*, note:\*, acquisition:\*, client:\*, agent:\*, session:\*, queue:\*, schedule:\*, om:\*, ui:\*, skill:\*), see [CLI Management](cli-management.mdx).
 
 ---
 
@@ -30,6 +30,7 @@ elevasis-sdk check
 **Behavior:**
 
 - Imports your `src/index.ts` and runs it through `ResourceRegistry` validation
+- Runs the skill coverage gate when `.claude/registries/skill-coverage.json` is present, ensuring every live CLI domain is covered by a template skill or explicitly waived
 - Catches the same errors that the platform catches at deploy time:
   - Duplicate `resourceId` within the organization
   - Invalid model configuration (temperature and token bounds)