linersh 0.5.6 → 1.0.0

package/cli-update-docs/AI-HANDOFF.md

@@ -1,227 +1,99 @@
 # Liner AI Handoff
 
-Last updated: 2026-06-01
+Last updated: 2026-06-25
 
-This handoff summarizes the current Liner state after the 0.5.5 TUI/core release,
-marketing-site launch-prep pass, and 0.5.6 source-extraction hardening prep. It
-is intended for any AI agent continuing the work without the full chat history.
+This is the short orientation document for an AI agent continuing Liner work without the full chat history. It intentionally avoids release-candidate scratch paths and old local worktrees; verify the current checkout with `pwd` and `git status --short` before editing.
 
 ## Current Product State
 
-- `linersh@0.5.5` is published on npm and promoted to `latest`.
-- The published Python core/platform packages are `0.5.5`; matching
-  `linersh-*@0.5.5` platform packages are published on npm and promoted to
-  `latest`.
-- The repo is prepared for `0.5.6` (`pyproject.toml`, `src/liner/__init__.py`,
-  and `packages/tui/package.json`). It needs rebuilt platform packages because
-  the Python core changed.
-- Platform packages are available for macOS arm64/x64, Linux arm64/x64, and Windows x64.
-- The TUI is installed/tested locally from the packed tarball in `/tmp/liner-playwright-test`.
-- The main tested mixtape is `staff-design-engenieer` (typo preserved in the folder name).
-- Clean npm smoke passed with `npx linersh@latest --version`: `liner 0.5.5 (tui)  ·  0.5.5 (core)`.
-
-## Important Local Paths
-
-- Active repo/worktree for this thread: `/Users/arturo/.codex/worktrees/875c/liner`
-- Previous v0.5.5 implementation worktree: `/Users/arturo/.codex/worktrees/44f8/liner`
-- Original Liner project folder: `/Users/arturo/Documents/Projects/Youtube Grabber/liner`
-- Original mixtapes folder: `/Users/arturo/Documents/Projects/Youtube Grabber/liner/mixtapes`
-- CMD-UX copied mixtapes folder: `/Users/arturo/Documents/Projects/CMD-UX/Case Studies/mixtapes`
-- Local TUI test install: `/tmp/liner-playwright-test`
-- 0.5.5 release artifacts: `/tmp/liner-release-artifacts-0.5.5`
-- 0.5.6 release artifacts: `/tmp/liner-release-artifacts-0.5.6`
-- Tested mixtape now moved back to: `/Users/arturo/Documents/Projects/Youtube Grabber/liner/mixtapes/staff-design-engenieer`
-
-## What Was Fixed In This Pass
-
-0.5.6 source-extraction hardening:
-
-- Remote web PDFs are detected before HTML extraction and extracted through the
-  shared PDF helper. This prevents raw `%PDF-` bytes from entering generated
-  source Markdown.
-- Bad web cache entries are purged and refetched when they contain raw PDF
-  bytes, stale PDF URL fallbacks, tiny soft/playwright fallback bodies, or
-  cookie-consent-only text.
-- Server HTML that looks like an empty client-side app shell now raises
-  `JsRenderingRequired`, so existing auto-fallback can try Playwright.
-- Cookie-consent-only output is rejected as unusable, including after Playwright
-  rendering. This is intentionally an honest failure, not an automatic
-  cookie-clicker.
-- Partial compile output now says how many source files are usable versus
-  unavailable placeholders.
-
-0.5.5 TUI/core release:
-
-- Skill bundle resolution for npm installs:
-  - TUI now resolves the bundled `cli-update-docs/SKILL.md` reliably from the installed package.
-  - `LINER_SKILL_PATH` can point either at the skill directory or at `SKILL.md`.
-
-- Playwright/JS rendering onboarding:
-  - First-run TUI flow now asks whether to install JS rendering support after agent/model setup.
-  - Compile results that detect missing Chromium show a `JS rendering needed` callout.
-  - The callout says: `Some pages require headless Chromium to fetch correctly. Press j to run liner setup-js --yes (~150MB).`
-  - Pressing `j` runs setup and retries compile.
-
-- Compile result UX:
-  - Long source lists use an internal viewport with `↑↓` and `pgup/pgdn`.
-  - PhaseRunner done screens use an internal viewport for the final response.
-  - Partial compiles now count as complete when `MIXTAPE.md` is written.
-  - The hub shows `Ready to use — compiled with warnings` when some sources failed.
-  - Pressing Enter on completed Compile opens the existing compile result instead of fetching again.
-  - Recompile/retry is explicit with `r` from CompileView.
-
-- Web extraction fallback:
-  - `trafilatura` crashes are caught.
-  - Web handlers keep useful fallback text where possible and surface a soft warning instead of raw Python errors like `'NoneType' object is not subscriptable`.
-
-- Clean reinstall:
-  - `liner uninstall` was added to the npm shim.
-  - It removes `~/.liner`, npm `_npx`, and Playwright Chromium cache.
-  - It does not remove mixtape project folders.
-
-## Known Gotchas
-
-- The tested mixtape folder is misspelled `staff-design-engenieer`; do not silently rename it unless the user asks, because existing references and copied paths use that spelling.
-- `LINER_BIN` matters during local testing. To test TUI changes plus local Python handler fixes, run the TUI with:
+- Repo version files currently agree on `1.0.0`:
+  - `pyproject.toml`
+  - `src/liner/__init__.py`
+  - `packages/tui/package.json`
+- The npm package is `linersh`; running `liner` opens the TUI and forwards CLI subcommands to the bundled core.
+- The TUI can run agent-backed methodology phases with Claude or Codex, using
+  the tracked skill bundle at `docs/curation-skill/`. During npm packaging, it
+  is copied into `packages/tui/cli-update-docs/`.
+- JS rendering support is optional. `liner setup-js` installs Playwright Chromium; the TUI offers this during onboarding and again when compile detects a source that needs browser rendering.
+- Compilation is the product completion milestone. If `MIXTAPE.md` is written with warnings, the project can still be ready to use with warnings shown.
 
