@elevasis/sdk 1.33.1 → 1.34.1

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

@@ -55,6 +55,10 @@ metadata:
       - show me all reference docs
       - where does
       - apply
+      - build a system
+      - design a system
+      - create a system that
+      - system architecture
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
@@ -87,18 +91,34 @@ Auto-invocation is driven by frontmatter `description`, `metadata.pathPatterns`,
 
 ---
 
-## 5-Bucket Decision Tree
+## Operations
+
+| Operation | Description                                                                                                              | Execute                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| `build`   | Codify-ceremony runbook for building a System end to end (shell → ontology → resources → topology → knowledge → verify). | `.claude/skills/om/operations/build.md` |
+
+---
 
-Once invoked, classify the user's input into ONE of these buckets and dispatch the matching
-primitive. When two buckets fit, prefer the higher one (more specific → more general).
+## 5-Bucket Decision Tree
 
-| #   | Bucket                         | Trigger                                                                                          | Dispatch                                                                        |
-| --- | ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| 1   | Named knowledge/role/policy id | User names `knowledge.<id>`, `role.<id>`, `policy.<id>` directly                                 | `om:cat <id>` for body, `om:describe <id>` for neighborhood                     |
-| 2   | Named system                   | User names a system path (`sales.crm`, `sales.lead-gen`)                                         | `om:describe <id>`                                                              |
-| 3   | Named ontology id              | Id contains `:object/`, `:action/`, `:event/`, `:catalog/`, `:interface/`, `:link/`, `:surface/` | `om:describe <id>` (or `om:ls /by-ontology/<id> --ids-only` then `om:cat` each) |
-| 4   | Kind keyword                   | "playbooks", "strategies", "all references", "list policies"                                     | `om:ls /by-kind/<kind> --ids-only` then `om:cat` each                           |
-| 5   | Free-text discovery            | Anything else ("lead gen", "outreach", "what governs X?")                                        | `om:search "<query>"` then drill into top hit with `om:describe`                |
+If the user expresses intent to **build, design, or architect a system** -- phrased as "build a
+system", "design a system", "create a system that does X", "I want a system for Y", "system
+architecture for Z", or any free-text describing a system they want to construct rather than
+query -- route to `/om build` **before** the buckets below. Read
+`.claude/skills/om/operations/build.md` and follow its ordered phases. This is the primary
+entry; the user does not need to type `/om build` explicitly.
+
+Once invoked for read/write intents (not build), classify the user's input into ONE of these
+buckets and dispatch the matching primitive. When two buckets fit, prefer the higher one (more
+specific → more general).
+
+| #   | Bucket                         | Trigger                                                                                           | Dispatch                                                                        |
+| --- | ------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| 1   | Named knowledge/role/policy id | User names `knowledge.<id>`, `role.<id>`, `policy.<id>` directly                                  | `om:cat <id>` for body, `om:describe <id>` for neighborhood                     |
+| 2   | Named system                   | User names a system path (`sales.crm`, `sales.lead-gen`)                                          | `om:describe <id>`                                                              |
+| 3   | Named ontology id              | Id contains `:object/`, `:action/`, `:event/`, `:catalog/`, `:interface/`, `:link/`, `:endpoint/` | `om:describe <id>` (or `om:ls /by-ontology/<id> --ids-only` then `om:cat` each) |
+| 4   | Kind keyword                   | "playbooks", "strategies", "all references", "list policies"                                      | `om:ls /by-kind/<kind> --ids-only` then `om:cat` each                           |
+| 5   | Free-text discovery            | Anything else ("lead gen", "outreach", "what governs X?")                                         | `om:search "<query>"` then drill into top hit with `om:describe`                |
 
 On ambiguous input, default to **bucket 5 (search)** and surface the top hits. Codify and Toggle
 intents are write paths -- see "Write Power" below.
@@ -107,17 +127,20 @@ intents are write paths -- see "Write Power" below.
 
 ## CLI Surface
 
