linersh 1.0.0 → 1.0.1

package/README.md

@@ -27,7 +27,32 @@ liner
 
 With no arguments, `liner` launches the Go TUI. CLI subcommands such as
 `liner compile`, `liner share`, `liner import`, `liner status`, and
-`liner setup-js` pass through to the Python core.
+`liner setup-js` pass through to the Python core. If you are using one-shot
+`npx` instead of a global install, pass subcommands through the package:
+`npx --yes linersh@latest setup-js` or
+`npx --yes linersh@latest uninstall --yes`.
+
+## Try It Cleanly
+
+For a regular-user smoke test without touching your real Liner workspace:
+
+```sh
+tmp=$(mktemp -d)
+home="$tmp/home"
+cache="$tmp/npm-cache"
+projects="$tmp/projects"
+mkdir -p "$home" "$cache" "$projects"
+
+HOME="$home" npm_config_cache="$cache" LINER_DIR="$projects" npx --yes linersh@latest --version
+HOME="$home" npm_config_cache="$cache" LINER_DIR="$projects" npx --yes linersh@latest
+
+rm -rf "$tmp"
+```
+
+The second command opens the Go TUI. Create a test Liner Project, build the
+corpus with your configured local Claude or Codex runner, then run Create
+Operating Layer. Because `HOME`, the npm cache, and `LINER_DIR` all point inside
+`$tmp`, cleanup is just `rm -rf "$tmp"`.
 
 ## Run Locally
 

package/bin/liner.js

@@ -83,12 +83,14 @@ if (wantsCli(argv)) {
   }
 
   const resolved = resolveGoTuiBinary();