-```sh
-cd /tmp/liner-playwright-test
-LINER_BIN=/Users/arturo/.codex/worktrees/875c/liner/.venv/bin/liner ./node_modules/.bin/liner
-```
+## What Liner Is Building
 
-- Running `./node_modules/.bin/liner` without `LINER_BIN` uses the bundled platform binary, which may not include local Python source edits until platform packages are rebuilt.
-- If Python source changed, publishing only the main `linersh` package is not
-  enough. Rebuild and publish all platform packages at the same version first.
-- Cookie-banner auto-dismissal is not implemented in 0.5.6. The safety net is
-  to reject cookie-only output; a future dismissal pass should keep that final
-  rejection in place.
-- The TUI package generated `packages/tui/cli-update-docs/` during `prepack`; the canonical docs live at repo-root `cli-update-docs/`.
-- The old root `docs/` folder was removed. `LINER-MASTER.md` now lives at `cli-update-docs/LINER-MASTER.md`.
-- The Jhey source URL currently 404s on the live site. The useful archived version is:
-
-```text
-https://web.archive.org/web/20250408204038id_/https://jhey.dev/cheep/rotating-gallery-with-css-scroll-driven-animations/
-```
+Liner creates a hyper-specific corpus that helps a downstream AI agent perform one task better. It is not a generic research collector and not a persona builder.
 
-## Verification Already Run
+The durable artifact set is:
 
-TUI package:
+- `tape.yaml` - source recipe
+- `synthesis.md` - curator framing
+- `working/` - methodology trace
+- `MIXTAPE.md` and `sources/` - compiled consumable context
+- `LINER.md` and root `SKILL.md` - operating layer files that tell future agents how to discover and use the project
 
-```sh
-cd /Users/arturo/.codex/worktrees/875c/liner/packages/tui
-npm run typecheck
-npm run build
-npm test
-npm pack --json
-```
+For the current design rationale, read `docs/tui/TERMINAL_TOOLING_DESIGN_FRAMEWORK.md`. The final section, "Always Last: Arturo As A Designer," should stay at the bottom when updating that document.
 
-Python suite:
+## Current Methodology Shape
 
-```sh
-cd /Users/arturo/.codex/worktrees/875c/liner
-uv run --extra dev pytest
-```
+Phase 1 framing must now produce more than a knowledge map. `working/01-jtbd-and-knowledge-map.md` needs:
 
-Result from the latest full Python run in this pass: `190 passed, 1 deselected`.
+- `Capability Brief`
+- `Required source roles`
+- knowledge map
 
-Release-prep verification:
+Each source role needs role name, why it matters, good evidence, and minimum coverage. This is generic: an Art Director Liner, a medical SEO Liner, and a CI debugging Liner should infer different roles from their task.
 