-All commands run with `pnpm exec elevasis-sdk <cmd>` (or the `om:` alias of the legacy `knowledge:` name).
-
-| Command            | Alias                | Purpose                                                                                                                                                                                 |
-| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `om:search <q>`    | `knowledge:search`   | Universal keyword search across all 6 OM surfaces                                                                                                                                       |
-| `om:describe <id>` | `knowledge:describe` | Structured neighborhood view; kind auto-detected from id shape                                                                                                                          |
-| `om:cat <id>`      | `knowledge:cat`      | Raw MDX body of a knowledge node                                                                                                                                                        |
-| `om:ls <path>`     | `knowledge:ls`       | List by mount path. Enumeration: `/all-systems`, `/all-resources`, `/all-roles`. Scoped: `/by-system/`, `/by-kind/`, `/by-ontology/`, `/by-owner/`, `/graph/<id>/{governs,governed-by}` |
-| `om:graph <id>`    | `knowledge:graph`    | Show outgoing + incoming graph edges                                                                                                                                                    |
-| `om:skills <id>`   | `knowledge:skills`   | Show callable invocations on graph neighbors                                                                                                                                            |
-| `om:generate`      | `knowledge:generate` | Regenerate `_generated/nodes.ts` from MDX sources                                                                                                                                       |
+All commands run with `pnpm elevasis-sdk <cmd>` from the tenant project root (uses the root script
+alias). Alternatively, use `pnpm -C operations exec elevasis-sdk <cmd>` from the monorepo root.
+Do NOT use `pnpm exec elevasis-sdk <cmd>` at the project root -- `@elevasis/sdk` is a dependency of
+`operations/` only; the binary is not found from the project root without the alias.
+
+| Command            | Alias                | Purpose                                                                                                                                                                                                             |
+| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `om:search <q>`    | `knowledge:search`   | Universal keyword search across all 6 OM surfaces                                                                                                                                                                   |
+| `om:describe <id>` | `knowledge:describe` | Structured neighborhood view; kind auto-detected from id shape; also resolves `item:<domain>:<id>` and bare `<prefix>:<uuid>` domain-item forms                                                                     |
+| `om:cat <id>`      | `knowledge:cat`      | Raw MDX body of a knowledge node                                                                                                                                                                                    |
+| `om:ls <path>`     | `knowledge:ls`       | List by mount path. Enumeration: `/all-systems`, `/all-resources`, `/all-roles`. Scoped: `/by-system/`, `/by-kind/`, `/by-ontology/`, `/by-owner/`, `/by-domain/`, `/by-item/`, `/graph/<id>/{governs,governed-by}` |
+| `om:graph <id>`    | `knowledge:graph`    | Show outgoing + incoming graph edges                                                                                                                                                                                |
+| `om:skills <id>`   | `knowledge:skills`   | Show callable invocations on graph neighbors                                                                                                                                                                        |
+| `om:generate`      | `knowledge:generate` | Regenerate `_generated/nodes.ts` from MDX sources                                                                                                                                                                   |
 
 Common flags: `--json`, `--ids-only`, `--limit <n>`, `--kinds <list>`.
 
@@ -128,23 +151,42 @@ Common flags: `--json`, `--ids-only`, `--limit <n>`, `--kinds <list>`.
 ### Free-text discovery (default for natural-language queries)
 
 ```bash
-pnpm exec elevasis-sdk om:search "lead gen"
-pnpm exec elevasis-sdk om:search outreach --kinds knowledge --limit 5
-pnpm exec elevasis-sdk om:search apollo --ids-only
+pnpm elevasis-sdk om:search "lead gen"
+pnpm elevasis-sdk om:search outreach --kinds knowledge --limit 5
+pnpm elevasis-sdk om:search apollo --ids-only
 ```
 
 ### Neighborhood view for any OM node
 
 ```bash
-pnpm exec elevasis-sdk om:describe sales.crm
-pnpm exec elevasis-sdk om:describe knowledge.outreach-playbook
-pnpm exec elevasis-sdk om:describe sales.crm:object/deal
+pnpm elevasis-sdk om:describe sales.crm
+pnpm elevasis-sdk om:describe knowledge.outreach-playbook
+pnpm elevasis-sdk om:describe sales.crm:object/deal
 ```
 
