linersh 0.5.6 → 1.0.0

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

@@ -2,13 +2,13 @@
 
 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.
+> **Status:** This specification describes the **v1 tape format** (with v1.1 additions for `local_file`, `skill`, and `render: js`) and the **v2 Liner project folder shape** now used by new projects. Legacy root-level mixtape folders remain readable.
 
 ---
 
 ## 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.
+A Liner project is a **folder**, not a single file. The root folder contains `LINER.md` and project capabilities. The `mixtape/` subfolder contains the recipe, fetched source content, synthesis, run logs, and compiled `MIXTAPE.md`. Together they form a self-contained artifact ready to share, publish, or paste into an AI conversation.
 
 This document specifies:
 
@@ -23,37 +23,35 @@ This document specifies:
 
 ## The project folder
 
-Every Liner mixtape is a directory. The directory name is a slug — lowercase, hyphenated, filesystem-safe:
+Every Liner project 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
+├── liner.yaml            # v2 project marker
+├── LINER.md              # project instructions for using the corpus
+├── skills/               # reusable project capabilities
+├── working/              # audits, impact tests, composition drafts
+├── children/             # optional child project references
+├── lineage.yaml          # optional composition history
+└── mixtape/
+    ├── MIXTAPE.md        # the consumable corpus artifact
+    ├── tape.yaml         # the recipe
+    ├── synthesis.md      # the curator's distilled understanding
+    ├── sources/          # extracted content for kept sources
+    ├── local-sources/    # curator/local captured files (optional)
+    ├── .liner-runs/      # phase run logs
+    └── working/          # methodology working files
 ```
 
-The folder is the canonical unit. Any operation that reads or writes a mixtape works on a folder, not on individual files.
+The root folder is the canonical unit. Any operation that reads or writes a Liner project works on the project folder, not on individual files. Corpus-specific readers resolve through `mixtape/`; legacy folders with root-level `tape.yaml` still resolve at the root.
 
-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.
+A minimal compiled v2 project contains `liner.yaml`, `mixtape/tape.yaml`, `mixtape/synthesis.md`, `mixtape/MIXTAPE.md`, and `mixtape/sources/` with at least one file. The methodology `mixtape/working/` folder is recommended but not required. `mixtape/local-sources/` exists only when local or captured sources are saved.
 
 ---
 
 ## `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/`.
+The recipe lists the kept sources with curator notes, organized by section. It is the input to `liner compile`, which produces `mixtape/MIXTAPE.md` and populates `mixtape/sources/` in v2 projects.
 
 ### Required top-level fields
 
@@ -64,7 +62,7 @@ The recipe lists the kept sources with curator notes, organized by section. It i
 | `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 |
+| `sources` | list | Source entries. May be empty while drafting; compile/share require usable sources. |
 
 ### Optional top-level fields
 
@@ -80,15 +78,15 @@ The recipe lists the kept sources with curator notes, organized by section. It i
 
 ### Source entries
 
-v1 supports three source types: `youtube`, `web`, and `local_file`.
+v1 supports four source types: `youtube`, `web`, `local_file`, and `skill`.
 
 **Required fields per source:**
 
 | Field | Type | Description |
 |---|---|---|
-| `type` | string | One of `youtube`, `web`, `local_file` |
+| `type` | string | One of `youtube`, `web`, `local_file`, `skill` |
 | `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`) |
+| `path` | string | Required for `local_file`; accepted for `skill`. `local_file` paths live under `local-sources/` or legacy `personal/` (e.g., `local-sources/foo.pdf`) |
 | `citation` | string | Required for `local_file`. Human-readable provenance: author, title, publication, date |
 
 **Optional fields per source (all types):**