-```sh
-cd /Users/arturo/.codex/worktrees/875c/liner/packages/tui
-npm ci
-npm run typecheck
-npm test
-npm run build
-npm pack --dry-run
-
-cd /Users/arturo/.codex/worktrees/875c/liner
-python3 -m compileall -q src/liner
-uv run --extra dev pytest
-```
+Phase 2 searches against both the knowledge map and required source roles. Phase 5 includes required source-role fit as a quality test. A source is useful only if fetched content actually supports the role it was kept for.
 
-Results: TUI `92 passed`; Python `179 passed, 1 skipped, 1 deselected`.
+## TUI UX Rules To Preserve
 
-Platform artifact workflow:
+- Enter should advance the primary next action. Preview/log/retry/open actions need their own keys.
+- Long-running work should use the established loading/progress pattern and keep default logs short.
+- Warnings need a recovery route: open, drop, replace, retry, add sources, or continue with a documented limitation.
+- Letter commands must not interfere with typing.
+- Two-option setup/improvement screens should use the shared option style: active orange, inactive gray, selected description white, inactive description gray.
+- Completed compile should open the existing result by default; recompile is explicit.
 
-```text
-Status: latest post-release-prep run is green; check `gh run list --workflow platform-bundles.yml --limit 3` if you need the current run ID.
-Artifacts downloaded to: /tmp/liner-release-artifacts-0.5.5
-Local npm bundle smoke: liner 0.5.5 (tui)  ·  0.5.5 (core)
-```
+## Active Docs
 
-npm release smoke:
+Read these first for product and methodology work:
 
-```sh
-rm -rf ~/.npm/_npx
-npx linersh@latest --version
-# liner 0.5.5 (tui)  ·  0.5.5 (core)
-```
+1. `README.md`
+2. `docs/tui/TERMINAL_TOOLING_DESIGN_FRAMEWORK.md`
+3. `docs/curation-skill/CURATION.md`
+4. `docs/curation-skill/SKILL.md`
+5. `docs/curation-skill/source-finding-tactics.md`
+6. `docs/curation-skill/quality-check-tests.md`
+7. `packages/tui/README.md` if changing user-facing TUI keybindings or flows
 
-## Useful Test Commands
+Marketing-site work has separate docs in `marketing/site/`.
 
-Install the local TUI tarball into the scratch project:
+## Verification Commands
 
-```sh
-cd /tmp/liner-playwright-test
-npm install /tmp/liner-release-artifacts-0.5.5/linersh-darwin-arm64/linersh-darwin-arm64-0.5.5.tgz /tmp/liner-release-artifacts-0.5.5/linersh-tui/linersh-0.5.5.tgz
-```
-
-Run the TUI against the local Python core:
-
-```sh
-cd /tmp/liner-playwright-test
-LINER_BIN=/Users/arturo/.codex/worktrees/875c/liner/.venv/bin/liner ./node_modules/.bin/liner
-```
-
-Force a fresh compile/fetch:
+TUI:
 
 ```sh
-cd /tmp/liner-playwright-test
-LINER_BIN=/Users/arturo/.codex/worktrees/875c/liner/.venv/bin/liner ./node_modules/.bin/liner cache clear --yes
-LINER_BIN=/Users/arturo/.codex/worktrees/875c/liner/.venv/bin/liner ./node_modules/.bin/liner
+npm --prefix packages/tui test -- --run
+npm --prefix packages/tui run typecheck
+npm --prefix packages/tui run build
 ```
 
-Run JS setup explicitly:
+Python/core:
 
 ```sh
-cd /tmp/liner-playwright-test
-LINER_BIN=/Users/arturo/.codex/worktrees/875c/liner/.venv/bin/liner ./node_modules/.bin/liner setup-js --yes
+uv run --extra dev pytest
+python3 -m compileall -q src/liner
 ```
 
-Clean local state for reinstall testing:
+Docs hygiene:
 
 ```sh
-liner uninstall --yes
-npm uninstall -g linersh 2>/dev/null || true
+git diff --check
+rg -n "four tests|five tests|two gates|two human-in-the-loop|current release v0\\.5\\.[56]|EAI-HANDOFF" README.md docs packages/tui/README.md --glob "*.md" --glob "!docs/curation-skill/TUI-BACKLOG.md" --glob "!docs/curation-skill/AI-HANDOFF.md"
 ```
 