+### Domain-item profile (clients, roles, policies, customers, offerings, goals)
+
+Use `om:describe item:<domain>:<id>` to read a rich domain-item profile -- identity, branding,
+location, and governing knowledge. The bare `<prefix>:<uuid>` form (e.g. `client:<uuid>`) is
+accepted as a back-compat alias and resolves identically.
+
+```bash
+pnpm elevasis-sdk om:describe item:clients:<uuid>     # full ClientProfile + location + governing knowledge
+pnpm elevasis-sdk om:describe item:roles:<id>
+pnpm elevasis-sdk om:describe item:policies:<id>
+pnpm elevasis-sdk om:describe item:customers:<id>
+pnpm elevasis-sdk om:describe item:offerings:<id>
+pnpm elevasis-sdk om:describe item:goals:<id>
+```
+
+Do not confuse this with `client:get <uuid>` (the portfolio/DB surface for status, lineage, and
+deals). `om:describe item:clients:<uuid>` returns the org-model `ClientProfile`; `client:get`
+returns a sparse DB record. They share the same `id` and can be cross-linked by it.
+
 ### Read a single knowledge node body
 
 ```bash
-pnpm exec elevasis-sdk om:cat knowledge.outreach-playbook
+pnpm elevasis-sdk om:cat knowledge.outreach-playbook
 ```
 
 ### Top-level enumeration (drill-down entry point)
@@ -153,10 +195,10 @@ Start here when an agent needs to discover what this tenant's custom OM contains
 building on it -- list everything in a domain, then narrow with `om:describe` / `om:cat`:
 
 ```bash
-pnpm exec elevasis-sdk om:ls /all-systems              # every System (path + label)
-pnpm exec elevasis-sdk om:ls /all-resources            # every resource (id, kind, title)
-pnpm exec elevasis-sdk om:ls /all-roles                # every role (id, title)
-pnpm exec elevasis-sdk om:ls /all-systems --ids-only   # pipe paths into om:describe
+pnpm elevasis-sdk om:ls /all-systems              # every System (path + label)
+pnpm elevasis-sdk om:ls /all-resources            # every resource (id, kind, title)
+pnpm elevasis-sdk om:ls /all-roles                # every role (id, title)
+pnpm elevasis-sdk om:ls /all-systems --ids-only   # pipe paths into om:describe
 ```
 
 These resolve against this tenant's resolved model -- they enumerate the project's own custom
@@ -165,11 +207,13 @@ OM, not the platform's. Use `--json` for the wrapped envelope or `--ids-only` fo
 ### Scoped mount-path listings
 
 ```bash
-pnpm exec elevasis-sdk om:ls /by-system/sales.crm
-pnpm exec elevasis-sdk om:ls /by-kind/playbook --ids-only
-pnpm exec elevasis-sdk om:ls /by-ontology/sales.crm:object/deal --ids-only
-pnpm exec elevasis-sdk om:ls /by-owner/role.ops-lead --ids-only
-pnpm exec elevasis-sdk om:graph knowledge.outreach-playbook
+pnpm elevasis-sdk om:ls /by-system/sales.crm
+pnpm elevasis-sdk om:ls /by-kind/playbook --ids-only
+pnpm elevasis-sdk om:ls /by-ontology/sales.crm:object/deal --ids-only
+pnpm elevasis-sdk om:ls /by-owner/role.ops-lead --ids-only
+pnpm elevasis-sdk om:ls /by-domain/clients                    # enumerate all client domain items
+pnpm elevasis-sdk om:ls /by-item/clients/<uuid>               # single item record (same as om:describe item:clients:<uuid>)
+pnpm elevasis-sdk om:graph knowledge.outreach-playbook
 ```
 
 When a query clearly names an ontology id such as `sales.crm:object/deal`, route through
@@ -179,17 +223,31 @@ When a query clearly names an ontology id such as `sales.crm:object/deal`, route
 
 ### `/om read-folder` (chat shorthand from the Knowledge Browser)
 