+  const headlessRunner = tryResolveHeadlessRunnerScript();
   const child = spawn(resolved.command, resolved.args, {
     stdio: "inherit",
     cwd: resolved.cwd || process.cwd(),
     env: {
       ...process.env,
       LINER_BIN: process.env.LINER_BIN || tryResolveCliCommand() || "",
+      LINER_HEADLESS_RUNNER: process.env.LINER_HEADLESS_RUNNER || headlessRunner || "",
     },
   });
   child.on("exit", (code, signal) => {
@@ -352,6 +354,11 @@ function tryResolveCliCommand() {
   return findRepoVenvBinary() || findBundledBinary() || findPathBinary() || null;
 }
 
+function tryResolveHeadlessRunnerScript() {
+  const candidate = join(packageRoot, "dist", "agents", "headless-runner.js");
+  return existsSync(candidate) ? candidate : null;
+}
+
 function printVersion() {
   const tui = readTuiVersion();
   let coreVer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linersh",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Liner — npm shim, Go TUI launcher, and headless methodology runner.",
   "type": "module",
   "license": "MIT",

package/cli-update-docs/ABOUT.md

@@ -1,69 +0,0 @@
-# About Liner
-
-Liner is an open-source toolkit for building curated context bundles — *mixtapes* — that make AI systems more useful within a specific domain.
-
-## The premise
-
-AI tools are bottlenecked on context, not capability. A model can produce better mobile design feedback when it has access to a thoughtful selection of platform conventions, practitioner writing, and contested perspectives than when it's relying on whatever made it into its training data. The same applies to almost any domain: the model improves dramatically when given good context, and the practical problem becomes assembling that context well.
-
-Right now, that work is invisible and manual. People paste transcripts and articles into chats one at a time. They maintain ad-hoc notes. They rebuild the same context bundle from scratch every time they switch tools. Existing platforms solve hosted use cases — NotebookLM and Claude Projects let you upload files into a sandbox — but the resulting artifact is trapped in the platform and can't be shared as a recipe.
-
-Liner treats curation as the work and produces a portable artifact.
-
-## What Liner is
-
-Liner is several things sharing a methodology and a file format:
-
-- **A CLI** for compiling mixtape projects
-- **A Go TUI** for the multi-step authoring lifecycle
-- **A skill** that runs the methodology inside Claude
-- **A planned MCP server** that will expose the same functions to any agent (Claude Code, Codex, Cursor, others)
-- **A planned library** of curated mixtapes anyone can clone, fork, or run as-is
-- **A methodology** documented in [CURATION.md](./CURATION.md) and applied across all the above
-
-The implemented pieces are independent. The CLI works without the TUI. The skill works without the CLI. The planned MCP server will add an agent-native surface later. Users pick the surface that fits their workflow.
-
-## What a mixtape is
-
-A mixtape is the corpus inside a Liner project folder. In v2 projects it lives under `mixtape/`; legacy root-level mixtape folders remain readable. The corpus contains:
-
-- A **recipe** (`mixtape/tape.yaml`) — the curated list of sources with notes and sections
-- A **synthesis** (`mixtape/synthesis.md`) — the curator's distilled understanding of the domain
-- **Source content** (`mixtape/sources/`) — extracted text from every source in the recipe
-- **Working notes** (`mixtape/working/`) — the methodology's traces: JTBD, capability brief, knowledge map, source roles, evaluation, quality checks
-- A **master file** (`mixtape/MIXTAPE.md`) — the consumable artifact, with the synthesis up front and sources referenced by file
-
-The recipe is small, shareable, and recompilable. The full Liner project folder is heavier, self-contained, and ready to hand to an AI session. The two artifacts have different sharing properties and different purposes.
-
-## Who Liner is for
-
-Developers, designers, researchers, and AI-curious power users who feed AI tools a lot of context and want to do it better. The audience overlaps significantly with people who already use the terminal, write Markdown, and have an opinion about how AI tools should work.
-
-Liner is not aimed at users who want a polished hosted product with no setup. NotebookLM is better for that audience. Liner is aimed at people who want a portable, scriptable, forkable workflow they control.
-
-## What makes Liner different
-
-A few decisions that distinguish Liner from adjacent tools:
-
-- **Curation is the work.** The methodology is the product, not an afterthought. Tools that auto-generate context bundles produce mediocre results because they skip the judgment step. Liner is structured around making that judgment easier.
-- **Portable artifacts.** Mixtape folders are plain text — YAML and Markdown. They can be edited by hand, generated by tools, shared in repositories, and forked into derivatives. Nothing is locked into a platform.
-- **No hosted backend.** Liner doesn't run a service. The CLI runs locally. The planned library will be a static repository. The website is a static site. No accounts, no servers, no infrastructure that can disappear.
-- **Two modes, same architecture.** Quick mode runs the methodology automatically; methodology mode runs it with substantive curator involvement. Same files, same format, different intensity. The planned library will accept methodology-mode mixtapes; personal use is whatever the curator wants.
-- **Multiple surfaces, one methodology.** The same curation process applies whether the user is in the terminal, in a Claude conversation, or driving an agent. The methodology document is the source of truth; everything else implements it.
-
-## How the pieces fit together
-
-- The **methodology** ([CURATION.md](./CURATION.md)) defines how to curate well.
-- The **mixtape format** ([MIXTAPE-FORMAT.md](./MIXTAPE-FORMAT.md)) defines what a mixtape folder contains and how `tape.yaml` is structured.
-- The **platform** ([PLATFORM.md](./PLATFORM.md)) defines how the Liner project specifically operates — implemented surfaces, planned surfaces, the future library, the contribution process, and the boundaries.
-- The **tools** (CLI, Go TUI, skill, and planned MCP server) implement the methodology and consume the format.
-
-A curator who learns the methodology can apply it with or without Liner's tools. A curator using Liner's tools can produce mixtapes that exist outside the Liner ecosystem. The methodology, the format, and the tools compose without locking into each other.
-
-## Project status
-
-Active development. The CLI and Go TUI are both functional and published on npm (current release v1.0.0, Mac, Linux, and Windows x64). They support the current tape format — `youtube`, `web`, `local_file`, and `skill` sources, with optional Playwright-backed JavaScript rendering for sites that need it (`liner setup-js`, surfaced by the TUI during onboarding and compile warnings). The TUI treats compilation as the corpus-ready milestone, opens existing compile results instead of rerunning by default, validates Phase 1 framing before source discovery can proceed, and creates an Operating Layer with `LINER.md`, root `SKILL.md`, and `liner.yaml`. The public library and MCP server are planned. The `curating-mixtapes` skill ships inside the TUI package. Maintained as a side project — see [PLATFORM.md](./PLATFORM.md) for the maintenance contract.
-
-## License
-
-MIT.

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

@@ -1,99 +0,0 @@
-# Liner AI Handoff
-
-Last updated: 2026-06-25
-
-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
-
-- 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.
-
-## What Liner Is Building
-
-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.
-
-The durable artifact set is:
-
-- `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
-
-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.
-
-## Current Methodology Shape
-
-Phase 1 framing must now produce more than a knowledge map. `working/01-jtbd-and-knowledge-map.md` needs:
-
-- `Capability Brief`
-- `Required source roles`
-- knowledge map
-
-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.
-
-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.
-
-## TUI UX Rules To Preserve
-
-- 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.
-
-## Active Docs
-
-Read these first for product and methodology work:
-
-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
-
-Marketing-site work has separate docs in `marketing/site/`.
-
-## Verification Commands
-
-TUI:
-
-```sh
-npm --prefix packages/tui test -- --run
-npm --prefix packages/tui run typecheck
-npm --prefix packages/tui run build
-```
-
-Python/core:
-
-```sh
-uv run --extra dev pytest
-python3 -m compileall -q src/liner
-```
-
-Docs hygiene:
-
-```sh
-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"
-```
-
-## Gotchas
-
-- `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

@@ -1,290 +0,0 @@
-# Curating Mixtapes
-
-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 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.
-
-The methodology has two intended audiences:
-
-- **Tools running the methodology automatically** — like the Liner skill, which encodes this document as instructions for an AI executing the lifecycle on a curator's behalf.
-- **Curators practicing the methodology themselves** — building library-quality mixtapes by engaging substantively at each step.
-
-Most users will be in the first group. Their tool runs the methodology for them; they confirm or lightly edit. The second group is the minority that produces the best mixtapes — including everything in the Liner library. This document serves both.
-
----
-
-## The bar
-
-A good mixtape demonstrably improves the AI's output on tasks within its domain. That's the only test that matters.
-
-A bad mixtape is one of three things: a bookmark dump (no curation), a popular-content collection (no taste), or a topical Wikipedia-style overview (no specificity). All three are easy to produce. None of them help.
-
-What makes a mixtape useful for an AI is different from what makes a reading list useful for a human. An AI doesn't need motivation, doesn't get bored, doesn't benefit from inspirational framing. What it does benefit from:
-
-- **Primary sources over commentary.** The original specification beats someone explaining the specification.
-- **Concrete over abstract.** "Touch targets should be 44pt minimum because..." beats "design with users in mind."
-- **Specific over general.** A 20-minute deep dive on one pattern beats a 60-minute survey of ten.
-- **Recent enough to be accurate, old enough to be durable.** The sweet spot for most topics is one to four years old for principles, very recent for platform specifics.
-- **Diverse perspectives where the field is contested.** If experts disagree, include both sides. The AI synthesizes better from disagreement than from echo chambers.
-
-A mixtape stuffed with motivational talks will produce worse AI output than a mixtape of three dense technical specifications. Counterintuitive but real.
-
----
-
-## The lifecycle
-
-Every mixtape moves through the same phases. The phases are ordered because each one's output is the next one's input. Skipping phases or running them out of order produces lower-quality mixtapes — even if the result looks complete.
-
-### Phase 1 — Framing
-
-Define the reusable capability. Not the topic. The *specific thing a future AI agent should be able to do*.
-
-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:
-
-- *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.*
-- *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 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.
-
-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 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:
-
-**Follow the citations.** Pick one excellent piece on the topic and find what *it* cites or links to. Then follow those sources' citations. Three or four hops in, you'll find the canonical sources nobody links to anymore because everyone assumes you've read them.
-
-**Reverse-engineer experts' reading lists.** Many domain experts publish their own reading lists or syllabi. Constrain searches to platforms like Notion, GitHub, Are.na, or personal blogs. Are.na in particular is underused.
-
-**Mine course syllabi.** University courses, bootcamp curricula, and serious online courses have already done curation work. `"<topic> syllabus" filetype:pdf` is a productive query.
-
-**Find who experts cite.** Pick three to five acknowledged experts. Look at *their* references — bibliographies, acknowledgments, who they cite in their own writing. The overlap is your shortlist.
-
-**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 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, 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 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 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:
-
-1. **Canonical references.** Apple HIG, Material Design docs, W3C specs, RFC documents, official platform documentation. Always include the primary source if one exists.
-2. **Practitioner deep-dives from people who built things.** Engineers and designers at credible companies writing about specific decisions they made. Concrete and battle-tested.
-3. **Conference talks from credible speakers.** Pre-filtered by the conference's curation. Better than random video search.
-4. **Books, but chapters not whole books.** Link to a specific chapter or excerpt. A tape isn't a book club.
-5. **Long-form interviews with practitioners.** Best when you cite a specific episode for a specific point.
-6. **Academic papers when relevant.** Often underrepresented in design and engineering mixtapes.
-
-What to avoid:
-
-- Listicles ("10 tips for...")
-- AI-generated content (now widespread, often subtly wrong)
-- Twitter threads as primary sources
-- Vendor blog posts with promotional angles
-- Most TED-style talks — too much narrative, not enough density
-- "Ultimate guides" — usually shallow despite the name
-
-Evaluations should include a brief reason. "This source is canonical for the foundations section." "This source duplicates Source 4 — drop the weaker one." "This source has a strong perspective; useful but read alongside Source 7." These reasons go into the working notes.
-
-### Phase 5 — Quality checks
-
-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.
-
-**The coverage test.** Walk through the knowledge map. Any bucket with zero sources? Either fill it or explicitly note that the mixtape doesn't cover that area. A mixtape that silently omits a major area is worse than one that says "this mixtape doesn't cover X — see [other mixtape] for that."
-
-**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 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.
-
-**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.
-
-**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
-
-Write the synthesis. This is the distilled understanding of the domain expressed in the curator's own voice — the principles, the contested questions, the framework distinctions, the recommended applications.
-
-The synthesis lives at the top of the compiled mixtape. It's the first thing the consuming AI reads. Without a synthesis, the AI gets a list of sources and curator notes; with a synthesis, the AI gets the curator's framing of the entire domain. The difference in downstream AI output is substantial.
-
-Length: 800–2000 words is typical. Shorter for narrow topics; longer for broader ones.
-
-The synthesis is required, not optional. In automated curation, the AI drafts it. In methodology-mode curation, the curator writes or substantially edits it. Either way, every mixtape has one.
-
-### Phase 7 — Final assembly
-
-Compile the mixtape. The compile step:
-
-- Reads the recipe and the synthesis
-- Reads cached source content for every kept source
-- Writes the master file (synthesis + how-to-use + source index)
-- Writes individual source files referenced by the master file
-
-The output is a self-contained mixtape folder ready to share, publish, or paste into an AI conversation.
-
-### Phase 8 — Empirical test (optional but recommended)
-
-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 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 capability is too broad.
-
-This empirical check is required for library contributions. Run it. Document the result.
-
----
-
-## Curator notes
-
-Every source in a mixtape has a curator note. The note tells the AI (and the human reading the mixtape) three things:
-
-- *Why this source is in the mixtape.* Signals weight. "Watch first — this is the foundational piece" vs. "Skim if time permits — useful for context but not essential."
-- *Where the high-value portion is.* "The first ten minutes are setup, the load-bearing content starts around 10:30."
-- *What the source's limitations are.* "Dated on platform specifics, durable on principles."
-
-Good notes are 15–40 words. Shorter is fine when the source is self-explanatory. Longer is usually a sign the source needs more framing — or that the note is doing work the synthesis should be doing.
-
-In automated curation, the AI drafts notes during evaluation. In methodology-mode curation, the curator writes or substantially edits them. Notes are not optional.
-
----
-
-## Personal sources
-
-Not every source has a public URL. The strongest mixtapes often draw on material that isn't publicly available — book chapters, gated articles, course transcripts, personal notes. These are often the highest-density material in a mixtape and shouldn't be excluded just because they aren't on the public web.
-
-Cite non-public sources clearly. Author, title, publication, date. The compiled mixtape uses these citations to signal what kind of source the AI is looking at, which matters for how it weights the content. A passage labeled as a 2019 book chapter gets read differently than one labeled as a recent newsletter post.
-
----
-
-## Sharing mixtapes
-
-Most mixtapes are personal — built for your own thinking, used by you, drawing on whatever you have legitimate access to. There's nothing to think hard about here.
-
-Sharing is different. A mixtape passed to a colleague or posted publicly distributes its contents to people other than you. Sources that are fine for personal use may not be appropriate to redistribute. Use your own judgment.
-
-When in doubt, share the recipe (the tape file) rather than the compiled mixtape. The recipe references sources; the compiled mixtape contains them. They have different properties when they leave your hands.
-
----
-
-## The two modes
-
-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 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.
-
-The default is quick mode because that's what most users want. Methodology mode is the path for serious curation work, including all library contributions.
-
----
-
-## Common failure modes
-
-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 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.
-
-**The transcript dump.** Many video transcripts, no articles, no specifications, no primary sources. Transcripts are useful but conversational and low-density. Mix sources.
-
-**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 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
-
-Most curators will use AI to help with research, source discovery, and drafting. This is fine and expected. The work goes better when the AI is treated as a collaborator with biases, not an oracle.
-
-AI is especially prone to:
-
-- Suggesting popular and recent sources at the expense of canonical or older ones
-- Hallucinating sources that sound plausible but don't exist (always verify URLs)
-- 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.
-
-The methodology assumes a human in the loop. Quick mode reduces what the human does; it doesn't eliminate it. The minimum is reviewing the AI's proposals at each gate. Anything less is automated source-listing, not curation.
-
----
-
-## What this is not
-
-Not a content recommendation system. Not a way to compile reading lists. Not optimized for human learning paths — those are different artifacts with different constraints.
-
-This is a way of producing artifacts that make AI systems demonstrably more useful within a specific domain. Everything in this document serves that goal.
-
-If decisions start prioritizing human readability or aesthetic completeness over AI utility, the methodology is drifting. Drift back.
-
----
-
-*Current version: 2.0. Changes are tracked in the repository changelog.*