-## Documentation State
-
-Canonical docs now live in `cli-update-docs/`:
-
-- `LINER-MASTER.md` — current conceptual and technical overview.
-- `AI-HANDOFF.md` — this document.
-- `TUI-BACKLOG.md` — backlog and done log.
-- `MIXTAPE-FORMAT.md` — tape/mixtape format.
-- `CURATION.md` — methodology.
-- `SKILL.md` and companion files — bundled curation skill.
-
-Package-specific docs still live in `packages/tui/`:
-
-- `packages/tui/README.md`
-- `packages/tui/PUBLISH-CHECKLIST.md`
-- `packages/tui/PLATFORM-BUNDLES.md`
-
-## Suggested Next Work
+## Gotchas
 
-- Deploy the marketing site from `marketing/site` once DNS/Vercel details are ready.
-- Update the public website docs and changelog for 0.5.6 after the release
-  artifacts are ready.
-- Consider a conservative Playwright cookie-banner dismissal pass for common,
-  low-risk labels, while still rejecting cookie-only output if dismissal fails.
-- Consider surfacing extraction mode/body length in the TUI compile details.
-- Consider adding `liner doctor-source <url>` or equivalent single-source
-  diagnostics.
-- Consider adding Wayback as an automatic fetcher tier between Playwright and agent-summary fallback.
-- Add per-source failure actions in CompileView: open URL, drop source, retry one source.
-- Add a regression test for completed Compile opening existing results rather than running `streamCompile`.
+- `docs/curation-skill/` is packaged into the npm TUI, so stale methodology docs become user-facing.
+- Do not update archived research transcripts just to quiet searches.
+- Do not reintroduce "advisor" language for the operating layer. Use artifact names and concrete roles.
+- Do not treat URL existence as source quality. Fetched content quality is the real gate.
+- Before reporting state, separate your edits from pre-existing dirty worktree changes.

package/cli-update-docs/CURATION.md

@@ -6,7 +6,7 @@ A methodology for assembling AI-consumable context bundles that actually work.
 
 ## What this document is
 
-A methodology for building mixtapes — curated bundles of sources designed to give an AI substantive context on a specific topic, so it can produce better answers, better drafts, and better judgments than it would from its training data alone.
+A methodology for building mixtapes — curated bundles of sources designed to help an AI agent perform one hyper-specific task better than it could from its training data alone.
 
 This document is platform-agnostic. It describes *how to curate well*, not how any specific tool implements curation. Liner is one implementation; the methodology applies equally to mixtapes built with other tools or by hand.
 
@@ -43,9 +43,15 @@ Every mixtape moves through the same phases. The phases are ordered because each
 
 ### Phase 1 — Framing
 
-Define the job-to-be-done. Not the topic. The *use case*.
+Define the reusable capability. Not the topic. The *specific thing a future AI agent should be able to do*.
 
-The JTBD is written as a Job Story: **"When [circumstance], I want [motivation], so I can [outcome]."** All three slots are required. The form is permissive on what fills them — a legal, clinical, or engineering Job Story share this shape but no vocabulary. What it guarantees is that no slot can be empty, which raises the floor on what counts as a JTBD before any qualitative judgment kicks in.
+The user-facing prompt is:
+
+> What do you want this Liner to help your AI agent do?
+
+The user may answer in normal language. They do not need to provide source categories, research lanes, or a formal Job Story. Liner's job is to infer those from the desired capability, ask a few targeted follow-up questions only when the capability is under-specified, and then create a source-grounded resource that future AI sessions can load.
+
+Liner still derives an internal job-to-be-done because the downstream phases need a testable target. A Job Story is one useful internal shape: **"When [circumstance], I want [motivation], so I can [outcome]."** The user should not have to know or write this format. The AI may translate the capability into a Job Story silently, then expose the plain-language intent and research plan for review.
 
 "Mobile design" is a topic. It is too vague to curate against. Three Job Stories in that same topic produce three different mixtapes:
 
@@ -53,15 +59,29 @@ The JTBD is written as a Job Story: **"When [circumstance], I want [motivation],
 - *When I review mobile design portfolios as a senior IC hiring manager, I want to compare candidates against a consistent rubric of taste and decision-making, so I can decide who to advance with confidence.*
 - *When I'm choosing a platform strategy for a new mobile product, I want to weigh native vs. cross-platform against the specific constraints of my team and timeline, so I can commit to one path without re-litigating the question every quarter.*
 