-The Knowledge Browser's copy button on a top-level system or kind group emits a single
-`/om read-folder <axis>:<id>` line (or the legacy `/knowledge read-folder ...` form) instead of
-N per-node `read` lines. Resolve it by listing the folder via `om:ls` and reading each child:
+The Knowledge Browser's copy button on a top-level system, kind group, or domain-item node
+emits a single `/om read-folder <axis>:<id>` line (or the legacy `/knowledge read-folder ...`
+form) instead of N per-node `read` lines. Resolve it by the table below:
+
+| Copy form                            | Resolution                                                                                                                 |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `/om read-folder system:<id>`        | `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`, then `om:cat` each                                                   |
+| `/om read-folder kind:<kind>`        | `pnpm elevasis-sdk om:ls /by-kind/<kind> --ids-only`, then `om:cat` each                                                   |
+| `/om read-folder owner:<id>`         | `pnpm elevasis-sdk om:ls /by-owner/<id> --ids-only`, then `om:cat` each                                                    |
+| `/om read-folder ontology:<id>`      | `pnpm elevasis-sdk om:ls /by-ontology/<id> --ids-only`, then `om:cat` each                                                 |
+| `/om read-folder item:<domain>:<id>` | `pnpm elevasis-sdk om:describe item:<domain>:<id>` -- returns profile + location + governing knowledge                     |
+| `/om read-folder graph:<id>`         | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids                                   |
+| `/om read-folder group:<id>`         | browser overview reference only; resolve by visible children -- `pnpm elevasis-sdk om:ls /by-system/<id> --ids-only`       |
+| `/om read-folder domain:<domain>`    | browser overview reference only; resolve by enumerating domain -- `pnpm elevasis-sdk om:ls /by-domain/<domain> --ids-only` |
+| `/om read-folder folder:<id>`        | browser overview reference only; treat as `domain:<id>` and enumerate with `/by-domain/<id>`                               |
+
+**Legacy bridge -- `graph:client:<uuid>` and other `graph:<prefix>:<uuid>` domain-item forms:**
+Older Knowledge Browser builds emitted `graph:client:<uuid>` for client items. This is a
+graph-neighborhood shorthand, not a profile read. When you receive such a reference:
+
+1. Resolve the graph neighborhood: `pnpm elevasis-sdk om:graph client:<uuid>` (may return empty or only `contains` edges -- that is expected; no `ClientProfile` is accessible this way).
+2. For the rich profile, pivot to: `pnpm elevasis-sdk om:describe item:clients:<uuid>`.
 
-| Copy form                       | Resolution                                                                               |
-| ------------------------------- | ---------------------------------------------------------------------------------------- |
-| `/om read-folder system:<id>`   | `pnpm exec elevasis-sdk om:ls /by-system/<id> --ids-only`, then `om:cat` each            |
-| `/om read-folder kind:<kind>`   | `pnpm exec elevasis-sdk om:ls /by-kind/<kind> --ids-only`, then `om:cat` each            |
-| `/om read-folder owner:<id>`    | `pnpm exec elevasis-sdk om:ls /by-owner/<id> --ids-only`, then `om:cat` each             |
-| `/om read-folder ontology:<id>` | `pnpm exec elevasis-sdk om:ls /by-ontology/<id> --ids-only`, then `om:cat` each          |
-| `/om read-folder graph:<id>`    | inspect `/graph/<id>/governs` and `/graph/<id>/governed-by`; read returned knowledge ids |
+In short: `graph:client:<uuid>` points to the graph node; `item:clients:<uuid>` resolves the
+full org-model profile. Always use `item:` for profile reads going forward.
 
 Dotted system ids may use either dots or slashes (`sales.crm` and `sales/crm` both work).
 Legacy `feature:<id>` copy lines from older browser builds are compatibility aliases for
@@ -261,8 +319,8 @@ Placement examples:
 
 Before adding a System:
 
-1. Run `pnpm exec elevasis-sdk om:ls /all-systems`.
-2. Run `pnpm exec elevasis-sdk om:describe <candidate-parent-or-owner>`.
+1. Run `pnpm elevasis-sdk om:ls /all-systems`.
+2. Run `pnpm elevasis-sdk om:describe <candidate-parent-or-owner>`.
 3. If the proposed System name is a resource kind, shell group, or catch-all, do not create it;
    attach or create a Resource under the real owning System.
 4. Create a new System only when no existing System owns the capability and the new System has
@@ -414,4 +472,4 @@ classification names a specific domain.
 
 ---
 
-**Last Updated:** 2026-05-14
+**Last Updated:** 2026-06-06

package/reference/claude-config/skills/om/operations/build.md

