@zigrivers/scaffold 3.33.5 → 3.33.6

package/content/knowledge/VERSION

@@ -1 +1 @@
-0.1.10
+0.1.12

package/content/knowledge/browser-extension/browser-extension-store-submission.md

@@ -1,13 +1,26 @@
 ---
 name: browser-extension-store-submission
-description: Chrome Web Store review process, AMO submission, screenshot and promotional image requirements, listing optimization, and managing version updates
-topics: [browser-extension, store-submission, chrome-web-store, amo, listing-optimization, review-process, screenshots]
+description: >-
+  Chrome Web Store review process, AMO submission, screenshot and promotional image requirements, listing optimization,
+  and managing version updates
+topics:
+  - browser-extension
+  - store-submission
+  - chrome-web-store
+  - amo
+  - listing-optimization
+  - review-process
+  - screenshots
 volatility: evolving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://developer.chrome.com/docs/webstore/publish
+    hash: sha256:c81bca9d736a2ad631c41f1c4f484b6341afcbd5cd5e5ea6d1dbccf909c04511
+    retrieved: 2026-06-07
   - url: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/Distribution
+    hash: sha256:36cf6edeaf11509b684bdf7b21d78cb5fe0330697a34acff91903d70d33430e7
+    retrieved: 2026-06-07
 ---
 
 Store submission is the deployment step for browser extensions. Unlike web applications where you push to a server, extensions must pass store review before reaching users. Review timelines, policy requirements, and listing quality directly affect user acquisition and approval success. Understanding the process before writing the first line of code prevents costly late-stage pivots.

package/content/knowledge/browser-extension/browser-extension-testing.md

@@ -1,13 +1,27 @@
 ---
 name: browser-extension-testing
-description: Extension testing with Puppeteer and Playwright, unit testing shared logic, and manual cross-browser smoke test procedures
-topics: [browser-extension, testing, puppeteer, playwright, unit-testing, e2e, smoke-tests, cross-browser]
+description: >-
+  Extension testing with Puppeteer and Playwright, unit testing shared logic, and manual cross-browser smoke test
+  procedures
+topics:
+  - browser-extension
+  - testing
+  - puppeteer
+  - playwright
+  - unit-testing
+  - e2e
+  - smoke-tests
+  - cross-browser
 volatility: evolving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://developer.chrome.com/docs/extensions/how-to/test/end-to-end-testing
+    hash: sha256:66bf76a65993daa9fcb0daba148e6780cd54d34a0fd013c24634ed86f4115e4f
+    retrieved: 2026-06-07
   - url: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Testing_persistent_and_restart_features
+    hash: sha256:ca07150330ba40d75080deedf3928e78776615c6fdab4ad83de7999c17890ee8
+    retrieved: 2026-06-07
 ---
 
 Browser extension testing is harder than web app testing because the extension runs in a privileged browser context that most test frameworks cannot easily access. The strategy is to maximize the code that lives in plain TypeScript (easily unit-tested), minimize the code that requires a real browser to test (expensive), and write targeted end-to-end tests that exercise the extension in a real browser for the scenarios that matter most.

package/content/knowledge/cli/cli-dev-environment.md

@@ -1,12 +1,23 @@
 ---
 name: cli-dev-environment
-description: Local development setup for CLIs including npm link, cargo install, debug flags, manual testing workflow, and hot reload
-topics: [cli, dev-environment, npm-link, cargo, debug, hot-reload, testing-workflow]
+description: >-
+  Local development setup for CLIs including npm link, cargo install, debug flags, manual testing workflow, and hot
+  reload
+topics:
+  - cli
+  - dev-environment
+  - npm-link
+  - cargo
+  - debug
+  - hot-reload
+  - testing-workflow
 volatility: evolving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://docs.astral.sh/uv/
+    hash: sha256:81d5796b079a3cd0448a2a99ffd23bcd684922c52c36f8c8ecf212804da271e2
+    retrieved: 2026-06-07
 ---
 
 CLI development has a tighter feedback loop requirement than library development: you need to run the actual binary, observe its output, and verify behavior against real filesystem and network state. Setting up a fast local development workflow is not optional — a slow iteration cycle compounds across hundreds of test invocations.

package/content/knowledge/cli/cli-distribution-patterns.md

@@ -1,12 +1,25 @@
 ---
 name: cli-distribution-patterns
-description: npm, pip, and cargo publishing, Homebrew formulae, standalone binaries, Docker images, and GitHub Releases with checksums
-topics: [cli, distribution, npm, homebrew, cargo, pip, standalone-binaries, github-releases, checksums]
+description: >-
+  npm, pip, and cargo publishing, Homebrew formulae, standalone binaries, Docker images, and GitHub Releases with
+  checksums
+topics:
+  - cli
+  - distribution
+  - npm
+  - homebrew
+  - cargo
+  - pip
+  - standalone-binaries
+  - github-releases
+  - checksums
 volatility: evolving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://peps.python.org/pep-0621/