-If the job-to-be-done can't be stated as a tight Job Story — single circumstance, single motivation, single outcome, no solutions named, no aspirational mush — the mixtape will be unfocused. This is the single most common failure mode. The [JTBD Master Prompt](JTBD-MASTER-PROMPT.md) is a drop-in interview that elicits one in a single human turn; use it (or have the AI use it) at the start of any new mixtape.
+If the desired capability cannot be made hyper-specific, the mixtape will be unfocused. This is the single most common failure mode. "SEO" is a topic; "SEO keyword research for a mental-health startup specialized in brain surgery" is specific enough for Liner to infer research lanes such as search strategy, medical-content constraints, brain-surgery terminology, and Google guidance.
+
+Write a short Capability Brief alongside the internal JTBD. It should name:
+
+- what future AI sessions should be able to do,
+- what outputs or decisions the resource should support,
+- the research lanes Liner inferred,
+- source requirements and obvious exclusions,
+- runtime behavior for the future agent, including when to ask the user clarifying questions.
+
+Sketch a knowledge map alongside the Capability Brief and internal JTBD: the major areas of the domain, the sub-areas, the edge cases. For mobile design, that might be foundations, patterns, craft, process, edge cases. For another domain, the buckets are different. The map serves three purposes: it structures research, it surfaces gaps, and it becomes the section structure of the finished mixtape.
 
-Sketch a knowledge map alongside the JTBD: the major areas of the domain, the sub-areas, the edge cases. For mobile design, that might be foundations, patterns, craft, process, edge cases. For another domain, the buckets are different. The map serves three purposes: it structures research, it surfaces gaps, and it becomes the section structure of the finished mixtape.
+Also write a capability brief and required source roles.
+
+The **capability brief** says what this mixtape should make a downstream AI agent better at. It is not a persona. It is the operational job the corpus must support.
+
+**Required source roles** name the kinds of evidence the corpus needs before it can be trusted. Each role should say why it matters, what good evidence looks like, and the minimum coverage needed. For a medical SEO mixtape, roles might include search-engine guidance, medical-topic authority, patient-language evidence, and compliance boundaries. For an art-direction mixtape, roles might include visual-analysis vocabulary, translation methods, high-craft examples, and critique language. The roles change with the JTBD; the requirement does not.
 
 Treat the map as a hypothesis. It will get revised during research.
 
 ### Phase 2 — Candidate discovery
 
-Generate a long list of candidate sources covering the knowledge map. Lots of them. This phase is about recall, not precision — gather more than you need; you'll cut later.
+Generate a long list of candidate sources covering the knowledge map and the required source roles. Lots of them. This phase is about recall, not precision — gather more than you need; you'll cut later.
 
 Methods that produce better candidates than generic search:
 
@@ -75,21 +95,23 @@ Methods that produce better candidates than generic search:
 
 **Conference proceedings.** Going through three years of a specific conference is more efficient than searching for talks topic-by-topic.
 
-**Ask the AI to find gaps, not sources.** Once you have a candidate list, ask: *what's missing from this collection for someone trying to [job-to-be-done]?* AI is bad at recall and good at critique. Use it for the right thing.
+**Ask the AI to find gaps, not sources.** Once you have a candidate list, ask: *what's missing from this collection for an AI agent trying to [capability]?* AI is bad at recall and good at critique. Use it for the right thing.
+
+**Search by source role.** A knowledge-map section can look populated while a required evidence role is missing. Search directly for the role the source needs to play: canonical method, domain authority, applied example, boundary/risk, or whatever the Phase 1 source roles require.
 
 No fetching yet. This phase produces URLs and titles, not content.
 
 ### Phase 3 — Fetching
 
-Pull content for every candidate into the cache. Transcripts, articles, metadata. This is the expensive phase — network calls, transcript scraping, content extraction.
+Pull content for every candidate into the cache. Transcripts, articles, PDFs, local files, and only then metadata when the content cannot be reached. This is the expensive phase — network calls, transcript scraping, content extraction.
 
 Two things matter here. First, fetching is part of research, not a tail step. A source can't be honestly evaluated without reading it. Second, fetched content should be cached. The same source used in multiple mixtapes should be fetched once.
 
-After fetching, every candidate has readable content available for evaluation.
+After fetching, every candidate has either readable content available for evaluation or an explicit failure state. Search snippets, titles, and URLs are not source evidence.
 
 ### Phase 4 — Evaluation
 
-Read the fetched content and rate each candidate against the job-to-be-done. This is where keep/trim/drop decisions actually happen.
+Read the fetched content and rate each candidate against the Capability Brief and internal JTBD. This is where keep/trim/drop decisions actually happen. Kept and trimmed sources must include `fetch_status`, `content_quality`, and at least two content-specific evidence bullets so the corpus can prove the decision came from content, not just URL plausibility.
 
 Source quality, roughly in order of preference:
 
