@vpxa/aikit 0.1.380 → 0.1.382

package/scaffold/dist/definitions/skills/aikit.mjs

@@ -1,105 +1,4 @@
-var e=[{file:`SKILL.md`,content:`---
-name: aikit
-description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, context compression, validation, and persistent memory. Load at session start or before using aikit_* tools. This skill teaches tool judgment: minimize raw reads, choose the smallest useful retrieval path, and persist decisions that matter."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: always
-  inputs: [codebase]
-  outputs: [search-results, analysis, knowledge]
-  relatedSkills: [session-handoff, present]
----
-
-# @vpxa/aikit - AI Kit
-
-Use AI Kit as compression, memory, validation, and coordination layer. Each call should reduce uncertainty or token load.
-
-## Session Loop
-
-Start:
-1. status({ includePrelude: true }).
-2. If prelude.workspaceCore is null → run \`onboard({ path, mode: 'generate' })\`, then \`status({ includePrelude: true })\` again.
-3. **L0 session start**: Fetch \`aikit://l0/workspace-core\` resource (full card) or \`status({ includePrelude: true })\` (compact summary). Extract workspace shape, package map, tool surfaces, key entry points, constraints, and known pitfalls before broad retrieval. If L0 answers enough, skip \`scope_map\`/wide \`search\`. If a flow is active, workflow card loaded via flow context. ≤ 2,100 tokens.
-4. search({ query: "SESSION CHECKPOINT", origin: "curated" }).
-5. flow({ action: 'status' }) when active flow may exist — use L1 snapshot before broad retrieval.
-6. scope_map({ task }) only when L0 + checkpoint do not identify a narrow workset.
-
-During:
-- Prefer search/file_summary/digest/symbol/trace/graph over raw reads.
-- Use stash for temporary findings; knowledge for durable decisions.
-- Run blast_radius before shared/public edits.
-- Validate with check + relevant test_run.
-
-End:
-- reindex after structural changes.
-- produce_knowledge for durable project updates.
-- session_digest({ persist: true }).
-- knowledge remember session checkpoint with done/decisions/next/blockers.
-
-## Retrieval Ladder — Layered (L0-L3)
-
-| Layer | Need | Tool |
-|-------|------|------|
-| **L0** | Session briefing (after onboard) | Resource \`aikit://l0/workspace-core\` (full card) or \`status({ includePrelude: true })\` (compact summary). Run \`onboard\` first if card missing. Consume before broad scans. |
-| **L0** | Architecture overview | \`architecture\` briefing card |
-| **L0** | Known issues | \`known-issues\` briefing card |
-| **L0** | Flow-specific context | \`workflow:<flow>\` briefing card |
-| **L1** | Active flow state | \`knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })\` |
-| **L2** | Prior decisions/conventions | \`search\` / \`knowledge\` |
-| **L2** | File structure | \`file_summary({ files, tier: 'T1' })\` |
-| **L2** | Exact relevant section | \`file_summary({ files, tier: 'T2' })\` |
-| **L2** | Many files | \`digest\` |
-| **L2** | Symbol defs/refs | \`symbol\` |
-| **L2** | Call/data flow | \`trace\` |
-| **L2** | Module/import relationships | \`graph\` |
-| **L2** | Impact | \`blast_radius\` |
-| **L2** | Type/lint/test | \`check\` / \`test_run\` |
-| **L3** | Evidence, provenance, conflict review | \`search\` with \`knowledge({ action: 'lesson' })\` — focused only |
-| **General** | Tool choice unknown | \`list_tools\` → \`search_tools\` → \`describe_tool\` |
-
-Raw read_file only for exact edit lines after compressed tools identify target.
-
-## Context Reuse
-
-Before rereading path/topic, search exact path/topic first. If response gives ctxc_..., reuse with file_summary({ ref }) or file_summary({ ref, query }). Use enrich: true on tools that support it after first pass.
-
-## Patterns
-
-- New area: search -> scope_map -> file_summary -> graph/trace -> stash.
-- Bug: search -> symbol -> trace -> file_summary -> test/check -> remember.
-- Refactor shared code: blast_radius -> checkpoint -> file_summary -> rename/codemod -> check -> test_run.
-- Web/API: web_search/web_fetch/http; browser only when JS/auth interaction needed. Browser snapshots now use ~200-400 tokens, making them practical for quick page state checks.
-
-## Memory Discipline
-
-Store only high-signal facts:
-- Decisions and rationale.
-- Conventions that constrain future work.
-- Non-obvious root causes and fixes.
-- Checkpoints and blockers.
-
-Review decayed/stale entries periodically with knowledge({ action: 'flagged' }). Use lesson actions for reusable engineering lessons; load lesson-learned after implementation/review work.
-
-## Flow + FORGE
-
-Flows guide multi-step work. Read active step before acting. FORGE handles tiering/evidence/gates; load references only when main skill is too thin.
-
-### Layered Knowledge Protocol
-- **L0** → Generated briefing cards: load \`workspace-core\` at session start via \`aikit://l0/workspace-core\` resource (full card, live-updated) or \`status({ includePrelude: true })\` (compact summary). Requires \`onboard()\` first — if card null, run \`onboard\` before session start. Consume L0 as the default workspace map before \`search\`, \`scope_map\`, \`digest\`, or repeated \`file_summary\`; add \`workflow:<flow>\` if flow active, or one task card if no flow. Use \`file_summary({ tier: 'T1' })\` for structure, or \`file_summary({ tier: 'T2', query })\` for content only after L0 narrows the workset. Token-bounded.
-- **L1** → Flow working context. Withdraw before dispatch; reuse before broad retrieval.
-- **L2** → Canonical curated knowledge. Retrieve on demand; never preload broadly.
-- **L3** → Evidence/auto-knowledge. Inspect only for provenance, conflict, or promotion assessment.
-
-Reference docs:
-- references/coordination.md - queue, lanes, stash, checkpoints, signaling.
-- references/forge-protocol.md - tiering, evidence, gates.
-- references/search-patterns.md - search, trace, graph, compression recipes.
-- references/layered-knowledge-protocol.md - L0-L3 operating policy and hot path.
-
-## Self-Dogfooding
-
-When developing AI Kit itself: regenerate scaffold output, run focused checks, rebuild, then reindex so future searches see new shape.
-`},{file:`references/coordination.md`,content:`# Coordination
+var e=[{file:`SKILL.md`,content:"---\nname: aikit\ndescription: \"Use the @vpxa/aikit AI Kit MCP server for codebase search, context compression, validation, and persistent memory. Load at session start or before using aikit_* tools. This skill teaches tool judgment: minimize raw reads, choose the smallest useful retrieval path, and persist decisions that matter.\"\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [session-handoff, present]\n---\n\n# @vpxa/aikit - AI Kit\n\nUse AI Kit as compression, memory, validation, and coordination layer. Each call should reduce uncertainty or token load.\n\n## Communicating With the User\n\n**Use `present({ schemaVersion: 1, title, blocks })` for ALL non-trivial output.** This is the preferred way to show summaries, results, evidence maps, task plans, reviews, comparisons, dashboards, charts, timelines, and batch results to the user. Plain text is only for 1-2 sentence status updates or simple questions. The `present` tool renders rich, structured output that the user can interact with.\n\n## Session Loop\n\nStart:\n1. status({ includePrelude: true }).\n2. If `onboarded` is false or `prelude.onboardContext` / `structuredContent.onboard_context` is null → run `onboard({ path, mode: 'generate' })`, then `status({ includePrelude: true })` again.\n3. If `onboard_context.freshness.status` is `stale` or `unknown`, or `nextAction.kind === \"update_onboard\"` → run `onboard({ path, update: true })`, then `status({ includePrelude: true })` again.\n4. **Workspace context start**: Extract workspace skill + fresh onboard context from status: `workspace_skill.uri`, `prelude.workspaceSkillResource`, `onboard_context.freshness`, `onboard_context.packageMap`, `onboard_context.architecture`, and `onboard_context.recommendedReadOrder`. Read `aikit://skill/SKILL.md` when full repo-specific guidance is needed. Use fresh onboard context before broad retrieval. ≤ 2,100 tokens.\n5. search({ query: \"SESSION CHECKPOINT\", origin: \"curated\" }).\n6. flow({ action: 'status' }) when active flow may exist — use L1 snapshot before broad retrieval.\n7. scope_map({ task }) only when workspace context + checkpoint do not identify a narrow workset.\n\nDuring:\n- Prefer search/file_summary/digest/symbol/trace/graph over raw reads.\n- Use stash for temporary findings; knowledge for durable decisions.\n- Run blast_radius before shared/public edits.\n- Validate with check + relevant test_run.\n\nEnd:\n- reindex after structural changes.\n- produce_knowledge for durable project updates.\n- session_digest({ persist: true }).\n- knowledge remember session checkpoint with done/decisions/next/blockers.\n\n## Retrieval Ladder — Layered (Workspace Context + L1-L3)\n\n> This table maps knowledge layers to tool needs. For the canonical quick-reference tool decision table, see `aiKitToolPreference()` in protocols.mjs.\n\n| Layer | Need | Tool |\n|-------|------|------|\n| **Workspace Context** | Workspace skill + fresh onboard context | `status({ includePrelude: true })`; read `aikit://skill/SKILL.md` only when full guidance is needed. Run `onboard({ path, mode: 'generate' })` if `onboard_context` is missing; run `onboard({ path, update: true })` if `onboard_context.freshness.status` is `stale` or `unknown`. Consume fresh context before broad scans. |\n| **Workspace Context** | Architecture overview | `status({ includePrelude: true }).onboard_context.architecture`, then onboard `diagram.md` / `domains.md` when deeper detail is needed |\n| **Workspace Context** | Package map / repo shape | `status({ includePrelude: true }).onboard_context.packageMap`, then onboard `structure.md` / `dependencies.md` |\n| **Flow Context** | Flow-specific context | L1 flow snapshot via `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })` |\n| **L1** | Active flow state | `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })` |\n| **L2** | Prior decisions/conventions | `search` / `knowledge` |\n| **L2** | File structure | `file_summary({ files, tier: 'T1' })` |\n| **L2** | Exact relevant section | `file_summary({ files, tier: 'T2' })` |\n| **L2** | Many files | `digest` |\n| **L2** | Symbol defs/refs | `symbol` |\n| **L2** | Call/data flow | `trace` |\n| **L2** | Module/import relationships | `graph` |\n| **L2** | Impact | `blast_radius` |\n| **L2** | Type/lint/test | `check` / `test_run` |\n| **L3** | Evidence, provenance, conflict review | `search` with `knowledge({ action: 'lesson' })` — focused only |\n| **General** | Tool choice unknown | `list_tools({ intent: \"<task>\" })` (use intent param for planner-ranked results) or `search({ query: \"tool to <do X>\" })` |\n\nRaw read_file only for exact edit lines after compressed tools identify target.\n\n## Context Reuse\n\nBefore rereading path/topic, search exact path/topic first. If response gives ctxc_..., reuse with file_summary({ ref }) or file_summary({ ref, query }). Use enrich: true on tools that support it after first pass.\n\n## Patterns\n\n- New area: search -> scope_map -> file_summary -> graph/trace -> stash.\n- Bug: search -> symbol -> trace -> file_summary -> test/check -> remember.\n- Refactor shared code: blast_radius -> checkpoint -> file_summary -> rename/codemod -> check -> test_run.\n- Web/API: web_search/web_fetch/http; browser only when JS/auth interaction needed. Browser snapshots now use ~200-400 tokens, making them practical for quick page state checks.\n\n## Memory Discipline\n\nStore only high-signal facts:\n- Decisions and rationale.\n- Conventions that constrain future work.\n- Non-obvious root causes and fixes.\n- Checkpoints and blockers.\n\nReview decayed/stale entries periodically with knowledge({ action: 'flagged' }). Use lesson actions for reusable engineering lessons; load lesson-learned after implementation/review work.\n\n## Flow + FORGE\n\nFlows guide multi-step work. Read active step before acting. FORGE handles tiering/evidence/gates; load references only when main skill is too thin.\n\n### Layered Knowledge Protocol\n- **Workspace Context** → Workspace skill + fresh onboard context: load via `status({ includePrelude: true })`. Requires `onboard()` first — if `onboard_context` is null, run `onboard`; if `onboard_context.freshness.status` is `stale` or `unknown`, run `onboard({ path, update: true })`. Consume the workspace skill preview/resource pointer and fresh onboard package map/architecture/read-order before `search`, `scope_map`, `digest`, or repeated `file_summary`. Use `file_summary({ tier: 'T1' })` for structure, or `file_summary({ tier: 'T2', query })` for content only after status/onboard context narrows the workset. Token-bounded.\n- **L1** → Flow working context. Withdraw before dispatch; reuse before broad retrieval.\n- **L2** → Canonical curated knowledge. Retrieve on demand; never preload broadly.\n- **L3** → Evidence/auto-knowledge. Inspect only for provenance, conflict, or promotion assessment.\n\nReference docs:\n- references/coordination.md - queue, lanes, stash, checkpoints, signaling.\n- references/forge-protocol.md - tiering, evidence, gates.\n- references/search-patterns.md - search, trace, graph, compression recipes.\n- references/layered-knowledge-protocol.md - workspace context + L1-L3 operating policy and hot path.\n\n## Self-Dogfooding\n\nWhen developing AI Kit itself: regenerate scaffold output, run focused checks, rebuild, then reindex so future searches see new shape.\n"},{file:`references/coordination.md`,content:`# Coordination
 
 Use coordination tools when work is parallel, long-running, or easy to repeat incorrectly.
 
@@ -194,53 +93,4 @@ file_summary (T1=structure, T2=content) or digest (multi-file synthesis). Read_f
 ## Rule of Thumb
 
 If you are about to read raw code, ask whether the answer is really about structure, relevance, flow, or relationships. AI Kit has a smaller tool for each of those.
-`},{file:`references/layered-knowledge-protocol.md`,content:`# Layered Knowledge Protocol
-
-AI Kit delivers knowledge through four layers:
-
-## L0 — Generated Briefing Cards
-
-Fast, compact task setup loaded at session start.
-
-- **Auto-injected**: \`workspace-core\` (800-1200 tokens) — available via \`status({ includePrelude: true })\` after \`onboard()\` generates the card. If null → run \`onboard({ path, mode: 'generate' })\` then retry status.
-- **If flow active**: Load \`workflow:<flow>\` (500-900 tokens) via flow start refs (replaces task card)
-- **If no flow**: Optionally load one task card via \`file_summary\`
-- **Budget**: ≤ 2,100 tokens total
-- **Storage**: Generated workspace cache (path from server config)
-- **Card families**: \`workspace-core\`, \`architecture\`, \`testing-release\`, \`known-issues\`, \`workflow:<flow>\`
-- Session-start budget: workspace-core (800-1200 tokens) + 1 additional card ≤ 2,100 tokens total
-- Generated cache, not canonical — rebuildable from L2 canonical sources
-
-## L1 — Flow Working Context
-
-Active run state and role-filtered dispatch context.
-
-- Withdraw via \`knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>', budget: 6000 })\`
-- Use withdrawn refs before calling \`file_summary\`, \`scope_map\`, \`blast_radius\`, or \`search\`
-- Each step has a declared \`contextProfile\` (implementer, reviewer, researcher, documenter, debugger)
-
-## L2 — Canonical Curated Knowledge
-
-Durable workspace archive managed by CuratedKnowledgeManager.
-
-- Retrieve on demand via \`search()\` or \`knowledge({ action: 'read' })\`
-- Never preload broadly at session start when L1 refs are already supplied
-- Markdown is the canonical form; vector/FTS indexes are derived
-
-## L3 — Evidence Archive
-
-High-volume observations, proofs, failures, and runtime traces.
-
-- Never auto-injected into session or step context
-- Inspect only for provenance verification, conflict review, or promotion assessment
-- Auto-knowledge extractors write to L3; they cannot navigate flow state or promote
-
-## Retrieval Order
-
-1. L0 (loaded cards at session start)
-2. L1 (flow withdrawal when active)
-3. L2 (on-demand canonical knowledge)
-4. L3 (focused evidence retrieval only)
-
-No active flow → keep L1 absent; use L0 + on-demand L2; turn-local context only.
-`}];export{e as default};
+`},{file:`references/layered-knowledge-protocol.md`,content:"# Layered Knowledge Protocol\n\nAI Kit delivers knowledge through startup workspace context plus L1-L3:\n\n## Workspace Context — Workspace Skill + Onboard Context\n\nFast, compact task setup loaded at session start.\n\n- **Auto-injected/discoverable**: `status({ includePrelude: true })` returns workspace skill preview/resource pointer and `onboard_context` after `onboard()` generates artifacts. If `onboard_context` is null → run `onboard({ path, mode: 'generate' })` then retry status. If `onboard_context.freshness.status` is `stale` or `unknown` → run `onboard({ path, update: true })` then retry status.\n- **Full workspace skill**: Read `aikit://skill/SKILL.md` only when full conventions, commands, or lessons are needed.\n- **Onboard files**: Use `onboard_context.recommendedReadOrder` and paths for `synthesis-guide.md`, `structure.md`, `dependencies.md`, `diagram.md`, `domains.md`, `entry-points.md`, and `code-map.md`.\n- **If flow active**: Load L1 via `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>' })` and reuse supplied refs before broad retrieval.\n- **If no flow**: Optionally load one task card via `file_summary`\n- **Budget**: ≤ 2,100 tokens total\n- **Storage**: Workspace skill plus generated onboard artifacts under the status `onboardDir`\n- Generated workspace context, not canonical — rebuildable from L2 canonical sources and current repo analysis\n\n## L1 — Flow Working Context\n\nActive run state and role-filtered dispatch context.\n\n- Withdraw via `knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>', budget: 6000 })`\n- Use withdrawn refs before calling `file_summary`, `scope_map`, `blast_radius`, or `search`\n- Each step has a declared `contextProfile` (implementer, reviewer, researcher, documenter, debugger)\n\n## L2 — Canonical Curated Knowledge\n\nDurable workspace archive managed by CuratedKnowledgeManager.\n\n- Retrieve on demand via `search()` or `knowledge({ action: 'read' })`\n- Never preload broadly at session start when L1 refs are already supplied\n- Markdown is the canonical form; vector/FTS indexes are derived\n\n## L3 — Evidence Archive\n\nHigh-volume observations, proofs, failures, and runtime traces.\n\n- Never auto-injected into session or step context\n- Inspect only for provenance verification, conflict review, or promotion assessment\n- Auto-knowledge extractors write to L3; they cannot navigate flow state or promote\n\n## Retrieval Order\n\n1. Workspace context (workspace skill + onboard context at session start)\n2. L1 (flow withdrawal when active)\n3. L2 (on-demand canonical knowledge)\n4. L3 (focused evidence retrieval only)\n\nNo active flow → keep L1 absent; use workspace context + on-demand L2; turn-local context only.\n"}];export{e as default};