@@ -111,7 +109,16 @@ v1 supports three source types: `youtube`, `web`, and `local_file`.
 |---|---|---|
 | (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.
+`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 `local-sources/` subdirectory or the legacy `personal/` subdirectory; absolute paths and `..` traversal are rejected at validation. Supported extensions are `.md`, `.txt`, `.html`, `.htm`, `.pdf`. The maximum file size is 10MB.
+
+**Fields specific to `skill` sources:**
+
+| Field | Type | Description |
+|---|---|---|
+| `path` | string | Installed skill name, local skill folder, `SKILL.md` path, or project-relative snapshot |
+| `url` | URL | GitHub skill URL. Use instead of `path` |
+
+Skill sources are read as reference artifacts. Liner never installs or executes them.
 
 ### Example
 
@@ -158,14 +165,19 @@ sources:
   - type: web
     url: https://developer.apple.com/design/human-interface-guidelines/accessibility
     render: js
-    note: Requires headless-browser rendering; install `linersh[js]` first.
+    note: Requires headless-browser rendering; run `liner setup-js` first.
     section: foundations
 
   - type: local_file
-    path: personal/touch-target-paper.pdf
+    path: local-sources/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
+
+  - type: skill
+    path: mobile-design-review
+    note: Reference skill for how to structure mobile design critique.
+    section: craft
 ```
 
 ### Validation rules
@@ -176,14 +188,15 @@ A `tape.yaml` is valid if and only if:
 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`
+5. `sources` is a list. It may be empty while drafting; compile/share require usable sources.
+6. Every source has a `type` in the allowed set: `youtube`, `web`, `local_file`, `skill`
 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
+10. For `local_file` sources: `path` is a relative POSIX path starting with `local-sources/` or legacy `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`
+12. For `skill` sources: either `path` or a GitHub `url` is present
+13. `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).
 
@@ -204,7 +217,7 @@ The synthesis covers:
 
 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`.
+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 corpus folder (`mixtape/synthesis.md` in v2 projects) and gets included verbatim at the top of `MIXTAPE.md`.
 
 ---
 
@@ -304,12 +317,13 @@ working/
 ├── 02-candidate-longlist.md
 ├── 03-evaluation.yaml
 ├── 04-quality-checks.md
-└── 05-empirical-test.md   # optional methodology validation
+├── 05-operating-fit-audit.md   # optional improvement recommendation
+└── 06-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.
+The evaluation file (`03-evaluation.yaml`) is structured — it lists every candidate source with the decision (`kept`, `trim`, or `dropped`), the rationale, and content evidence for every kept or trimmed source. This is distinct from the cache (which holds source *content*); the evaluation file holds *decisions about* sources and the evidence that those decisions came from readable content.
 
 Example `03-evaluation.yaml`:
 
@@ -320,6 +334,15 @@ candidates:
     section: foundations
     rationale: Canonical reference for the foundations section.
     rating: 5
+    jtbd_fit: direct
+    fetch_status: readable
+    content_quality: high
+    evidence:
+      - The article names the core method the corpus teaches.
+      - It shows the method working through a concrete example.
+    note: >
+      Role: Canonical reference. Value: Defines the foundation clearly.
+      Limitations: Needs to be paired with applied examples.
   - url: https://example.com/listicle
     decision: dropped
     rationale: Shallow listicle, duplicates content in Source 3.
@@ -329,17 +352,26 @@ candidates:
     section: patterns
     rationale: Strong perspective; paired with Source 5 which disagrees.
     rating: 4
+    jtbd_fit: bridge
+    fetch_status: partial
+    content_quality: medium
+    evidence:
+      - The available excerpt makes a specific argument about the pattern.
+      - The source identifies a tradeoff that can be tested against Source 5.
+    note: >
+      Role: Contrasting perspective. Value: Prevents a one-note pattern section.
+      Limitations: Partial fetch, so only use the claims evidenced by the excerpt.
 ```
 
 ---
 
 ## 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).
+Source content fetched during research is stored in the curator's local cache, not in the project folder. The cache lives at `~/.liner/cache.db` (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.
+When `liner compile` runs, it copies the cached content for kept sources into `sources/` in the corpus 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.
 
@@ -349,14 +381,14 @@ See [PLATFORM.md](./PLATFORM.md) for the cache's role in the broader architectur
 
 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.