@@ -113,7 +135,7 @@ Evaluations should include a brief reason. "This source is canonical for the fou
 
 ### Phase 5 — Quality checks
 
-Four tests every mixtape should pass. Run them deliberately.
+Run the quality tests deliberately. This phase checks whether the corpus can actually support the future agent's task, not just whether it has plausible sources.
 
 **The redundancy test.** Read each source's role in the mixtape. Are any two sources making essentially the same point? If yes, keep the better one and cut the other. Mixtape volume is not a virtue. Five excellent sources beat fifteen good ones.
 
@@ -121,11 +143,15 @@ Four tests every mixtape should pass. Run them deliberately.
 
 **The disagreement test.** Pick the strongest claim made by sources in the mixtape. Find someone credible who disagrees with it. Either include the disagreement or explicitly note that the mixtape takes a position. A mixtape that only includes one side of a contested question produces worse AI output, because the AI then can't see the contested-ness.
 
-**The framing-gap test.** Step back and look at the whole mixtape. Is there a major perspective on this topic that's missing entirely — not just an individual source, but a whole way of thinking about the JTBD? If yes, the framing was too narrow. Expand the knowledge map and revisit Phase 2.
+**The framing-gap test.** Step back and look at the whole mixtape. Is there a major perspective on this capability that's missing entirely — not just an individual source, but a whole way of thinking about the task? If yes, the framing was too narrow. Expand the knowledge map and revisit Phase 2.
 
-This last test is the one most curators skip. It's also the highest-leverage. Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. The framing-gap test catches this.
+**The source-kind balance test.** Check the distribution of reference, principle, prescription, and example sources. A zero in any role is a decision, not an accident. Backfill or defend it.
 
-If a mixtape fails any of these tests, fix it before moving on.
+**The required source-role fit test.** Return to the roles from Phase 1. Does each role have fetched, readable, useful evidence? Is the evidence strong enough for the role, or merely adjacent? If a role is weak or absent, run a backfill pass, narrow the capability claim, or document the limitation and what custom source the curator should add.
+
+The framing-gap and source-role fit tests are the ones most curators skip. They are also the highest-leverage. Single-pass curation tends to produce mixtapes that are well-covered within one narrow framing. These tests catch what the first pass could not see.
+
+If a mixtape fails any of these tests, fix it before moving on when the fix is small enough for the quality phase. If the failure points to a wider source-role gap, write `working/05-operating-fit-audit.md` with `status: improvement_recommended`: name the missing role, explain why it matters, suggest search lanes, and list concrete custom sources the user could add if public research remains thin. Do not call the corpus ready with a limitation when the right next step is to run a focused improvement pass.
 
 ### Phase 6 — Synthesis
 
@@ -154,11 +180,11 @@ Theory aside — here's how to know if the mixtape is actually working:
 
 1. Compile the mixtape
 2. Paste it into an AI conversation as context
-3. Ask the AI a question that the mixtape's job-to-be-done should help with
+3. Ask the AI to do something the mixtape's capability should support
 4. Ask the same question without the mixtape in a separate conversation
 5. Compare the answers honestly
 
-If the answer with the mixtape is meaningfully better — more specific, more correct, more nuanced, less generic — the mixtape is working. If the answers are similar, the mixtape isn't earning its place. Either the sources are too generic, the synthesis isn't doing enough work, or the JTBD is too broad.
+If the answer with the mixtape is meaningfully better — more specific, more correct, more nuanced, less generic — the mixtape is working. If the answers are similar, the mixtape isn't earning its place. Either the sources are too generic, the synthesis isn't doing enough work, or the capability is too broad.
 
 This empirical check is required for library contributions. Run it. Document the result.
 
@@ -202,7 +228,7 @@ The methodology supports two intensities of engagement.
 
 **Quick mode** runs the methodology automatically. The curator provides the JTBD and confirms the AI's proposals at each gate. The AI does the heavy lifting — generating candidates, evaluating, drafting curator notes, drafting the synthesis. The curator's job is to catch obvious errors and make final calls. A complete mixtape takes 15–30 minutes. Output is good enough for personal use.
 
