@elevasis/sdk 1.8.2 → 1.9.0

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

@@ -1,78 +1,78 @@
----
-name: explore
-description: Codebase exploration anchored to project documentation
----
-
-# Explore
-
-Codebase exploration anchored to project documentation.
-
-**Usage:** `/explore [area or question]`
-
-## Process
-
-### Step 0: OS-Vocab Classification
-
-Before orienting, scan the user's query for Organization OS terminology. If any of the following appear, classify the query as **OS-relevant** and follow the OS context steps below; otherwise skip to Step 1.
-
-**OS vocabulary triggers:**
-
-- Feature layer: `feature`, `features`, `FeatureModule`, `feature key`, `feature gate`, `feature access`, `gate`, `gating`, `access`, `enable`, `disable`
-- Shell / nav: `manifest`, `shell`, `sub-shell`, `sidebar`, `nav`, `navigation`, `route`
-- Auth / guards: `guard`, `FeatureGuard`, `AdminGuard`, `ProtectedRoute`, `admin`
-- Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
-- Foundations: `foundation`, `foundations`, `@foundation/`, `adapter`
-- Platform ops: `workflow`, `agent`, `deployment`, `resource`
-
-**If OS-relevant:**
-
-1. Read `.claude/rules/active-change-index.md` immediately. If the target area is flagged as under active refactor, surface the watch-area warning to the user before proceeding — include the "Load:" doc paths listed in that entry so investigation does not rely on stale scaffold prose.
-2. Build the OS context bundle to pass into Step 3:
-   - Always: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`, `.claude/rules/active-change-index.md`, `.claude/rules/agent-start-here.md`
-   - Features / Shell / Gating queries: add `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
-   - Workflow / Operations queries: add `.claude/rules/operations.md` + glob `operations/resources/**`
-   - Organization-model queries: add `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` + `foundations/config/README.md`
-
-**OS layer → query intent map** (guides which reference docs the investigator loads first):
-
-| Query intent                             | Primary OS layers                | Key reference                                                                            |
-| ---------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
-| "Why doesn't my feature show up?"        | Features + UI Shell Runtime      | `glossary.md` (accessFeatureKey, FEATURE_KEY_ALIASES), `feature-flags-and-gating.md`     |
-| "How do I add a nav item?"               | Features + Toolkit               | `feature-flags-and-gating.md`, `contracts.md`                                            |
-| "How does admin gating work?"            | Features + UI Shell Runtime      | `glossary.md` (AdminGuard, requiresAdmin, ProtectedRoute), `feature-flags-and-gating.md` |
-| "What runs when this workflow triggers?" | Platform Public API + Operations | `.claude/rules/operations.md`, `resources.md`                                            |
-| "Why does the foundations adapter fail?" | Foundations                      | `glossary.md` (domain vs surface, settings asymmetry), `foundations/config/README.md`    |
-
-### Step 1: Orient
-
-1. Read `.claude/rules/agent-start-here.md` for project structure, task-class routing, and boundary resolution
-2. Determine which domain the user's question falls into
-
-### Step 2: Load Domain Context
-
-Read the relevant doc(s) and source directories based on the area being explored. Use the Navigation table in `CLAUDE.md` for quick reference.
-
-For OS-relevant queries, also inject the OS context bundle assembled in Step 0 into the investigator's starting context.
-
-### Step 3: Investigate
-
-For targeted questions:
-
-- Use Grep to search for specific patterns, function names, or strings
-- Use Glob to find files by pattern
-- Read specific files for detailed understanding
-
-For broad exploration:
-
-- Dispatch a `general-purpose` subagent with the domain context and exploration question
-- The subagent should read files, trace data flow, and return a structured report
-- For OS-relevant queries, pass the preloaded OS context bundle so the subagent starts with terminology already resolved
-
-### Step 4: Report
-
-Present findings with:
-
-- Direct answers to the question
-- Relevant code locations (file:function format)
-- Connections to other parts of the system
-- Suggestions for related areas to explore (if relevant)
+---
+name: explore
+description: Codebase exploration anchored to project documentation
+---
+
+# Explore
+
+Codebase exploration anchored to project documentation.
+
+**Usage:** `/explore [area or question]`
+
+## Process
+
+### Step 0: OS-Vocab Classification
+
+Before orienting, scan the user's query for Organization OS terminology. If any of the following appear, classify the query as **OS-relevant** and follow the OS context steps below; otherwise skip to Step 1.
+
+**OS vocabulary triggers:**
+
+- Feature layer: `feature`, `features`, `FeatureModule`, `feature key`, `feature gate`, `feature access`, `gate`, `gating`, `access`, `enable`, `disable`
+- Shell / nav: `manifest`, `shell`, `sub-shell`, `sidebar`, `nav`, `navigation`, `route`
+- Auth / guards: `guard`, `FeatureGuard`, `AdminGuard`, `ProtectedRoute`, `admin`
+- Org model: `organization`, `org model`, `organization model`, `domain`, `surface`
+- Foundations: `foundation`, `foundations`, `@foundation/`, `adapter`
+- Platform ops: `workflow`, `agent`, `deployment`, `resource`
+
+**If OS-relevant:**
+
+1. Read `.claude/rules/active-change-index.md` immediately. If the target area is flagged as under active refactor, surface the watch-area warning to the user before proceeding — include the "Load:" doc paths listed in that entry so investigation does not rely on stale scaffold prose.
+2. Build the OS context bundle to pass into Step 3:
+   - Always: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`, `.claude/rules/active-change-index.md`, `.claude/rules/agent-start-here.md`
+   - Features / Shell / Gating queries: add `node_modules/@elevasis/sdk/reference/scaffold/ui/feature-flags-and-gating.md` + `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md`
+   - Workflow / Operations queries: add `.claude/rules/operations.md` + glob `operations/resources/**`
+   - Organization-model queries: add `node_modules/@elevasis/sdk/reference/scaffold/reference/contracts.md` + `foundations/config/README.md`
+
+**OS layer → query intent map** (guides which reference docs the investigator loads first):
+
+| Query intent                             | Primary OS layers                | Key reference                                                                            |
+| ---------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
+| "Why doesn't my feature show up?"        | Features + UI Shell Runtime      | `glossary.md` (accessFeatureKey, FEATURE_KEY_ALIASES), `feature-flags-and-gating.md`     |
+| "How do I add a nav item?"               | Features + Toolkit               | `feature-flags-and-gating.md`, `contracts.md`                                            |
+| "How does admin gating work?"            | Features + UI Shell Runtime      | `glossary.md` (AdminGuard, requiresAdmin, ProtectedRoute), `feature-flags-and-gating.md` |
+| "What runs when this workflow triggers?" | Platform Public API + Operations | `.claude/rules/operations.md`, `resources.md`                                            |
+| "Why does the foundations adapter fail?" | Foundations                      | `glossary.md` (domain vs surface, settings asymmetry), `foundations/config/README.md`    |
+
+### Step 1: Orient
+
+1. Read `.claude/rules/agent-start-here.md` for project structure, task-class routing, and boundary resolution
+2. Determine which domain the user's question falls into
+
+### Step 2: Load Domain Context
+
+Read the relevant doc(s) and source directories based on the area being explored. Use the Navigation table in `CLAUDE.md` for quick reference.
+
+For OS-relevant queries, also inject the OS context bundle assembled in Step 0 into the investigator's starting context.
+
+### Step 3: Investigate
+
+For targeted questions:
+
+- Use Grep to search for specific patterns, function names, or strings
+- Use Glob to find files by pattern
+- Read specific files for detailed understanding
+
+For broad exploration:
+
+- Dispatch a `general-purpose` subagent with the domain context and exploration question
+- The subagent should read files, trace data flow, and return a structured report
+- For OS-relevant queries, pass the preloaded OS context bundle so the subagent starts with terminology already resolved
+
+### Step 4: Report
+
+Present findings with:
+
+- Direct answers to the question
+- Relevant code locations (file:function format)
+- Connections to other parts of the system
+- Suggestions for related areas to explore (if relevant)

package/reference/claude-config/skills/git-sync/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: git-sync
+description: Pull latest changes, surface new sync notes, install when needed, and run baseline verification without auto-reconciling template drift
+---
+
+# Git Sync
+
+Pull the latest upstream changes for this project, detect any newly introduced template sync notes, install dependencies when the pull changed package baselines, and run the baseline verification flow.
+
+**Usage:** `/git-sync`
+
+Use this when:
+
+- you just pulled a release-train update from the template repo
+- the branch may include dependency or scaffold baseline changes
+- you want the current sync-note guidance before making any manual reconciliation edits
+
+This command is intentionally narrower than template reconciliation. It stops after pull, install, verification, and note surfacing. It never auto-overwrites project-owned files.
+
+## Sync Notes Contract
+
+Downstream release guidance lives in `.claude/sync-notes/`.
+
+- Operative note files are named `YYYY-MM-DD-<slug>.md`
+- `README.md` documents the contract and is ignored by note detection
+- Notes are append-only release guidance; do not rewrite old note filenames after they ship
+- Every operative note uses these exact headings:
+  - `## Why this note exists`
+  - `## Applies to`
+  - `## Required actions`
+  - `## Verification`
+  - `## Not handled by /git-sync`
+
+## Process
+
+### Step 1: Check for Uncommitted Changes
+
+```bash
+git status --short
+```
+
+If the worktree is dirty, stop and tell the user to commit, stash, or discard changes first. Do not pull on top of local edits.
+
+### Step 2: Snapshot Current Sync Notes
+
+Capture the current operative note filenames before pulling:
+
+```bash
+git ls-files ".claude/sync-notes/*.md"
+```
+
+Ignore `README.md` when building the pre-pull note set.
+
+### Step 3: Pull Latest Changes
+
+```bash
+git pull --rebase
+```
+
+If the pull conflicts, stop and report the conflict. Do not attempt auto-resolution.
+
+### Step 4: Detect Whether Install Is Required
+
+If the pull changed any dependency baseline files, run a fresh install:
+
+```bash
+git diff --name-only HEAD@{1} HEAD -- package.json pnpm-lock.yaml pnpm-workspace.yaml ui/package.json operations/package.json shared/package.json
+```
+
+If the diff is non-empty:
+
+```bash
+pnpm install
+```
+
+If none of those files changed, skip install and report that the dependency baseline was unchanged.
+
+### Step 5: Run Baseline Verification
+
+Run the standard project verification flow:
+
+```bash
+pnpm -C ui check-types
+pnpm -C ui build
+pnpm -C operations check
+pnpm -C operations check-types
+```
+
+Stop on the first failure and report it clearly.
+
+### Step 6: Surface Newly Introduced Sync Notes
+
+Build the post-pull operative note set and compare it to the pre-pull set. Any newly added note filename is considered unread guidance for this pull.
+
+When new notes exist:
+
+- print each new note filename
+- summarize the `## Required actions`, `## Verification`, and `## Not handled by /git-sync` sections
+- tell the user exactly which manual follow-up remains
+
+When no new notes exist, say so explicitly.
+
+### Step 7: Stop Before Reconciliation
+
+`/git-sync` ends after pull, optional install, verification, and note surfacing.
+
+It does **not**:
+
+- run registry/template reconciliation
+- overwrite project-owned files
+- resolve downstream migration conflicts
+- treat a passing baseline verify as proof that manual follow-up is complete
+
+If a sync note or the pulled diff requires project-specific changes, leave those as an explicit next step.
+
+## Report
+
+```text
+Git Sync Complete
+=================
+Git:        pulled (<branch>)
+Install:    ran | skipped (no dependency baseline changes)
+Verify:     PASS | FAIL at <step>
+Sync notes: none | 2026-04-22-example-change.md
+Next step:  manual reconciliation required | none
+```

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

@@ -1,183 +1,183 @@
----
-name: save
-description: Auto-manage project documentation and persist task resume context from conversation
----
-
-# Save
-
-Auto-manage project documentation from conversation context, and fan out conversation signals to the canonical project system (`prj_tasks.resume_context`, `prj_notes`) via the `elevasis-sdk` CLI.
-
-## Canonical Sources of Truth
-
-- **Task resume context (DB):** `prj_tasks.resume_context` is canonical. Agents write it via `elevasis-sdk project:task:save`. Humans edit it via the inline task editor in Command Center. **Never** stash resume context into task-doc frontmatter.
-- **Task-doc frontmatter:** ONLY `title`, `description`, `status`. No `resume_context`, no files-modified, no next-steps arrays -- those belong in the DB.
-- **Project notes (DB):** `prj_notes` via `elevasis-sdk project:note:create`. Typed notes (`status_update` / `issue` / `blocker` / `call_note`) are the durable record of conversation signals.
-
-## Process
-
-### Step 1: Resolve Project + Task Context
-
-Before doing anything else, determine the active project / task:
-
-1. Look for an active task-doc frontmatter in the current conversation or the most recently edited file. Expected frontmatter:
-
-   ```yaml
-   ---
-   title: Short title
-   description: One-line summary
-   status: planned | in-progress | blocked | complete
-   ---
-   ```
-
-2. If the task doc references a project/task UUID anywhere in its body (link, callout, or prior save output), capture those IDs.
-3. If no task / project context is resolvable, PROMPT the user:
-   - "Which project is this work under?" (accepts slug or UUID)
-   - "Is there an existing task I should attach this to? (task UUID, or 'new')"
-
-   Do not guess. Without a task ID, skip Step 4 (DB resume-context save) but still perform Steps 2, 3, 5, 6, 7.
-
-### Step 2: Analyze Conversation
-
-Review the current conversation to identify:
-
-1. **New knowledge** -- architecture decisions, feature implementations, bug fixes, discoveries
-2. **Changed state** -- what was in-progress that is now complete, what new work started
-3. **Stale docs** -- information in existing docs that is now outdated
-4. **Signal events** -- blocker hit, status update worth recording, issue uncovered, call outcome
-5. **OS contract paths touched** -- scan files read/written/edited for any of these signals:
-   - `foundations/config/organization-model.ts` -> Foundations layer, Organization Model
-   - `foundations/types/index.ts` -> Foundations layer, Workflow Contracts
-   - `ui/src/routes/__root.tsx` -> UI Shell Runtime composition
-   - `ui/src/features/**/manifest.ts` or any file defining a `FeatureModule` -> Features layer
-   - `operations/src/index.ts` or `operations/elevasis.config.ts` -> Foundations/Deployment (DeploymentSpec)
-   - Any file inside `ui/src/features/<feature>/` combined with manifest, nav, or sidebar changes -> Features + Toolkit layers
-
-   Record which OS layers were touched: `foundations`, `features`, `shell-runtime`, `toolkit`, `deployment`. If none matched, OS awareness stays dormant for the rest of this run.
-
-### Step 3: Update Knowledge Docs
-
-Scan for unindexed or stale knowledge docs and draft creates / updates / moves. This template does not have a `docs/` tree — look for any local knowledge files (`.claude/rules/`, `operations/src/README.md`, `foundations/`, or project-specific docs the user has created). All edits are on knowledge/architecture/feature docs -- NOT on task resume state (that flows to the DB in Step 4).
-
-Determine what needs to happen:
-
-- **Create** new docs for significant new knowledge (new features, architecture decisions)
-- **Update** existing docs with corrections, completions, or new details
-- **Move** docs between directories (e.g., `ui/` to `operations/` when ownership shifts)
-- **Delete** docs that are fully obsolete (rare -- prefer updating)
-
-**Frontmatter requirement (all docs in `docs/`):**
-
-```markdown
----
-title: Short descriptive title
-description: One-line summary of what this doc covers
----
-```
-
-In-progress task docs additionally require `status`:
-
-```markdown
----
-title: Feature Name
-description: What this task is about
-status: planned | in-progress | blocked | complete
----
-```
-
-No other fields. Do NOT add `resume_context`, `files_modified`, or `next_steps` to frontmatter -- those flow to the DB via Step 4.
-
-**Doc structure rules:**
-
-- All docs are `.md` (not .mdx)
-- Keep docs focused -- one topic per file
-- Use markdown tables for structured data
-- Include "Last Updated: YYYY-MM-DD" at the bottom of modified docs
-
-**OS layer annotation:** If OS contract paths were touched (Step 2), include an `## Organization OS Impact` section in any newly created architecture doc:
-
-```markdown
-## Organization OS Impact
-
-Touched contracts: [list files]
-Affected layers: [list of layers]
-Cross-reference: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`
-Downstream: template consumer adapters may need review.
-```
-
-Dispatch a `general-purpose` subagent with the plan, conversation context, and these rules. The subagent must read each target file before editing.
-
-### Step 4: Persist Task Resume Context to DB
-
-If Step 1 resolved a task ID, save the current state to `prj_tasks.resume_context` via the SDK CLI. This is the canonical persistence step and must run every `/save` invocation that has a task in scope:
-
-```bash
-pnpm elevasis-sdk project:task:save <task-uuid> \
-  --current-state "<concise prose summary of where we are>" \
-  --next-steps "<concise prose of the next concrete action>" \
-  --files-modified '["path/one.ts","path/two.tsx"]' \
-  --key-docs '["operations/resources/foo/index.ts"]' \
-  --tools '["project:task:save","project:note:create"]'
-```
-
-Arg rules:
-
-- `--current-state` (required) -- terse, present-tense "what is true right now". Prefer latest state over accumulated history.
-- `--next-steps` -- single next concrete action another agent could execute without re-deriving intent.
-- `--files-modified` -- JSON array of uncommitted / just-changed file paths (relative to project root).
-- `--key-docs` -- JSON array of doc paths an agent should re-read to resume.
-- `--tools` -- JSON array of tool / CLI names used this session that are worth flagging.
-
-The endpoint is `PATCH /api/external/tasks/<id>/resume-context` and merges (does not replace) provided fields. Omit any arg that has nothing meaningful to record.
-
-### Step 5: Create Typed Project Notes on Signal Events
-
-For each signal event identified in Step 2, create a typed `prj_note`. One CLI call per note:
-
-```bash
-pnpm elevasis-sdk project:note:create \
-  --project <project-uuid> \
-  --task <task-uuid>          # optional, omit if not scoped to a task \
-  --type <note-type> \
-  --content "<what happened, why it matters, any next action>"
-```
-
-Note-type mapping (use the first type that matches, in this order):
-
-- **`blocker`** -- work cannot proceed without external action (decision, credential, fix elsewhere, upstream change). Always create if detected. Trigger phrases: "I'm stuck", "blocked on", "can't proceed until", "waiting on <X>". When detected AND a task ID is in scope, ALSO fire a status transition -- see Step 5a below.
-- **`issue`** -- bug, regression, unexpected failure, contract mismatch. Include reproduction context in `--content`.
-- **`status_update`** -- milestone-level progress worth flagging to the human operator (phase complete, substantial deliverable landed, direction change). Keep it substantive -- `/save` runs shouldn't emit a status_update every turn.
-- **`call_note`** -- only if the conversation is transcribing a live client / stakeholder call.
-
-If no signal rises to note-worthy, skip this step entirely. Do not create filler notes.
-
-### Step 5a: Blocker Signal -> Task Status Transition
-
-Run this ONLY when Step 5 created a `blocker` note AND Step 1 resolved a task ID. It's the second half of the "I'm stuck" fanout: the note captures the why, this call flips the task's lifecycle state so it surfaces as blocked in portfolio views.
-
-```bash
-pnpm elevasis-sdk project:task:update <task-uuid> --status blocked
-```
-
-Rules:
-
-- **Explicit task ID only** -- use the UUID resolved in Step 1. Do not re-derive or guess. If no task is in scope, skip this step (the blocker note still ships without it).
-- **Best-effort** -- if the CLI returns non-2xx, surface a single warning line in Step 7 ("Warning: could not transition task <id> to blocked: <reason>") and continue. Do not retry, do not block the rest of `/save`.
-- **Idempotent** -- if the task is already `blocked`, the update is a no-op. Fire it anyway; do not pre-check.
-- **Order** -- the `blocker` note (Step 5) creates first; this transition follows. Keeps the note attached to the task even if the status update later fails.
-
-### Step 6: Report
-
-Summarize:
-
-- Knowledge docs created / updated / moved / deleted
-- Task ID written to (Step 4): `resume_context.last_saved` timestamp from the CLI response
-- Notes created (Step 5): count, types, IDs
-- OS classification (if applicable): layers detected, contracts touched
-- Any files skipped due to missing frontmatter (Step 3 subagent should have added it)
-- Any follow-ups for the human operator
-
-## Failure Modes
-
-- **No task in scope + user declines to provide one:** proceed with Steps 2, 3, 6, 7; skip Step 4; still allow Step 5 if a `--project` UUID is available.
-- **`project:task:save` returns non-2xx:** surface the error in the report, do not retry silently; Step 5 and Step 6 still run.
-- **Knowledge doc edits fail to write:** surface the error; any edits already applied are on disk and not lost.
+---
+name: save
+description: Auto-manage project documentation and persist task resume context from conversation
+---
+
+# Save
+
+Auto-manage project documentation from conversation context, and fan out conversation signals to the canonical project system (`prj_tasks.resume_context`, `prj_notes`) via the `elevasis-sdk` CLI.
+
+## Canonical Sources of Truth
+
+- **Task resume context (DB):** `prj_tasks.resume_context` is canonical. Agents write it via `elevasis-sdk project:task:save`. Humans edit it via the inline task editor in Command Center. **Never** stash resume context into task-doc frontmatter.
+- **Task-doc frontmatter:** ONLY `title`, `description`, `status`. No `resume_context`, no files-modified, no next-steps arrays -- those belong in the DB.
+- **Project notes (DB):** `prj_notes` via `elevasis-sdk project:note:create`. Typed notes (`status_update` / `issue` / `blocker` / `call_note`) are the durable record of conversation signals.
+
+## Process
+
+### Step 1: Resolve Project + Task Context
+
+Before doing anything else, determine the active project / task:
+
+1. Look for an active task-doc frontmatter in the current conversation or the most recently edited file. Expected frontmatter:
+
+   ```yaml
+   ---
+   title: Short title
+   description: One-line summary
+   status: planned | in-progress | blocked | complete
+   ---
+   ```
+
+2. If the task doc references a project/task UUID anywhere in its body (link, callout, or prior save output), capture those IDs.
+3. If no task / project context is resolvable, PROMPT the user:
+   - "Which project is this work under?" (accepts slug or UUID)
+   - "Is there an existing task I should attach this to? (task UUID, or 'new')"
+
+   Do not guess. Without a task ID, skip Step 4 (DB resume-context save) but still perform Steps 2, 3, 5, 6, 7.
+
+### Step 2: Analyze Conversation
+
+Review the current conversation to identify:
+
+1. **New knowledge** -- architecture decisions, feature implementations, bug fixes, discoveries
+2. **Changed state** -- what was in-progress that is now complete, what new work started
+3. **Stale docs** -- information in existing docs that is now outdated
+4. **Signal events** -- blocker hit, status update worth recording, issue uncovered, call outcome
+5. **OS contract paths touched** -- scan files read/written/edited for any of these signals:
+   - `foundations/config/organization-model.ts` -> Foundations layer, Organization Model
+   - `foundations/types/index.ts` -> Foundations layer, Workflow Contracts
+   - `ui/src/routes/__root.tsx` -> UI Shell Runtime composition
+   - `ui/src/features/**/manifest.ts` or any file defining a `FeatureModule` -> Features layer
+   - `operations/src/index.ts` or `operations/elevasis.config.ts` -> Foundations/Deployment (DeploymentSpec)
+   - Any file inside `ui/src/features/<feature>/` combined with manifest, nav, or sidebar changes -> Features + Toolkit layers
+
+   Record which OS layers were touched: `foundations`, `features`, `shell-runtime`, `toolkit`, `deployment`. If none matched, OS awareness stays dormant for the rest of this run.
+
+### Step 3: Update Knowledge Docs
+
+Scan for unindexed or stale knowledge docs and draft creates / updates / moves. This template does not have a `docs/` tree — look for any local knowledge files (`.claude/rules/`, `operations/src/README.md`, `foundations/`, or project-specific docs the user has created). All edits are on knowledge/architecture/feature docs -- NOT on task resume state (that flows to the DB in Step 4).
+
+Determine what needs to happen:
+
+- **Create** new docs for significant new knowledge (new features, architecture decisions)
+- **Update** existing docs with corrections, completions, or new details
+- **Move** docs between directories (e.g., `ui/` to `operations/` when ownership shifts)
+- **Delete** docs that are fully obsolete (rare -- prefer updating)
+
+**Frontmatter requirement (all docs in `docs/`):**
+
+```markdown
+---
+title: Short descriptive title
+description: One-line summary of what this doc covers
+---
+```
+
+In-progress task docs additionally require `status`:
+
+```markdown
+---
+title: Feature Name
+description: What this task is about
+status: planned | in-progress | blocked | complete
+---
+```
+
+No other fields. Do NOT add `resume_context`, `files_modified`, or `next_steps` to frontmatter -- those flow to the DB via Step 4.
+
+**Doc structure rules:**
+
+- All docs are `.md` (not .mdx)
+- Keep docs focused -- one topic per file
+- Use markdown tables for structured data
+- Include "Last Updated: YYYY-MM-DD" at the bottom of modified docs
+
+**OS layer annotation:** If OS contract paths were touched (Step 2), include an `## Organization OS Impact` section in any newly created architecture doc:
+
+```markdown
+## Organization OS Impact
+
+Touched contracts: [list files]
+Affected layers: [list of layers]
+Cross-reference: `node_modules/@elevasis/sdk/reference/scaffold/reference/glossary.md`
+Downstream: template consumer adapters may need review.
+```
+
+Dispatch a `general-purpose` subagent with the plan, conversation context, and these rules. The subagent must read each target file before editing.
+
+### Step 4: Persist Task Resume Context to DB
+
+If Step 1 resolved a task ID, save the current state to `prj_tasks.resume_context` via the SDK CLI. This is the canonical persistence step and must run every `/save` invocation that has a task in scope:
+
+```bash
+pnpm elevasis-sdk project:task:save <task-uuid> \
+  --current-state "<concise prose summary of where we are>" \
+  --next-steps "<concise prose of the next concrete action>" \
+  --files-modified '["path/one.ts","path/two.tsx"]' \
+  --key-docs '["operations/resources/foo/index.ts"]' \
+  --tools '["project:task:save","project:note:create"]'
+```
+
+Arg rules:
+
+- `--current-state` (required) -- terse, present-tense "what is true right now". Prefer latest state over accumulated history.
+- `--next-steps` -- single next concrete action another agent could execute without re-deriving intent.
+- `--files-modified` -- JSON array of uncommitted / just-changed file paths (relative to project root).
+- `--key-docs` -- JSON array of doc paths an agent should re-read to resume.
+- `--tools` -- JSON array of tool / CLI names used this session that are worth flagging.
+
+The endpoint is `PATCH /api/external/tasks/<id>/resume-context` and merges (does not replace) provided fields. Omit any arg that has nothing meaningful to record.
+
+### Step 5: Create Typed Project Notes on Signal Events
+
+For each signal event identified in Step 2, create a typed `prj_note`. One CLI call per note:
+
+```bash
+pnpm elevasis-sdk project:note:create \
+  --project <project-uuid> \
+  --task <task-uuid>          # optional, omit if not scoped to a task \
+  --type <note-type> \
+  --content "<what happened, why it matters, any next action>"
+```
+
+Note-type mapping (use the first type that matches, in this order):
+
+- **`blocker`** -- work cannot proceed without external action (decision, credential, fix elsewhere, upstream change). Always create if detected. Trigger phrases: "I'm stuck", "blocked on", "can't proceed until", "waiting on <X>". When detected AND a task ID is in scope, ALSO fire a status transition -- see Step 5a below.
+- **`issue`** -- bug, regression, unexpected failure, contract mismatch. Include reproduction context in `--content`.
+- **`status_update`** -- milestone-level progress worth flagging to the human operator (phase complete, substantial deliverable landed, direction change). Keep it substantive -- `/save` runs shouldn't emit a status_update every turn.
+- **`call_note`** -- only if the conversation is transcribing a live client / stakeholder call.
+
+If no signal rises to note-worthy, skip this step entirely. Do not create filler notes.
+
+### Step 5a: Blocker Signal -> Task Status Transition
+
+Run this ONLY when Step 5 created a `blocker` note AND Step 1 resolved a task ID. It's the second half of the "I'm stuck" fanout: the note captures the why, this call flips the task's lifecycle state so it surfaces as blocked in portfolio views.
+
+```bash
+pnpm elevasis-sdk project:task:update <task-uuid> --status blocked
+```
+
+Rules:
+
+- **Explicit task ID only** -- use the UUID resolved in Step 1. Do not re-derive or guess. If no task is in scope, skip this step (the blocker note still ships without it).
+- **Best-effort** -- if the CLI returns non-2xx, surface a single warning line in Step 7 ("Warning: could not transition task <id> to blocked: <reason>") and continue. Do not retry, do not block the rest of `/save`.
+- **Idempotent** -- if the task is already `blocked`, the update is a no-op. Fire it anyway; do not pre-check.
+- **Order** -- the `blocker` note (Step 5) creates first; this transition follows. Keeps the note attached to the task even if the status update later fails.
+
+### Step 6: Report
+
+Summarize:
+
+- Knowledge docs created / updated / moved / deleted
+- Task ID written to (Step 4): `resume_context.last_saved` timestamp from the CLI response
+- Notes created (Step 5): count, types, IDs
+- OS classification (if applicable): layers detected, contracts touched
+- Any files skipped due to missing frontmatter (Step 3 subagent should have added it)
+- Any follow-ups for the human operator
+
+## Failure Modes
+
+- **No task in scope + user declines to provide one:** proceed with Steps 2, 3, 6, 7; skip Step 4; still allow Step 5 if a `--project` UUID is available.
+- **`project:task:save` returns non-2xx:** surface the error in the report, do not retry silently; Step 5 and Step 6 still run.
+- **Knowledge doc edits fail to write:** surface the error; any edits already applied are on disk and not lost.