docs(todo): add make-remove fzf-picker task

Captures the design discussion for an interactive Makefile target that
lists installed rulesets and removes selected entries via fzf. Granular
alternative to the bulk make uninstall.

1 files changed, 1130 insertions, 0 deletions

diff --git a/todo.org b/todo.org
index b936ead..763b646 100644
--- a/todo.org
+++ b/todo.org
@@ -5,6 +5,1074 @@
 Tracking TODOs for the rulesets repo that span more than one commit.
 Project-scoped (not the global =~/sync/org/roam/inbox.org= list).
 
+* TODO [#A] Build =create-documentation= skill for high-quality project/product docs
+
+Create a Claude skill named =create-documentation= that can plan, write,
+refresh, and review software documentation across README files, project docs,
+developer guides, API docs, operational docs, and generated/published doc
+sites.
+
+This is broader than =arch-document=. =arch-document= should remain the
+architecture-specific arc42 skill. =create-documentation= should know when to
+delegate to it for architecture documentation, but its main job is the full
+documentation system around a product or repo: onboarding, tutorials, how-to
+guides, reference, explanation, operations, troubleshooting, contribution,
+release/upgrade, and publication format.
+
+** Why this matters
+
+The repo currently has strong skills for architecture, testing, review,
+debugging, and workflow. It does not have a general documentation skill that:
+
+- Chooses the right documentation type for the user need.
+- Audits existing docs against code and expected user journeys.
+- Creates a coherent doc map instead of dumping everything into =README.md=.
+- Writes in a consistent technical style.
+- Decides source/publish format intentionally (=.md=, =.org=, generated
+  =.html=, OpenAPI, etc.).
+- Treats docs as a maintained product surface with verification, ownership,
+  navigation, accessibility, and freshness checks.
+
+** Research notes
+
+*** Documentation frameworks and best-practice sources
+
+- Diataxis separates documentation by reader need:
+  - Tutorials: learning-oriented, take the reader by the hand.
+  - How-to guides: task-oriented, solve a specific real problem.
+  - Reference: information-oriented, accurate and complete lookup material.
+  - Explanation: understanding-oriented, concepts, background, tradeoffs.
+  Source: [[https://diataxis.fr/][Diataxis]] and the official guidance around
+  tutorials/how-to/reference/explanation.
+- Django explicitly documents this same organization and teaches readers how
+  to navigate it: tutorials for beginners, topic guides for concepts,
+  reference for APIs, how-to guides for recipes. This is a major reason the
+  docs feel navigable despite large scope.
+  Source: [[https://docs.djangoproject.com/en/5.2/][Django documentation]]
+- Kubernetes separates concepts, tasks, tutorials, and reference. It also has
+  current/previous-version docs, localization, contribution paths, and
+  task-focused landing pages. Its docs are good at answering "what is this?"
+  separately from "how do I do one thing?"
+  Sources: [[https://kubernetes.io/docs/home/][Kubernetes docs home]],
+  [[https://kubernetes.io/docs/tasks/][Kubernetes tasks]],
+  [[https://kubernetes.io/docs/tutorials/][Kubernetes tutorials]]
+- Write the Docs emphasizes docs that are precursory, participatory,
+  exemplary, consistent, current, discoverable, addressable, cumulative, and
+  comprehensive. Especially important: incorrect docs are worse than missing
+  docs, and examples should cover common use cases without overwhelming the
+  reference.
+  Source: [[https://www.writethedocs.org/guide/writing/docs-principles/][Write the Docs principles]]
+- Google developer docs guidance emphasizes project-specific style first,
+  clarity and consistency, conversational but not frivolous tone, active voice,
+  second person, descriptive links, global audience, accessibility, sentence
+  case headings, numbered lists for procedures, code font for code, and alt
+  text for images.
+  Sources: [[https://developers.google.com/style/][Google developer documentation style guide]],
+  [[https://developers.google.com/style/highlights][Google style highlights]],
+  [[https://developers.google.com/style/accessibility][Google accessible docs]]
+- Google's doc best-practices page adds a pragmatic maintenance principle:
+  minimum viable documentation, update docs with code, delete dead docs, prefer
+  good over perfect, tell the story of code, and avoid duplication.
+  Source: [[https://google.github.io/styleguide/docguide/best_practices.html][Google documentation best practices]]
+- The Good Docs Project is useful as a template source, especially for
+  README, how-to, tutorial, concept, reference, troubleshooting, contributor,
+  and release-note patterns. Do not vendor wholesale; use as prior art.
+  Source: [[https://www.thegooddocsproject.dev/][The Good Docs Project]]
+
+*** Praised project docs to analyze and steal from
+
+**** Django
+
+Why it works:
+- It labels the doc types directly and explains when to use each.
+- It has a beginner path, advanced tutorials, topic guides, API reference,
+  how-to recipes, deployment, security, testing, release notes, and community
+  help in one coherent index.
+- It is versioned, so readers know which framework version the docs target.
+- It cross-links introductory material to deeper references without making the
+  first page a wall of every detail.
+
+Patterns to use:
+- Make the top-level docs home a routing page by reader intent.
+- Put "How these docs are organized" near the top when the doc set is large.
+- Split concept, task, tutorial, and reference instead of mixing them.
+- Include "getting help" and "not found?" paths so the docs have an exit ramp.
+
+Source: [[https://docs.djangoproject.com/en/5.2/][Django documentation]]
+
+**** Kubernetes
+
+Why it works:
+- It has a large, complex product but maintains separate lanes for Concepts,
+  Tasks, Tutorials, Reference, and Contribute.
+- Task pages are short sequences for one operation; tutorials are larger goals
+  with several sections. This prevents "one page tries to teach everything."
+- It exposes version state clearly, including static old versions and current
+  docs.
+- It supports localization and documentation contribution, which makes the
+  docs a product surface rather than a side artifact.
+
+Patterns to use:
+- For platform or infrastructure docs, include Concepts / Tasks / Tutorials /
+  Reference as first-class folders.
+- Create version/freshness metadata when docs are tied to released software.
+- Add doc contribution guidance for projects with external contributors.
+- Make operational tasks discoverable by category, not just search.
+
+Sources: [[https://kubernetes.io/docs/home/][Kubernetes docs home]],
+[[https://kubernetes.io/docs/tasks/][Kubernetes tasks]]
+
+**** Rust
+
+Why it works:
+- Rust has a "bookshelf" rather than one overloaded manual: The Book, Rust by
+  Example, standard library API reference, Reference, Cargo Guide, Error Index,
+  Rustonomicon, release notes, platform support, policies, etc.
+- The learning path is honest about audience: "assume programmed before, not in
+  any specific language."
+- Reference and learning material are separated. Advanced unsafe guidance gets
+  its own book.
+- Offline docs via =rustup doc= are treated as part of the product.
+
+Patterns to use:
+- For broad ecosystems, create a documentation bookshelf rather than a single
+  mega-doc.
+- Separate beginner path, examples, formal reference, advanced/unsafe topics,
+  tooling docs, error index, release notes, and policies.
+- Document assumptions about reader experience.
+- Consider offline/local docs for CLI/library ecosystems.
+
+Source: [[https://doc.rust-lang.org/][Rust documentation]]
+
+**** Stripe API docs
+
+Why it works:
+- The API reference is organized around resources and common cross-cutting
+  concerns: authentication, errors, idempotency, pagination, request IDs,
+  versioning, metadata, connected accounts.
+- It pairs prose with concrete request/response examples and client-library
+  language selection.
+- It exposes test-mode vs live-mode distinctions early.
+- It offers "Copy for LLM" / "View as Markdown", which acknowledges modern
+  consumption patterns without sacrificing normal docs UX.
+- Its reputation comes from matching developer mental models and making the
+  common path implementable quickly, not just visual polish.
+
+Patterns to use:
+- API docs should be generated from or checked against OpenAPI/JSON schema or
+  source annotations wherever possible.
+- Keep cross-cutting API behavior near the front, before endpoint lists.
+- Include runnable examples, auth, errors, pagination, versioning, idempotency,
+  and sandbox/test data.
+- Consider LLM-friendly exports (=llms.txt=, "view as Markdown", stable
+  anchors), but do not make the docs only for AI.
+
+Source: [[https://docs.stripe.com/api][Stripe API Reference]]
+
+**** FastAPI
+
+Why it works:
+- Documentation is part of the framework's value proposition: OpenAPI and JSON
+  Schema drive interactive Swagger UI and ReDoc automatically.
+- It reduces manual drift for API reference by deriving docs from typed code.
+- It integrates examples and tutorial-style explanations with standards-based
+  generated reference.
+
+Patterns to use:
+- Prefer generated API reference from code/specs over hand-maintained endpoint
+  tables.
+- Generated docs need human-written overview, concepts, authentication,
+  examples, and operational guidance around them.
+- The skill should identify when an OpenAPI/Swagger/ReDoc/Scalar route already
+  exists and improve metadata/schema quality instead of creating duplicate
+  manual docs.
+
+Source: [[https://fastapi.tiangolo.com/features/][FastAPI features]]
+
+** Format and presentation decisions
+
+*** Default source format: Markdown
+
+Use =.md= as the default for shared project documentation when:
+- The repo is on GitHub/GitLab/Forgejo and readers browse docs in the web UI.
+- The project already uses MkDocs, Docusaurus, VitePress, Sphinx+MyST,
+  Jekyll, GitHub Pages, or plain README-driven docs.
+- Contributors are expected to edit docs without Emacs-specific tooling.
+- The docs need easy static-site publishing.
+- The content is README, tutorial, how-to, reference, troubleshooting,
+  contributing, release notes, runbooks, or ordinary prose + code blocks.
+
+Markdown source works well because it is low-friction, reviewable in diffs,
+rendered by repository hosts, and supported by documentation site generators.
+MkDocs is a good reference point: Markdown source, YAML config, built-in dev
+server, static HTML output, and easy hosting.
+Source: [[https://www.mkdocs.org/][MkDocs]]
+
+*** Use Org when the document is Emacs-native or personal/planning-heavy
+
+Use =.org= when:
+- The user's workflow is explicitly Emacs/org-mode.
+- The document contains TODO states, schedules, priorities, tags, agenda
+  integration, property drawers, clocking, or personal planning.
+- The document is an internal strategy/planning artifact such as V2MOM,
+  research notes, meeting notes, task triage, or a living personal operating
+  document.
+- The output may later be exported, but the source of truth is intended to be
+  edited in org-mode.
+
+Do not default team-facing documentation to =.org= unless the team already uses
+org-mode. Org can export to HTML, but that does not make it the right authoring
+format for non-Emacs contributors.
+Sources: [[https://orgmode.org/org.html][Org manual]],
+[[https://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html][Org publish HTML tutorial]]
+
+*** Use HTML as generated/published output, rarely as hand-authored source
+
+Use =.html= when:
+- The deliverable is a published static documentation site.
+- The document needs interactive widgets, embedded API consoles, custom layout,
+  or generated navigation/search.
+- The project already publishes docs as a website.
+- The target audience needs searchable, browsable, linkable pages rather than
+  repo-local files.
+
+Prefer generated HTML from Markdown/Org/reStructuredText/AsciiDoc/OpenAPI over
+hand-authored HTML. Hand-edit HTML only for standalone artifacts, custom landing
+pages, or cases where the project already treats HTML templates as docs source.
+
+*** Consider generated/spec-backed formats
+
+Use generated reference when possible:
+- API reference: OpenAPI/Swagger/ReDoc/Scalar from code/spec.
+- CLI reference: generated from command parser/help output.
+- Library API reference: language-native doc tools such as rustdoc, pydoc,
+  TypeDoc, JSDoc, Go doc, Sphinx autodoc, etc.
+- Config reference: generated from schema, types, or validated defaults.
+
+The skill should not duplicate generated reference by hand. It should improve
+source comments, schema descriptions, examples, front matter, and surrounding
+guides.
+
+*** Presentation requirements
+
+Every generated doc set should have:
+- A docs home or README that routes by reader intent.
+- Stable headings and anchors for addressability.
+- Descriptive link text, no "click here."
+- Search/navigation plan when docs exceed a handful of pages.
+- Version/freshness metadata when tied to released software.
+- Ownership/review cadence for docs likely to rot.
+- Accessible structure: semantic headings, alt text, no image-only info,
+  tables only when appropriate, left-aligned text, readable code blocks.
+- Copyable commands and code examples.
+- "What changed?" / release notes / migration path when docs describe a new or
+  changed behavior.
+- Troubleshooting path for common failures.
+- Clear prerequisites before procedures.
+- Verification steps after procedures.
+- Support/escalation path when the docs do not answer the question.
+- Optional LLM-friendly surfaces for larger doc sets: =llms.txt=,
+  "copy as Markdown" equivalents, concise page summaries, and stable anchors.
+
+** Proposed skill design
+
+*** Skill name and trigger
+
+Name: =create-documentation=
+
+Trigger when the user asks to:
+- create documentation, docs, README, guide, manual, runbook, tutorial,
+  quickstart, API docs, CLI docs, troubleshooting docs, contributor docs,
+  architecture-adjacent docs, release notes, upgrade guide, or doc site;
+- improve, audit, reorganize, or publish existing docs;
+- decide documentation structure or format for a project.
+
+Do not trigger for:
+- architecture-only arc42 docs when =arch-document= is the direct fit;
+- ADR creation (=arch-decide=);
+- design docs before implementation shape is known (=brainstorm= or
+  =arch-design=);
+- prose polishing only (future writing/humanizer skill);
+- inline code comments/docstrings only, unless the user asks to create docs
+  from them.
+
+*** V1 should be one orchestrating skill, not many separate skills
+
+Build v1 as one skill with explicit phases and subcommands rather than a set
+of separate skills. Rationale:
+- Documentation tasks often start ambiguous; the first job is classification.
+- Splitting too early creates command-discovery burden.
+- A single skill can dispatch to existing specialized skills
+  (=arch-document=, =c4-diagram=, =security-check=, =playwright-js/py= for
+  doc-site verification) without making users choose the internal pipeline.
+
+Support discoverable subcommands inside one skill:
+
+#+begin_example
+/create-documentation audit <path>
+/create-documentation plan <path-or-scope>
+/create-documentation write <doc-type> <scope>
+/create-documentation refresh <path>
+/create-documentation publish <path>
+/create-documentation review <path>
+#+end_example
+
+The default =/create-documentation <scope>= runs audit -> plan -> write ->
+review, asking for confirmation before broad rewrites.
+
+*** Future split if v1 gets too large
+
+If the skill grows past a manageable size, split into a discoverable
+=documentation-*= chain. Names and order:
+
+1. =documentation-audit= — inventory existing docs, code/docs drift, reader
+   journeys, missing doc types, stale/generated docs.
+2. =documentation-plan= — choose audiences, doc map, formats, source of truth,
+   publishing path, ownership, and freshness policy.
+3. =documentation-write= — write or update the selected docs.
+4. =documentation-reference= — generate or improve API/CLI/config/library
+   reference from source/spec.
+5. =documentation-publish= — configure MkDocs/Docusaurus/Sphinx/GitHub Pages
+   or equivalent, build static HTML, verify links/search.
+6. =documentation-review= — quality gate for accuracy, style, navigation,
+   accessibility, examples, and freshness.
+
+Keep =create-documentation= as the orchestrator and user-facing entry point.
+The chain is discoverable because every helper starts with =documentation-= and
+the orchestrator prints the next command at each handoff.
+
+** V1 workflow details
+
+*** Phase 1: Intake and classification
+
+Ask only what is missing from local context:
+- Who is the reader? New user, evaluator, integrator, maintainer, operator,
+  contributor, auditor, support engineer?
+- What is the reader trying to do or understand?
+- Is this for a public project, internal team, personal workflow, regulated
+  audience, or customer-facing product?
+- Is the output repo-browsed, web-published, printed/exported, or Emacs-native?
+- Is there existing code, existing docs, an API spec, generated reference, or
+  only a concept?
+- What is the maintenance expectation? One-off, release-maintained,
+  continuously updated?
+
+Classify the work into one or more doc types:
+- README / landing page.
+- Quickstart.
+- Tutorial.
+- How-to guide.
+- Concept/explanation.
+- API reference.
+- CLI reference.
+- Configuration reference.
+- Architecture docs (delegate to =arch-document= if arc42/C4/ADR-driven).
+- Operations/runbook.
+- Troubleshooting/FAQ.
+- Upgrade/migration/release notes.
+- Contributor/development docs.
+- Security/compliance docs.
+- Examples/cookbook.
+
+*** Phase 2: Audit existing material
+
+Inventory:
+- =README*=, =docs/=, =doc/=, =site/=, =mkdocs.yml=, =docusaurus.config.*=,
+  =vitepress=, =sphinx=, =docs.rs=, =pkg.go.dev=, OpenAPI specs,
+  generated docs folders, GitHub Pages config, ADRs, architecture docs,
+  examples, scripts, CLI help, package metadata.
+- Existing doc type coverage: tutorial/how-to/reference/explanation.
+- Broken links, stale version numbers, commands that no longer exist,
+  screenshots that may be stale, code snippets not exercised, doc/code drift.
+- Source of truth for generated docs. Flag generated files; do not hand-edit
+  them until source is known.
+- Reader journey gaps: "new user can install?", "first success path?",
+  "operator can recover?", "contributor can run tests?", "API consumer can
+  authenticate and handle errors?"
+
+Use =rg= first. For API/CLI reference, prefer structured sources:
+OpenAPI/JSON Schema, package metadata, command =--help= output, docstrings, or
+language-native documentation tooling.
+
+*** Phase 3: Documentation plan
+
+Write a short plan before broad edits:
+- Audiences and priority order.
+- Proposed doc map/tree.
+- Doc type for each page.
+- Source format decision: =.md= / =.org= / generated spec / generated HTML.
+- Publishing target, if any.
+- Existing docs to preserve, move, merge, or delete.
+- Generated-reference strategy.
+- Ownership and freshness policy.
+- Verification plan.
+
+Stop for confirmation when the plan moves or rewrites more than one file.
+
+*** Phase 4: Write or update docs
+
+Writing rules:
+- Lead with the reader's goal, not the implementation history.
+- Put prerequisites before steps.
+- Use numbered lists for procedures.
+- Use bullets for non-ordered choices.
+- Use active voice and second person for instructions.
+- Keep sentences short and globally readable.
+- Define acronyms on first use.
+- Use code font for commands, file names, env vars, API names, and literals.
+- Use descriptive links.
+- Prefer examples that cover the common path and one meaningful edge/error
+  path.
+- Separate examples/tutorials from dense reference.
+- Avoid stale duplication: link to canonical generated reference instead of
+  copying it.
+- Include expected output after commands where it helps verification.
+- Include cleanup/rollback steps when procedures change state.
+- Include troubleshooting for common failures.
+- Avoid marketing voice in technical docs. State capability and constraints
+  plainly.
+- No AI attribution in docs, examples, comments, generated pages, footers, or
+  screenshots.
+
+Page skeletons:
+
+README / docs home:
+#+begin_example
+# <Project>
+
+<One-paragraph purpose>
+
+## Start here
+- New user: <quickstart>
+- Existing user with a task: <how-to index>
+- API lookup: <reference>
+- Maintainer/operator: <operations/contributing>
+
+## Quick example
+...
+
+## Documentation map
+...
+
+## Support / contributing
+...
+#+end_example
+
+Tutorial:
+#+begin_example
+# Tutorial: <goal>
+
+## What you'll build
+## Prerequisites
+## Step 1 ...
+## Checkpoint
+## Step 2 ...
+## What you learned
+## Next
+#+end_example
+
+How-to:
+#+begin_example
+# How to <task>
+
+## When to use this
+## Prerequisites
+## Steps
+## Verify
+## Troubleshooting
+## Related
+#+end_example
+
+Reference:
+#+begin_example
+# <Thing> reference
+
+## Summary
+## Parameters / options / fields
+## Behavior
+## Errors
+## Examples
+## Version notes
+#+end_example
+
+Explanation:
+#+begin_example
+# <Concept>
+
+## Problem it solves
+## Mental model
+## How it fits with related concepts
+## Tradeoffs and constraints
+## Further reading
+#+end_example
+
+Runbook:
+#+begin_example
+# Runbook: <operation>
+
+## Scope
+## Preconditions
+## Normal procedure
+## Verification
+## Rollback
+## Alerts and escalation
+## Post-incident notes
+#+end_example
+
+*** Phase 5: Presentation and publishing
+
+If docs are repo-local only:
+- Ensure links render on GitHub/GitLab.
+- Keep relative links stable.
+- Add an index if more than 4-5 docs exist.
+
+If docs are web-published:
+- Detect existing generator and follow it.
+- Prefer project-native tooling over introducing MkDocs/Docusaurus/Sphinx.
+- If no tooling exists and user wants a site, choose conservatively:
+  - Python/simple repo: MkDocs Material is a pragmatic default.
+  - JS/React ecosystem: Docusaurus or VitePress if already in stack.
+  - Python libraries: Sphinx or MkDocs depending on existing ecosystem.
+  - API docs: ReDoc/Swagger/Scalar from OpenAPI.
+- Build locally if dependencies exist.
+- Check links, nav, search, mobile viewport, and accessibility basics.
+- Do not commit generated =site/= output unless the project already does.
+
+*** Phase 6: Verification
+
+Verification should match doc type:
+- Commands in quickstarts/how-tos: run them or mark not run with reason.
+- Code snippets: compile/run where feasible, or use fenced language and note
+  assumptions.
+- API docs: validate OpenAPI/spec if tooling exists.
+- Links: run link checker if configured; otherwise sample-check changed links.
+- Published site: build docs and inspect output.
+- Screenshots: verify current UI if included.
+- Generated docs: regenerate from source and confirm no unexpected diff.
+
+Final report must say:
+- Files created/changed.
+- Doc types covered.
+- Format/source-of-truth decisions.
+- What was verified.
+- What could not be verified.
+- Known gaps/follow-ups.
+
+** Relationship to existing skills
+
+- =arch-document=: use when the requested docs are specifically architecture
+  docs from brief + ADRs + C4/arc42. =create-documentation= may call it, then
+  wrap the output in a broader docs map.
+- =c4-analyze= / =c4-diagram=: use for diagrams in architecture or concept
+  docs when visual structure helps.
+- =brainstorm=: use before =create-documentation= when the product/feature
+  itself is still unclear.
+- =arch-design= / =arch-decide=: use when documentation reveals missing
+  architectural choices.
+- =security-check=: use when docs include security guidance, auth, secrets,
+  deployment, or compliance claims.
+- =playwright-js= / =playwright-py=: use to verify published doc sites,
+  interactive docs, screenshots, and browser-rendered examples.
+- =codify=: use after a documentation session reveals reusable project-specific
+  documentation rules.
+
+** Quality bar and anti-patterns
+
+The skill should reject:
+- A giant README that mixes tutorial, reference, architecture, and operations.
+- Duplicating generated API/CLI/config reference by hand.
+- Unverified commands in quickstarts without a "not run" note.
+- Screenshots with no alt text or no update path.
+- Tables used for layout instead of actual tabular data.
+- "Overview" pages that do not route readers to tasks.
+- Tutorials that become reference dumps.
+- How-to guides that explain concepts for pages before giving steps.
+- Reference pages that hide required options in prose.
+- Marketing claims without concrete examples.
+- Docs that mention local private paths, personal tooling, or AI attribution in
+  public artifacts.
+- Publishing generated HTML as source unless the project explicitly owns HTML
+  docs that way.
+
+** Acceptance criteria for building the skill
+
+- [ ] Directory =create-documentation/= with =SKILL.md=.
+- [ ] Frontmatter description includes positive and negative triggers.
+- [ ] Skill body includes the V1 phases above.
+- [ ] Includes a source-format decision table for =.md= / =.org= / =.html= /
+  generated spec/reference.
+- [ ] Includes doc-type classifier based on Diataxis plus README/runbook/API
+  additions.
+- [ ] Includes examples/skeletons for README, tutorial, how-to, reference,
+  explanation, runbook, troubleshooting, contributor docs, and API overview.
+- [ ] Includes audit checklist for existing repos.
+- [ ] Includes publishing guidance without hardcoding one static-site tool.
+- [ ] Includes verification checklist and "unable to verify" reporting.
+- [ ] Cross-references =arch-document=, =brainstorm=, =security-check=,
+  =playwright-js=, =playwright-py=, and =codify=.
+- [ ] Adds =references/= only if needed; suggested files:
+  - =references/doc-type-decision.md=
+  - =references/style-guide.md=
+  - =references/format-decision.md=
+  - =references/page-skeletons.md=
+  - =references/doc-audit-checklist.md=
+- [ ] Keep =SKILL.md= concise enough to load; move long skeletons/checklists to
+  references for progressive disclosure.
+- [ ] Run =./scripts/lint.sh= after adding the skill.
+
+** Open design questions before implementation
+
+- Should the user-facing command be exactly =/create-documentation= while
+  internal helper names use =documentation-*=, or should all names share the
+  =create-documentation <subcommand>= form? Recommendation: one skill with
+  subcommands for v1.
+- Should Markdown be the hard default for team docs? Recommendation: yes,
+  unless the project already uses org/reST/AsciiDoc or the output is personal
+  Emacs-native planning.
+- Should the skill create a docs site automatically? Recommendation: no. It
+  should propose a site when the doc set exceeds README-scale or when search,
+  versioning, or public publishing is required. Ask before adding tooling.
+- Should it write docs before code exists? Recommendation: yes for specs,
+  user journeys, and design docs, but route unclear feature/product decisions
+  through =brainstorm= or =arch-design= first.
+- Should it include LLM-specific docs surfaces? Recommendation: optional for
+  public/library/API docs: =llms.txt= or markdown export is valuable, but normal
+  human navigation remains primary.
+
+* TODO [#A] Review pass: tighten skills and rulesets after 2026-05-04 audit
+
+Source notes used in this pass:
+- C4 official docs: C4 is notation-independent; System Context and Container
+  diagrams are enough for most teams; every diagram needs title, key/legend,
+  explicit element types, and audience-appropriate abstraction.
+  [[https://c4model.com/diagrams][C4 diagrams]],
+  [[https://c4model.com/diagrams/notation][C4 notation]],
+  [[https://c4model.com/abstractions/component][C4 component]]
+- arc42 docs: quality requirements need measurable scenarios; section 10
+  should reference top quality goals and capture lesser quality requirements
+  with specific measures. [[https://docs.arc42.org/section-10/][arc42 section 10]],
+  [[https://quality.arc42.org/articles/specify-quality-requirements][specifying quality requirements]]
+- ADR references: ADRs capture one justified architecturally significant
+  decision and its rationale; Nygard's original guidance emphasizes short,
+  numbered, repository-stored records and superseding rather than rewriting old
+  decisions. [[https://adr.github.io/][adr.github.io]],
+  [[https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions][Nygard ADR article]]
+- Playwright docs: prefer user-visible locators and web assertions; locators
+  auto-wait and retry; =networkidle= is discouraged for testing readiness.
+  [[https://playwright.dev/docs/best-practices][Playwright best practices]],
+  [[https://playwright.dev/docs/locators][Playwright locators]],
+  [[https://playwright.dev/docs/next/api/class-page][Playwright page API]]
+- OWASP references: Top 10 2021 includes Broken Access Control,
+  Cryptographic Failures, Injection, Insecure Design, Security
+  Misconfiguration, Vulnerable and Outdated Components, Identification and
+  Authentication Failures, Software and Data Integrity Failures, Security
+  Logging and Monitoring Failures, and SSRF; WSTG adds a broader testing map
+  across configuration, identity, authn/z, sessions, input validation, error
+  handling, cryptography, business logic, client-side, and API testing.
+  [[https://owasp.org/Top10/2021/][OWASP Top 10 2021]],
+  [[https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/][OWASP WSTG]]
+- V2MOM references: Salesforce calls the last M "Measures" and emphasizes a
+  simple alignment document with prioritized Methods, explicit Obstacles, and
+  measurable outcomes. [[https://trailhead.salesforce.com/content/learn/modules/selfmotivation/get-focused-with-your-personal-v2mom][Salesforce Trailhead personal V2MOM]],
+  [[https://www.salesforce.com/blog/?p=12][Salesforce V2MOM alignment]]
+- Prompt research: the cited Meincke paper is titled "Call Me A Jerk:
+  Persuading AI to Comply with Objectionable Requests"; its scope is
+  persuasion increasing compliance with objectionable requests, not a general
+  proof that persuasion framing improves prompt quality.
+  [[https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5357179][SSRN paper]]
+- Combinatorial testing references: NIST supports t-way combinatorial testing
+  and notes pairwise is one covering strength, with higher-strength arrays
+  useful for failures requiring more interacting factors.
+  [[https://www.nist.gov/publications/practical-combinatorial-testing-beyond-pairwise][NIST beyond pairwise]],
+  [[https://www.nist.gov/publications/combinatorial-software-testing][NIST combinatorial testing]]
+
+** TODO [#A] =playwright-js=: replace raw CSS/page actions and =networkidle= defaults with locator/assertion-first guidance
+
+Current examples lean on =page.click=, =page.fill=, =waitForSelector=, and
+=waitForLoadState('networkidle')=. Official Playwright guidance prefers
+locators based on user-visible attributes, web assertions for readiness, and
+calls =networkidle= discouraged for testing. Keep reconnaissance, but revise it
+to wait for a visible app-specific landmark instead of treating network quiet
+as readiness.
+
+** TODO [#B] =playwright-js= and =playwright-py=: reconcile headless/visible-browser defaults
+
+=playwright-js= says visible Chromium by default; =playwright-py= says
+headless by default. That may be intentional, but the difference should be
+explicit: interactive visual debugging -> headed, CI/pytest smoke tests ->
+headless. Add a small decision table so agents don't flip modes by habit.
+
+** TODO [#B] =playwright-js= and =playwright-py=: remove emoji console markers from examples
+
+The broader rules discourage emojis in shared engineering output. The
+Playwright examples print camera/check/cross emoji. Replace with plain ASCII
+status prefixes.
+
+** TODO [#B] =frontend-design=: make accessibility non-optional and align with WCAG 2.2
+
+The workflow only loads =references/accessibility.md= for interactive
+components. Accessibility should be a baseline for all frontend work: keyboard
+operation, focus visibility/not-obscured, target size, contrast, reduced
+motion, labels, and semantic structure. Add WCAG 2.2-oriented gates before
+handoff.
+
+** TODO [#B] =frontend-design=: harmonize aesthetic guidance with current UI anti-pattern rules
+
+The skill encourages gradient meshes, heavy texture, custom cursors, overlap,
+and maximalist directions. Those can conflict with the repo's newer frontend
+discipline against generic gradients, decorative blobs/orbs, text overlap,
+single-hue palettes, unreadable layouts, and marketing-style dashboards. Add a
+"creative but bounded" section: domain fit, readability, responsive stability,
+and no decorative effects that degrade the task workflow.
+
+** TODO [#A] =security-check=: update OWASP coverage to the 2021 categories and WSTG test areas
+
+The current security checklist uses older category names and misses several
+current Top 10 items: Insecure Design, Software and Data Integrity Failures,
+Security Logging and Monitoring Failures, and SSRF. Expand the review table so
+each finding maps to either OWASP Top 10 2021 or a WSTG area, and add explicit
+checks for authorization object/function-level access, SSRF URL fetches,
+integrity of update/plugin paths, and security-relevant logging gaps.
+
+** TODO [#B] =security-check=: add practical tooling and offline/network caveats
+
+Add optional use of project-configured scanners such as =gitleaks= or
+=trufflehog= for secrets, =semgrep= for source patterns, =pip-audit= / =npm
+audit= / OSV where configured, and lockfile diff review. Note that dependency
+audits may need network access and should report "not run" clearly rather than
+silently passing.
+
+** TODO [#B] =pairwise-tests=: add t-way escalation guidance beyond pairwise
+
+Pairwise is a pragmatic default, but NIST's combinatorial testing work covers
+higher-strength t-way arrays too. Add a rule: start with pairwise for broad
+coverage, escalate selected high-risk parameter clusters to 3-way or higher
+when history, safety, security, or domain reasoning suggests faults require
+more than two interacting factors.
+
+** TODO [#B] =pairwise-tests=: clarify negative value syntax and actual generator availability
+
+The examples use =~0= style values that are PICT-specific and easy to
+misread. Add a short "negative testing values are labels, not operators unless
+PICT treats them specially" explanation, and make the run path honest: if PICT
+or =pypict= is unavailable, produce the model and stop instead of implying
+cases were generated.
+
+** TODO [#A] =create-v2mom=: rename "Metrics" to Salesforce's "Measures" or explicitly justify the deviation
+
+V2MOM's final M is officially "Measures." The skill uses "Metrics" throughout.
+Either rename the section and description to "Measures" or add a clear note
+that this fork intentionally says "Metrics" while preserving the V2MOM concept.
+
+** TODO [#B] =create-v2mom=: prevent task migration from turning V2MOM into a backlog
+
+Salesforce presents V2MOM as a simple alignment framework. This skill's
+optional task-migration phase can make the V2MOM the entire todo system. Split
+strategy from execution: keep the V2MOM concise, and link to method-specific
+backlogs instead of embedding every task under the strategic document.
+
+** TODO [#B] =create-v2mom=: add mitigation/owner fields for Obstacles
+
+The current Obstacles phase captures barriers but not consistently how each
+will be overcome. Add "mitigation, owner, and review cadence" per obstacle so
+the section becomes operational instead of just candid.
+
+** TODO [#A] =prompt-engineering=: correct and narrow the Meincke citation
+
+The skill cites "Persuasion and Compliance in Large Language Models" but the
+paper found in research is "Call Me A Jerk: Persuading AI to Comply with
+Objectionable Requests." Revise the reference and avoid overgeneralizing the
+result: it shows persuasion can raise compliance with objectionable requests,
+which is a cautionary prompt-safety finding, not broad evidence that persuasion
+principles improve engineering prompt quality.
+
+** TODO [#B] =prompt-engineering=: add an evaluation harness requirement for production prompts
+
+Prompt critique currently ends with a rewrite and checklist. Add a requirement
+for fragile or reusable prompts: create 3-5 adversarial/edge examples, run the
+old and new prompt against them, and record the observed behavioral delta.
+Without examples, prompt quality remains asserted rather than verified.
+
+** TODO [#B] =codify=: add stale-entry review and privacy checks before writing project =CLAUDE.md=
+
+The skill has good gates, but it should explicitly scan for stale entries,
+private context, and team-visible leakage before appending. Add "would this be
+safe if the project were public?" and "does this belong in private memory
+instead?" as mandatory checks, not just table background.
+
+** TODO [#A] =review-code=: resolve the local-verification vs CI boundary
+
+=review-code= says "Trust CI for lint, typecheck, test runs; don't re-run
+them." =verification.md= and =finish-branch= require fresh local evidence
+before completion. Clarify: code review should not duplicate CI while reading a
+PR, but pre-commit/pre-push workflows still need local verification or a clear
+"not run because..." statement.
+
+** TODO [#B] =review-code=: handle public-artifact scope when citing =CLAUDE.md=
+
+The skill requires auditing and reporting =CLAUDE.md= adherence, while
+=commits.md= says personal tooling files should not be cited as authority in
+public artifacts. Add two output modes: private/internal review may cite
+=CLAUDE.md= directly; public/team review should translate the rule into the
+underlying engineering reason without naming personal rulesets.
+
+** TODO [#B] =review-code=: relax mandatory "three strengths" for tiny or failing diffs
+
+"Three minimum" strengths can force filler on small diffs or bad PRs. Adjust to
+"up to three specific strengths; say none found when appropriate" so the review
+stays honest and avoids synthetic praise.
+
+** TODO [#A] =respond-to-review=: remove review-process language from commit messages
+
+The skill suggests commits like =fix: Address review — [description]=, which
+conflicts with =commits.md='s "what changed and why, not the process" rule and
+also uses a non-ASCII dash. Replace with conventional subjects that name the
+actual fix, e.g. =fix: validate export filename=.
+
+** TODO [#B] =respond-to-review=: use unresolved review threads and resolution state, not only flat comments
+
+Fetching inline and top-level comments via REST misses thread resolution and
+can re-process already-resolved feedback. Add the same thread-level workflow as
+the GitHub comment-addressing skill: gather unresolved threads, group by
+requested change, implement, reply, and resolve only after verification.
+
+** TODO [#B] =respond-to-cj-comments=: remove personal absolute path references from public-writing instructions
+
+The skill embeds =/home/cjennings/code/rulesets/claude-rules/commits.md= in
+the public-writing section. That contradicts the public-artifact scope rule.
+Refer to "the commit/public-writing rules" internally, and ensure any emitted
+public text never cites the local path.
+
+** TODO [#B] =respond-to-cj-comments=: add fallback when =humanizer= or =emacsclient= is unavailable
+
+The workflow requires =/humanizer= and opens long summaries in =emacsclient=.
+Neither is guaranteed in a fresh environment. Add tool-availability checks and
+fallbacks: apply the style passes inline if =humanizer= is absent, and write the
+summary file path without opening an editor if =emacsclient= fails.
+
+** TODO [#A] =finish-branch=: fix base-branch detection
+
+Phase 2 says "determine base branch" but the command shown returns a merge-base
+commit SHA, not the branch name to check out, pull, merge into, or pass as PR
+base. Replace with explicit branch detection: upstream PR base if present,
+configured default branch from =origin/HEAD=, or user-selected branch, then
+compute merge-base separately.
+
+** TODO [#B] =finish-branch=: make pull/merge steps safer and worktree-aware
+
+Option 1 runs =git pull= and =git merge --no-ff= after checkout. Add checks for
+dirty worktree, upstream tracking, protected branches, and rebase-vs-merge team
+policy. Worktree detection via grepping branch names is fragile; use =git
+worktree list --porcelain= or =git rev-parse --git-common-dir= based checks.
+
+** TODO [#B] =start-work=: add tool-availability and ceremony-scaling rules
+
+The workflow assumes Linear MCP, GitHub CLI, =humanizer=, Playwright skills, and
+multi-commit TDD ceremony. Add a first-class "tools unavailable" path and a
+ceremony scale: trivial local fixes should not require the full ticket,
+branch, three approval gates, and commit-per-phase flow unless the user wants
+that process.
+
+** TODO [#B] =start-work=: resolve the "claim before justify" rollback risk
+
+The skill marks Linear/GitHub/todo tasks in progress before the Justify gate,
+then says rolling back is required if justification fails. Consider moving
+claiming after Gate 1 for personal todo tasks, or make the rollback steps
+explicit per tracker with stored prior state.
+
+** TODO [#B] =add-tests=: fix missing =typescript-testing.md= reference or add the ruleset
+
+Phase 3 references =typescript-testing.md=, but this repo currently has Python
+and Elisp testing rules only. Either add the TypeScript ruleset or change the
+skill to discover project-local JS/TS testing conventions instead of pointing
+to a missing file.
+
+** TODO [#B] =add-tests=: add explicit exceptions to "all three categories per function"
+
+The Normal/Boundary/Error rule is useful, but some functions are pure adapters,
+generated code, tiny wrappers, or framework glue. Add an exception protocol:
+state why a category does not apply, and cover the behavior at the integration
+or E2E level when unit categories would test framework behavior.
+
+** TODO [#B] =debug=: capture environment and recent-change context before hypotheses
+
+The debugging workflow covers reproduction and logs, but should explicitly
+record environment, versions, feature flags, data set, seed/time, concurrency,
+and recent commits/config changes. Many intermittent failures are environment
+or state transitions, not just local code paths.
+
+** TODO [#B] =root-cause-trace=: constrain defense-in-depth to trust boundaries and invariants
+
+The skill says add defense at each intermediate layer that could have caught
+the bad value. That risks validation spam. Tighten it: add checks at ingress,
+trust boundaries, persistence boundaries, and invariant-owning layers; avoid
+duplicative null checks in every pass-through function.
+
+** TODO [#B] =five-whys=: require evidence and counterfactual validation per why
+
+The skill says "one best-supported answer" but should require an evidence
+field for each link and a counterfactual check: if this cause were removed,
+would the next symptom plausibly disappear? This reduces monocausal storytelling.
+
+** TODO [#B] =brainstorm=: add timebox and research/source rules for high-stakes designs
+
+The one-question-at-a-time flow can run long. Add a timebox and a rule that
+claims about markets, regulations, tools, vendors, or current APIs require
+fresh sources. The design doc should distinguish researched facts from
+assumptions.
+
+** TODO [#B] =arch-decide=: make examples technically timeless and avoid unverifiable claims
+
+The sample ADRs include claims such as MongoDB lacking ACID for multi-document
+transactions "at decision time." Examples age and can teach stale facts. Replace
+with either clearly dated examples or domain-neutral placeholders, and require
+references for real technical claims in generated ADRs.
+
+** TODO [#B] =arch-decide=: standardize statuses and immutability language
+
+The skill mixes Accepted, Decided, Deprecated, Superseded, Rejected, and "Not
+Accepted." Pick a canonical status set and state that accepted ADR content is
+not edited except for status/link metadata; changed decisions get new ADRs that
+supersede old ones.
+
+** TODO [#B] =arch-design=: add threat modeling and privacy/compliance as first-class design inputs
+
+Security appears as one quality attribute, but architecture design should also
+ask about trust boundaries, data classification, abuse cases, privacy
+constraints, compliance evidence, and operational ownership. These influence
+architecture early and should not wait for =security-check=.
+
+** TODO [#B] =arch-design=: separate architecture paradigms from tactical patterns
+
+The candidate table mixes paradigms (modular monolith, microservices,
+event-driven) with tactical or partial patterns (DDD, CQRS, event sourcing).
+Revise the matrix so candidates can compose patterns rather than treating each
+as a mutually exclusive architecture choice.
+
+** TODO [#B] =arch-document=: strengthen quality scenarios using arc42/Q42 structure
+
+Section 10 currently says "Under [condition], the system should [response]
+within [measure]." Expand to a compact quality-scenario template: source,
+stimulus, environment, artifact, response, response measure. This better
+matches architecture-quality practice and makes requirements testable.
+
+** TODO [#B] =arch-document=: add staleness and ownership metadata to generated docs
+
+arc42 docs are living documents. Add owner, source commit/date, review cadence,
+and "known stale when..." notes per section or in the README so generated docs
+do not become authoritative after the code has moved on.
+
+** TODO [#B] =arch-evaluate=: add confidence levels for framework-agnostic findings
+
+Claude-read import graphs and public API comparisons can be incomplete in large
+or dynamic languages. Add confidence/provenance per finding and require "not
+fully checked because..." when scale or dynamic imports limit certainty.
+
+** TODO [#B] =arch-evaluate=: report skipped tool checks explicitly
+
+The workflow says skip unconfigured language-specific tools silently, but the
+review checklist also wants checks run. For audit usefulness, list detected
+languages and "tool not configured" entries under Info instead of silent skips.
+
+** TODO [#A] =c4-analyze= and =c4-diagram=: add notation/output fallback instead of draw.io-only
+
+C4 is notation-independent. These skills hard-require draw.io XML, PNG export,
+and opening draw.io desktop. Add supported outputs (Structurizr DSL, Mermaid,
+PlantUML, draw.io) and a fallback path when =drawio= or a GUI is unavailable.
+
+** TODO [#B] =c4-analyze= and =c4-diagram=: clarify C4 abstraction boundaries
+
+Emphasize that C4 Containers are deployable/runnable units, not necessarily
+Docker containers, and that Components are not separately deployable. Add a
+check that every relationship and element stays at one abstraction level.
+
+** TODO [#B] =commits.md=: split DeepSat/Linear/Slack-specific publishing rules from global commit rules
+
+The global commit rule file includes Linear status transitions and a hard-coded
+Slack channel. That is team-specific and may leak or misfire in unrelated
+projects. Move those steps to a project/team overlay, leaving global rules for
+author identity, attribution, commit format, review gate, and verification.
+
+** TODO [#A] =commits.md= and publish flows: define fallback when =humanizer= is unavailable
+
+Several workflows make =humanizer= mandatory, but no =humanizer= skill exists
+in this repo. Either add the skill, install instructions, or a fallback
+plain-English pass that satisfies the same checks without an external skill.
+
+** TODO [#B] =verification.md=: add explicit "unable to verify" reporting standard
+
+The rule says run tests/lint/typecheck/build before claiming done. Add the
+required final wording when a command cannot be run: command attempted, reason
+it could not run, risk left unverified, and the smallest next command for the
+user to run.
+
+** TODO [#B] =testing.md=: add property-based and mutation testing as escalation paths
+
+The testing rules cover categories and pairwise matrices. Add guidance for
+property-based testing when invariants matter across broad input domains, and
+mutation testing when test quality is suspect despite high coverage.
+
+** TODO [#B] =testing.md=: soften absolute TDD with an explicit spike protocol
+
+The rule currently treats TDD as non-negotiable. Keep TDD as the default, but
+define a disciplined spike exception: timebox, do not commit spike code, write
+the first failing test before productionizing the discovered approach.
+
+** TODO [#B] =subagents.md=: add capability/availability and cost checks
+
+The rule assumes subagents exist and should handle failures. Add "if the
+environment lacks subagents, continue locally and preserve the same scope
+boundaries" plus a cost check for tasks where context handoff exceeds the work.
+
+** TODO [#A] =languages/python/claude/rules/python-testing.md=: revisit in-memory SQLite guidance
+
+"Prefer in-memory SQLite for speed in unit tests" is risky for Django or
+SQLAlchemy projects whose production database is PostgreSQL/MySQL; query
+semantics, constraints, transactions, JSON, time zones, and indexes differ.
+Recommend production-like DBs for ORM/query behavior and reserve SQLite for
+pure unit tests that do not depend on database semantics.
+
+** TODO [#B] =languages/python/claude/rules/python-testing.md=: separate "never mock ORM" from true unit-test boundaries
+
+For domain services, real model methods and validation are usually right. For
+thin orchestration units, a repository/interface fake may be cleaner than
+hitting a real database. Clarify the boundary: do not mock ORM internals, but
+do inject fakes at deliberate data-access ports.
+
+** TODO [#B] =languages/elisp/claude/rules/elisp.md=: update editing workflow to avoid tool-specific advice
+
+The rule says prefer Write over repeated Edits. That advice is Claude-tooling
+specific and can conflict with environments that require patch-based edits.
+Rephrase around the intent: for nontrivial Elisp, make cohesive edits and run
+paren/byte-compile checks immediately.
+
+** TODO [#B] =languages/elisp/claude/rules/elisp-testing.md=: add batch-mode and native-comp caveats
+
+ERT guidance is solid, but add rules for =emacs --batch= reproducibility,
+isolating =user-emacs-directory= / package state, and optionally catching
+native-comp or byte-compile warnings depending on the project's Emacs version.
+
+** TODO [#A] =hooks/README.md=: include =destructive-bash-confirm.py= in install/settings snippets
+
+The table documents the destructive-command hook, but the manual install and
+settings JSON snippets only include the commit and PR hooks. Add the destructive
+hook to both snippets so documented installation matches the listed hooks.
+
+** TODO [#A] =hooks/git-commit-confirm.py= and =hooks/gh-pr-create-confirm.py=: inspect message/body files
+
+=commits.md= uses =git commit -F /tmp/commit-*.md= and =gh pr create
+--body-file ...=. The hooks currently treat file-backed messages as
+unparseable or just display the file path, so attribution scanning may miss the
+actual committed/posted text. Read safe local files referenced by =-F=,
+=--file=, and =--body-file= before deciding whether the command is clean.
+
+** TODO [#B] =hooks/destructive-bash-confirm.py=: replace regex command parsing with shell-aware parsing where possible
+
+The hook's regexes can miss quoted paths, variables, aliases, =env= wrappers,
+or compound commands, and can misidentify targets. Use =shlex= for simple
+commands, document unsupported shell constructs, and fail toward asking when a
+destructive pattern is ambiguous.
+
 * TODO [#B] Build =ov-1= skill for DoDAF OV-1 (High-Level Operational Concept Graphic)
 
 Triggered by SOFWeek (May 2026, Tampa) — DeepSat attending; DoD attendees
@@ -398,3 +1466,65 @@ Trigger for building: an actual DoD deliverable that's blocked on not
 having a skill to generate or check OV-1-shaped artifacts. Don't build
 speculatively — defense-specific notations are narrow enough that each
 skill should be driven by a concrete contract need, not aspiration.
+
+* TODO [#B] Add =make remove= for interactive ruleset removal via fzf
+
+Add a Makefile target that lists every currently-installed ruleset entry
+and lets me pick one or more to remove via fzf. Granular alternative to
+=make uninstall= (removes everything) and =make uninstall-hooks= (removes
+only hooks).
+
+** Why this matters
+
+Tearing down a single skill, rule, hook, or config file currently means
+either running =make uninstall= and re-installing what I want to keep,
+or =rm=ing the symlink directly and remembering the exact path. Both are
+friction. An interactive picker lets me filter, multi-select with Tab,
+and confirm with Enter — the typical fzf flow. Costs about 3-5 seconds
+per teardown instead of 15+ seconds of "what's the exact name?".
+
+** Design
+
+The recipe builds a tab-separated list of every currently-installed item,
+categorized by type, and pipes it to =fzf --multi=. The user filters,
+marks with Tab, and confirms with Enter. The recipe parses the selections
+and =rm=s the matching symlinks.
+
+#+begin_example
+  skill     debug
+  rule      commits.md
+  hook      destructive-bash-confirm.py
+  config    settings.json
+  commands  commands
+  bridge    claude-rules
+#+end_example
+
+Each line is =<kind>\t<name>=. The recipe maps =<kind>= to the right path:
+
+- =skill=    → =$(SKILLS_DIR)/<name>=
+- =rule=     → =$(RULES_DIR)/<name>=
+- =hook=     → =$(HOOKS_DIR)/<name>=
+- =config=   → =$(CLAUDE_DIR)/<name>=
+- =commands= → =$(CLAUDE_DIR)/commands=
+- =bridge=   → =$(SKILLS_DIR)/claude-rules=
+
+Source files in =rulesets/= stay untouched. =make install= re-creates the
+removed links if needed (the install loop is idempotent).
+
+** Edge cases
+
+- Esc instead of Enter → empty selection → clean exit, no removal.
+- Filter to nothing then Enter → same as Esc.
+- Selected item already gone → =rm= fails visibly, processing continues
+  on the rest.
+- =fzf= not installed → fail fast with a clear error (matches the pattern
+  used by =install-lang=).
+
+** Possible extensions
+
+- Parallel =make pick-install= target that lists not-yet-installed items
+  and installs the chosen ones. Symmetric UX, same fzf flow.
+- Confirmation prompt when more than N items selected (defense against
+  accidental select-all).
+- =--source= flag that also runs =git rm= against the rulesets source for
+  the selected item. Probably bad idea — too easy to lose work.