+The archive contains the project folder at its root. For v2 projects that includes root project files such as `liner.yaml`, `LINER.md`, and `SKILL.md`, plus `mixtape/tape.yaml`, `mixtape/synthesis.md`, `mixtape/MIXTAPE.md`, `mixtape/sources/`, `mixtape/working/`, and `mixtape/local-sources/` when present. Legacy root-level projects with `tape.yaml`, `MIXTAPE.md`, `sources/`, `working/`, and `personal/` remain supported. 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.
+On CLI import, the receiving Liner unzips the folder, then refetches any sources whose URLs aren't already in the receiving curator's cache unless `--no-refetch` is passed. Sources already cached are reused. `local_file` sources are read from archived `local-sources/` or legacy `personal/` files directly — no refetch. TUI import extracts the archive into the workspace and leaves refetching to a later compile.
 
 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-personal`: exclude `local-sources/` and legacy `personal/` files 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.
 
@@ -369,7 +401,7 @@ Flags affecting the export:
 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.
+- **v1.1 additions** (additive, non-breaking): the `local_file` and `skill` source types, the `render` field on `web` sources, and the `local-sources/` subdirectory with legacy `personal/` compatibility. 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.
 
@@ -388,8 +420,8 @@ The following source types and fields are designed but not yet implemented. Full
 ### 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.
+- `content_file` (for `gated_url`) — path under `local-sources/` to a local file containing the saved content.
+- `path` (for `local_media`) — path under `local-sources/` to the media file.
 
 ---
 

package/cli-update-docs/PLATFORM.md

@@ -10,17 +10,17 @@ This document assumes the reader has read [ABOUT.md](./ABOUT.md) (what Liner is)
 
 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.
+**CLI** (bundled Python core behind the npm `liner` binary). Atomic operations on Liner 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`.
+**Go TUI** (Charm Bubble Tea, launched with `npx linersh`). Interactive multi-step lifecycle runner. Drives the methodology with sensible defaults, calls the bundled Python core for setup and compilation, and invokes the configured AI runner for research phases. The right tool for authoring new Liner projects. Features a projects browser, guided agent phases, structured review gates, optional JS-rendering setup, source-warning recovery paths, import file picker, and progress views for long-running work.
 
 **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.
+**MCP server** (planned). Will expose 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.
+**Web builder** (planned). 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 implemented surfaces are independent. Planned surfaces should preserve that contract.
 
 ---
 
@@ -42,46 +42,47 @@ The TUI runs quick mode by default with methodology mode available as a slower p
 
 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
+1. **Framing** — JTBD statement, capability brief, knowledge map, required source roles
+2. **Candidate discovery** — long-list of URLs based on the knowledge map and source roles, 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
+5. **Quality checks** — redundancy, coverage, disagreement, framing-gap, source-kind, and source-role 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/`
+7. **Final assembly** — `liner compile` writes `mixtape/MIXTAPE.md` and populates `mixtape/sources/` in v2 projects
 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.
+Three natural human-in-the-loop gates: framing confirmation before source search, candidate confirmation before fetching (saves wasted network calls), and evaluation review before synthesis (catches the AI's misjudgments). Quick mode can auto-accept gates while preserving progress state; methodology mode pauses for real review.
+
+The TUI also enforces a Phase 1 artifact contract. Framing is not complete until `working/01-jtbd-and-knowledge-map.md` contains a capability brief and required source roles with why/evidence/minimum coverage. If the agent exits cleanly but misses the contract, the TUI keeps the project on Phase 1 and resumes the agent with the validation issue.
 
 ---
 
 ## The artifacts
 
-A mixtape is a folder, not a file. The folder is the canonical unit; everything else is derived from it.
+A Liner project is a folder, not a file. The project folder is the canonical unit; the mixtape corpus lives under `mixtape/` in v2 projects and 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
+├── liner.yaml            # v2 project marker and metadata
+├── LINER.md              # operating instructions for future agents
+├── SKILL.md              # optional project skill entry point
+├── skills/               # reusable project capabilities
+├── working/              # audits, impact tests, composition drafts
+└── mixtape/
+    ├── MIXTAPE.md        # the consumable corpus artifact
+    ├── tape.yaml         # the recipe — kept sources, sections, notes
+    ├── synthesis.md      # the curator's distilled understanding
+    ├── sources/          # extracted content for kept sources
+    ├── local-sources/    # curator/local captured files (optional)
+    ├── .liner-runs/      # phase run logs
+    └── working/          # methodology working files
 ```
 
 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.
+- A **tape file** (`mixtape/tape.yaml` in v2 projects) 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 corpus inside the project folder. In v2 projects it lives under `mixtape/`; legacy root-level mixtape folders remain readable.
+- The **consumable mixtape** is `mixtape/MIXTAPE.md` plus the `mixtape/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.
 
@@ -91,7 +92,7 @@ Three concepts to distinguish:
 
 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).
+Default location: `~/.liner/cache.db` (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.
 
@@ -101,15 +102,15 @@ The cache is never included in `.mixtape` exports. When a recipient imports a `.
 
 ---
 