-**Methodology mode** treats the AI as a research assistant rather than the curator. The curator engages substantively at each gate — revises the knowledge map, reviews evaluation rationales, makes deliberate keep/drop decisions, writes their own synthesis. The AI accelerates the tedious work; the judgment stays human. A complete mixtape takes several hours. Output is library-eligible.
+**Methodology mode** treats the AI as a research assistant rather than the curator. The curator engages substantively at each gate — revises the capability brief, knowledge map, and source roles; reviews evaluation rationales; makes deliberate keep/drop decisions; writes their own synthesis. The AI accelerates the tedious work; the judgment stays human. A complete mixtape takes several hours. Output is library-eligible.
 
 Both modes use the same lifecycle and produce the same artifact shape. They differ in how much human judgment shows up in the working notes and the synthesis. Quick mode mixtapes can be upgraded to methodology mode by going back and doing the substantive work; methodology mode mixtapes can be produced in one pass by curators who already know the domain.
 
@@ -216,7 +242,7 @@ Patterns that produce bad mixtapes. Watch for them.
 
 **The greatest-hits mixtape.** A list of the most famous resources on a topic. Looks impressive, adds little value because the AI already knows about famous resources from training. Curate for *non-obvious* sources, not popular ones.
 
-**The unfocused mixtape.** No clear job-to-be-done; tries to cover the entire field. Result: shallow on everything, deep on nothing.
+**The unfocused mixtape.** No clear capability; tries to cover the entire field. Result: shallow on everything, deep on nothing.
 
 **The author-tribute mixtape.** Three of the five sources are by the same person, because the curator is a fan. This narrows perspective and reduces the AI's ability to synthesize across views.
 
@@ -224,10 +250,12 @@ Patterns that produce bad mixtapes. Watch for them.
 
 **The noteless mixtape.** Sources without curator notes. Either the curator was lazy or didn't actually have a reason for each source. Both are problems. If a source's role can't be articulated, it doesn't belong.
 
-**The aspirational mixtape.** Sources the curator thinks people *should* read, not sources that help with the actual job-to-be-done. Mixtapes are tools, not reading recommendations.
+**The aspirational mixtape.** Sources the curator thinks people *should* read, not sources that help with the actual capability. Mixtapes are tools, not reading recommendations.
 
 **The single-pass mixtape.** Curated without a framing-gap test. Well-covered within one narrow framing, blind to whole perspectives the curator didn't think to look for.
 
+**The role-missing mixtape.** Every section has sources, but one required evidence role is absent. The corpus looks full while still failing the job. Fix by backfilling the role, narrowing the claim, or documenting the limitation.
+
 ---
 
 ## A note on AI assistance
@@ -241,6 +269,7 @@ AI is especially prone to:
 - Producing generic curator notes that say "this is a useful resource" without specificity
 - Missing primary documents (specs, papers) in favor of secondary commentary
 - Failing the framing-gap test because it doesn't notice what it didn't search for
+- Filling knowledge-map sections while missing required source roles
 
 Compensate deliberately. Search for primary sources yourself even when AI doesn't surface them. Verify every URL. Treat AI-drafted notes as first drafts. Run the framing-gap test with intent.
 

package/cli-update-docs/JTBD-MASTER-PROMPT-ABOUT.md

@@ -14,7 +14,7 @@ The JTBD Master Prompt fixes that gap. It's a single, drop-in prompt that takes
 
 ## What it is
 
-A self-contained master prompt stored at `cli-update-docs/JTBD-MASTER-PROMPT.md`. The body sits between `---BEGIN---` and `---END---` markers and is meant to be copy-pasted into an AI conversation, embedded inside the `curating-mixtapes` skill, or spawned as a TUI subprocess.
+A self-contained master prompt stored at `docs/curation-skill/JTBD-MASTER-PROMPT.md`. The body sits between `---BEGIN---` and `---END---` markers and is meant to be copy-pasted into an AI conversation, embedded inside the `curating-mixtapes` skill, or spawned as a TUI subprocess.
 
 The prompt's sole deliverable is a single sentence in the Intercom Job Story form: *"When [circumstance], I want [motivation], so I can [outcome]."* No rationale, no knowledge map, no commentary — those belong to later phases. One sentence on one line.
 
@@ -36,10 +36,10 @@ Five moves, in order:
 
 ## Where it came from
 
