linersh 0.5.7 → 1.0.1

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

@@ -1,398 +0,0 @@
-# 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   # optional methodology validation
-```
-
-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   # optional methodology validation
-```
-
-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.

package/cli-update-docs/PLATFORM.md

@@ -1,210 +0,0 @@
-# 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   # optional methodology validation
-```
-
-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`. This is methodology guidance, not a driven TUI phase.
-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.