@@ -0,0 +1,237 @@
+---
+name: build
+description: Guided Codify-ceremony runbook for building a new Organization Model System end to end in a tenant project — shell, ontology, resources, topology, knowledge node, and verify.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# /om build (Tenant)
+
+Intent-driven runbook for authoring a complete Organization Model System in this tenant project.
+The **primary entry is intent**: `/om` routes free-text build intent here via `promptSignals` and
+the 5-bucket classifier whenever you describe a system you want to build. Manual `/om build` is a
+supported secondary entry.
+
+Every write runs through the Codify ceremony (snapshot → propose → confirm → write → validate →
+rollback). See the "Write Power" section in `SKILL.md` for the ceremony steps.
+
+**Tenant authoring files** (split layout):
+
+- `core/config/organization-model/systems.ts` — System entries and system-owned resources
+- `core/config/organization-model/navigation.ts` — sidebar wiring
+- `core/config/knowledge/nodes/` — knowledge node MDX files
+
+---
+
+## Phase 0 — Capture Intent
+
+Before writing anything, extract:
+
+1. **System name and dotted path** (`parent.child` format, e.g. `sales.crm`).
+2. **Kind**: `product`, `operational`, `platform`, or `diagnostic`.
+3. **What it does** — one sentence. This becomes the `description`.
+4. **What it owns** — objects, actions, catalogs, events (these become `system.ontology` entries).
+5. **What it calls or reacts to** — other systems, triggers, human checkpoints.
+6. **Whether it needs a UI route** — yes/no determines whether `system.ui` is authored.
+7. **Whether it adopts a platform API interface** — yes/no determines whether `system.apiInterface`
+   is authored (see "API Interface Readiness" in `SKILL.md`).
+
+Run a pre-flight read to ground id choices in current model state:
+
+```bash
+pnpm elevasis-sdk om:ls /all-systems
+```
+
+---
+
+## Phase 1 — System Shell (Codify Level-A)
+
+Use `om:scaffold:system` (dry-run first) or the Codify Level-A ceremony to add the `SystemEntry`
+to `core/config/organization-model/systems.ts`.
+
+**Dry-run:**
+
+```bash
+pnpm elevasis-sdk om:scaffold:system --dry-run
+```
+
+Minimum fields: `id`, `order`, `label`. Optional at this stage: `description`, `kind`,
+`lifecycle`, `responsibleRoleId`.
+
+**Validate after write:**
+
+```bash
+pnpm -C operations check-types
+pnpm -C operations check
+```
+
+---
+
+## Phase 2 — Ontology (`system.ontology`)
+
+Add owned ontology kinds inside the `ontology` field of the `SystemEntry` in `systems.ts`.
+
+Valid scope keys: `objectTypes`, `linkTypes`, `actionTypes`, `catalogTypes`, `eventTypes`,
+`interfaceTypes`, `valueTypes`, `sharedProperties`, `groups`, `endpoints`.
+
+All ids use the canonical format: `system.path:kind/local-id`
+(e.g. `sales.crm:object/deal`, `sales.crm:action/qualify-lead`).
+
+Apply via the Codify Level-A ceremony — read, propose diff, confirm, write, validate.
+
+**Validate after write:**
+
+```bash
+pnpm -C operations check-types
+pnpm -C operations check
+```
+
+---
+
+## Phase 3 — Resources (Codify Level-A + scaffold)
+
+Add resource entries to `systems.ts` (or the split `resources` section if your project uses one).
+Each resource carries `systemPath` (canonical system attachment) and `ontology` bindings.
+
+Use `om:scaffold:resource` for guided creation, or Codify Level-A for manual addition.
+
+**Dry-run:**
+
+```bash
+pnpm elevasis-sdk om:scaffold:resource --dry-run --system-path <your.system>
+```
+
+Key invariants:
+
+- `resource.systemPath` is the canonical attachment for `getResourcesForSystem()`.
+- Choose `systemPath` based on the business capability the resource operates, not its kind.
+- `primaryAction` must be a member of `resource.ontology.actions`.
+
+**Validate after write:**
+
+```bash
+pnpm -C operations check-types
+pnpm -C operations check
+```
+
+---
+
+## Phase 4 — Topology (optional)
+
+If the system reacts to events, calls other systems, or requires human checkpoints, author
+topology relationships. In a tenant project, topology lives alongside the System entries in
+`systems.ts` (or a dedicated `topology` field if your project uses the split layout with a
+separate topology section).
+
+Canonical relationship kinds:
+
+- `triggers` — event, webhook, or schedule fires a resource handler
+- `uses` — this system calls another system or integration
+- `approval` — a step requires human checkpoint before continuing
+
+Cross-system API handoff requires a `uses` edge with `systemInterfaceGrant` metadata — see the
+"API Interface Readiness" section in `SKILL.md`.
+
+Apply via Codify Level-A ceremony. Validate after each topology write.
+
+---
+
+## Phase 5 — Knowledge Node (optional)
+
+Author a governing knowledge node to make the system searchable via `/om` and surfaced in the
+knowledge browser.
+
+Use `om:scaffold:knowledge` for guided creation:
+
+```bash
+pnpm elevasis-sdk om:scaffold:knowledge --dry-run --system-path <your.system> --kind playbook
+```
+
+MDX frontmatter shape:
+
+```mdx
+---
+id: knowledge.my-system-playbook
+kind: playbook
+label: My System Playbook
+description: Rules and patterns for operating My System.
+governs:
+  - my.system
+---
+```
+
+After authoring, regenerate the knowledge index:
+
+```bash
+pnpm elevasis-sdk om:generate
+```
+
+---
+
+## Phase 6 — UI and Navigation (optional)
+
+If the system needs a sidebar entry, author `system.ui` and add a navigation surface entry.
+
+`system.ui` fields: `path`, `surfaces[]`, `icon`, `order`. Apply via Codify Level-A.
+
+Navigation wiring lives in `core/config/organization-model/navigation.ts`. Add the system's
+path to the relevant sidebar section. Validate after the navigation write.
+
+---
+
+## Phase 7 — apiInterface (API-backed systems only)
+
+`system.apiInterface` is adopt-only in tenant projects. Only add it when the system adopts a
+platform-provided API capability from the installed `@elevasis/core` / `@elevasis/sdk` version.
+Use only readiness profiles listed in
+`node_modules/@elevasis/sdk/reference/scaffold/reference/system-interface-capabilities.md`.
+
+The profile also fixes the required System path — do not invent a profile or repoint a cataloged
+profile to a custom path.
+
+Apply via Codify Level-A after confirming the readiness profile with the user:
+
+```bash
+pnpm -C operations check-types
+pnpm -C operations check   # conformance gate fires here if the marker is incomplete
+```
+
+---
+
+## Phase 8 — Full Verify
+
+Run both validation gates once all phases are done:
+
+```bash
+pnpm -C operations check-types
+pnpm -C operations check
+```
+
+If the conformance gate reports a gaps file, apply it:
+
+```bash
+pnpm elevasis-sdk om:scaffold:fill --gaps .elevasis/conformance-gaps.json --dry-run
+```
+
+---
+
+## Quick Reference
+
+| Phase | OM Slot                           | Authoring File                    | Ceremony                |
+| ----- | --------------------------------- | --------------------------------- | ----------------------- |
+| 1     | `systems` map                     | `systems.ts`                      | Scaffold or Level-A     |
+| 2     | `system.ontology.<scope>`         | `systems.ts`                      | Level-A                 |
+| 3     | resources + `resource.systemPath` | `systems.ts`                      | Scaffold or Level-A     |
+| 4     | topology relationships            | `systems.ts` / topology section   | Level-A                 |
+| 5     | `system.governedByKnowledge[]`    | `knowledge/nodes/<path>/<id>.mdx` | Scaffold or Level-A     |
+| 6     | `system.ui` + navigation surfaces | `systems.ts` + `navigation.ts`    | Level-A                 |
+| 7     | `system.apiInterface`             | `systems.ts`                      | Level-A (adopt-only)    |
+| 8     | —                                 | —                                 | `check` + `check-types` |
+
+---
+
+## Cross-Links
+
+- Codify Level-A ceremony: `.claude/skills/om/operations/codify-level-a.md`
+- Scaffold (guided new entries): `.claude/skills/om/operations/scaffold.md`
+- API interface readiness: "API Interface Readiness" section in `.claude/skills/om/SKILL.md`
+- Platform narrative guide + worked examples: `node_modules/@elevasis/sdk/reference/guides/building-systems.md` (if present)

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-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.