+    hash: sha256:7a37a1354520a9a9f31ff547e6318d8f06fbf3c02c435caf41d3cb9306989995
+    retrieved: 2026-06-07
 ---
 
 Distribution is where many CLI projects fail: the tool works perfectly in development but is painful to install, update, or run in different environments. A well-distributed CLI reaches users through multiple channels (package manager, direct download, container) and handles updates gracefully.

package/content/knowledge/core/adr-craft.md

@@ -1,15 +1,24 @@
 ---
 name: adr-craft
 description: Writing effective architecture decision records including technology selection
-topics: [adr, architecture-decisions, tech-stack, decision-documentation, technology-selection]
+topics:
+  - adr
+  - architecture-decisions
+  - tech-stack
+  - decision-documentation
+  - technology-selection
 volatility: stable
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://adr.github.io/
     anchor: '#decision-record-templates'
+    hash: sha256:56c48fcbfa504a3b058d57058dd6dfbab83fc879bc405317d847ec5a2efbd2b6
+    retrieved: 2026-06-07
   - url: https://github.com/joelparkerhenderson/architecture-decision-record
     anchor: '#adr-templates'
+    hash: sha256:0155a98859571e056061d2205db0bf1a7088ee91d6681d85a98f7401d0a6a962
+    retrieved: 2026-06-07
 ---
 
 ## Summary

package/content/knowledge/core/ai-memory-management.md

@@ -1,13 +1,29 @@
 ---
 name: ai-memory-management
-description: AI memory and context management patterns for Claude Code projects including modular rules, MCP memory servers, lifecycle hooks, decision logging, and external context integration
-topics: [ai-memory, claude-code, claude-rules, mcp-servers, lifecycle-hooks, context-management, session-handoff, decision-logging, mcp-knowledge-graph, context7]
+description: >-
+  AI memory and context management patterns for Claude Code projects including modular rules, MCP memory servers,
+  lifecycle hooks, decision logging, and external context integration
+topics:
+  - ai-memory
+  - claude-code
+  - claude-rules
+  - mcp-servers
+  - lifecycle-hooks
+  - context-management
+  - session-handoff
+  - decision-logging
+  - mcp-knowledge-graph
+  - context7
 volatility: fast-moving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://modelcontextprotocol.io/specification
+    hash: sha256:ebe289f5f9ad3d8fd9eb09105a74bff6f5efdfc4cd383759f6f82cf57f3ba724
+    retrieved: 2026-06-07
   - url: https://docs.anthropic.com/en/docs/build-with-claude/memory
+    hash: sha256:e246d2cd069bcb9c7b78d437ffc1672ce45d6ae2393571c00d436e9f7e494f0f
+    retrieved: 2026-06-07
 ---
 
 # AI Memory Management