package/scaffold/dist/definitions/skills/browser-use.mjs

@@ -450,7 +450,7 @@ browser({ action: 'eval', pageId, code: 'localStorage.getItem("authToken")' })
 | Console + eval hybrid | \`console\` | consoleSubAction: get, expression (evaluates JS) |
 | Compare changes | \`diff\` | (compares to previous snapshot) |
 
-For full parameter details: \`describe_tool('browser')\`
+For full parameter details: \`list_tools({ intent: "browser automation" })\` or check the tool's schema
 
 ## Principles
 

package/scaffold/dist/definitions/skills/c4-architecture.mjs

@@ -141,15 +141,15 @@ Default: Context + Container. Add Component only for a complex container and a c
 2. Identify audience and decision the diagram supports.
 3. **Gather evidence with AI Kit - check onboard cache FIRST:**
    a. **Check onboard cache:**
-      - Run status({ includePrelude: true }) - if workspaceCore shows onboard data available:
-        - Read cache from ~/.aikit/workspaces/<hash>/onboard/:
+     - Run status({ includePrelude: true }) - if structuredContent.onboard_context is present and onboard_context.freshness.status == "fresh":
+        - Use onboard_context.recommendedReadOrder and read cache files from onboardDir:
           - structure.md - module tree, layers, directory shape
           - dependencies.md - internal/external dependency graph
+          - diagram.md / domains.md - architecture boundaries
           - symbols.md - exported symbols, type signatures
           - entry-points.md - API surface, CLI entry points
-        - Freshness: cache fresh if status().onboarded == true and index recent.
-          For finer control: compare git diff --stat pending change count.
-          Default: <50 pending changes -> serve from cache | >=50 -> refresh.
+        - Freshness: trust status().onboard_context.freshness.status, not timestamps inferred by the model.
+          If freshness is stale/unknown, run onboard({ path: ".", update: true }) and status again before using onboard files.
    b. **Use cache data for C4:**
       - Extract layers from structure analysis (layer-detector classifications)
       - Extract modules/containers from directory tree

package/scaffold/dist/definitions/skills/docs.mjs

@@ -155,8 +155,9 @@ Detailed workflow for acquiring and documenting project knowledge into \`docs/ar
 
 ### Phase 1: Scan and Read Intent (IR-aware)
 
-Pre-flight — load L0 + L1 context:
+Pre-flight — load workspace context + L1 context:
 - \`status({ includePrelude: true })\`
+- If \`onboard_context\` is missing, run \`onboard({ path: ".", mode: "generate" })\`; if \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`, run \`onboard({ path: ".", update: true })\`; then status again.
 - \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\`
 
 Then check \`docs/.docs-state.json\` (the Committed Docs IR):
@@ -789,7 +790,7 @@ Use this template for any generated section that includes factual claims:
 
 ### Update Mode Template (\`docs/.docs-state.json\`)
 
-Committed state file for incremental documentation updates. L0 regeneratable cache,
+Committed state file for incremental documentation updates. Workspace-context regeneratable cache,
 committed to git so clones have warm cache.
 
 **Design: extends existing schema (backward compatible).** NO parallel \`_lastSynced\` block.
@@ -798,7 +799,7 @@ Adds \`signatureHash\`, \`contractHash\` (optional), and \`syncedAt\` to the exi
 \`\`\`json
 {
   "version": "1.1",
-  "layer": "l0",
+  "layer": "workspace-context",
   "timestamp": "ISO-8601",
   "lastCommitSha": "git rev-parse HEAD of last documented commit",
 
@@ -1732,7 +1733,7 @@ Orchestrate phased documentation generation with document-type-specific outputs
 
 Before executing the generation pipeline, load available context from across the infrastructure:
 
-- L0: \`status({ includePrelude: true })\` — workspace context (lessons, conventions)
+- Workspace context: \`status({ includePrelude: true })\` — workspace skill, onboard context, lessons, conventions
 - L1: \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\` — flow context
 - L2: \`search({ origin: 'curated' })\` + \`knowledge({ action: 'lesson', subAction: 'list-lessons' })\` — curated knowledge
 - L3: Evidence archive (provenance only, never auto-injected)
@@ -1741,8 +1742,9 @@ Before executing the generation pipeline, load available context from across the
 
 ### Phase 1 — Docs IR Producer (deterministic)
 
-Pre-flight: load L0 + L1 context from infrastructure.
-- \`status({ includePrelude: true })\` — L0 prelude
+Pre-flight: load workspace context + L1 context from infrastructure.
+- \`status({ includePrelude: true })\` — workspace skill + onboard context prelude
+- If \`onboard_context\` is missing, generate onboard. If \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`, update onboard, then status again.
 - \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\` — L1 flow context
 
 Step 1: Check \`docs/.docs-state.json\` (the Committed Docs IR):
@@ -1810,7 +1812,7 @@ Step 2: Doc inventory (always runs, not cached):
 - \`blast_radius({ files: changedFiles })\` — stale doc detection
 
 The IR (\`docs/.docs-state.json\`) stores:
-- \`version\` + \`layer: "l0"\` (regeneratable cache, not curated; committed to git)
+- \`version\` + \`layer: "workspace-context"\` (regeneratable cache, not curated; committed to git)
 - \`lastCommitSha\` (committed = warm clones, no cold starts)
 - \`onboardRef\` (pointer to onboard cache, NO duplicated analysis data)
 - \`sourceFiles\` (per-file contentHash, signatureHash, contractHash, syncedAt, changeClass)
@@ -3304,7 +3306,7 @@ Each doc type uses specific tools. Load the tools before generating.
 Documentation is the bridge between AI Kit's layered knowledge and human readers.
 
 \`\`\`
-L0 (Briefing Cards) ─→ docs/ — Human-readable summaries of workspace state
+Workspace skill + onboard context ─→ docs/ — Human-readable summaries of workspace state
        │
 L1 (Flow Context) ───→ docs/architecture/flows/ — Flow design decisions → durable docs
        │                      │
@@ -3315,7 +3317,7 @@ L3 (Evidence Archive) ──→ docs/reference/ — Verified claims with tool re
 
 | Layer | Docs Role | Action |
 |---|---|---|
-| L0 | Regenerate via briefing-card-compiler when topics change | Card invalidation trigger |
+| Workspace context | Regenerate via onboard/status/skill compiler when topics change | Onboard + workspace skill freshness trigger |
 | L1 | Withdraw flow context, extract decisions/artifacts → docs/ | \`knowledge({action:'withdraw',scope:'flow'})\` |
 | L2 | Candidate for promotion from verified docs | Consolidation adjudication |
 | L3 | Evidence chain for every doc claim | \`knowledge({action:'lesson'})\` + receipts |
@@ -3439,7 +3441,7 @@ Report: "No documentation updates needed" + brief reason.
     - If \`syncedAt\` missing on doc → treat as stale (conservative), emit warning
     - If no recent lessons match → continue silently
     - Session dedup: maintain \`Set<string>\` of checked topic+entry IDs per session; skip if already checked
-2. **Load layered context**: \`status({ includePrelude: true })\` → L0. \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\` → L1.
+2. **Load layered context**: \`status({ includePrelude: true })\` → fresh workspace context (generate/update onboard first if missing/stale/unknown). \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\` → L1.
 3. Gather intent/evidence from flow artifacts, git diff, blast_radius, produce_knowledge, analyze, changelog, or search.
 4. Classify target docs with Diataxis or extended doc type table.
 5. Map changed capability to doc action.

package/scaffold/dist/definitions/skills/multi-agents-development.mjs

@@ -467,8 +467,8 @@ Every subagent prompt includes:
 2. Goal + acceptance criteria.
 3. Files/boundary + do-not-touch list.
 4. Compressed context: relevant snippets, conventions, decisions, active flow paths.
-5. **L0/L1 refs**: Include \`selectedCardRefs\`, \`retrievedRefs\`, and L1 \`FlowContextSnapshotV1\` fields relevant to the role.
-6. **Hard rule — no broad card reload**: Subagent must reuse supplied refs first. Must NOT independently reload \`workspace-core\`, architecture, testing-release, or known-issues cards when the dispatch already carries applicable refs.
+5. **Workspace/L1 refs**: Include supplied workspace skill/onboard context, \`retrievedRefs\`, and L1 \`FlowContextSnapshotV1\` fields relevant to the role.
+6. **Hard rule — no broad rediscovery**: Subagent must reuse supplied refs first. Must NOT independently rediscover workspace basics or reload architecture context when the dispatch already carries applicable refs.
 7. Constraints: skills to load, libraries/patterns, no present, no flow advance.
 8. FORGE: tier, task_id, evidence claims to add.
 9. Validation: expected check, test_run, or reason skipped.
@@ -480,10 +480,10 @@ Use references/implementer-prompt.md for implementation dispatches and reference
 
 Before dispatch:
 - knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>', budget: 6000 })
-- Include \`selectedCardRefs\` (L0 card refs) and \`retrievedRefs\` (from L1) in the dispatch envelope.
+- Include supplied workspace/onboard context refs and \`retrievedRefs\` (from L1) in the dispatch envelope.
 - Add only missing snippets with file_summary/digest.
 - Paste context into dispatch; do not tell subagent to rediscover basics.
-- **Hard rule**: Subagent must reuse supplied L0/L1 refs before broad retrieval. Block if it reloads \`workspace-core\` or architecture cards independently.
+- **Hard rule**: Subagent must reuse supplied workspace/L1 refs before broad retrieval. Block if it independently rediscovers workspace basics already present in the dispatch.
 
 After subagent work:
 - Store durable findings with knowledge({ action: 'remember', scope: 'flow', ... }).

package/scaffold/dist/definitions/skills/orchestrator.mjs

@@ -14,19 +14,45 @@ metadata:
 
 YOU MUST FOLLOW THIS PROTOCOL ON EVERY TASK. You are an orchestrator, not an implementer.
 
-## Hard Rules
+## Priority Ladder (conflict resolution order)
 
-**RULE 1 — Decompose everything.** Every task gets a TODO list via \`TodoWrite\` in your first response. Break it into independent, parallelizable subtasks.
+1. Safety + user approval.
+2. Tool/bootstrap correctness.
+3. Delegation boundary.
+4. Evidence + verification.
+5. Context budget.
+6. Terse communication.
 
-**RULE 2 — Delegate, never implement.** For every subtask, spawn a sub-agent via \`Task()\`. If you catch yourself about to edit a file directly, STOP. Spawn a sub-agent.
+## MANDATORY FIRST ACTIONS (session start)
 
-**RULE 3 — Wait and synthesize.** After all sub-agents complete, consolidate their outputs. Only then deliver the final result to the user.
+Execute these before ANY other work:
+1. \`flow({ action: 'status' })\` — Check active flow state.
+2. \`status({ includePrelude: true })\` — Load workspace skill summary plus onboard context.
+3. If \`onboarded\` is false or \`onboard_context\` is null → \`onboard({ path: ".", mode: "generate" })\` first, then status again.
+4. If \`onboard_context.freshness.status\` is \`stale\` or \`unknown\`, or \`nextAction.kind === "update_onboard"\` → \`onboard({ path: ".", update: true })\` first, then status again.
+5. \`skill({ name: 'aikit' })\` — Load the AI Kit skill for tool routing, retrieval ladder, and communication patterns.
 
-**RULE 4 — No direct coding.** You NEVER write, edit, or create files yourself. That is sub-agent work. If you think you need to write code, you need a sub-agent.
+On platforms without native \`skill()\` support, the AI Kit instructions are already in your system prompt via other channels.
 
-**RULE 5 — Parallel fan-out.** Subtasks without data dependencies MUST run in parallel. Do not serialize independent work.
+**Workspace skill:** \`status({ includePrelude: true })\` gives you the compact summary. For full content (conventions, commands, lessons): read \`aikit://skill/SKILL.md\` MCP resource on demand.
 
-**RULE 6 — Full cycle per phase.** Each phase (Plan → Implement → Review → Verify) gets its own delegation cycle. Do not skip phases.
+## User-Facing Presentation
+
+Use \`present({ schemaVersion: 1, title, blocks })\` for almost every substantive response to the user. If the response is more than 3 sentences, contains a list/table/checklist/plan/status/verdict/summary/progress/evidence map, or asks for approval/choice, use \`present\`. Prefer \`present\` even without actions for read-only summaries; add \`actions\` for approvals, confirmations, and selections. Plain text only for tiny status updates or one simple question that fits in 3 short sentences.
+
+## Delegation Rules
+
+**RULE 1 — Decompose everything.** Break every task into independent, parallelizable subtasks.
+
+**RULE 2 — Delegate, never implement.** For every subtask, spawn a sub-agent via Task(). If you catch yourself about to edit a file directly, STOP. Spawn a sub-agent.
+
+**RULE 3 — Wait and synthesize.** After all sub-agents complete, consolidate their outputs.
+
+**RULE 4 — No direct coding.** You NEVER write, edit, or create files yourself. That is sub-agent work.
+
+**RULE 5 — Parallel fan-out.** Subtasks without data dependencies MUST run in parallel.
+
+**RULE 6 — Full cycle per phase.** Each phase (Plan → Implement → Review → Verify) gets its own delegation cycle.
 
 ## Exceptions (ONLY these)
 
@@ -35,4 +61,20 @@ You MAY write code directly ONLY when:
 - You are fixing a sub-agent's output (typo, quick patch)
 - There is no sub-agent available for the required skill
 
-When in doubt, delegate. When unsure, spawn an extra sub-agent.`}];export{e as default};
+## Dispatch Envelope (every subagent prompt)
+
+Every subagent dispatch MUST include:
+1. Agent + Goal — specialist name, acceptance criteria
+2. Files + Boundary — target files, do-not-touch list
+3. Arch Context — compress with file_summary/digest before including
+4. Prior Knowledge — search lessons + conventions
+5. FORGE — tier, task_id, evidence requirements
+6. Flow Context — withdraw context FIRST, reuse refs
+7. Constraints — no present tool, no flow advance, stay in scope
+8. Return contract — DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED (≤200 words)
+
+## Emergency Recovery
+
+STOP → ASSESS (\`git diff --stat\` + \`check({})\`) → CONTAIN (1-3 files: fix, widespread: stash) → RECOVER (stash first) → DOCUMENT (remember what went wrong).
+
+Max 2 retries per task. Same failure twice → stop loop, change plan.`}];export{e as default};