-The prompt is the engineering output of a mixtape compiled specifically for this question. The mixtape lives at:
+The prompt is the engineering output of a mixtape compiled specifically for this question. That local source mixtape is archived at:
 
 ```
-mixtapes/jtbd-master-prompt/
+/Users/arturo/Documents/Projects/0-archive/liner-archive/2026-06-25-root-cleanup/mixtapes/jtbd-master-prompt/
 ├── MIXTAPE.md              # compiled master file
 ├── tape.yaml               # the recipe
 ├── synthesis.md            # the curator's framing
@@ -83,7 +83,7 @@ Three deployment paths, all using the same prompt:
 
 **Agent with filesystem access (Claude Code, Cowork desktop, Codex, the Liner TUI as a subprocess).** Both file attachments and folder paths are live. The user picks; the agent reads accordingly.
 
-**Embedded inside the `curating-mixtapes` skill.** Drop the prompt block into `cli-update-docs/SKILL.md` as the body of Phase 1 — Framing, replacing the current "Ask the user for the JTBD" paragraph. The skill's outer context provides Liner framing; this prompt handles JTBD elicitation. Filesystem access is the default in the skill's runtime.
+**Embedded inside the `curating-mixtapes` skill.** Drop the prompt block into `docs/curation-skill/SKILL.md` as the body of Phase 1 — Framing, replacing the current "Ask the user for the JTBD" paragraph. The skill's outer context provides Liner framing; this prompt handles JTBD elicitation. Filesystem access is the default in the skill's runtime.
 
 **As a TUI subprocess.** A future `liner jtbd <folder>` command could spawn this prompt with the folder path in context. The context-sharing question still fires — the user might want to add files or skip the folder — but the path is available if they want it.
 
@@ -122,12 +122,9 @@ A few decisions in the prompt aren't obvious and have been pushed back on during
 ## Related files
 
 - The prompt itself: [`JTBD-MASTER-PROMPT.md`](./JTBD-MASTER-PROMPT.md)
-- The format migration plan: [`JOB-STORY-MIGRATION.md`](./JOB-STORY-MIGRATION.md)
-- The source mixtape: [`mixtapes/jtbd-master-prompt/`](../mixtapes/jtbd-master-prompt/)
-  - Synthesis (the bridge between JTBD theory and prompt engineering): [`mixtapes/jtbd-master-prompt/synthesis.md`](../mixtapes/jtbd-master-prompt/synthesis.md)
-  - Tape recipe: [`mixtapes/jtbd-master-prompt/tape.yaml`](../mixtapes/jtbd-master-prompt/tape.yaml)
-  - 32 source extracts: [`mixtapes/jtbd-master-prompt/sources/`](../mixtapes/jtbd-master-prompt/sources/)
-- The Liner curation methodology that places this work in Phase 1: [`cli-update-docs/CURATION.md`](./CURATION.md)
-- The skill that will likely embed this prompt: [`cli-update-docs/SKILL.md`](./SKILL.md)
-- The mixtape format spec defining the `jtbd:` field the prompt's output lands in: [`cli-update-docs/MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
+- The current format spec: [`MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
+- The archived source mixtape: `/Users/arturo/Documents/Projects/0-archive/liner-archive/2026-06-25-root-cleanup/mixtapes/jtbd-master-prompt/`
+- The Liner curation methodology that places this work in Phase 1: [`CURATION.md`](./CURATION.md)
+- The skill that will likely embed this prompt: [`SKILL.md`](./SKILL.md)
+- The mixtape format spec defining the `jtbd:` field the prompt's output lands in: [`MIXTAPE-FORMAT.md`](./MIXTAPE-FORMAT.md)
 - Project-level overview of Liner: [`LINER-MASTER.md`](./LINER-MASTER.md)

package/cli-update-docs/JTBD-MASTER-PROMPT.md

@@ -134,7 +134,7 @@ The prompt's first move is always the same — ask the user whether they have pr
 
 **Agent with filesystem access (Claude Code, Cowork desktop, Codex, the Liner TUI as a subprocess).** Both file attachments and folder paths work. If the user gives a path, the agent reads from disk.
 
-**Inside the `curating-mixtapes` skill.** Drop the prompt block into `cli-update-docs/SKILL.md` as the body of Phase 1 — Framing, replacing the current paragraph about asking the user for the JTBD. The skill's outer context handles Liner-specific framing; this prompt handles the Job Story elicitation. The skill runs in environments with full filesystem access.
+**Inside the `curating-mixtapes` skill.** Drop the prompt block into `docs/curation-skill/SKILL.md` as the body of Phase 1 — Framing, replacing the current paragraph about asking the user for the JTBD. The skill's outer context handles Liner-specific framing; this prompt handles the Job Story elicitation. The skill runs in environments with full filesystem access.
 
 **Inside the TUI as a dedicated subprocess.** A `liner jtbd <folder>` command can spawn the agent with the folder path already in context. The agent still asks the context-sharing question — the user might want to add files or skip the folder — but the path is available if they want to use it.