-## The library
+## The library (planned)
 
-The Liner library is a curated collection of public mixtapes at [liner.sh/library](https://liner.sh/library), backed by a Git repository.
+The Liner library is planned as 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.
+**Structure.** Each mixtape will be a directory in the repo. The website will render these as individual pages. Users will be able to 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.
 
@@ -117,11 +118,11 @@ The Liner library is a curated collection of public mixtapes at [liner.sh/librar
 
 ## Contributing
 
-The library accepts pull requests for methodology-mode mixtapes only.
+The planned library will accept 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`
+2. Run the empirical test — compile the mixtape, compare AI output with and without it on a real question. Document the result in `mixtape/working/06-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 `mixtape/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.
@@ -134,16 +135,16 @@ Accepted mixtapes are credited to the curator by name. Curators retain authorshi
 
 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).
+The exported `.mixtape` includes everything in the project folder: root project files such as `liner.yaml`, `LINER.md`, and `SKILL.md`, plus `mixtape/tape.yaml`, `mixtape/synthesis.md`, `mixtape/MIXTAPE.md`, `mixtape/sources/`, `mixtape/working/`, and `mixtape/local-sources/` when present. Legacy root-level `sources/`, `working/`, and `personal/` folders are still supported. The archive does not include anything from the shared content cache.
 
-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.
+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 unless import is run with `--no-refetch`. Sources already cached are reused. `local_file` sources read from archived `local-sources/` or legacy `personal/` files directly — no refetch. The TUI import flow extracts the archive and leaves refetching to a later compile.
 
 **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.
+- `--no-working-notes`: exclude `mixtape/working/` and legacy root-level `working/` from the export. For curators who consider their working notes private. Default is to include them.
+- `--no-personal`: exclude `local-sources/` and legacy `personal/` files 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 `mixtape/sources/` and legacy root-level `sources/`. The recipient must re-fetch on first compile.
+- `--minimal`: produce a smaller zip containing only `mixtape/tape.yaml` in v2 projects. For sharing the recipe only. The recipient compiles fresh.
 
 ---
 
@@ -152,10 +153,10 @@ On `liner import <file.mixtape>`, the receiving Liner unzips the folder, then re
 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 accounts in v1.** The CLI, TUI, planned 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 LLM calls in the core CLI.** The CLI does not call AI models. The TUI invokes the user's configured local runner for methodology phases. All AI work happens through the user's own subscription or local toolchain. Liner doesn't pay for inference.
+- **No headless browser by default.** Plain `npx linersh` works without downloading Chromium. JavaScript-rendered sites (Apple HIG, Notion, many SPAs) require the opt-in `liner setup-js` step, which installs Playwright browser support locally. There is 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.
 
@@ -187,7 +188,7 @@ Liner is a side project. The maintenance contract:
 - 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
+- The planned library will be 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.
 
@@ -199,7 +200,7 @@ 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.
+- **Tools** (CLI, Go TUI, skill, and planned 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.
 

package/cli-update-docs/README.md

@@ -1,6 +1,6 @@
 # Curating Mixtapes — Skill Bundle
 
-This is the Liner methodology made executable by Claude. The bundle implements CURATION.md v2.0 as instructions to a running AI, drives the mixtape lifecycle from a topic to a project folder ready for `liner compile`, and supports both quick mode (the AI does most of the work, the user confirms at two gates) and methodology mode (the curator engages substantively at every phase).
+This is the Liner methodology made executable by Claude or Codex. The bundle implements CURATION.md v2.0 as instructions to a running AI, drives the mixtape lifecycle from a task description to a project folder ready for `liner compile`, and supports both quick mode (the AI does most of the work, with lightweight gate review) and methodology mode (the curator engages substantively at every phase).
 
 It is one of Liner's surfaces, alongside the CLI, the TUI, the planned MCP server, and the planned web builder. The skill is the surface for Claude-Code-native and TUI-subprocess authoring. Methodology-mode curators can also use it directly when working in a Claude Code session.
 
@@ -18,7 +18,7 @@ curating-mixtapes/
 └── synthesis-guidance.md           # Phase 6
 ```
 
-`SKILL.md` is the orchestrator. It defines the trigger description, the two modes, the two gates, the eight-phase lifecycle skeleton, the AI biases to compensate for, the boundaries (what the skill does NOT do), and the failure modes to watch. It is always loaded when the skill fires.
+`SKILL.md` is the orchestrator. It defines the trigger description, the two modes, the review gates, the lifecycle skeleton, the AI biases to compensate for, the boundaries (what the skill does NOT do), and the failure modes to watch. It is always loaded when the skill fires.
 
 The five companion files are loaded only at the phases that use them. Phases 1, 3, 7, and 8 have no companion file — their guidance fits inside SKILL.md.
 
@@ -28,7 +28,7 @@ The split is deliberate. Every invocation pulls SKILL.md's ~2,300 words into con
 
 **Local testing.** Drop this directory into `~/.claude/skills/curating-mixtapes/`. Claude Code and Claude Desktop both look there for user-installed skills. The skill fires when the user says something the description matches — "help me make a mixtape on [topic]" is the canonical trigger.
 
-**Shipping.** The canonical bundle lives at repo-root `cli-update-docs/`. The TUI copies this directory into `packages/tui/cli-update-docs/` during `prepack` and ships it inside the `linersh` npm package, so end users do not need a separate skill install for TUI-driven agent phases.
+**Shipping.** The canonical bundle lives at `docs/curation-skill/`. The TUI copies this directory into `packages/tui/cli-update-docs/` during `prepack` and ships it inside the `linersh` npm package, so end users do not need a separate skill install for TUI-driven agent phases.
 
 **Direct skill use.** A documented copy/install flow for using the skill outside the TUI is still planned. Until then, direct local use is a developer workflow.
 
@@ -48,7 +48,7 @@ The user says something the description matches. Claude loads SKILL.md. Claude r
 
 At Phase 2, Claude reads `source-finding-tactics.md`. At Phase 4, Claude reads `source-quality-hierarchy.md` and `curator-notes.md`. At Phase 5, Claude reads `quality-check-tests.md`. At Phase 6, Claude reads `synthesis-guidance.md`. Each companion file is read at the start of its phase, before any work in that phase happens.
 
-The two gates pause for user input. In quick mode, the default is "looks good, continue" — Claude proceeds unless the user actively objects. In methodology mode, Claude pauses for substantive review.
+The gates pause for user input. In quick mode, defaults can auto-continue while preserving project state. In methodology mode, the AI pauses for substantive review.
 
 The skill writes artifacts to a project folder named for the topic (e.g., `mobile-design-foundations/`) as it goes. The working notes are produced phase by phase, so the user can stop at any phase boundary and resume later — the working files are picked up where they were left.
 
@@ -80,7 +80,7 @@ The bundle is functional and ships inside the npm TUI package so agent-backed ph
 
 The bundle still benefits from more worked examples in the companion files, but it is no longer blocked by the old "second pass before any shipping" constraint. Current product risk lives more in curation quality and fetcher edge cases than in basic skill availability.
 
-As of `linersh@0.5.5`, compilation is the product completion milestone. A project can be "ready to use — compiled with warnings" when `MIXTAPE.md` is written but some sources are missing or soft-failed. The TUI opens the existing compile result for a completed mixtape and requires an explicit retry/re-run from that screen.
+As of `linersh@1.0.0`, compilation is the corpus-ready milestone and Create Operating Layer is the project-complete milestone. A project can be "ready to use — compiled with warnings" when `MIXTAPE.md` is written but some sources are missing or soft-failed. The TUI opens the existing compile result for a completed mixtape and requires an explicit retry/re-run from that screen. Framing also has a validation contract: Phase 1 must produce a capability brief and required source roles before source discovery can proceed.
 
 ## Versioning
 
@@ -100,7 +100,7 @@ The skill is the methodology made executable. It sits alongside Liner's other su
 
 **The Liner CLI** runs `liner compile` against the project folder this skill produces. The skill never compiles; the CLI never authors. Clean split.
 
-**The Liner TUI** invokes this skill internally for quick-mode authoring via the Claude Agent SDK. Same methodology, different UX.
+**The Liner TUI** invokes this skill internally for agent-backed authoring via the local Claude or Codex CLI. Same methodology, different UX.
 
 **The Liner MCP server** (planned) will expose mechanical operations — fetch this URL, validate this tape file, query the cache — as tools. A future skill version will use those tools where v1 uses Claude's own web search.