linersh 0.5.0 → 0.5.1

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

@@ -0,0 +1,147 @@
+# JTBD Master Prompt
+
+A drop-in prompt that interviews a Liner user and emits one tight, hyper-specific Job Story — the kind that belongs in the `jtbd:` field of a `tape.yaml`. Paste it into any AI chat as the opening message, or load it as Phase 1 inside the `curating-mixtapes` skill. Its only output is the Job Story sentence; everything downstream (knowledge map, candidate discovery, evaluation, synthesis) is Liner's job, not this prompt's.
+
+---
+
+## The prompt
+
+Copy everything between the `---BEGIN---` and `---END---` markers.
+
+```
+---BEGIN---
+You run a focused interview that ends in exactly one sentence: a job-to-be-done (JTBD) statement for the `jtbd:` field of a Liner `tape.yaml`. That sentence drives every downstream Liner decision, so it has to be tight. Your only deliverable is that statement, on its own line.
+
+## What "tight" means
+
+The form: "When [circumstance], I want [motivation], so I can [outcome]."
+
+All three slots are required. The form is permissive on what fills them — a legal Job Story, a clinical Job Story, and an engineering Job Story share this shape but no vocabulary. The form's only structural guarantee is that no slot can be empty; the rubric below catches the rest.
+
+Failures to refuse:
+
+- "When I'm working in healthcare, I want to do healthcare marketing, so I can grow the business." — All slots filled but each is mush; circumstance and motivation both restate the topic.
+- "When I'm practicing law, I want to be a better lawyer, so I can serve clients well." — Motivation is aspiration, not a concrete job.
+- "When our database hits scale limits, I want to migrate to PostgreSQL using Prisma, so I can ship features faster." — Solution baked into the motivation.
+- "When I'm prepping a class, I want to design a curriculum and teach it, so I can finish the term." — Two motivations joined by "and."
+- "When I'm doing marketing, I want to do it the right way, so I can succeed." — Circumstance, motivation, and outcome are all undefined.
+
+## Hard rules
+
+- No vendor, framework, library, methodology, or tool name in any slot of the final statement.
+- No "and," comma, or slash joining two circumstances, two motivations, or two outcomes. If the user describes two, ask which one this mixtape is for.
+- A bare noun phrase ("mobile design," "contract law") is not a JTBD. A JTBD has a scoped circumstance, a concrete motivation, and a meaningful outcome.
+- Do not invent context. If you don't know the user's role, platform, deadline, or audience, ask.
+- Do not credentialize ("As an expert JTBD practitioner..."). Name the task instead.
+- Do not narrate, summarize, or restate the conversation.
+- Output the statement alone on its own line. No quotes, code fence, header, or commentary.
+- Hard cap: five questions across the entire interview. Three is typical. If you're about to ask a fourth follow-up, draft instead.
+
+## Step 0: Offer to read project material
+
+Your first reply is one short question, before any interview questions:
+
+> Before we begin, do you have any documents or project material I should look at first? If yes, drop them into this chat (or point me at a folder if I have filesystem access here). If not, just say so and we'll talk it through.
+>
+> A few well-chosen files beat a full dump.
+
+This question does not count against the question budget.
+
+**If the user shares material:** Read it. Stop when you can name domain, audience, stage, and an explicit goal. Then go to confirmation (below).
+
+**If the user has no material to share:** Go straight to the interview protocol.
+
+**If the user points at a folder and you have no file tools:** Say so plainly and ask them to drop files into the chat or describe the project. Do not pretend you read something you couldn't.
+
+## Confirmation (after reading, if material was shared)
+
+One turn, one message:
+
+> I see your project is [X] for [Y], focused on [Z]. Is the mixtape meant to help you (a) [candidate], (b) [candidate], (c) [candidate], or (d) something else?
+
+Candidates are casual-language scopings, not Job Stories yet — you translate at emit time. `(d)` is required. If the user picks it, ask one descent question and draft.
+
+If the user contradicts what you read, the user wins. Probe the contradiction once if it changes the circumstance, motivation, or outcome; otherwise accept and proceed.
+
+## Interview protocol
+
+Open with a single batched message asking only what you can't infer from material the user shared:
+
+1. What domain or topic is this mixtape about?
+2. Who are you in this work — what role or context shapes which sources count as canonical?
+3. What will you actually do with an AI that has this context — one concrete activity, not a vibe?
+
+Skip any of those that shared material already answered.
+
+After the batch, one question at a time, walking down the scope ladder. The user expresses each level in casual language; you translate the micro level into Job Story form at emit time. Three illustrative fields (substitute the user's actual field):
+
+- **Clinical:** "be a great doctor" → "communicate diagnoses well" → "explain new diagnoses to patients" → "explain a new Type 2 diabetes diagnosis to an adult with low health literacy at a first visit."
+- **Engineering:** "ship faster" → "reduce CI runtime" → "speed up the integration test suite" → "speed up the integration test suite for a Rails 7 monolith with 3,200 tests while keeping coverage above 85%."
+- **Creative:** "write better" → "improve my essays" → "structure long-form essays" → "structure 4,000-word tech essays for a developer audience reading on mobile."
+
+The corresponding final Job Story for the clinical example would be: "When I deliver a new Type 2 diabetes diagnosis to an adult with low health literacy at a first visit, I want to explain the condition and the immediate care plan, so the patient leaves able to describe what diabetes is and one thing they need to do this week."
+
+The JTBD is done when the micro level is single-circumstance, single-scope, concrete enough that a mixtape built against it could be measurably better than no mixtape.
+
+**Prefer multi-choice over free-form.** Offer 2–4 candidate scopings in casual language; the user picks or overrides.
+
+**Stop when the next question wouldn't change the draft.** After the second descent question, draft silently. Only ask another question if the draft fails the rubric *and* the fix requires user input you don't already have.
+
+## Internal rubric (silent)
+
+Before emitting, check the draft. If any fail, fix and re-check.
+
+1. **Structural.** "When [X], I want [Y], so I can [Z]" — all three slots present and non-empty.
+2. **Solution-free.** No tool, framework, vendor, library, methodology, or specific method named in any slot.
+3. **Single scope.** No "and"/comma/slash joining two circumstances, two motivations, or two outcomes. If a slot decomposes into two complete jobs when split, you had two.
+4. **Specific, not generic or aspirational.** Circumstance is scoped to a real situation, not "when I'm working." Motivation is a concrete action, not "be better at X." Outcome is meaningful, not "so I can succeed."
+5. **Externally readable.** A stranger who has never seen this project could read it and understand what's being asked. Strip "my app," "the team," "our process" unless enough scope makes them legible cold.
+6. **Slot hygiene.** Audience and situational context belong in the circumstance, not the motivation. The motivation describes the action the user is taking; the circumstance describes who it's for and the situation around it. If the draft reads "I want to [action] for [audience]" or "I want to [action] that [explains/serves/teaches] [audience]," move the audience clause into the circumstance and tighten the motivation to the action alone. Sequential clauses in the outcome ("install, then understand, then build") are not a violation — they're one composite outcome.
+
+## Emit
+
+One line. The Job Story. Alone. No preamble, no "Here's your JTBD," no quotes, no code fence.
+
+If the user pushes back, do not defend. Take the correction, re-run the rubric, emit a new statement in the same format.
+---END---
+```
+
+---
+
+## Why it's shaped this way
+
+A few choices that aren't obvious:
+
+**Job Story format, not Liner's older house form.** Earlier versions of Liner used "Help me [verb] [object] [scope]." That form was easy to write and matched existing Liner artifacts, but it had no required slots — "Help me with healthcare marketing" looks like the form but isn't a job. The Job Story format ("When [circumstance], I want [motivation], so I can [outcome]") fails structurally when any slot is missing, which raises the floor on what counts as a JTBD before the rubric even runs. This realigns with the recommendation in the mixtape's own synthesis.
+
+**The first question is always the context-sharing offer.** This prompt is only ever used for one purpose: to help a user create a fresh JTBD for a Liner mixtape from scratch. Users won't paste pre-drafted JTBDs (the whole point is they don't have one yet) and they may not think to attach material unprompted. The single context-sharing question puts the affordance in front of them once, then gets out of the way. Earlier drafts of this prompt had a longer routing question and multiple "fast paths" for pre-attached material; both turned out to be friction solving for scenarios that don't happen in this prompt's actual deployment.
+
+**Slot hygiene as a sixth rubric check.** The other rubric tests catch missing slots, solution leakage, multi-scope jobs, mush, and unreadable references. They miss a recurring quieter failure: audience-scoping camped in the motivation slot. "I want to design a single-page site that explains the tool to people who already use AI" is technically one motivation, but the audience clause ("to people who already use AI") belongs in the circumstance. When audience drifts into the motivation, the circumstance gets thinner and the JTBD reads as less situated than it actually is. The sixth rubric check makes this generalizable rather than per-curator-judgment.
+
+**No persona block.** Recent empirical work on persona injection (Zheng et al., 162 personas / 2,410 questions) shows persona prompts don't improve task accuracy on average and that optimal-persona prediction is no better than random. Telling the model "you are an expert JTBD practitioner with twenty years of experience" buys nothing and costs a hedge in the output. The prompt names the task instead.
+
+**Failure modes listed before instructions.** Production system prompts shipped by frontier labs read as enumerated lists of mistakes the model used to make. That's the right register here — the prompt's job is to prevent the five specific failure modes (solution-baked-in, conflated jobs, topic-as-JTBD, aspirational mush, death-by-questions) more than it is to teach JTBD theory.
+
+**Hard question budget.** Five questions, three typical. The most common interview failure mode is death by clarification — the model keeps asking because "one more question" feels safer than committing. The budget forces a draft.
+
+**No rationale or knowledge map in the output.** This prompt has one job: produce the Job Story line. Anything else belongs to the next phase of curation, which Liner already runs.
+
+## How to use it
+
+The prompt's first move is always the same — ask the user whether they have project material to share, then either read what they hand over or interview them directly. What changes by environment is what counts as "shareable":
+
+**Pure chat (Claude.ai, ChatGPT, Cowork web).** Users paste the prompt block (between the BEGIN/END markers) into a fresh chat. They can drop files into the chat when the context-sharing question fires; folder paths aren't viable.
+
+**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 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.
+
+## Where it can still go wrong
+
+Three known soft spots worth knowing:
+
+- **Cooperative-user assumption.** The prompt has no defenses against a user trying to coax a JTBD that legitimizes a harmful product, or against prompt injection from pasted material. If you ever ship this in a context with hostile input, add a refusal clause.
+- **Asymmetric examples by design.** The prompt includes failing Job Story examples but no passing ones. Failing examples teach a rule (the failure mode generalizes the moment you read it); passing examples teach a style and anchor the model on whatever domains they're drawn from. The clinical example in the descent section illustrates *process shape*, not target output shape, which is a weaker anchor — but it's nonzero. If you observe users in adjacent fields pattern-matching on it, swap in two more descent examples from different fields, or strip the example entirely.
+- **Structural and slot-hygiene checks are necessary, not sufficient.** Slot 1 of the rubric only catches *omitted* slots, and slot 6 only catches misplaced audience clauses. They don't catch mush, weak audience scoping, or product-positioning that doesn't earn its slot — those remain curator-level judgments. The qualitative rubric stays load-bearing. The format and the structural checks raise the floor; they don't replace the rubric.

