incitaciones 0.2.0 → 0.3.1

package/content/distilled/park/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: park
+description: "Snapshot current work before switching context. Logs what was done and what's next without ending the day. Trigger when the user says '/park', 'park this', 'switching to', 'pause this', or 'context switch'."
+tools: Read, Write, Edit, Bash
+---
+
+# Park
+
+Snapshot the current session's work on a project/area before switching context. This is NOT end-of-day — just a context switch.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. The log subdirectory defaults to `log/`; set `$JOURNAL_LOG_SUBDIR` to override (e.g. `areas/log` for the JORNAL layout).
+
+## Steps
+
+1. Get today's date and current time (`date +%Y-%m-%d`, `date +%H:%M`).
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
+   ```
+
+2. Read today's log: `$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`
+   If it doesn't exist, create it with the daily log template.
+
+3. Review the conversation history to determine:
+   - What project/area was being worked on
+   - What was accomplished in this session
+   - What the logical next step is
+   - Any new tasks, decisions, or blockers discovered
+
+4. Append a session entry to today's log under `## Log`:
+   ```
+   ### Session:HH:MM (<project/area context>)
+   - what was done
+   - decisions made
+   - **Next:** what to do when resuming
+   ```
+
+5. Update the relevant project/area file if needed:
+   - Mark completed tasks `[x]`
+   - Add new tasks discovered during the session
+   - Add/update `[~]` waiting items with context
+   - Update `## Notes` with any decisions
+
+6. If there are uncommitted changes in the project's git worktree, note them in the log entry.
+
+7. **Release any in-progress ticket claim if leaving mid-work.**
+   Check whether a ticket was claimed for this session:
+   ```bash
+   BRANCH=$(git branch --show-current 2>/dev/null)
+   bd list --status in_progress --label branch:$BRANCH 2>/dev/null
+   ```
+   For each in-progress ticket that is NOT complete:
+   - **If meaningful work was committed:** keep the claim and append a progress note:
+     ```bash
+     bd note <id> "Session parked $(date +%H:%M). Done: <brief>. Safe to resume from: <last commit>."
+     ```
+   - **If nothing was committed:** release the claim so another agent can pick it up:
+     ```bash
+     bd update <id> --assignee "" --status open
+     ```
+
+8. **Record snapshot to `~/.whisper/`.** If `~/.whisper/` exists and a beads-epic is linked, append a note to the epic:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch_slug=$(git rev-parse --abbrev-ref HEAD | sed 's|/|--|g')
+   context_path=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"/context.md
+   beads_epic=$(grep '^beads-epic:' "$context_path" 2>/dev/null | sed 's/^beads-epic: *//')
+   if [ -n "$beads_epic" ]; then
+     bd note "$beads_epic" "Parked $(date +%H:%M). Done: <what was accomplished>. Next: <the logical continuation>."
+   fi
+   ```
+
+9. Do NOT commit/push the journal repo yet — that happens at `/close`. Just write the files.
+
+## Output format
+
+```
+---
+**Parked: <project/area name>**
+
+**Session summary**
+- what was accomplished
+
+**Next step** *(for when you /renew)*
+- the logical continuation
+
+**Updated**
+- files modified in status repo (log, project file, etc.)
+
+*Ready to switch context. Use `/renew <slug>` to pick up something else.*
+```
+
+## Rules
+
+- Do NOT ask questions — summarize automatically from conversation context.
+- Keep it brief — this is a quick snapshot, not a full report.
+- Do NOT commit or push the journal repo.
+- Do NOT run `/clear` — the user may continue working in this session.

package/content/distilled/renew/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: renew
+description: "Resume work on a specific project or area. Loads focused context for continuing where you left off. When no name is given, infers the project/area from the current repo and git branch. Trigger when the user says '/renew', '/renew <name>', 'pick up <project>', 'continue <project>', or 'back to <project>'."
+tools: Read, Write, Edit, Glob, Bash, Grep
+---
+
+# Renew
+
+Load focused context for a specific project or area to continue work.
+
+Uses `$JOURNAL_PATH` (defaults to `~/dev/status`) for the daily log journal, and `~/.whisper/` for accumulated operational knowledge. The log subdirectory defaults to `log/`; set `$JOURNAL_LOG_SUBDIR` to override (e.g. `areas/log` for the JORNAL layout).
+
+## Steps
+
+1. Pull the journal repo:
+   ```bash
+   JOURNAL="${JOURNAL_PATH:-$HOME/dev/status}"
+   LOG_SUBDIR="${JOURNAL_LOG_SUBDIR:-log}"
+   cd "$JOURNAL" && git pull
+   ```
+
+2. Identify the target.
+
+   **If a `<slug>` is provided:** The user says `/renew <slug>`.
+
+   **If no slug is provided:** Infer from the current workspace context:
+   - Get the repo name: `basename $(git rev-parse --show-toplevel 2>/dev/null)`
+   - Get the branch name: `git branch --show-current 2>/dev/null`
+   - Extract a candidate slug from the branch (strip prefix like `ak/`, `feature/`, etc.)
+   - Use both the repo name and branch-derived slug as candidates
+
+   **Match candidates** against:
+   - `$JOURNAL/projects/*.md` — check filenames and grep for repo/branch references
+   - `$JOURNAL/areas/*.md` — same
+   - Try exact match, then partial/substring match
+   - If multiple matches found, list them and ask the user to pick
+   - If no match found, list available projects/areas and ask
+
+3. Read the matched project or area file.
+
+4. Read today's log (`$JOURNAL/$LOG_SUBDIR/YYYY/YYYY-MM/YYYY-MM-DD.md`).
+   If it doesn't exist, create it with the daily log template.
+   Scan for any earlier session entries related to this project/area today.
+
+5. Search recent logs for context (last 3 days):
+   ```bash
+   grep -rl "<slug>" "$JOURNAL"/"$LOG_SUBDIR"/YYYY/YYYY-MM/ 2>/dev/null | tail -3
+   ```
+   Read any matches to understand recent session history.
+
+6. Search inbox for related items:
+   ```bash
+   grep -i "<slug>" "$JOURNAL"/inbox.md
+   ```
+
+7. **Check `~/.whisper/` for accumulated knowledge.**
+   If `~/.whisper/` exists, load context:
+   ```bash
+   repo_url=$(git remote get-url origin 2>/dev/null | sed 's|https://||;s|git@||;s|\.git$||')
+   branch_slug=$(git rev-parse --abbrev-ref HEAD | sed 's|/|--|g')
+   whisper_dir=~/.whisper/repos/"${repo_url}"/branches/"${branch_slug}"
+   ```
+   - Read `context.md` if it exists (extract beads-epic, status)
+   - Read `plan.md` if it has real content
+   - Read `notes.md` if it has real content
+   - Read `env.md` at repo level for infra facts
+   - If beads is available, fetch open issues:
+     ```bash
+     bd list --label branch:<branch> 2>/dev/null
+     bd list --status in_progress --label branch:<branch> 2>/dev/null
+     ```
+     Surface any `in_progress` tickets prominently. The **Suggested next step** must only reference tickets NOT currently `in_progress`.
+
+8. If the project/area has a worktree or repo path noted in its file, gather git context:
+   - `cd <worktree-path> && git branch --show-current`
+   - `git log --oneline -5`
+   - `git status --short`
+   - `git log --oneline origin/main..HEAD`
+
+## Output format
+
+```
+---
+**Resuming: Project/Area Name**
+
+**Status**: brief one-line summary of where things stand
+
+**Last session** *(from most recent log entry)*
+- what was done last time
+
+**Open tasks**
+- [ ] task list from the project/area file
+
+**Waiting**
+- [~] any blocked items and who/what they're waiting on
+
+**Related inbox items** *(if any)*
+- items that mention this project
+
+**Whisper context** *(if ~/.whisper/ exists)*
+- Plan: summary of current plan
+- Notes: key findings
+- Beads issues: <n> open, <n> in_progress
+
+**⚠ Active in flight** *(omit if none)*
+- ◐ `<id>` — <title> [started: <date>]
+- *(If your intended ticket is listed here, see **Claiming work** below.)*
+
+**Workspace**
+- Worktree: path, branch, status
+- Commits ahead of main, uncommitted changes, etc.
+
+**Suggested next step**
+- what makes sense to do next — only suggest tickets NOT currently in_progress
+```
+
+Then ask: *"Ready to continue, or want to adjust the plan?"*
+
+---
+
+## Claiming work
+
+Before writing any code, claim the ticket atomically and check for file conflicts.
+
+### Steps
+
+1. **Claim atomically:**
+   ```bash
+   bd update <ticket-id> --claim
+   ```
+
+2. **Check for file-level conflicts** with other in-progress tickets:
+   ```bash
+   bd list --status in_progress --label branch:<branch> --json 2>/dev/null \
+     | python3 -c "
+   import json, sys
+   issues = json.loads(sys.stdin.read() or '[]')
+   for i in issues:
+       files = (i.get('metadata') or {}).get('files', [])
+       for f in files:
+           print(i['id'] + '\t' + f)
+   "
+   ```
+   Cross-reference against the claimed ticket's own `metadata.files`.
+   If overlap found, surface a warning:
+   ```
+   ⚠ File conflict detected:
+     services/api.py is also claimed by ticket-abc (in_progress)
+
+   Options:
+     A) Gate this ticket until the blocker closes
+     B) Coordinate merge order
+     C) Proceed — accept the conflict (reconcile at merge time)
+   ```
+
+3. **If backing off** (chose option A):
+   ```bash
+   bd update <ticket-id> --assignee "" --status open
+   bd gate create <ticket-id> --type bead --await-id <blocking-id>
+   ```
+
+### Metadata coverage warning
+
+File conflict detection only works when both tickets have `metadata.files` populated (set by `create-issues` or `/w link` at ticket creation time). Tickets created before this convention was adopted have no metadata. For those tickets, **"no conflict found" means unknown, not safe**.

package/content/distilled/research-documentation/SKILL.md

@@ -0,0 +1,29 @@
+# Research Documentation Architecture
+
+Audit existing documentation or plan a new suite using the Unified Frameworks for Technical Information Architecture.
+
+## Core Rules
+
+- You are an architect, not a writer. Map structure and gaps; do not draft content.
+
+## Procedure
+
+1. Define the scope: identify the primary audience (novice vs. expert) and state the single-sentence "Core Assertion" (the value proposition). If existing docs have conflicting hooks, pick the most impactful or propose a synthesis.
+2. Analyze existing content (if any): for each file determine its Diátaxis quadrant, EPPO status (standalone utility), and cognitive load. Use `references/checklist.md` for the completeness and accessibility items to check against.
+3. Map the Snowflake outline: Core Assertion, Macro-Expansion, Component List, Topic Matrix by quadrant.
+4. Identify gaps and friction: quadrant imbalance, structural plot-holes, and AI-readiness gaps. Use `references/llm-readiness.md` to assess `llms.txt`, MCP, RAG chunking, and dual-audience design. Use `references/metrics.md` to recommend measurement signals (TTFS, search analytics, coverage, freshness).
+5. Produce the final research report using `references/report-template.md`.
+
+## Rules
+
+- Categorize every document into exactly one Diátaxis quadrant.
+- Flag "Frankenbooks" (documents with mixed intent/quadrants).
+- Verify EPPO compliance: does each page establish its own context?
+- Do not start writing content; focus on architecture and gaps.
+- Do not suggest stylistic changes; focus on structural integrity.
+- The canonical theory lives in `content/research-documentation-frameworks.md`; the references here are operational excerpts that link back to it.
+
+## Related Skills
+
+- `implement-documentation` — write topics from this audit.
+- `review-documentation` — review what you write.

package/content/distilled/research-documentation/references/checklist.md

@@ -0,0 +1,58 @@
+# Documentation Completeness Checklist
+
+Use during the audit (Step 2) to check existing or planned coverage. Source: `content/research-finding-library-docs-best-practices.md` (Section 1, the best-practices checklist, and Section 5, accessibility).
+
+## Completeness and accuracy
+
+- All public APIs, endpoints, parameters, and return values are documented.
+- All error codes and messages are documented with explanations and remediation steps.
+- Prerequisites and system requirements are stated upfront.
+- All code examples are tested and verified to work with the current version.
+- No documented features are missing from the implementation, and no undocumented features exist.
+
+## Getting started and onboarding
+
+- A "Getting Started" or "Quick Start" guide exists and can be completed in under 15 minutes.
+- The guide leads to a meaningful, working result (not just "Hello, World" unless that is genuinely useful).
+- Installation instructions cover all supported platforms and package managers.
+- Authentication and configuration are explained before any API calls are shown.
+
+## API reference
+
+- Each endpoint/function/method has a human-friendly description, not just a parameter list.
+- Request and response examples are provided for every endpoint.
+- Authentication requirements are documented per endpoint where relevant.
+- Rate limits, pagination, and other operational constraints are documented.
+- The reference is generated from or synchronized with a machine-readable specification (OpenAPI, TypeDoc, JSDoc, Sphinx autodoc).
+
+## Versioning and changelog
+
+- Documentation is versioned to match software releases.
+- A changelog exists and is kept up to date.
+- Breaking changes are prominently highlighted.
+- Deprecated features are marked with migration paths provided.
+- Old versions of documentation remain accessible.
+
+## Code examples
+
+- Examples exist for all major use cases.
+- Examples are provided in all officially supported languages/frameworks.
+- Examples are complete and runnable, not pseudocode or partial snippets.
+- Examples follow current best practices and idioms for each language.
+
+## Conceptual and explanatory content
+
+- Architecture and design decisions are explained (the "why", not just the "what").
+- Key concepts are defined before they are used.
+- Diagrams and visuals are used where they clarify complex relationships.
+
+## Accessibility (WCAG 2.1 AA)
+
+- Code syntax highlighting meets minimum contrast ratios.
+- All navigation, search, and interactive elements are operable by keyboard alone.
+- Code blocks, tables, and diagrams have appropriate ARIA labels and alt text.
+- The site is readable on mobile and manages focus correctly in single-page-app navigation.
+
+## Out of scope for this checklist
+
+Internationalization/localization and interactive documentation (live playgrounds, API explorers) are valid concerns but are tracked separately as platform/infrastructure decisions, not architectural-audit items.

package/content/distilled/research-documentation/references/llm-readiness.md

@@ -0,0 +1,43 @@
+# LLM & Agentic Readiness Reference
+
+Operational excerpt for the AI-readiness gap assessment in Step 4. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability"); this file distills the concrete checks.
+
+## `llms.txt` standard
+
+An emerging convention analogous to `robots.txt`: a machine-readable index at the docs site root that tells LLMs which pages matter most, with structured summaries. Check:
+
+- Is a `llms.txt` present at the documentation root?
+- Does it list the most authoritative pages (quick start, API reference, key how-tos)?
+- Are summaries concise and current with the latest version?
+
+## RAG-friendly chunking
+
+Documentation structured as single-topic, self-contained modules chunks cleanly for retrieval-augmented generation. Check:
+
+- Does each page cover one well-defined topic (Diátaxis quadrant purity enables this)?
+- Are pages small enough to be one RAG chunk, or do they need explicit section anchors?
+- Is there redundant cross-page duplication that would pollute retrieval?
+
+## MCP and agent manifests
+
+For tooling/agent documentation, the description fields are documentation. Check:
+
+- Are MCP tool manifests present with precise `name`, `description`, input/output JSON schemas?
+- Are plugin/agent cards machine-readable with capability boundaries and error conditions?
+- Is language precise enough for a machine (no context-dependent ambiguity a human would resolve but an agent would not)?
+
+## Dual-audience design
+
+Modern docs serve human readers and machine consumers. The practices that serve both: clear structure, consistent terminology, modular organization, explicit metadata. Check:
+
+- Are headings semantic and unique (not generic "Overview" repeated across pages)?
+- Is front matter present (title, description, version, category)?
+- Are API references generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
+
+## Docs-as-context
+
+Documentation is increasingly a runtime input to AI systems (system-prompt embedding, RAG retrieval, vector search). Check:
+
+- Is clean, navigation-chrome-free text available for context-window injection?
+- Are code examples complete and runnable (agents execute what they read)?
+- Is terminology consistent so a model trained on the docs retrieves accurately?

package/content/distilled/research-documentation/references/metrics.md

@@ -0,0 +1,42 @@
+# Documentation Quality Metrics
+
+Use in Step 4 to recommend measurement signals. The single most important metric is time-to-first-success; the rest build the feedback loops that keep docs honest. Source: `content/research-finding-library-docs-best-practices.md` (Section 7, Measuring Documentation Quality).
+
+## Key metrics
+
+- **Time-to-first-success (TTFS).** Time from a developer's first encounter with the docs to their first successful use of the library/API. Measure via user testing, analytics (first page view to first successful API call), or surveys. This is the headline number.
+- **Support ticket deflection.** Percentage of support questions answered by docs rather than a human. Quantifies economic value; track the ratio of tickets to page views, or add "Did this page answer your question?" widgets.
+- **Page engagement.** Time on page, scroll depth, return visits. High bounce on getting-started may mean unmet expectations; low time on reference may mean fast finds (good) or frustration (context matters).
+- **Search analytics.** Track queries, click-through rates, and "no results" queries. No-results queries are direct evidence of missing docs. High click-through to a page means it is well-titled and relevant.
+- **Broken link rates.** Percentage of internal/external links returning 404. Automated link checking should run on every deployment (see `doc-link-verifier` skill).
+- **Documentation coverage.** Percentage of public APIs/endpoints/features that have docs. Measurable automatically for API reference (OpenAPI vs. documented endpoints) and code docs (docstring coverage via `interrogate`).
+- **Page freshness.** Age of a doc page relative to the last code change that touched the documented feature. Stale docs are a leading frustration indicator.
+
+## User testing and feedback loops
+
+- **Usability testing.** Watch representative users attempt tasks using only the docs. Even informal tests reveal problems invisible to authors.
+- **Inline feedback widgets.** "Was this page helpful?" at the bottom of pages. Act on it: low-rated pages get prioritized.
+- **GitHub issues and discussions.** Questions already answered in docs indicate the docs are not discoverable or clear enough.
+- **Developer surveys.** Periodic structured feedback on quality, gaps, and priorities.
+- **Community channels.** Repeated questions in Discord/Slack/Stack Overflow are strong gap signals.
+
+## Automated quality tools (CI/CD)
+
+- **Vale** — prose linter enforcing style-guide rules (passive voice, jargon, inconsistent terminology).
+- **markdownlint** — Markdown formatting consistency.
+- **htmlproofer / lychee** — internal and external link checking on every deployment.
+- **interrogate** (Python) — docstring coverage reporting.
+- **cspell / aspell** — spell checking.
+- **Lighthouse** — page performance, accessibility, SEO, best practices in CI.
+
+A practical pipeline: on every PR run markdownlint + Vale + cspell + example tests; on every deployment run link checking + Lighthouse; weekly run a full broken-link crawl, coverage report, and freshness report; monthly review user feedback and search analytics.
+
+## Building a quality culture
+
+Metrics are necessary but not sufficient. Culture is the larger factor:
+
+- Add "docs updated" checkboxes to PR templates.
+- Allocate explicit sprint time (15-20%) to documentation and refactoring.
+- Apply "you touch it, you document it" — the author of a code change owns the doc update.
+- Assign a named owner to every documentation section.
+- Celebrate documentation contributions the same way as code contributions.

package/content/distilled/research-documentation/references/report-template.md

@@ -0,0 +1,42 @@
+# Documentation Research Report Template
+
+Output structure for the final report (Step 5). Keep the section order stable so reports can be compared across projects.
+
+```markdown
+# Documentation Research: [Project Name]
+
+## 1. Executive Summary & Core Assertion
+**Core Assertion:** [The one-sentence hook]
+**Status:** [Summary of current architecture health]
+
+## 2. Diátaxis Matrix
+| Quadrant | Existing Topics | Proposed/Missing Topics |
+| :--- | :--- | :--- |
+| **Tutorial** | | |
+| **How-to** | | |
+| **Reference** | | |
+| **Explanation** | | |
+
+## 3. Snowflake Structural Map
+- **Macro-Journey:** [Description]
+- **Key Components:** [List]
+
+## 4. EPPO & Cognitive Audit
+- **Frankenbooks Found:** [List of files with mixed intent]
+- **Context Gaps:** [Topics needing better orientation]
+
+## 5. AI-Readiness Assessment
+- [ ] `llms.txt` present?
+- [ ] Explicit semantic labeling for RAG?
+- [ ] MCP/agent manifests identified?
+
+## 6. Measurement Signals
+- [ ] TTFS measurable today?
+- [ ] Search analytics available?
+- [ ] Coverage / freshness tracked?
+
+## 7. Recommended Next Steps
+1. [Actionable structural change]
+2. [Actionable topic creation]
+3. [Actionable measurement setup]
+```

package/content/distilled/review-documentation/SKILL.md

@@ -0,0 +1,49 @@
+# Review Documentation Quality
+
+Perform a Rule of 5 review of the documentation using the Unified Frameworks for Technical Information Architecture.
+
+## Core Rules
+
+- You are a reviewer, not a writer. Flag issues with locations; do not rewrite content.
+
+## Procedure
+
+Perform 5 iterative passes. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged.
+
+### Pass 1: Diátaxis & Intent
+
+Goal: does this topic have a single, clear intent? Checks: is it a Tutorial, How-to, Reference, or Explanation? Are there leaked intents (e.g., too much theory in a Tutorial)? Issue prefix: [INTENT-001].
+
+### Pass 2: EPPO & Standalone Utility
+
+Goal: can a foraging reader land here and succeed? Checks: are context and prerequisites established in the first two sentences? Does it rely on "previous chapter" knowledge without links? Issue prefix: [EPPO-001].
+
+### Pass 3: Cognitive Scannability (Info Mapping)
+
+Goal: can the reader scan the page in under 10 seconds and find the key answer? Checks: are descriptive labels used for every 2-3 paragraphs? Are paragraphs chunked into small units? Are tables and lists used for complex data? Issue prefix: [SCAN-001].
+
+### Pass 4: Accuracy, "Whole Game" & Fail-States
+
+Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? Issue prefix: [ACC-001].
+
+### Pass 5: Excellence & AI-Readiness
+
+Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Issue prefix: [EXCL-001].
+
+## Final Report
+
+- Total Issues by Severity (Critical, High, Medium, Low).
+- Top 3 Findings.
+- Verdict: Ready, Needs Revision, or Needs Rework.
+- Rationale.
+
+## Rules
+
+- Reference exact locations (file, section, paragraph).
+- Validate issues exist; do not flag "potential" issues without evidence.
+- The canonical theory lives in `content/research-documentation-frameworks.md`; `references/ai-readiness-criteria.md` is an operational excerpt that links back to it.
+
+## Related Skills
+
+- `research-documentation` — architecture-level gaps.
+- `implement-documentation` — fixing what the review finds.

package/content/distilled/review-documentation/references/ai-readiness-criteria.md

@@ -0,0 +1,38 @@
+# AI-Readiness Criteria (Pass 5)
+
+Deep checks for Pass 5. The basic pass (TL;DR present, headers unique, Answer First) catches surface issues; these checks catch whether the page is actually consumable by an AI agent. The canonical theory is `content/research-documentation-frameworks.md` (section "Machine Readability").
+
+## LLM-friendly structure
+
+- Is there a concise TL;DR (1-2 sentences) at the top suitable for context-window injection?
+- Is the page free of navigation chrome when exported (menus, footers, ads) so the body text is clean?
+- Is prose minimalist and high-signal? Verbose docs cost more and retrieve worse.
+
+## RAG-compatible chunking
+
+- Does the page cover one well-defined topic so it chunks cleanly for retrieval?
+- Are section headings stable and unique so a chunk can be addressed precisely?
+- Is there redundant cross-page duplication that would pollute retrieval results?
+
+## Semantic headers
+
+- Are headers descriptive of content, not generic ("Overview", "Details")?
+- Are headers unique across the site so a model can disambiguate?
+- Is front matter present (title, description, version, category) for indexing?
+
+## Dual-audience precision
+
+- Is language precise enough for a machine? Natural-language ambiguity a human resolves from context is opaque to an agent.
+- Are error conditions and their meanings explicit?
+- Are capability boundaries stated (what the tool/API can and cannot do)?
+
+## Schema and spec sync (reference pages)
+
+- For API reference: is it generated from or synchronized with a machine-readable spec (OpenAPI, AsyncAPI, JSDoc/TypeDoc, Sphinx autodoc)?
+- For tool/agent docs: are MCP manifests and agent cards present with precise descriptions and JSON schemas for inputs/outputs?
+- Are code examples complete and runnable? Agents execute what they read; partial snippets mislead.
+
+## Site-level (flag only if the page is the canonical entry)
+
+- Is a `llms.txt` present at the documentation root and does it reference this page where authoritative?
+- Are canonical URLs set so a model retrieves the current stable version?

package/content/distilled/whisper/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: whisper
+description: "Manage the ~/.whisper/ knowledge workspace: init, check, status, link plan to beads, decommission, and knowledge routing. Trigger when the user says '/whisper', '/w', 'init workspace', 'check workspace', 'workspace status', 'link plan', or 'decommission worktree'."
+tools: Read, Write, Edit, Bash
+---
+
+# Whisper — Accumulated Operational Knowledge
+
+Manage `~/.whisper/` — a global, tiered knowledge directory that accumulates operational knowledge and planning context across all your work. Works with or without beads issue tracking.
+
+## Directory Layout
+
+```
+~/.whisper/
+  rules.md                          ← Global agent behavior rules (bd remember equiv)
+
+  repos/
+    github.com/user/repo/
+      env.md                        ← Repo-wide: deploy commands, infra facts, auth quirks
+      branches/
+        branch-slug/                ← One slot per branch (/ in name → -- in slug)
+          context.md                ← Branch anchor: repo, branch, beads epic ID, status
+          plan.md                   ← Narrative implementation plan
+          notes.md                  ← Free-form scratch and findings
+          agents/                   ← Optional sub-agent files when work is split across agents
+      worktrees/
+        worktree-name/              ← One slot per worktree (basename of worktree path)
+          env.md                    ← Worktree-specific: ports, venvs, credentials, local-only setup
+```
+
+**Branch slug rule:** `git rev-parse --abbrev-ref HEAD | sed 's|/|--|g'`
+
+**Worktree slot rule:** `basename $(git rev-parse --git-common-dir 2>/dev/null)` (the `.git` worktree dir name), or `basename $(pwd)` when not in a worktree.
+
+## Knowledge Routing
+
+When a session learns something worth keeping, route it by scope:
+
+| Scope | Test | Destination |
+|---|---|---|
+| **Global** | True for every repo and every project | `~/.whisper/rules.md` — append, don't overwrite |
+| **Repo-wide infra** | True regardless of which branch or feature you're on (deploy behavior, gateway/timeout limits, log retention, auth quirks) | `~/.whisper/repos/<host>/<repo>/env.md` — create or extend |
+| **Branch-specific** | Only matters for the work on *this* epic/branch | `~/.whisper/repos/<host>/<repo>/branches/<slug>/notes.md`, or `bd note <epic-id>` if beads is available |
+| **Worktree setup** | Credentials, service IDs, ports, venv/docker specifics for *this checkout* | `~/.whisper/repos/<host>/<repo>/worktrees/<name>/env.md` |
+| **Universal agent rule** | A standing instruction for how the agent should behave, independent of any branch or repo | `bd remember` if available, else `~/.whisper/rules.md` |
+
+**Rules:**
+- **No secrets anywhere.** Never write tokens, keys, passwords, or PII into `~/.whisper/`.
+- **Extend, don't duplicate.** Append to or correct an existing note rather than creating a new one that says the same thing.
+- **Search first.** Before creating a new entry, check if one already exists for the same topic.
+- If `bd` is not available, everything falls back to `~/.whisper/` files — there's no beads-backed alternative.
+
+## Modes
+
+Determine mode from how the skill is triggered:
+
+| Trigger | Mode |
+|---|---|
+| `/w init` or `~/.whisper/` does not exist | **init** |
+| `/w` or `/w status` | **status** |
+| `/w check` or called by `renew` | **check** |
+| `/w link [<path>]` or "link plan" | **link** |
+| `/w decommission` | **decommission** |
+
+See each reference file for the full procedure:
+
+- `references/init.md`
+- `references/check.md`
+- `references/status.md`
+- `references/link.md`
+- `references/decommission.md`
+
+## Rules
+
+- Never run `git worktree remove` automatically — always print the command for the user to execute.
+- Never close beads issues during decommission — only defer. Closing is intentional.
+- **One epic per branch, children via `--parent`, not flat siblings.**
+- **`env.md` is shared and immutable across branch switches.** Never overwrite it during init or check — only create if absent.
+- **Branch slug sanitization is mandatory.** Always run `sed 's|/|--|g'` on the branch name before using it as a directory path.
+- **Worktree reuse across branches is normal, not an edge case.** Expect multiple slots to accumulate in `branches/` over time.
+- **Legacy layout is still the common case.** Most worktrees never needed multiple branch slots — only migrate when a mismatch is detected.
+- This skill is self-contained. Do not rely on `create-plan`, `park`, or `create-handoff` having `~/.whisper/` awareness.
+- If `bd` is not initialized in the repo, skip beads steps gracefully and note what was skipped.