@@ -111,6 +127,163 @@ This replaces inline convention blocks, keeping CLAUDE.md under 200 lines (the e
 
 #### MCP Memory Servers
 
+The Model Context Protocol (MCP) specification (https://modelcontextprotocol.io/specification) defines the protocol for servers that provide context and capabilities to LLM applications. The specification covers server features including Resources, Prompts, and Tools, but does not prescribe specific MCP server implementations.
+
+**Configuration pattern** (`.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {
+        "MEMORY_FILE_PATH": ".claude/memory-graph.json"
+      }
+    }
+  }
+}
+```
+
+#### Lifecycle Hooks
+
+Hooks automate memory capture at key session events:
+
+**PreCompact** (highest value) — Triggers before context compression. Logs when compaction occurs for debugging context loss.
+
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "type": "command",
+      "command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') — Context compacting\" >> .claude/compaction-log.txt",
+      "timeout": 5000
+    }]
+  }
+}
+```
+
+File-logging for compaction events:
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "type": "command",
+      "command": "date '+%Y-%m-%d %H:%M' >> .claude/compaction-log.txt && echo 'Context compacted' >> .claude/compaction-log.txt",
+      "timeout": 5000
+    }]
+  }
+}
+```
+
+**Stop** — Triggers when a session ends. Good for capturing session-level summaries.
+
+**PreToolUse** — Triggers before tool calls. Can log decisions about file modifications. Use sparingly — high frequency means high overhead.
+
+**Hook selection guidance:**
+- Start with PreCompact only — it captures the most value with least noise
+- Hook commands must produce a side effect (write to MCP server, append to file) — echoing to `/dev/null` provides zero value
+- Add Stop if sessions frequently end with unrecorded decisions
+- Avoid PreToolUse unless you have a specific logging need — it fires constantly
+
+#### Decision Logging
+
+Decisions are the highest-value memory type because they cannot be derived from code. A decision log captures what was chosen, what was rejected, and why.
+
+**Structure:**
+```
+docs/decisions/
+  DECISIONS.md          # Index of all decisions
+  001-auth-strategy.md  # Individual decision records
+  002-database-choice.md
+```
+
+**Decision entry format:**
+```markdown
+## DEC-001: JWT over session cookies for auth
+
+**Date:** 2026-03-27
+**Context:** Need stateless auth for API-first architecture
+**Decision:** Use JWT with short-lived access tokens + refresh tokens
+**Rejected:** Session cookies (requires sticky sessions), OAuth-only (too complex for MVP)
+**Consequences:** Need token refresh logic in frontend, need secure token storage
+```
+
+This complements ADRs (which cover architecture-level decisions) by capturing day-to-day implementation decisions that would otherwise be lost between sessions.
+
+#### Session Handoff Patterns
+
+When context hits limits, structured handoff preserves continuity:
+
+1. **Before compaction**: Save current task state, open questions, and recent decisions
+2. **After compaction**: Claude Code auto-reloads CLAUDE.md and auto-memory, but loses working context
+3. **Recovery**: Agent reads decision log and memory server to reconstruct working state
+
+The `/compact` command is the natural handoff point. A PreCompact hook that saves session state ensures nothing critical is lost.
+
+### Tier 3: External Context
+
+#### Library Documentation Servers
+
+AI agents hallucinate APIs — they generate plausible but incorrect function signatures, especially for rapidly-evolving libraries. External doc servers solve this by providing current, version-specific documentation on demand.
+
+**Context7** (by Upstash) — Most popular, fetches current library docs via MCP
+- Covers major frameworks (React, Next.js, Vue, Angular, etc.)
+- Free tier: 1,000 requests/month
+- Caution: had a security vulnerability (patched) — review before enabling
+
+**Nia** (by Nozomio) — Indexes codebases + 3,000+ pre-indexed packages
+- Cross-session context persistence
+- Deep research agent for complex questions
+- Y Combinator backed, more comprehensive than Context7
+
+**Docfork** — 9,000+ libraries, MIT license
+- "Cabinets" for project-specific documentation isolation
+- Self-hostable
+
+**Configuration pattern:**
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+**When to enable:** Projects with 3+ external dependencies, especially rapidly-evolving frameworks (React, Next.js, Svelte). Skip for standard library-only projects or well-established stable APIs.
+
+### Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| Dumping entire codebase into context | Drowns signal in noise, costs tokens | Let the agent read files on demand |
+| Storing code patterns in memory | Duplicates what's in the code; goes stale | Store decisions and rationale only |
+| Huge CLAUDE.md (500+ lines) | Adherence drops sharply above 200 lines | Use .claude/rules/ for specifics |
+| Memory without structure | Unstructured notes become unsearchable noise | Use categories (decision, lesson, error) |
+| Capturing everything | Token cost with diminishing returns | Capture what can't be derived from code |
+| Multiple overlapping memory tools | Conflicting context, duplicated entries | Pick one MCP server, use it consistently |
+
+### Integration with Beads
+
+When Beads is configured, memory complements task tracking:
+- **Beads** tracks what work to do (tasks, dependencies, status)
+- **Memory** tracks how to do work better (patterns, decisions, lessons)
+- Decision log entries can reference Beads task IDs for traceability
+- `tasks/lessons.md` remains the cross-session learning file; MCP memory adds structured queryability
+- Don't duplicate: if a pattern is in `tasks/lessons.md`, don't also store it in the MCP server
+
+## Coding Conventions
+See `docs/coding-standards.md` for full reference. Key rules in `.claude/rules/code-style.md`.
+```
+
+This replaces inline convention blocks, keeping CLAUDE.md under 200 lines (the empirically-validated adherence threshold).
+
+### Tier 2: Persistent Memory
+
+#### MCP Memory Servers
+
 **Recommended: MCP Knowledge Graph** (`@modelcontextprotocol/server-memory`)
 - Official MCP server from the Model Context Protocol project
 - Stores entities, relations, and observations in a local JSON file

package/content/knowledge/core/api-design.md

@@ -1,13 +1,25 @@
 ---
 name: api-design
 description: API design principles for REST, GraphQL, and inter-service communication
-topics: [api, rest, graphql, endpoints, contracts, versioning, error-handling, authentication]
+topics:
+  - api
+  - rest
+  - graphql
+  - endpoints
+  - contracts
+  - versioning
+  - error-handling
+  - authentication
 volatility: evolving
-last-reviewed: null
-version-pin: 'OpenAPI 3.1 / GraphQL October 2021'
+last-reviewed: 2026-06-07
+version-pin: OpenAPI 3.1 / GraphQL October 2021
 sources:
   - url: https://spec.openapis.org/oas/v3.1.0
+    hash: sha256:ca07378639431519731065e397fa4170c2ddfe501a4aa69db60d6a3a9bb669fe
+    retrieved: 2026-06-07
   - url: https://spec.graphql.org/October2021/
+    hash: sha256:4f556e7bc74ffcdf6ba3c6a4d1f541bd736492db47e97349200a8dfcb80e0ad1
+    retrieved: 2026-06-07
 ---
 
 ## Summary

package/content/knowledge/core/automated-review-tooling.md

@@ -1,15 +1,31 @@
 ---
 name: automated-review-tooling
-description: Patterns for automated code review using AI CLI tools (Codex, Gemini, Claude) — three-CLI MMR orchestration plus Superpowers 4th channel in wrappers, reconciliation, compensating passes, PR + non-PR targets, and CI integration
-topics: [code-review, automation, codex, gemini, claude, pull-requests, non-pr-review, mmr, ci-cd, review-tooling]
+description: >-
+  Patterns for automated code review using AI CLI tools (Codex, Gemini, Claude) — three-CLI MMR orchestration plus
+  Superpowers 4th channel in wrappers, reconciliation, compensating passes, PR + non-PR targets, and CI integration
+topics:
+  - code-review
+  - automation
+  - codex
+  - gemini
+  - claude
+  - pull-requests
+  - non-pr-review
+  - mmr
+  - ci-cd
+  - review-tooling
 volatility: fast-moving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://docs.anthropic.com/en/docs/claude-code/overview
     anchor: '#claude-code-cli'
+    hash: sha256:0436534c3261c036f500f0497ade28c8063f46533e780cd7d4d76821e79d062c
+    retrieved: 2026-06-07
   - url: https://ai.google.dev/gemini-api/docs
     anchor: '#cli-tools'
+    hash: sha256:7b940f480b27022e4cd3394c125a0173e3d9c79b4e650ab5bea51355049592cc
+    retrieved: 2026-06-07
 ---
 
 # Automated Review Tooling

package/content/knowledge/core/claude-md-patterns.md

@@ -1,15 +1,26 @@
 ---
 name: claude-md-patterns
-description: Patterns for structuring CLAUDE.md files including section organization, rule authoring, pointer patterns, and merge strategies
-topics: [claude-md, ai-configuration, rule-files, memory-management, project-setup]
+description: >-
+  Patterns for structuring CLAUDE.md files including section organization, rule authoring, pointer patterns, and merge
+  strategies
+topics:
+  - claude-md
+  - ai-configuration
+  - rule-files
+  - memory-management
+  - project-setup
 volatility: fast-moving
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://docs.anthropic.com/en/docs/claude-code/memory
     anchor: '#claude-md-files'
+    hash: sha256:b6d5f2ae444b33ae686abf63de54471dfad7ff6d1bd57a9c5a6d69cb1096fae0
+    retrieved: 2026-06-07
   - url: https://docs.anthropic.com/en/docs/claude-code/settings
     anchor: '#configuration-precedence'
+    hash: sha256:664220cfa75c2236b9fc6f2ae7a278019eda3807858463121641a8d470f6e0b7
+    retrieved: 2026-06-07
 ---
 
 # CLAUDE.md Patterns

package/content/knowledge/core/coding-conventions.md

@@ -1,15 +1,25 @@
 ---
 name: coding-conventions
 description: Universal coding standards patterns across languages and linter/formatter configuration
-topics: [coding-standards, linting, formatting, naming, error-handling, code-style]
+topics:
+  - coding-standards
+  - linting
+  - formatting
+  - naming
+  - error-handling
+  - code-style
 volatility: stable
-last-reviewed: null
+last-reviewed: 2026-06-07
 version-pin: null
 sources:
   - url: https://google.github.io/styleguide/
     anchor: '#language-style-guides'
+    hash: sha256:250a15511160da60547e0daa20d398c1d0210ee4164a63001b0cc8272e3984ed
+    retrieved: 2026-06-07
   - url: https://peps.python.org/pep-0008/
     anchor: '#code-lay-out'
+    hash: sha256:8ed37af31c6b19c1384ef5c0cce501bd16d1a55d7984aed4a7d47c037ed5e7d5
+    retrieved: 2026-06-07
 ---
 
 # Coding Conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zigrivers/scaffold",
-  "version": "3.33.5",
+  "version": "3.33.6",
   "description": "AI-powered software project scaffolding pipeline",
   "type": "module",
   "workspaces": [