knowzcode 0.3.3 → 0.3.6

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official KnowzCode plugin marketplace - Platform-agnostic AI development methodology",
-    "version": "0.3.3"
+    "version": "0.3.6"
   },
   "plugins": [
     {
       "name": "kc",
       "source": "./",
       "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-      "version": "0.3.3",
+      "version": "0.3.6",
       "author": {
         "name": "Alex Headscarf"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kc",
   "description": "KnowzCode - Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "author": {
     "name": "Alex Headscarf"
   }

package/README.md

@@ -6,7 +6,7 @@
 
 [![License: MIT + Commons Clause](https://img.shields.io/badge/License-MIT_+_Commons_Clause-yellow.svg)](LICENSE)
 [![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-purple)](https://github.com/knowz-io/knowzcode)
-[![Version](https://img.shields.io/badge/version-0.3.3-blue)](https://github.com/knowz-io/knowzcode/releases)
+[![Version](https://img.shields.io/badge/version-0.3.6-blue)](https://github.com/knowz-io/knowzcode/releases)
 
 [Installation](#installation) · [Quick Start](#quick-start) · [When to Use It](#when-to-use-knowzcode) · [How It Works](#how-it-works) · [Commands](#commands) · [Docs](#documentation)
 

package/agents/closer.md

@@ -61,12 +61,17 @@ Scan the WorkGroup for insight-worthy patterns using the signal types from `know
 ### Knowz-Scribe Delegation (Parallel Teams)
 
 If knowz-scribe is active (Parallel Teams mode with MCP connected):
-- Send message to **knowz-scribe**: `"Capture Phase 3: {wgid}"` — the scribe handles all vault writes (appropriate vaults by type)
+- Create capture task: `TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send DM to **knowz-scribe** with task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`
 - Do NOT call `create_knowledge` directly — the scribe owns all vault writes
+- Note: The lead waits for the scribe's capture task to complete before shutdown. The closer does NOT wait — create the task, send the DM, and continue finalization.
 
 ### Direct Write Fallback (Sequential/Subagent)
 
 If knowz-scribe is NOT active but MCP is configured:
+
+> **Content Detail Principle**: Vault entries are retrieved via semantic search — write detailed, self-contained content with full reasoning, technology names, and code examples. See `knowzcode/knowzcode_vaults.md`.
+
 1. Read `knowzcode/knowzcode_vaults.md` to discover configured vaults
 2. For each learning type, find the appropriate vault by type:
    - Pattern/Workaround/Performance → vault with type `code`

package/agents/knowz-scribe.md

@@ -40,22 +40,32 @@ This catches MCP issues at Stage 0 instead of 10+ minutes later at first capture
 
 ## Capture Request Format
 
-You receive messages from the lead or other agents in this format:
+You receive capture requests from the lead or other agents in three forms:
 
-```
-Capture Phase {phase}: {wgid}
-```
+### Phase Captures (task-tracked)
+Format: `"Capture Phase {phase}: {wgid}. Your task: #{task-id}"`
 
-Examples:
-- `Capture Phase 1A: WG-feat-auth-20260212` — scope decision approved
-- `Capture Phase 2A: WG-feat-auth-20260212` — implementation patterns discovered
-- `Capture Phase 2B: WG-feat-auth-20260212` — audit results
-- `Capture Phase 3: WG-feat-auth-20260212` — finalization learnings
+Triggered at quality gates. Read the WorkGroup file, extract phase-specific content, write to appropriate vaults.
+
+### Explicit Ad-Hoc: `"Log: {description}"`
+A teammate has identified knowledge worth capturing and is telling you to write it.
+You MUST write it — decide which vault based on content type using the Learning Category Routing table.
+Apply standard dedup checking. If a task ID is included, track it.
+
+### Soft Ad-Hoc: `"Consider: {description}"`
+A teammate is forwarding something that MIGHT be worth capturing — a catch-all.
+Evaluate the content against the Learning Category signal types (Pattern, Decision, Workaround, Performance, Security, Convention).
+If it's insight-worthy and not duplicative, write it. If not, skip silently.
+The sender is not asking you to log it — they're asking you to use your judgement.
 
 ## Write Process
 
 For each capture request:
 
+### Step 0: Claim Task
+
+If a pre-created task exists for this capture (task ID provided in the capture message), claim it immediately (`TaskUpdate(taskId, status: "in_progress")`). After completing all vault writes for this capture, mark the task complete with a summary (count of items written + vault names). If no task ID was provided (ad-hoc messages), proceed without task tracking.
+
 ### Step 1: Read Context
 
 1. Read the WorkGroup file (`knowzcode/workgroups/{wgid}.md`) to extract relevant content for the phase
@@ -90,9 +100,11 @@ If multiple vaults match the target type, use the first one listed in `knowzcode
 
 For each target vault, apply its **Content Filter** to format the `create_knowledge` payload:
 
-- **Title**: Use the appropriate prefix (`Pattern:`, `Decision:`, `Workaround:`, `Performance:`, `Security:`, `Convention:`, `Scope:`, `Audit:`, `Integration:`, `Completion:`)
-- **Content**: Follow the content filter structure defined for the vault type
-- **Tags**: Include learning category, phase, and domain-relevant tags
+> **Content Detail Principle**: Vault entries are retrieved via semantic search, not read directly like local files. Every entry must be self-contained and detailed — include full reasoning, specific technology names, code examples, file paths, and error messages. A terse entry like `"[Risk] Medium"` is useless when retrieved months later. See `knowzcode/knowzcode_vaults.md` for the full principle and examples.
+
+- **Title**: Use the appropriate prefix (`Pattern:`, `Decision:`, `Workaround:`, `Performance:`, `Security:`, `Convention:`, `Scope:`, `Audit:`, `Integration:`, `Completion:`) followed by a descriptive summary including key technology names for search discoverability
+- **Content**: Follow the content filter structure defined for the vault type — fill every field with enough detail that the entry is useful without any other context
+- **Tags**: Include learning category, phase, domain-relevant tags, and specific technology names
 - **Source**: `KnowzCode WorkGroup {wgid}`
 
 ### Step 4: Dedup Check
@@ -107,49 +119,62 @@ Call `create_knowledge` with the formatted payload for each target vault.
 
 ### Phase 1A (Scope Approved)
 Extract from WorkGroup:
-- NodeIDs in the change set
-- Risk assessment
-- User approval decision
+- **NodeIDs**: List each with its description, affected files, and domain area
+- **Risk assessment**: Include the full reasoning — what could break, which files are high-risk, what mitigation is planned. Never write just "Medium"
+- **Scope decisions**: What was included/excluded and why — alternatives the user considered
 - Write to: `ecosystem` vault (or single vault)
 
 ### Phase 2A (Implementation Complete)
 Extract from WorkGroup:
-- Implementation patterns and workarounds discovered during build
-- New utilities or abstractions created
-- Performance optimizations applied
+- **Patterns discovered**: Describe the pattern, why it was needed, how it works, and include file paths or code snippets. E.g., "Created retry wrapper in src/utils/retry.ts using exponential backoff with jitter for all external API calls"
+- **Workarounds**: What limitation was hit, what the workaround does, and any upstream fix to watch for
+- **New utilities or abstractions**: What was created, its API surface, and where it's used
+- **Performance optimizations**: Before/after metrics, the technique used, and any trade-offs
 - Write to: `code` vault for patterns/workarounds/performance, `ecosystem` vault for decisions
 
 ### Phase 2B (Audit Complete)
 Extract from WorkGroup:
-- Audit score and findings
-- Security issues found
-- Gap resolution decisions
+- **Audit findings**: Completion percentage, specific gaps with file paths and line references
+- **Security issues**: Describe the vulnerability, affected code paths, severity reasoning, and how it was (or should be) fixed
+- **Gap resolution decisions**: What was deferred vs fixed, and the rationale for each decision
 - Write to: `ecosystem` vault for audit learnings, user's enterprise vault for audit trail (if configured + compliance enabled)
 
 ### Phase 3 (Finalization)
 Extract from WorkGroup:
-- Architectural learnings and consolidation decisions
-- Convention patterns established
-- Any remaining insight-worthy content
+- **Architectural learnings**: Structural discoveries, component relationships that weren't obvious, integration patterns that emerged
+- **Convention patterns established**: New team conventions with full rationale and examples
+- **Consolidation decisions**: What was merged or refactored during finalization and why
 - Write to: appropriate vault per learning category routing
 
 ## Communication
 
-- **Report to lead only on**: errors (MCP failures, vault not found) or dedup catches
-- **Silent on success** — do not broadcast write confirmations to the team
+- **Report to lead on**: errors (MCP failures, vault not found) or dedup catches
+- **Task-based confirmation**: Mark pre-created capture tasks complete with summary (count + vault names) — this is the primary confirmation mechanism
+- **Phase 3 DM confirmation REQUIRED**: After processing Phase 3, send confirmation DM to lead: `"Phase 3 capture complete: {N} items written to {vault names}"`
+- **Silent on success for other phases** — task completion is sufficient, do not broadcast
 - Respond to direct queries from teammates about what has been captured
 
 ## MCP Graceful Degradation
 
-If MCP calls fail:
-1. Log the failure
-2. Report the error to the lead via direct message
-3. Do not retry immediately — wait for the next capture request or lead instruction
-4. The workflow continues without vault writes
+If MCP calls fail or MCP is unavailable:
+1. **Queue locally**: Append the capture to `knowzcode/pending_captures.md` using this format:
+   ```markdown
+   ### {timestamp} — {title}
+   - **Intent**: {Phase capture | Log | Consider}
+   - **Category**: {Pattern|Decision|Workaround|Performance|Security|Convention}
+   - **Target Vault Type**: {code|ecosystem|enterprise|finalizations}
+   - **Source**: {agent name} / WorkGroup {wgid}
+   - **Content**: {description or extracted learning}
+   ```
+2. Report the MCP failure to the lead via DM: `"MCP unavailable — queued {N} capture(s) to pending_captures.md"`
+3. If MCP recovers mid-session, flush pending captures to vaults on the next capture request
+4. Mark the capture task complete (if task-tracked) with note: `"Queued locally — MCP unavailable"`
+
+Never drop knowledge. If MCP is down, queue it. The pending file can be flushed later via `/kc:learn --flush` or by a future scribe instance.
 
 ## Exit Expectations
 
-- All capture requests processed
-- Dedup catches reported to lead
-- Errors reported to lead
-- Ready for shutdown after closer completes
+- All capture tasks marked complete
+- Phase 3 confirmation DM sent to lead
+- Dedup catches and errors reported to lead
+- Ready for shutdown only after all capture tasks are complete

package/agents/project-advisor.md

@@ -69,10 +69,11 @@ Near the end of Stage 2 (before the gap loop), DM lead with structured proposals
 
 ## Knowz-Scribe Integration
 
-If knowz-scribe is active, DM it with idea captures:
-> "Capture idea: {description}. Category: {Pattern|Decision|Convention}. Source: WorkGroup {wgid}."
+If knowz-scribe is active, DM it with idea captures. Include enough detail for the scribe to write a rich vault entry — terse one-liners produce poor search results when stored in the vault.
 
-The scribe routes to the correct vault based on category.
+> "Log: {Detailed description including the specific technology, component, and rationale — e.g. 'Discovered that the Express auth middleware should validate JWT clockTolerance=0 to prevent revoked tokens being accepted during the tolerance window. Affects src/middleware/auth.ts and all protected routes.'}. Category: {Pattern|Decision|Convention}. Source: WorkGroup {wgid}."
+
+The scribe routes to the correct vault based on category. The more context you provide in the DM, the more useful the vault entry will be when retrieved via search months later.
 
 ## Enterprise Compliance (Optional)
 

package/commands/connect-mcp.md

@@ -88,9 +88,9 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    - Store parsed values for use in configuration
 
 2. **Check for existing configuration**
-   - Check if MCP server already configured: `claude mcp get knowzcode`
+   - Check if MCP server already configured: `CLAUDECODE= claude mcp get knowz`
    - If already configured, ask if user wants to reconfigure
-   - If yes, run `claude mcp remove knowzcode` first
+   - If yes, run `CLAUDECODE= claude mcp remove knowz` first
 
 3. **Prompt for API key (if not provided)**
    - If no API key in arguments, prompt user interactively:
@@ -308,14 +308,14 @@ Configure the KnowzCode MCP server using Claude Code's built-in MCP management.
    ```bash
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      <endpoint-url> \
      --header "Authorization: Bearer <api-key>" \
      --header "X-Project-Path: $(pwd)"
    ```
 
 8. **Verify configuration**
-   - Run: `claude mcp get knowzcode`
+   - Run: `CLAUDECODE= claude mcp get knowz`
    - Confirm server appears in the list
    - Check for any error messages
 
@@ -461,7 +461,7 @@ If using --dev environment, verify the dev server is running.
 To change from local to project scope:
 ```bash
 # Remove existing (or the command will prompt to reconfigure)
-claude mcp remove knowzcode
+CLAUDECODE= claude mcp remove knowz
 
 # Re-add with new scope
 /kc:connect-mcp <api-key> --scope project

package/commands/learn.md

@@ -182,6 +182,9 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
      ```
 
 7. **Build learning content**
+
+   > Vault entries are retrieved via semantic search — content must be detailed and self-contained. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
    ```markdown
    [CONTEXT]
    Project: {project-name}
@@ -189,9 +192,11 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
    Vault: {selected_vault_name}
    Source: {--source value or "KnowzCode /kc:learn command"}
    Date: {ISO timestamp}
+   Situation: {Expand on what prompted this learning — the problem being solved, the component involved, relevant technology stack. Provide enough background that someone unfamiliar with the project can understand.}
 
    [INSIGHT]
    {User's insight text}
+   Detail: {Expand the user's insight with technical specifics — include file paths, library names, version numbers, code patterns, or error messages that make this actionable when retrieved via search.}
 
    [SOURCE]
    Captured via /kc:learn command
@@ -202,7 +207,7 @@ Capture the provided insight to the appropriate vault using the MCP `create_know
    ```json
    create_knowledge({
      "content": "{formatted content}",
-     "title": "{Category}: {Brief summary from insight}",
+     "title": "{Category}: {Descriptive summary — include key technology names for search discoverability}",
      "knowledgeType": "Note",
      "vaultId": "{selected_vault_id}",
      "tags": ["{category}", "{extracted-tags}", "{project-name}"],

package/commands/register.md

@@ -111,7 +111,7 @@ YOU                              USER
 
 1. Check if MCP server already configured:
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
 2. If already configured, display:
@@ -127,7 +127,7 @@ YOU                              USER
    ```
 
    Use AskUserQuestion to get user choice. If they choose to keep existing, STOP.
-   If they choose to continue, run `claude mcp remove knowzcode` first.
+   If they choose to continue, run `CLAUDECODE= claude mcp remove knowz` first.
 
 3. If not configured: Continue to Step 2.
 
@@ -330,7 +330,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
    # Production (default)
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      https://mcp.knowz.io/mcp \
      --header "Authorization: Bearer <api_key>" \
      --header "X-Project-Path: $(pwd)"
@@ -338,7 +338,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
    # Development (with --dev flag)
    claude mcp add --transport http \
      --scope <chosen-scope> \
-     knowzcode \
+     knowz \
      https://mcp.dev.knowz.io/mcp \
      --header "Authorization: Bearer <api_key>" \
      --header "X-Project-Path: $(pwd)"
@@ -346,7 +346,7 @@ curl -X POST https://api.dev.knowz.io/api/v1/auth/register \
 
 5. **Verify MCP configuration**:
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
 6. **Configure vault in mcp_config.md**:

package/commands/status.md

@@ -41,7 +41,7 @@ Check Agent Teams status, then check the KnowzCode MCP server status, and report
 
 2. **Check MCP server configuration**
    ```bash
-   claude mcp get knowzcode
+   CLAUDECODE= claude mcp get knowz
    ```
 
    - If configured: Extract scope, endpoint, headers

package/commands/work.md

@@ -536,11 +536,16 @@ When Parallel Teams mode is active, follow these 4 stages instead of spawning on
    - Write ARC-Completion log entry
    - Review architecture docs for discrepancies
    - Schedule REFACTOR tasks for tech debt
-   - Send learnings to knowz-scribe (if active): `"Capture Phase 3: {wgid}"`. Knowz-scout remains available for vault queries during finalization.
+   - Create capture task for knowz-scribe (if active): `TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`, then send DM with task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. Knowz-scout remains available for vault queries during finalization.
    - Create final atomic commit
 4. Lead presents completion summary
-5. Shut down knowz-scout, knowz-scribe (after Phase 3 capture completes), closer, and all remaining agents
-6. Delete team
+5. **Wait for scribe Phase 3 capture** (if knowz-scribe is active):
+   - Check scribe capture task via `TaskGet(task-id)` — wait until status is `completed`
+   - Also wait for scribe's Phase 3 confirmation DM
+   - **Timeout**: If >2 minutes after closer completes and scribe task still not complete → DM scribe: `"Status check: Phase 3 capture for {wgid}?"`
+   - **Hard timeout**: If another minute passes with no completion → proceed with shutdown and log `WARNING: Scribe Phase 3 capture did not complete for {wgid}. Vault writes may be incomplete.`
+6. Shutdown order: knowz-scout, knowz-scribe, closer, remaining agents
+7. Delete team
 
 ### WorkGroup File Format (Parallel Mode)
 
@@ -592,6 +597,10 @@ When creating tasks, model the dependency chain with `addBlockedBy` and pre-assi
 | Fix gaps: NodeID-X round N | Audit: NodeID-X (or re-audit N-1) | builder-N |
 | Re-audit: NodeID-X round N | Fix gaps round N | reviewer-N |
 | Phase 3 finalization | All audits approved | closer |
+| Scribe: Capture Phase 1A | Phase 1A (gate approval) | knowz-scribe |
+| Scribe: Capture Phase 2A | Implement: NodeID-X | knowz-scribe |
+| Scribe: Capture Phase 2B | All audits approved | knowz-scribe |
+| Scribe: Capture Phase 3 | Phase 3 finalization | knowz-scribe |
 
 ---
 
@@ -855,7 +864,8 @@ If `AUTONOMOUS_MODE = false`: If rejected — re-run analyst with user feedback.
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after Change Set approval:
-- Send message to **knowz-scribe**: `"Capture Phase 1A: {wgid}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 1A")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 1A: {wgid}. Your task: #{task-id}"` — the scribe reads the WorkGroup file, extracts scope/risk/decision data, and writes to the appropriate vault
 - `search_knowledge({resolved_domain_vault_id}, "patterns for {domain}")` — pull relevant past learnings to inform specification
 - Share any relevant findings with the architect in the Phase 1B prompt
 
@@ -988,7 +998,8 @@ When complete, present implementation summary including files changed, tests wri
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after implementation completes:
-- Send message to **knowz-scribe**: `"Capture Phase 2A: {wgid}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 2A")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 2A: {wgid}. Your task: #{task-id}"` — the scribe reads implementation results from the WorkGroup file and captures patterns, workarounds, and performance optimizations to the `code` vault
 
 ---
 
@@ -1069,7 +1080,8 @@ If `AUTONOMOUS_MODE = false`: User decides — proceed / fix gaps / modify specs
 ### MCP Learning Capture (Optional)
 
 If MCP is configured and knowz-scribe is active, after audit approval:
-- Send message to **knowz-scribe**: `"Capture Phase 2B: {wgid}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
+- Create capture task: `TaskCreate("Scribe: Capture Phase 2B")` → `TaskUpdate(owner: "knowz-scribe")`
+- Send message to **knowz-scribe** with task ID: `"Capture Phase 2B: {wgid}. Your task: #{task-id}"` — the scribe reads audit results from the WorkGroup file and writes findings to the appropriate vault
 
 ---
 
@@ -1089,7 +1101,7 @@ If MCP is configured and knowz-scribe is active, after audit approval:
 >
 > **Your Task**: #{task-id} — claim immediately (`TaskUpdate(status: "in_progress")`). Mark completed with summary when done.
 > **Conventions**: Update WorkGroup file with results (prefix entries with `KnowzCode:`). If blocked, report blocker and notify lead.
-> **Vault writes**: If knowz-scribe is active, send it `"Capture Phase 3: {wgid}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
+> **Vault writes**: If knowz-scribe is active, create a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`), then send `"Capture Phase 3: {wgid}. Your task: #{task-id}"` to delegate learning capture and audit trail writes. Do NOT call `create_knowledge` directly.
 > **Deliverable**: Atomic finalization — update specs to FINAL, update tracker, write log entry, update architecture if needed, delegate learning capture to knowz-scribe, and create final commit.
 
 **Dispatch**:
@@ -1100,7 +1112,7 @@ If MCP is configured and knowz-scribe is active, after audit approval:
 ### Phase 3 Output
 
 When complete, if MCP is configured and knowz-scribe is active:
-- The closer sends a message to **knowz-scribe**: `"Capture Phase 3: {wgid}"` — the scribe reads the WorkGroup file, extracts learnings, decisions, and outcomes, and writes to the appropriate vaults
+- The closer creates a capture task (`TaskCreate("Scribe: Capture Phase 3")` → `TaskUpdate(owner: "knowz-scribe")`) and sends a message with the task ID: `"Capture Phase 3: {wgid}. Your task: #{task-id}"`. The lead waits for the scribe's capture task to complete before shutdown.
 
 Update workgroup to "Closed" and report:
 

package/knowzcode/knowzcode_loop.md

@@ -327,6 +327,8 @@ All phases work without MCP. MCP enhances analysis depth and organizational lear
 
 ## 7. Learning Capture (Optional)
 
+> **Vault content must be detailed and self-contained.** Vault entries are retrieved via semantic search — not read directly like local files. Include full reasoning, specific technology names, code examples, and file paths. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
 During finalization, scan the WorkGroup for insight-worthy patterns:
 
 | Signal Type | Examples |
@@ -351,13 +353,21 @@ At each quality gate, send a message to the knowz-scribe with the phase identifi
 
 The knowz-scribe reads the WorkGroup file, extracts relevant data, checks for duplicates, and writes to the appropriate vault. No other agent should call `create_knowledge` when the scribe is active.
 
+**Ad-hoc captures (any agent, any time):**
+
+Any agent can send knowledge to the knowz-scribe outside phase boundaries:
+- `"Log: {description}"` — explicit capture, scribe must write it (decides vault routing)
+- `"Consider: {description}"` — soft capture, scribe evaluates whether to log and where
+
+The scribe handles routing, dedup, and formatting for both modes. If MCP is unavailable, captures are queued to `knowzcode/pending_captures.md` for later sync.
+
 **Single-agent / no scribe (direct MCP writes):**
 
 If MCP is available but no knowz-scribe, resolve vault IDs from `knowzcode/knowzcode_vaults.md` before writing:
 
-- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {goal}", content="[NodeIDs] {list}\n[Risk] {assessment}", tags=["scope"])`
-- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles
-- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}%", content="[Findings] {gaps}\n[Security] {issues}", tags=["audit"])`
+- After Phase 1A: `create_knowledge({ecosystem_vault}, title="Scope: {descriptive goal summary}", content="[CONTEXT] {problem description, what prompted this work, constraints}\n[INSIGHT] {scope decisions — what's included/excluded and why}\n[RATIONALE] {risk assessment with full reasoning, affected files, mitigation}\n[TAGS] scope, {domain}", tags=["scope", "{domain}"])`
+- After Phase 2A: Capture implementation patterns and workarounds discovered during TDD cycles — include specific file paths, code examples, and the problem each pattern solves
+- After Phase 2B: `create_knowledge({ecosystem_vault}, title="Audit: {wgid} - {score}% — {key finding summary}", content="[CONTEXT] {what was audited, scope of the review}\n[INSIGHT] {specific gaps with file paths and line references, security findings with severity reasoning}\n[RATIONALE] {gap resolution decisions — what was deferred vs fixed and why}\n[TAGS] audit, {domain}", tags=["audit", "{domain}"])`
 - After Phase 2B (enterprise): If enterprise vault configured and compliance enabled, push audit results to enterprise vault
 - After Phase 3: Capture architectural learnings and consolidation decisions (handled by closer agent)
 

package/knowzcode/knowzcode_vaults.md

@@ -124,16 +124,39 @@ On confirmation, each vault is created via the MCP `create_vault(name, descripti
 
 Each vault type defines when it accepts writes (Write Conditions) and how content should be formatted (Content Filter).
 
+### Content Detail Principle
+
+Vault entries live in a vector search index — they are chunked and retrieved via semantic search. Unlike local files (specs, workgroups, logs) which are read directly and benefit from being scannable, vault entries must be **self-contained, detailed, and keyword-rich** because they are discovered by meaning, not by file path.
+
+**Include in every vault entry:**
+- Full reasoning and context — why, not just what
+- Specific technology names, library versions, framework details
+- Code examples, file paths, error messages where relevant
+- Consequences and alternatives considered
+
+**Anti-pattern** (poor search recall, useless when retrieved):
+
+> `"[NodeIDs] AuthMiddleware\n[Risk] Medium"`
+
+**Good pattern** (rich search matches, self-contained on retrieval):
+
+> `[CONTEXT] During JWT authentication implementation for the Express API, the jsonwebtoken library's verify() method silently accepts expired tokens when clockTolerance is set above 0.`
+> `[INSIGHT] Always set clockTolerance to 0 (default) and handle TokenExpiredError explicitly. Some tutorials suggest 30s tolerance which creates a security window where revoked tokens remain valid.`
+> `[RATIONALE] A 30-second tolerance means stolen tokens stay usable after revocation. Our auth middleware in src/middleware/auth.ts now checks expiry with zero tolerance.`
+> `[TAGS] security, jwt, express, authentication`
+
+Write vault content as if the reader has no project context — they will find this entry via a search query months from now.
+
 ### code
 
 **Write Conditions**: Learning category is Pattern, Workaround, or Performance.
 
 **Content Filter**:
 ```
-[CONTEXT] {where the pattern/workaround was encountered}
-[PATTERN] {what was built or discovered}
-[EXAMPLE] {code snippet or usage example}
-[TAGS] {learning category, domain, language}
+[CONTEXT] {Where and why the pattern was encountered — include the component, framework, and problem being solved. Provide enough background for someone with no project familiarity.}
+[PATTERN] {What was built or discovered — describe the approach, the key insight, and how it differs from the obvious/naive solution.}
+[EXAMPLE] {Code snippet, usage example, or file path reference — concrete enough to be directly useful when retrieved.}
+[TAGS] {learning category, domain, language, framework — include specific technology names for search discoverability}
 ```
 
 ### ecosystem
@@ -142,10 +165,10 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[CONTEXT] {what prompted the decision or convention}
-[INSIGHT] {the decision, convention, security finding, or integration detail}
-[RATIONALE] {why this approach was chosen}
-[TAGS] {learning category, domain}
+[CONTEXT] {What prompted the decision — the problem, the alternatives considered, and the constraints. Include component names and file paths where relevant.}
+[INSIGHT] {The decision, convention, security finding, or integration detail — state it clearly and completely so it stands alone without context.}
+[RATIONALE] {Why this approach was chosen over alternatives — include trade-offs, risks of the rejected options, and any conditions that might change this decision.}
+[TAGS] {learning category, domain, specific technology names — be generous with tags for search discoverability}
 ```
 
 ### finalizations
@@ -154,11 +177,12 @@ Each vault type defines when it accepts writes (Write Conditions) and how conten
 
 **Content Filter**:
 ```
-[GOAL] {original goal from WorkGroup}
-[OUTCOME] {success | partial | abandoned}
-[NODES] {NodeIDs changed}
-[DURATION] {phases completed, e.g. "1A-3"}
-[TAGS] {finalization, domain, outcome}
+[GOAL] {Original goal from WorkGroup — restate fully, not just the WorkGroup slug}
+[OUTCOME] {success | partial | abandoned — include what was delivered and what was deferred}
+[NODES] {NodeIDs changed — list each with a one-line summary of what it covers}
+[DURATION] {Phases completed (e.g. "1A-3"), total iterations, any notable delays or blockers}
+[SUMMARY] {Key learnings from this WorkGroup — architectural discoveries, patterns established, gotchas encountered. This is the most valuable field for future search queries.}
+[TAGS] {finalization, domain, outcome, key technology names}
 ```
 
 ---

package/knowzcode/platform_adapters.md

@@ -58,17 +58,28 @@ Specialized agents handle each phase when using Agent Teams or subagent executio
 If configured, agents use `search_knowledge`, `ask_question`, and `create_knowledge` for enhanced context.
 All commands work without MCP — it enhances but never blocks.
 
-### Vault Targeting (MANDATORY when MCP is connected)
-**When calling `create_knowledge` or `update_knowledge`, ALWAYS pass `vaultId`.**
-Omitting `vaultId` saves to the tenant default vault (often Personal) — NOT the project vault.
+### Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds, convention changes —
+**must** be captured. Knowledge lives in two places:
 
-Before any MCP write:
-1. Check if vault IDs are already in context from a previous read or CLAUDE.md
-2. If not, read `knowzcode/knowzcode_vaults.md` for vault IDs and routing rules
-3. Match your content type to the correct vault using the routing table
-4. Pass `vaultId` explicitly in every call
+- **MCP vaults** (when connected): `knowzcode/knowzcode_vaults.md` defines vault IDs, routing rules,
+  and write conditions. Always pass `vaultId` when calling `create_knowledge` — omitting it saves
+  to the tenant default vault, NOT the project vault.
+- **Local files** (always available): specs, workgroup files, log entries, architecture docs, and
+  `knowzcode/pending_captures.md` (scribe fallback queue when MCP is unavailable).
 
-For ad-hoc learning capture, prefer `/kc:learn "insight"` — it handles routing automatically.
+If MCP is not connected, knowledge still gets captured locally. Never let insights die in the conversation.
+
+**Vault content detail**: Vault entries are retrieved via semantic search, not read directly like local files. Write detailed, self-contained entries with full reasoning, specific technology names, code examples, and file paths. Terse entries produce poor search results. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
+
+### Knowz-Scribe Delegation
+When knowz-scribe is active (Agent Teams mode), it owns all vault writes — do NOT call `create_knowledge` directly. Send knowledge to the scribe instead:
+
+- **Phase captures**: Handled automatically at quality gates via task-tracked DMs
+- **Explicit**: `"Log: {description}"` — scribe MUST write it; it decides routing (which vault or local file)
+- **Soft**: `"Consider: {description}"` — scribe evaluates whether to capture and where; may skip if not insight-worthy or duplicative
+
+Any agent can send ad-hoc knowledge to the scribe at any time. The scribe handles routing, dedup, and formatting. If MCP is unavailable, the scribe queues captures to `knowzcode/pending_captures.md` for later sync. When no scribe is active, use `/kc:learn "insight"` for automatic routing.
 
 ## WorkGroup Files
 - Created in `knowzcode/workgroups/` (gitignored)
@@ -142,9 +153,12 @@ Read `knowzcode/knowzcode_loop.md` before starting any feature work.
 - Every WorkGroup todo must start with `KnowzCode:` prefix
 - Target <20 specs per project — consolidate when domains overlap
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 
 ## Quick Fix (Micro-Fix)
 For single-file, <50 line, no-ripple-effect changes:
@@ -258,9 +272,12 @@ Read these files before starting any feature work (use @import syntax for direct
 - Log completions in `knowzcode/knowzcode_log.md`
 - Target <20 specs — consolidate when domains overlap >50%
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 
 ## Micro-Fix (for small changes)
 Single file, <50 lines, no ripple effects:
@@ -330,9 +347,12 @@ Before any feature work, read:
 - Read `knowzcode/knowzcode_tracker.md` for active work
 - Log completions in `knowzcode/knowzcode_log.md`
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 ```
 
 ---
@@ -426,9 +446,12 @@ Follow Red-Green-Refactor for every feature/criterion in the spec.
 If configured in `.vscode/mcp.json`, use `search_knowledge` and `ask_question` tools
 for enhanced context from knowledge vaults. All prompts work without MCP.
 
-### Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 
 ## Copilot Coding Agent
 
@@ -900,22 +923,22 @@ Optionally generated by `/kc:init` when Copilot is detected and MCP is configure
 ```json
 {
   "servers": {
-    "knowzcode": {
+    "knowz": {
       "type": "http",
-      "url": "${input:knowzcode_mcp_url}",
+      "url": "${input:knowz_mcp_url}",
       "headers": {
-        "x-api-key": "${input:knowzcode_api_key}"
+        "x-api-key": "${input:knowz_api_key}"
       }
     }
   },
   "inputs": [
     {
-      "id": "knowzcode_mcp_url",
+      "id": "knowz_mcp_url",
       "description": "KnowzCode MCP server URL",
       "type": "promptString"
     },
     {
-      "id": "knowzcode_api_key",
+      "id": "knowz_api_key",
       "description": "KnowzCode API key",
       "type": "promptString",
       "password": true
@@ -1001,9 +1024,12 @@ Follow `knowzcode/knowzcode_loop.md` for all feature development.
 - Target <20 specs per project
 - Every WorkGroup todo starts with `KnowzCode:` prefix
 
-## Vault Targeting
-When calling `create_knowledge`, always pass `vaultId` from `knowzcode/knowzcode_vaults.md`.
-Omitting it saves to the wrong vault. Use `/kc:learn` for automatic routing.
+## Knowledge Capture (CRITICAL — DO NOT SKIP)
+Every piece of durable knowledge — decisions, patterns, gotchas, workarounds — **must** be captured.
+When MCP is connected, write to vaults per `knowzcode/knowzcode_vaults.md` — always pass `vaultId` with `create_knowledge`.
+When MCP is unavailable, capture locally in specs, log entries, or docs. Never let insights die in the conversation.
+Use `/kc:learn "insight"` for automatic routing.
+Vault entries are retrieved via semantic search — write detailed, self-contained content. See `knowzcode/knowzcode_vaults.md` Content Detail Principle.
 
 ## Micro-Fix (for small changes)
 Single file, <50 lines, no ripple effects:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowzcode",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Platform-agnostic AI development methodology with TDD, quality gates, and structured workflows",
   "type": "module",
   "bin": {

package/skills/alias-resolver.json

@@ -1,6 +1,6 @@
 {
   "name": "alias-resolver",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Resolves friendly natural-language aliases to KnowzCode canonical values (phase, audit, plan, workgroup_type).",
   "parameters": [
     {"name": "domain", "type": "string", "required": true},

package/skills/architecture-diff.json

@@ -1,6 +1,6 @@
 {
   "name": "architecture-diff",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Highlights differences between specs and the Mermaid flowchart in knowzcode_architecture.md.",
   "parameters": [],
   "actions": [

package/skills/check-installation-status.json

@@ -1,6 +1,6 @@
 {
   "name": "check-installation-status",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Checks if KnowzCode is initialized in the current project and reports current status",
 
   "parameters": [],

package/skills/environment-guard.json

@@ -1,6 +1,6 @@
 {
   "name": "environment-guard",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Verifies that knowzcode/environment_context.md no longer contains placeholder brackets.",
   "parameters": [],
   "actions": [

package/skills/generate-workgroup-id.json

@@ -1,6 +1,6 @@
 {
   "name": "generate-workgroup-id",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Generates a WorkGroupID following the KnowzCode convention [type]-[slug]-YYYYMMDD-HHMMSS. The slug is a 2-4 word descriptor extracted from the goal.",
   "parameters": [
     {

package/skills/install-knowzcode.json

@@ -1,6 +1,6 @@
 {
   "name": "install-knowzcode",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Initializes KnowzCode directory structure and required files in the current project",
 
   "parameters": [

package/skills/load-core-context.json

@@ -1,6 +1,6 @@
 {
   "name": "load-core-context",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Loads the KnowzCode project overview, architecture, tracker, log header, and automation manifest for downstream steps.",
   "parameters": [],
   "actions": [

package/skills/log-entry-builder.json

@@ -1,6 +1,6 @@
 {
   "name": "log-entry-builder",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Appends structured entries to knowzcode/knowzcode_log.md with KnowzCode formatting.",
   "parameters": [
     {"name": "entry_type", "type": "string", "required": true},

package/skills/spec-quality-check.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-quality-check",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Validates KnowzCode spec files for mandatory sections. Supports new 4-section format and legacy numbered format.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true}

package/skills/spec-template.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-template",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Seeds or repairs KnowzCode spec files with the lean 4-section template.",
   "parameters": [
     {"name": "node_id", "type": "string", "required": true},

package/skills/spec-validator.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-validator",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Validates NodeID specification completeness and quality. Supports new 4-section format (preferred) and legacy numbered sections (deprecated).",
   "parameters": [
     {

package/skills/tracker-scan.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-scan",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Extracts NodeID statuses and WorkGroup assignments from the KnowzCode tracker.",
   "parameters": [],
   "actions": [

package/skills/tracker-update.json

@@ -1,6 +1,6 @@
 {
   "name": "tracker-update",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Applies validated updates to knowzcode/knowzcode_tracker.md while preserving table structure.",
   "parameters": [
     {

package/skills/validate-installation.json

@@ -1,6 +1,6 @@
 {
   "name": "validate-installation",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Validates that KnowzCode installation completed successfully with required directories and files",
 
   "parameters": [],