linersh 0.5.0 → 0.5.1

package/cli-update-docs/PLATFORM.md

@@ -0,0 +1,210 @@
+# Liner Platform
+
+How the Liner project operates: the surfaces, the lifecycle, the library, and the boundaries.
+
+This document assumes the reader has read [ABOUT.md](./ABOUT.md) (what Liner is) and [CURATION.md](./CURATION.md) (the methodology). It describes Liner's specific implementation choices, not the methodology itself.
+
+---
+
+## The surfaces
+
+Liner is several tools sharing a methodology and a file format. Each surface exists for a specific moment in the workflow.
+
+**CLI** (Python, `pipx install linersh`). Atomic operations on mixtape projects — `liner init`, `liner compile`, `liner share`, `liner import`, `liner list`, `liner clone`, `liner cache {info,list,show,clear,purge}`, `liner setup-js` (one-shot JavaScript-rendering setup). The right tool for scripting, automation, and one-shot operations.
+
+**TUI** (Node + Ink, `npx linersh`). Interactive multi-step lifecycle runner. Drives the methodology with sensible defaults, calls the Python CLI as subprocesses for fetching, parsing, and compilation. The right tool for authoring new mixtapes. Features a project-folder browser, a structured editor for `tape.yaml` with synthesis-readiness indicator, a local-file picker for `local_file` sources, and a live progress view that streams NDJSON events from `liner compile --emit-events`.
+
+**Skill** (`curating-mixtapes`). A portable methodology document Claude reads when invoked. Drops into `~/.claude/skills/`. Works without the CLI for users who prefer chat-native authoring.
+
+**MCP server**. Exposes Liner's functions as tools any MCP-compatible host can call (Claude Code, Codex, Cursor, others). Local install, stdio transport. The right tool for agent-driven workflows.
+
+**Web builder**. Stateless form on `liner.sh` that produces a `tape.yaml` for download. The right tool for casual users who don't want to install anything.
+
+The surfaces are independent. None requires the others.
+
+---
+
+## The two modes
+
+Most curators won't practice the methodology in detail. They want a tool that produces a usable mixtape with minimal effort. A small minority will engage substantively at each step.
+
+Liner supports both through two modes that share the same architecture and produce the same artifact shape.
+
+**Quick mode** (default). The AI does maximum work. The curator confirms or lightly edits at each gate. Defaults are accept-all. A complete mixtape takes 15–30 minutes. Quality is "good enough for personal use."
+
+**Methodology mode**. The curator engages substantively. Writes their own synthesis if they want. Reviews evaluation rationales. Adds and rejects sources deliberately. A complete mixtape takes several hours. Quality is library-eligible.
+
+The TUI runs quick mode by default with methodology mode available as a slower path. The skill defaults to quick mode and includes instructions for methodology mode. Library contributions require methodology mode.
+
+---
+
+## The lifecycle
+
+Every mixtape moves through the same phases regardless of mode. Quick mode runs through them with AI doing the work and the curator confirming. Methodology mode runs through them with the curator doing substantive work alongside the AI.
+
+1. **Framing** — JTBD statement, knowledge map
+2. **Candidate discovery** — long-list of URLs based on the knowledge map, no fetching yet
+3. **Fetching** — pull content for candidates into the shared cache
+4. **Evaluation** — AI reads fetched content, proposes keep/trim/drop with ratings against the JTBD
+5. **Quality checks** — redundancy, coverage, disagreement, framing-gap tests
+6. **Synthesis** — AI drafts the synthesis; curator may edit (synthesis is required, not optional)
+7. **Final assembly** — `liner compile` writes `MIXTAPE.md` and populates `sources/`
+8. **Empirical test** (optional but recommended) — compile, paste into AI conversation, compare with/without
+
+Two natural human-in-the-loop gates: candidate confirmation before fetching (saves wasted network calls) and evaluation review before finalization (catches the AI's misjudgments). Quick mode shows these gates with "looks good, continue" defaulted; methodology mode pauses for real review.
+
+---
+
+## The artifacts
+
+A mixtape is a folder, not a file. The folder is the canonical unit; everything else is derived from it.
+
+```
+mobile-design-foundations/
+├── MIXTAPE.md            # the consumable artifact
+├── tape.yaml             # the recipe — kept sources, sections, notes
+├── synthesis.md          # the curator's distilled understanding
+├── sources/              # extracted content for kept sources
+│   ├── 01-<slug>.md
+│   └── ...
+├── personal/             # curator's local copies of `local_file` sources (optional)
+│   └── ...
+└── working/              # the methodology made visible
+    ├── 01-jtbd-and-knowledge-map.md
+    ├── 02-candidate-longlist.md
+    ├── 03-evaluation.yaml
+    ├── 04-quality-checks.md
+    └── 05-empirical-test.md
+```
+
+Three concepts to distinguish:
+
+- A **tape file** (`tape.yaml`) is the recipe. References sources by URL or path. Shareable on its own; anyone with the file can recompile from scratch.
+- A **mixtape** is the project folder. Contains the recipe, the working notes, the fetched content, the synthesis, and the master file.
+- The **consumable mixtape** is `MIXTAPE.md` plus the `sources/*.md` files it references. This is what gets pasted into an AI conversation.
+
+[MIXTAPE-FORMAT.md](./MIXTAPE-FORMAT.md) specifies the structure in detail.
+
+---
+
+## The content cache
+
+The cache is a shared, curator-level resource. One cache per machine, used across all projects.
+
+Default location: `~/.liner/cache/` (or wherever `platformdirs` puts it on the user's OS).
+
+The cache holds extracted source content keyed by canonical URL. The same source used in three different mixtapes is fetched once. Sources that change over time (transcripts, articles) have per-type TTLs; permanent references (specs, papers) can be pinned.
+
+The cache is the curator's local research library. Treat it that way. `liner cache list` shows what's there. `liner cache show <url>` displays a cached source. `liner cache purge <url>` removes one.
+
+The cache is never included in `.mixtape` exports. When a recipient imports a `.mixtape`, the receiving Liner repopulates *their* cache by fetching sources fresh — reusing whatever they already have.
+
+---
+
+## The library
+
+The Liner library is a curated collection of public mixtapes at [liner.sh/library](https://liner.sh/library), backed by a Git repository.
+
+**What the library contains.** Methodology-mode mixtapes authored by Liner maintainers and invited guest curators. Every mixtape uses only sources anyone can fetch. The folders are published in full — recipe, synthesis, working notes, sources, the compiled `MIXTAPE.md`. Library readers can browse the compiled artifact directly without compiling anything themselves.
+
+**What the library does not contain.** Quick-mode tapes. Tapes containing `local_file` sources (which by definition reference content the maintainers can't republish). Tapes with `render: js` that depend on opt-in dependencies. Tapes that haven't passed the empirical test.
+
+**Structure.** Each mixtape is a directory in the repo. The website renders these as individual pages. Users can clone the tape file and edit it, browse the compiled mixtape, or read the working notes.
+
+**Curation philosophy.** Small, slow-growing, opinionated. Quality over coverage. A library of fifty excellent mixtapes is more useful than five hundred mediocre ones.
+
+---
+
+## Contributing
+
+The library accepts pull requests for methodology-mode mixtapes only.
+
+1. Build the mixtape in methodology mode, applying [CURATION.md](./CURATION.md) substantively
+2. Run the empirical test — compile the mixtape, compare AI output with and without it on a real question. Document the result in `working/05-empirical-test.md`
+3. Submit a PR with the full project folder — exported via `liner share --no-personal`, and with no `local_file` sources in `tape.yaml`
+4. A maintainer reviews. Submissions can be accepted, returned with feedback, or declined
+
+The bar is "demonstrably improves AI output for the stated job-to-be-done." Effort alone isn't sufficient. A well-meaning mixtape that doesn't move the needle isn't a library mixtape.
+
+Accepted mixtapes are credited to the curator by name. Curators retain authorship. Library mixtapes are MIT-licensed by default unless otherwise specified.
+
+---
+
+## Sharing
+
+Mixtapes are folders. To share a mixtape as a single file, use `liner share <project-folder>`. This produces `<project-folder>.mixtape` — a zip containing the project folder.
+
+The exported `.mixtape` includes everything in the project folder: `MIXTAPE.md`, `tape.yaml`, `synthesis.md`, `sources/`, `working/`, and `personal/` (when the recipe uses `local_file` sources). It does not include anything from the shared content cache (which lives outside the project folder anyway).
+
+On `liner import <file.mixtape>`, the receiving Liner unzips the folder, then refetches any sources that aren't already in the receiving curator's cache. Sources already cached are reused. `local_file` sources read from the archived `personal/` directly — no refetch. The result is a working project folder identical to what the original curator had.
+
+**Flags worth knowing about:**
+
+- `--no-working-notes`: exclude the `working/` folder from the export. For curators who consider their working notes private. Default is to include them.
+- `--no-personal`: exclude `personal/` from the export. Used when the local copies are licensed/gated material the curator can't redistribute, or when preparing a library submission. The recipient won't be able to compile `local_file` sources without supplying their own copies.
+- `--no-source-content`: skip the `sources/` folder. The recipient must re-fetch on first compile.
+- `--minimal`: produce a smaller zip containing only `tape.yaml`. For sharing the recipe only. The recipient compiles fresh.
+
+---
+
+## What Liner doesn't do
+
+Boundaries that shape the project's scope:
+
+- **No hosted compilation.** All compilation happens on the curator's machine. Liner does not run a server that fetches sources for users.
+- **No accounts in v1.** The CLI, TUI, library, and website all work without authentication. A future community index will use GitHub OAuth only.
+- **No paywall bypass.** Liner does not help users access content they don't already have. Source handlers for gated content require the user to provide content from their existing access.
+- **No LLM calls in the core tools.** The CLI, TUI, library tools, and web builder don't make LLM calls. All AI work happens through the user's own subscription (Claude Code, Codex, or API key) via the skill or MCP server. Liner doesn't pay for inference.
+- **No headless browser by default.** Plain `pipx install linersh` ships with the lightweight server-side web handler only. JavaScript-rendered sites (Apple HIG, Notion, many SPAs) require the opt-in `linersh[js]` extra, which adds Playwright and a Chromium binary. The extra is local-only — there's no hosted rendering service.
+- **No telemetry.** The tools don't phone home. Usage is the user's own business.
+- **No curator-required compression decisions.** Sources are stored at full extracted length. In-context efficiency comes from the master file pattern — `MIXTAPE.md` is small and always-loaded, sources are referenced and loaded on demand by the consuming AI.
+
+These boundaries are stable. Anything outside them either lives in a separate project or doesn't get built.
+
+---
+
+## The community index (planned, deferred)
+
+A future addition will be a community index — a directory of community-published mixtapes hosted by their curators on GitHub. Liner does not host the content; it indexes links to user repositories.
+
+The design:
+
+- Curators sign in with GitHub OAuth and submit a link to a public GitHub repository containing their mixtape folder
+- The repository must be on GitHub (no other hosts in v1)
+- Entries are reviewed before featuring; the front page is editorially curated
+- No comments, ratings, or community voting in v1
+- A passive popularity signal may be shown but does not drive default sorting
+
+This feature is not part of the initial Liner release. It will be built only if there's evidence of demand from real users of the v1 tools and library. In the meantime, the `/mixtapes` route on the website serves as a placeholder with an interest signup.
+
+---
+
+## Maintenance contract
+
+Liner is a side project. The maintenance contract:
+
+- Issues and PRs are reviewed when time permits, not on any schedule
+- No SLA, no guaranteed compatibility, no support commitments
+- Breaking changes are possible between versions; versioning will be honest about them
+- The transcript-fetching and content-extraction layers depend on third-party platforms that change over time; the tools will sometimes break and will be fixed when fixes are practical
+- The library is curated by the maintainer and invited guest curators; submissions are welcomed but not guaranteed acceptance or response
+
+Open source does not mean free maintenance. Users who need guaranteed support should use a hosted product.
+
+---
+
+## Versioning
+
+Liner versions three things independently:
+
+- **Tape format** has its own version field. Breaking format changes increment the format version; older tapes either continue to work or get a clear migration path. See [MIXTAPE-FORMAT.md](./MIXTAPE-FORMAT.md) for the versioning policy.
+- **Methodology** is versioned in [CURATION.md](./CURATION.md). Substantive changes increment the methodology version.
+- **Tools** (CLI, TUI, skill, MCP server) follow semver. Major versions can break compatibility; minor and patch versions don't.
+
+The methodology, the format, and the tools are versioned independently. Updates to one don't force updates to the others unless there's a real dependency.
+
+---
+
+## License
+
+MIT.

package/cli-update-docs/README.md

@@ -0,0 +1,107 @@
+# Curating Mixtapes — Skill Bundle
+
+This is the Liner methodology made executable by Claude. The bundle implements CURATION.md v2.0 as instructions to a running AI, drives the eight-phase mixtape lifecycle from a topic to a project folder ready for `liner compile`, and supports both quick mode (the AI does most of the work, the user confirms at two gates) and methodology mode (the curator engages substantively at every phase).
+
+It is one of Liner's surfaces, alongside the CLI, the TUI, the planned MCP server, and the planned web builder. The skill is the surface for Claude-Code-native and TUI-subprocess authoring. Methodology-mode curators can also use it directly when working in a Claude Code session.
+
+## Bundle contents
+
+Six files in one directory:
+
+```
+curating-mixtapes/
+├── SKILL.md                       # the orchestrator
+├── source-finding-tactics.md       # Phase 2
+├── source-quality-hierarchy.md     # Phase 4
+├── curator-notes.md                # Phase 4
+├── quality-check-tests.md          # Phase 5
+└── synthesis-guidance.md           # Phase 6
+```
+
+`SKILL.md` is the orchestrator. It defines the trigger description, the two modes, the two gates, the eight-phase lifecycle skeleton, the AI biases to compensate for, the boundaries (what the skill does NOT do), and the failure modes to watch. It is always loaded when the skill fires.
+
+The five companion files are loaded only at the phases that use them. Phases 1, 3, 7, and 8 have no companion file — their guidance fits inside SKILL.md.
+
+The split is deliberate. Every invocation pulls SKILL.md's ~2,300 words into context regardless. Companion files add 1,000–1,500 words each but only at the phase that needs them, so total context cost scales with where the user is in the lifecycle rather than with the bundle's full size.
+
+## Where the bundle lives
+
+**Local testing.** Drop the `curating-mixtapes/` folder into `~/.claude/skills/`. Claude Code and Claude Desktop both look there for user-installed skills. The skill fires when the user says something the description matches — "help me make a mixtape on [topic]" is the canonical trigger.
+
+**Shipping.** The bundle lives at `liner/skills/curating-mixtapes/` in the main Liner repository. End users install it from there (installation flow TBD — likely a `liner skills install` command or a documented copy step in the Liner README).
+
+**TUI subprocess.** The Liner TUI bundles the skill internally and invokes it via the Claude Agent SDK in quick mode. The user doesn't see the skill directly; they see the TUI's wizard UI. The methodology being applied is this skill's.
+
+The same file contents work in all three locations. Don't fork between a local-test version and a ship version.
+
+## Runtime requirements
+
+Filesystem access is required, not optional. The skill reads its own companion files at specific phases and writes mixtape artifacts to a project folder. It is designed for execution inside Claude Code or as a TUI subprocess, both of which have filesystem access by default. It is not designed for pure-chat (claude.ai) use.
+
+No MCP server is required. v1 uses Claude's own web search for candidate discovery and URL verification. When the Liner MCP server ships, a future skill version will use it for fetching and cache operations; v1 doesn't depend on it.
+
+## How invocation works
+
+The user says something the description matches. Claude loads SKILL.md. Claude reads it, identifies which mode applies (quick by default unless the user says otherwise or asks for library contribution), and begins the lifecycle.
+
+At Phase 2, Claude reads `source-finding-tactics.md`. At Phase 4, Claude reads `source-quality-hierarchy.md` and `curator-notes.md`. At Phase 5, Claude reads `quality-check-tests.md`. At Phase 6, Claude reads `synthesis-guidance.md`. Each companion file is read at the start of its phase, before any work in that phase happens.
+
+The two gates pause for user input. In quick mode, the default is "looks good, continue" — Claude proceeds unless the user actively objects. In methodology mode, Claude pauses for substantive review.
+
+The skill writes artifacts to a project folder named for the topic (e.g., `mobile-design-foundations/`) as it goes. The working notes are produced phase by phase, so the user can stop at any phase boundary and resume later — the working files are picked up where they were left.
+
+When all phases complete, the user runs `liner compile <project-folder>` themselves. The skill never compiles.
+
+## How to test the bundle
+
+Pick a small topic the curator hasn't already researched. "Writing better LLM evals," "Notion API patterns," "designing for color blindness" — narrow, technical, with enough source material that the corpus has shape but not so much that the run takes hours. Run the skill end-to-end in quick mode. Note where Claude struggles, where the methodology produces friction, where the gates fire awkwardly.
+
+Run again in methodology mode on the same topic. Compare the artifacts. The two modes should produce same-shape folders with different depth of curator engagement showing through. If the methodology-mode output looks indistinguishable from the quick-mode output, that's a signal the skill isn't asking enough of methodology-mode curators.
+
+For higher signal: run the skill in quick mode on a topic that already has a hand-curated mixtape (the CLI/TUI corpus is the obvious one). Compare the skill's tape file and synthesis against the hand-curated version. This is the empirical test for the skill itself, structurally identical to the methodology's Phase 8 test for mixtapes. If the skill's quick-mode output is meaningfully worse than the hand-curated version, that's expected — quick mode targets "good enough for personal use." If the gap is larger than expected, the skill needs work.
+
+## How to update or extend the bundle
+
+Three kinds of changes happen, each with a different shape.
+
+**Tightening SKILL.md.** Phase descriptions, gate behavior, trigger description, the AI-biases list, the failure-modes list. Edit in place. SKILL.md is the source of truth for the bundle's structure; everything else conforms to what SKILL.md says.
+
+**Editing a companion file.** Refinements to the tactics, hierarchy, notes guidance, tests, or synthesis advice. Edit in place. Keep the orchestrator references in SKILL.md unchanged unless the change affects when or how a companion gets read.
+
+**Adding a new companion file.** Two questions to answer first. Is the content concretely better than what could fit in SKILL.md? (Worked examples and pattern catalogs are the usual reasons.) Does the content apply to one specific phase rather than the whole lifecycle? If yes to both, add the companion and reference it from SKILL.md's lifecycle section. If no to either, the content probably belongs in SKILL.md itself or in CURATION.md.
+
+When adding a companion, update this README's "Bundle contents" section and the load-profile note in SKILL.md. Don't let the bundle's structure drift from how the README describes it.
+
+## v0.3 status and the second pass
+
+The current bundle is v0.3. SKILL.md is complete and reflects CURATION.md v2.0. The five companion files contain the methodology content in instructional voice but use `TODO` markers in place of worked examples.
+
+The second pass — pulling those examples from the Cowork CLI/TUI synthesis — is the immediate next deliverable. The `TODO` markers name specific candidates: the Caligula rescue for the rescue-move pattern in Phase 4, the Van Slyck duplicate for the redundancy test, the form-design tradition rescue for the framing-gap test in Phase 5, the OpenClaw original notes for bad-note contrast in curator-notes.md.
+
+Hold off shipping the bundle to `liner/skills/` until the second pass lands. The `TODO` markers are specific enough that a methodology-mode curator could fill them by hand, but it's faster and more consistent to do it in one focused session pointed at the Cowork material.
+
+## Versioning
+
+The skill bundle has its own version, independent of the CLI, TUI, and methodology document. Three version numbers track separately:
+
+- **Methodology version** is tracked in CURATION.md (`Current version: 2.0`).
+- **Skill bundle version** is the bundle's own — currently v0.3 internally, not yet stamped into SKILL.md frontmatter. Adding a `version` field to the frontmatter is a small open decision; the convention isn't established yet across Liner's surfaces.
+- **Methodology compatibility** is asserted by the `methodology_version` field the skill writes into generated `tape.yaml` files. The skill claims compatibility with the methodology version it was built against.
+
+When CURATION.md updates, the skill bundle may need a corresponding update. The question to ask: does the methodology change affect what the running AI should do, or just how a human reader explains the work? If the former, the skill needs an update; if the latter, the skill is fine as-is. Bias toward updating both together when in doubt.
+
+## Relationship to other Liner pieces
+
+The skill is the methodology made executable. It sits alongside Liner's other surfaces and shares the format and methodology with them.
+
+**CURATION.md** is the methodology described to humans. The skill bundle implements it for an AI executor. The two are paired artifacts that update together when the methodology changes substantively.
+
+**The Liner CLI** runs `liner compile` against the project folder this skill produces. The skill never compiles; the CLI never authors. Clean split.
+
+**The Liner TUI** invokes this skill internally for quick-mode authoring via the Claude Agent SDK. Same methodology, different UX.
+
+**The Liner MCP server** (planned) will expose mechanical operations — fetch this URL, validate this tape file, query the cache — as tools. A future skill version will use those tools where v1 uses Claude's own web search.
+
+**The Liner library** publishes methodology-mode mixtapes. The skill can produce library-eligible output if run in methodology mode and the empirical test passes — but the bar for library contribution is real curator engagement, not the skill's quick-mode default.
+
+Treat changes to the bundle the way you'd treat changes to the methodology: deliberately, with examples, with a clear reason. The skill is the methodology executed at scale; drift in the skill is drift in the methodology.

package/cli-update-docs/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: curating-mixtapes
+description: Use when the user wants to build a "mixtape" — a curated bundle of sources (videos, articles, papers, specs) assembled as AI context for a specific job-to-be-done. Triggers include "help me make a mixtape on X", "curate sources on Y for AI", "build a context bundle for Z", "let's research X with Liner", "make me a tape on Y", "help me build a Liner mixtape". Drives the eight-phase Liner curation methodology end-to-end and produces a mixtape project folder — `tape.yaml`, `synthesis.md`, and `working/*` notes — ready for `liner compile`. Defaults to quick mode (the AI does the heavy lifting, the user confirms at two gates); methodology mode is available when the user wants to engage substantively at every step or is targeting library contribution.
+---
+
+# Curating Mixtapes
+
+This skill implements the Liner curation methodology (CURATION.md v2.0). A mixtape is a curated bundle of sources designed to make AI conversations meaningfully better within a specific domain. The bar: a good mixtape demonstrably improves AI output on tasks within its job-to-be-done.
+
+The output of this skill is a project folder ready for `liner compile`. The skill does not compile.
+
+**Runtime requirement:** this skill assumes filesystem access. It reads companion files from its own directory at specific phases and writes artifacts to a project folder. Designed for execution inside Claude Code or as a subprocess driven by the Liner TUI. Not designed for pure-chat use.
+
+## Terminology — get these right
+
+- **Tape file** (`tape.yaml`) — the recipe. Sources with notes and sections.
+- **Mixtape** — the project folder. Recipe + synthesis + working notes + source content + master file.
+- **Consumable mixtape** — `MIXTAPE.md` plus the `sources/*.md` files. What gets pasted into an AI conversation. Produced by `liner compile`.
+
+Tape ≠ mixtape. The recipe is small; the mixtape is the realized artifact.
+
+## What this skill produces
+
+A project folder named for the topic (e.g., `mobile-design-foundations/`) containing:
+
+- `tape.yaml` — the recipe, conforming to MIXTAPE-FORMAT v1 (with v1.1 additions: `mode`, `jtbd`, `local_file` sources, optional `render` field on web sources)
+- `synthesis.md` — the curator's distilled understanding of the domain
+- `working/01-jtbd-and-knowledge-map.md` — framing artifacts
+- `working/02-candidate-longlist.md` — the unfiltered candidate pool
+- `working/03-evaluation.yaml` — keep/trim/drop decisions with rationales and ratings
+- `working/04-quality-checks.md` — redundancy, coverage, disagreement, and framing-gap findings
+
+`sources/` and `MIXTAPE.md` are produced later by `liner compile`. The `working/05-empirical-test.md` file is produced when Phase 8 is run.
+
+When the curator has supplied local material (book chapters, exported PDFs, Reader-Mode-saved articles), the skill may write `local_file` entries in `tape.yaml` pointing at files the curator has placed under `personal/`. This is a methodology-mode affordance — the curator's local context belongs to them, not the public web, and the `local_file` source type makes it first-class. Library contributions still exclude `local_file` sources; the skill should not invent them or suggest paths the curator hasn't supplied.
+
+## Companion files
+
+This skill is split across files in its own directory. Read each companion file at the start of the phase that uses it. Do not skip the read.
+
+- `source-finding-tactics.md` — read before Phase 2
+- `source-quality-hierarchy.md` — read before Phase 4
+- `curator-notes.md` — read before Phase 4
+- `quality-check-tests.md` — read before Phase 5
+- `synthesis-guidance.md` — read before Phase 6
+
+The orchestration logic, the two modes, the two gates, the AI-bias list, and the failure-mode list stay in this file because they apply across the whole lifecycle.
+
+## Two modes
+
+Default to **quick mode** unless the user says they want methodology mode or library contribution.
+
+**Quick mode.** The AI does maximum work. Defaults at every gate are "looks good, continue." Total wall-clock target: 15–30 minutes. Output quality: good enough for personal use.
+
+**Methodology mode.** The curator engages substantively at every phase. Revises the knowledge map. Reviews evaluation rationales. Writes or substantially rewrites the synthesis in their own voice. Runs the empirical test. Several hours over one or more sessions. Output quality: library-eligible.
+
+Same lifecycle. Same artifacts. The difference is how much human judgment shows up in the working notes and the synthesis.
+
+## Two human-in-the-loop gates
+
+Two gates exist regardless of mode. Quick mode defaults them to "continue." Methodology mode pauses for substantive review.
+
+- **Gate 1 — Candidate confirmation** (after Phase 2, before Phase 3). Show the candidate long-list. The user confirms before any fetching happens. Saves wasted network calls; catches missing categories early.
+- **Gate 2 — Evaluation review** (after Phase 4, before Phase 6). Show keep/trim/drop with rationales and quality-check findings. The user confirms before synthesis is drafted.
+
+## The lifecycle
+
+Run these phases in order. Each phase's output feeds the next. Do not reorder.
+
+### Phase 1 — Framing
+
+Define the job-to-be-done and sketch a knowledge map.
+
+**The JTBD is a Job Story, not a topic.** Required form: `When [circumstance], I want [motivation], so I can [outcome].` All three slots required. "Mobile design" is a topic. *"When I'm designing the core UI of a consumer iOS app, I want to follow Apple's interaction conventions while choosing where to deviate visually, so I can ship something that feels native without looking generic."* is a JTBD. Three different Job Stories in the same topic area produce three different mixtapes.
+
+Elicit the JTBD using the [JTBD Master Prompt](JTBD-MASTER-PROMPT.md) — drop its body into this phase as your interview script. It opens with a single short context-sharing question (offering to read project material if the user has any), reads what's shared if anything, then either runs a budgeted interview (five questions max) or descends the scope ladder from what was inferred. It drafts silently, checks the draft against a six-test rubric, and emits one sentence. If the user pushes back, take the correction and re-run the rubric — don't defend.
+
+If you can't use the master prompt as-is (e.g., you're in a context where pasting it doesn't make sense), the minimum bar is: refuse any answer that's a bare topic, an aspiration ("be better at X"), a slot-missing fragment, or two jobs joined by "and." Stay on framing until the JTBD is a concrete single-sentence Job Story.
+
+**Knowledge map.** A short outline of the conceptual territory the corpus needs to cover. Four to eight sections, each with a few sub-areas. Treat it as a hypothesis — it will get revised during research.
+
+Write both to `working/01-jtbd-and-knowledge-map.md`. In quick mode: draft, show, get a one-line confirmation. In methodology mode: iterate with the curator until both feel right.
+
+### Phase 2 — Candidate discovery
+
+**Read `source-finding-tactics.md` before starting this phase.**
+
+Generate a long list of candidate sources across the knowledge map. URLs and titles only — no fetching yet. Aim wide: two to four times the eventual kept count. This phase is recall, not precision.
+
+Verify each candidate exists at the URL given. AI is prone to hallucinating plausible-sounding URLs. Treat unverified URLs as candidates only until they're confirmed.
+
+Write to `working/02-candidate-longlist.md`, grouped by knowledge-map section. For each candidate: URL, title, one-line reason it's a candidate.
+
+**At Gate 1, show the long-list and ask:** "Anything obviously missing? Anything obviously wrong? Confirm to start fetching." In quick mode the default is "looks good, continue." In methodology mode, expect real edits.
+
+### Phase 3 — Fetching
+
+Pull content for every confirmed candidate.
+
+For each URL, retrieve the full text. YouTube: transcript. Articles, papers, docs: extracted body text. Skim each as it comes back to confirm the URL contains what the title promised.
+
+If a URL fails to fetch (paywall, dead link, no transcript, geographic block): note the failure, decide whether the source is critical enough to chase via an alternate route (Wayback Machine, alternate venue), and either find a substitute or drop it. Don't silently lose candidates.
+
+A successful transcript fetch is not the same as a high-value source. Many tutorial videos transcribe cleanly but contain no transferable content. The next phase handles that judgment.
+
+Don't write fetched content into the project folder yet. That happens at compile time, only for kept sources.
+
+### Phase 4 — Evaluation
+
+**Read `source-quality-hierarchy.md` and `curator-notes.md` before starting this phase.**
+
+Read every fetched source against the JTBD. Decide keep / trim / drop. Rate kept sources 1–5. Draft curator notes for kept and trim sources.
+
+Write decisions to `working/03-evaluation.yaml`:
+
+```yaml
+candidates:
+  - url: https://example.com/source
+    title: Source title
+    decision: kept            # kept | trim | dropped
+    rating: 5                 # 1-5; required for kept and trim
+    section: foundations
+    rationale: One-sentence reason this decision was made.
+```
+
+Drafted curator notes land in `tape.yaml` at Phase 7. Write them now in their final form; don't postpone the work to assembly.
+
+### Phase 5 — Quality checks
+
+**Read `quality-check-tests.md` before starting this phase.**
+
+Step back from the keep-pile. Run the four tests. Document findings in `working/04-quality-checks.md`.
+
+If a test fails, fix it before moving on. Don't proceed to synthesis with known coverage or framing gaps.
+
+*Tip: this phase benefits from running with fresh attention. If the conversation has been long, consider starting a separate chat with just the JTBD, knowledge map, and the kept-source list (titles + notes only) to run the checks. Optional, not required by the methodology.*
+
+**At Gate 2, show the final keep-list, the curator notes, and the quality-check findings. Ask:** "Confirm to proceed to synthesis." Quick mode default: continue. Methodology mode: expect substantive edits.
+
+### Phase 6 — Synthesis
+
+**Read `synthesis-guidance.md` before starting this phase.**
+
+Draft `synthesis.md`. The synthesis is the curator's distilled understanding of the domain expressed as continuous prose. 800–2000 words.
+
+Quick mode: draft, show, default to "looks good, save it." The curator lightly edits if they want.
+
+Methodology mode: draft a starting point. Expect the curator to rewrite it substantially in their own voice. Library mixtapes need a substantially curator-written synthesis.
+
+### Phase 7 — Assembly
+
+Write `tape.yaml`.
+
+**Required top-level fields:** `title`, `description`, `curator`, `version: 1`, `mode` (`quick` or `methodology`), `sources` (non-empty list).
+
+**Recommended top-level fields:** `tags`, `created` (ISO date), `jtbd`, `methodology_version: "2.0"`, `license`.
+
+**Each kept source needs:**
+
+- `type` — `youtube` or `web` (v1 supports only these two; gated content, local files, and pasted content are v2)
+- `url`
+- `note` — the curator note drafted in Phase 4
+- `section` — matches a knowledge-map section
+- `priority: optional` — only for sources the user can skip with `--skip-optional`
+
+Order sources within each section by importance (most important first). Order sections by reading order (foundations first, applications later).
+
+**Validate before declaring done:**
+
+- YAML parses
+- All required fields present
+- `version: 1`
+- `mode` is `quick` or `methodology`
+- `sources` is non-empty
+- Every source has `type` and `url`
+- Every `type` is `youtube` or `web`
+- Every `url` parses
+
+If validation fails, fix and re-check before showing the user.
+
+### Phase 8 — Empirical test (optional in quick mode, required for library contribution)
+
+The only real test of whether the mixtape works.
+
+1. Compile: `liner compile <project-folder>`
+2. Open a fresh AI conversation. Don't paste the mixtape. Ask a substantive question that should benefit from the JTBD. Save the response.
+3. Open another fresh AI conversation. Paste `MIXTAPE.md` plus relevant `sources/*.md` files. Ask the same question. Save the response.
+4. Compare. Is the with-mixtape response meaningfully better — more specific, more accurate, more nuanced, less generic?
+
+Write findings to `working/05-empirical-test.md`: the question, the two responses (or summaries), the honest verdict. If the mixtape didn't help: what's missing? Back to Phase 2 or 5.
+
+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. Don't skip this for library contributions.
+
+## AI biases this skill must compensate for
+
+The skill is the AI running the methodology. The AI has systematic biases that produce worse mixtapes if left uncorrected. Watch for these in your own work throughout every phase — these are not phase-specific.
+
+- **Popularity bias.** AI surfaces popular and recent sources at the expense of canonical or older ones. Search deliberately for primary sources. The Apple HIG, the W3C spec, the canonical paper — these often won't appear in generic search results and need to be found directly.
+- **URL hallucination.** AI invents URLs that sound plausible but don't exist. Verify every URL with a web fetch before adding it to the candidate list. A 404 candidate is worse than a missing one.
+- **Generic curator notes.** AI drafts notes that say "this is a useful resource" without specifying role, location of value, or limitations. Compensate by writing each note against the three-thing template in `curator-notes.md`.
+- **Primary-document blindness.** AI gravitates to secondary commentary over primary sources. If a domain has a spec, a standard, or a foundational paper, search for it specifically. Don't accept commentary as a substitute.
+- **Framing-gap blindness.** AI can't see what it didn't search for. The framing-gap test in Phase 5 is the methodological correction for this. Run it with intent — not as a checkbox, as a genuine "what am I missing" question.
+- **Synthesis-as-recap.** AI-drafted synthesis tends to recap source content rather than distill the curator's framing of the domain. Push toward principles, contested questions, and framework distinctions — not "Source 1 says X; Source 2 says Y."
+
+If you find yourself producing any of these patterns, stop and correct.
+
+## Final delivery
+
+When all phases complete, the project folder contains:
+
+```
+<topic-slug>/
+├── tape.yaml
+├── synthesis.md
+└── working/
+    ├── 01-jtbd-and-knowledge-map.md
+    ├── 02-candidate-longlist.md
+    ├── 03-evaluation.yaml
+    ├── 04-quality-checks.md
+    └── 05-empirical-test.md   # if Phase 8 was run
+```
+
+Tell the user the folder is ready to compile with `liner compile <topic-slug>`. The compile step produces `MIXTAPE.md` and the `sources/` folder.
+
+## What this skill does NOT do
+
+- **Does not run `liner compile`.** That's the user's call, with the user's tools.
+- **Does not fetch from gated or local sources.** v1 supports only public `youtube` and `web` URLs. Personal sources (book chapters, gated articles, local files) are real and often high-value, but v1 doesn't support them.
+- **Does not maintain the shared content cache.** That's the CLI's job.
+- **Does not publish to the library.** Library contributions happen via PR to the Liner repo, in methodology mode, after passing the empirical test.
+
+## Common failure modes
+
+Patterns that produce bad mixtapes. Watch for them in your own work:
+
+- **The greatest-hits mixtape.** A list of the most famous resources. Looks impressive, adds little value because the AI already knows about famous resources from training. Curate for *non-obvious* sources.
+- **The unfocused mixtape.** No clear JTBD. Tries to cover the field. Shallow on everything, deep on nothing.
+- **The author-tribute mixtape.** Three of five sources by the same person because the curator is a fan. Narrows perspective, reduces synthesis quality.
+- **The transcript dump.** All video transcripts, no articles, no specs, no primary sources. Mix source types.
+- **The noteless mixtape.** Sources without curator notes. The curator either was lazy or didn't have a reason. Both are problems.
+- **The aspirational mixtape.** Sources the curator thinks people *should* read, not sources that help with the JTBD. Mixtapes are tools, not reading recommendations.
+- **The single-pass mixtape.** Curated without a framing-gap test. Well-covered within one narrow framing, blind to perspectives the curator didn't think to look for.
+
+If the mixtape this skill produces fits any of these patterns, return to the relevant phase and fix it.