package/cli-update-docs/MIXTAPE-FORMAT.md

@@ -0,0 +1,398 @@
+# Mixtape Format
+
+The technical specification for Liner mixtapes.
+
+> **Status:** This specification describes the **v1** format (with v1.1 additions for `local_file` sources and `render: js`) as implemented in the CLI. Additional source types planned for v2 are documented at the end.
+
+---
+
+## Overview
+
+A Liner mixtape is a **folder**, not a single file. The folder contains the recipe, fetched source content, a synthesis, and a master file. Together they form a self-contained artifact ready to share, publish, or paste into an AI conversation.
+
+This document specifies:
+
+- The project folder structure
+- The `tape.yaml` recipe format
+- The contents of `MIXTAPE.md`, `synthesis.md`, and `sources/*.md`
+- The `working/` folder convention
+- The `.mixtape` export format
+- The versioning policy
+
+---
+
+## The project folder
+
+Every Liner mixtape is a directory. The directory name is a slug — lowercase, hyphenated, filesystem-safe:
+
+```
+mobile-design-foundations/
+├── MIXTAPE.md            # the consumable artifact
+├── tape.yaml             # the recipe
+├── synthesis.md          # the curator's distilled understanding
+├── sources/              # extracted content for kept sources
+│   ├── 01-<slug>.md
+│   ├── 02-<slug>.md
+│   └── ...
+├── personal/             # curator's local copies of `local_file` sources (optional)
+│   ├── chapter-3.pdf
+│   └── reader-mode-saved-article.md
+└── 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
+```
+
+The folder is the canonical unit. Any operation that reads or writes a mixtape works on a folder, not on individual files.
+
+A minimal valid project folder contains `tape.yaml`, `synthesis.md`, `MIXTAPE.md`, and a `sources/` directory with at least one file. The `working/` folder is recommended but not required. The `personal/` folder exists only when the recipe references at least one `local_file` source.
+
+---
+
+## `tape.yaml` — the recipe
+
+The recipe lists the kept sources with curator notes, organized by section. It is the input to `liner compile`, which produces `MIXTAPE.md` and populates `sources/`.
+
+### Required top-level fields
+
+| Field | Type | Description |
+|---|---|---|
+| `title` | string | Display name of the mixtape |
+| `description` | string | One-sentence description of the mixtape's purpose |
+| `curator` | string | Name of the curator |
+| `version` | integer | Tape format version. Must be `1` for v1 format |
+| `mode` | string | `quick` or `methodology` — how this mixtape was curated |
+| `sources` | list | At least one source entry |
+
+### Optional top-level fields
+
+| Field | Type | Description |
+|---|---|---|
+| `tags` | list of strings | Tags for discovery and filtering |
+| `created` | ISO date | Creation date |
+| `updated` | ISO date | Last meaningful update |
+| `license` | string | License identifier (e.g., `CC-BY-4.0`, `MIT`) |
+| `homepage` | URL | Link to the mixtape's home (e.g., its GitHub page) |
+| `jtbd` | string | The job-to-be-done statement in Job Story form: `When [circumstance], I want [motivation], so I can [outcome].` All three slots required. No solution names (vendor, framework, library, methodology, tool) in any slot. One job per slot — no "and"/comma/slash conjunctions. See [`CURATION.md`](CURATION.md) Phase 1 and [`JTBD-MASTER-PROMPT.md`](JTBD-MASTER-PROMPT.md) for the full rubric. |
+| `methodology_version` | string | Which version of CURATION.md was applied |
+
+### Source entries
+
+v1 supports three source types: `youtube`, `web`, and `local_file`.
+
+**Required fields per source:**
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | One of `youtube`, `web`, `local_file` |
+| `url` | URL | Required for `youtube` and `web` source types. Omitted for `local_file` |
+| `path` | string | Required for `local_file`. Relative path under `personal/` (e.g., `personal/foo.pdf`) |
+| `citation` | string | Required for `local_file`. Human-readable provenance: author, title, publication, date |
+
+**Optional fields per source (all types):**
+
+| Field | Type | Description |
+|---|---|---|
+| `note` | string | Curator note. Strongly recommended; required for library contributions |
+| `section` | string | Section label for grouping sources in the compiled mixtape |
+| `priority` | string | `required` (default) or `optional`. Optional sources can be excluded with `--skip-optional` |
+
+**Optional fields specific to `web` sources:**
+
+| Field | Type | Description |
+|---|---|---|
+| `render` | string | Controls how the page is fetched. **Absent (default)** — try server-rendered HTML first; if the page turns out to be JavaScript-only, automatically fall back to headless Chromium (requires `liner setup-js` to have been run). **`js`** — skip the server attempt and go straight to Chromium. **`server`** — server-rendered only; fail loudly on a JS stub. Use `server` for library submissions where you want the recipe to declare no hidden Playwright dependency. |
+
+**Optional fields specific to `local_file` sources:**
+
+| Field | Type | Description |
+|---|---|---|
+| (none yet) | | The required `path` and `citation` cover v1.1 |
+
+`local_file` sources can reference content the curator has on disk — book chapters, gated articles, exported PDFs, Reader-Mode-saved HTML. The `path` must resolve under the project's `personal/` subdirectory; absolute paths and `..` traversal are rejected at validation. Supported extensions are `.md`, `.txt`, `.html`, `.htm`, `.pdf`. The maximum file size is 10MB.
+
+### Example
+
+```yaml
+title: Mobile Design Foundations
+description: Core principles for native mobile UX.
+curator: Your Name
+version: 1
+mode: methodology
+tags: [mobile, design, ux]
+created: 2026-05-18
+license: CC-BY-4.0
+jtbd: 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.
+methodology_version: "2.0"
+
+sources:
+  - type: web
+    url: https://developer.apple.com/design/human-interface-guidelines/gestures
+    note: |
+      Apple's canonical gesture reference. Skim the overview;
+      the per-gesture detail is what matters.
+    section: foundations
+
+  - type: youtube
+    url: https://www.youtube.com/watch?v=XXXX
+    note: |
+      Watch first. The section starting at 14:30 on touch
+      target hierarchy is the load-bearing point.
+    section: foundations
+
+  - type: web
+    url: https://example.com/article-on-mobile-nav
+    note: |
+      Critique of bottom-tab navigation patterns. Take with
+      the next source which disagrees.
+    section: patterns
+
+  - type: web
+    url: https://example.com/counterargument
+    note: Defends bottom tabs for high-frequency apps.
+    section: patterns
+    priority: optional
+
+  - type: web
+    url: https://developer.apple.com/design/human-interface-guidelines/accessibility
+    render: js
+    note: Requires headless-browser rendering; install `linersh[js]` first.
+    section: foundations
+
+  - type: local_file
+    path: personal/touch-target-paper.pdf
+    citation: "Parhi et al., 'Target Size for One-Handed Thumb Use on Small Touchscreen Devices,' Mobile HCI 2006."
+    note: The canonical empirical study behind Apple's 44pt minimum.
+    section: craft
+```
+
+### Validation rules
+
+A `tape.yaml` is valid if and only if:
+
+1. The YAML parses
+2. All required top-level fields are present
+3. `version` is `1` (v1 parsers reject other values)
+4. `mode` is `quick` or `methodology`
+5. `sources` is a non-empty list
+6. Every source has a `type` in the allowed set: `youtube`, `web`, `local_file`
+7. For `youtube` and `web` sources: `url` is present and parses as a valid URL
+8. For `web` sources: if `render` is present, it is `server` or `js`
+9. For `local_file` sources: `path` and `citation` are present
+10. For `local_file` sources: `path` is a relative POSIX path starting with `personal/` and contains no `..` segments
+11. For `local_file` sources: the extension is one of `.md`, `.txt`, `.html`, `.htm`, `.pdf`
+12. `youtube` and `web` sources must not declare `path` or `citation`; `local_file` sources must not declare `url`
+
+Path existence and file-size limits are checked at compile time, not validation time — a tape can be valid even when the file isn't on disk yet (e.g., shared recipe before the recipient adds their own copy).
+
+Validation errors should point to the specific field and the specific problem.
+
+---
+
+## `synthesis.md`
+
+The synthesis is the curator's distilled understanding of the domain, expressed in their own voice. It is required — every mixtape has one.
+
+The synthesis covers:
+
+- The principles or framework the curator sees in the domain
+- Contested questions and where the curator stands
+- Distinctions between concepts that get confused
+- When to use what's in the mixtape and when to look elsewhere
+
+Length is typically 800–2000 words. Shorter for narrow topics; longer for broader ones.
+
+In quick mode, the synthesis is AI-drafted during compilation. In methodology mode, the curator writes or substantially edits it. Either way, it lives at `synthesis.md` in the project folder and gets included verbatim at the top of `MIXTAPE.md`.
+
+---
+
+## `MIXTAPE.md` — the master file
+
+`MIXTAPE.md` is what the consuming AI actually reads. It is produced by `liner compile` and combines the synthesis with a source index.
+
+Structure:
+
+```markdown
+# {title}
+
+> {description}
+
+**Curator:** {curator}
+**Compiled:** {ISO timestamp}
+**Sources:** {n}
+**JTBD:** {jtbd if present}
+
+---
+
+## How to use this mixtape
+
+[Standard boilerplate explaining that this is a curated context
+bundle, that the synthesis below provides framing, and that
+individual source files are referenced in the index and should
+be consulted when specific detail is needed.]
+
+---
+
+## Synthesis
+
+{contents of synthesis.md, verbatim}
+
+---
+
+## Sources
+
+{for each section, in order of first appearance:}
+
+### {section name}
+
+#### Source {N}: {source title or citation}
+
+- **Type:** {youtube|web|local_file}
+- **URL:** {source url} *(for youtube/web)*
+- **Citation:** {citation} *(for local_file)*
+- **Local path:** {path} *(for local_file)*
+- **Render:** {server|js} *(for web sources, only when explicitly set)*
+- **Author:** {author if known}
+- **Published:** {date if known}
+- **Curator note:** {note}
+- **Content file:** [sources/{nn}-{slug}.md](./sources/{nn}-{slug}.md)
+```
+
+The "How to use this mixtape" section is standard boilerplate. It tells the consuming AI that the synthesis carries the curator's framing, that source content lives in referenced files, and that the AI should load sources on demand when conversation requires specific detail.
+
+The source index entries contain enough metadata for the consuming AI to decide whether to load each source's full content. Curator notes are load-bearing for this routing decision — they're the signal that tells the AI which sources matter for which questions.
+
+---
+
+## `sources/`
+
+The `sources/` folder contains extracted text for every kept source, one file per source, named `01-<slug>.md` through `nn-<slug>.md`. Numbers match the source's position in the compiled mixtape; slugs come from the source's title.
+
+Each source file contains:
+
+```markdown
+# {source title or citation}
+
+**Source type:** {youtube|web|local_file}
+**URL:** {url}             *(for youtube/web)*
+**Citation:** {citation}   *(for local_file)*
+**Local path:** {path}     *(for local_file)*
+**Author:** {author if known}
+**Published:** {date if known}
+**Fetched:** {ISO timestamp}
+
+{extracted content}
+```
+
+For YouTube sources, the extracted content is the transcript, cleaned and joined into paragraphs. For web sources, it's the article text extracted via readability tools, stripped of navigation and boilerplate. For `local_file` sources, the content is extracted by type: `.md`/`.txt` files are read as-is; `.html` is extracted via the same readability pipeline as web sources; `.pdf` is extracted page-by-page via pdfplumber.
+
+Source content is stored at full extracted length. The master file pattern handles in-context efficiency by referencing sources on demand rather than embedding them in `MIXTAPE.md`.
+
+---
+
+## `working/` — the methodology made visible
+
+The `working/` folder contains the curator's research artifacts: the JTBD statement, the knowledge map, the candidate long-list, the evaluation pass with decisions and ratings, and the empirical test result if performed.
+
+Files are numbered to indicate phase order:
+
+```
+working/
+├── 01-jtbd-and-knowledge-map.md
+├── 02-candidate-longlist.md
+├── 03-evaluation.yaml
+├── 04-quality-checks.md
+└── 05-empirical-test.md
+```
+
+These are not required by the format but are recommended. Library contributions must include them.
+
+The evaluation file (`03-evaluation.yaml`) is structured — it lists every candidate source with the decision (kept, dropped, deferred) and the rationale. This is distinct from the cache (which holds source *content*); the evaluation file holds *decisions about* sources.
+
+Example `03-evaluation.yaml`:
+
+```yaml
+candidates:
+  - url: https://example.com/great-article
+    decision: kept
+    section: foundations
+    rationale: Canonical reference for the foundations section.
+    rating: 5
+  - url: https://example.com/listicle
+    decision: dropped
+    rationale: Shallow listicle, duplicates content in Source 3.
+    rating: 1
+  - url: https://example.com/contested
+    decision: kept
+    section: patterns
+    rationale: Strong perspective; paired with Source 5 which disagrees.
+    rating: 4
+```
+
+---
+
+## The content cache
+
+Source content fetched during research is stored in the curator's local cache, not in the project folder. The cache lives at `~/.liner/cache/` (or wherever `platformdirs` puts it on the user's OS).
+
+The cache is shared across all the curator's projects. A source fetched for one mixtape is available for all future mixtapes.
+
+When `liner compile` runs, it copies the cached content for kept sources into `sources/` in the project folder. The cache itself is not part of the mixtape and is not included in exports.
+
+See [PLATFORM.md](./PLATFORM.md) for the cache's role in the broader architecture.
+
+---
+
+## The `.mixtape` export format
+
+A `.mixtape` file is a zip archive of a project folder, produced by `liner share` and consumed by `liner import`.
+
+The archive contains the project folder at its root: `MIXTAPE.md`, `tape.yaml`, `synthesis.md`, `sources/`, `working/`, and `personal/` (when present). The archive does not contain anything from the shared content cache.
+
+On import, the receiving Liner unzips the folder, then refetches any sources whose URLs aren't already in the receiving curator's cache. Sources already cached are reused. `local_file` sources are read from the archived `personal/` directly — no refetch.
+
+Flags affecting the export:
+
+- `--no-working-notes`: exclude `working/` from the archive
+- `--no-personal`: exclude `personal/` from the archive. Used when the curator considers the local copies private (gated content, licensed material) or is preparing a library submission.
+- `--no-source-content`: exclude `sources/` from the archive. The recipient must re-fetch on first compile.
+- `--minimal`: include only `tape.yaml`. The recipient compiles from scratch — and must supply their own local files for any `local_file` sources.
+
+**Library contributions** must use `--no-personal` *and* must not contain any `local_file` sources in `tape.yaml`. The library accepts only mixtapes built from publicly fetchable sources.
+
+---
+
+## Versioning policy
+
+The mixtape format has its own version number, independent of the CLI/TUI version.
+
+- **v1** is the current format. Stable.
+- **v1.1 additions** (additive, non-breaking): the `local_file` source type, the `render` field on `web` sources, and the `personal/` subdirectory. v1 parsers that don't know about these will reject tapes that use them — they're not silently forward-compatible. v1.1-aware parsers accept everything older v1 parsers accept.
+- Breaking changes increment the format version. v1 mixtapes will continue to parse with v1 tools indefinitely. v2 tools will accept both v1 and v2 mixtapes for some transition period, with a documented migration path.
+- Additive, non-breaking changes (new optional fields, new source types) may happen within a major version with a minor version note.
+
+---
+
+## v2 — Planned additions (not yet implemented)
+
+The following source types and fields are designed but not yet implemented. Full specifications will land when the implementations do.
+
+### Additional source types
+
+- `gated_url` — content behind a paywall or login the curator has access to. References the original URL for provenance; requires a `content_file` pointing at a local copy.
+- `pasted` — short content entered directly into `tape.yaml`.
+- `local_media` — audio or video files. Requires external transcription before use.
+
+### Additional fields
+
+- `content` (for `pasted` sources) — the literal content as a multi-line string.
+- `content_file` (for `gated_url`) — path under `personal/` to a local file containing the saved content.
+- `path` (for `local_media`) — path under `personal/` to the media file.
+
+---
+
+## License
+
+This specification is part of the Liner project and is MIT-licensed.