linersh 0.5.7 → 1.0.0

package/cli-update-docs/LINER-MASTER.md

@@ -6,13 +6,13 @@ This document explains what Liner is, how it works, how it is built, how it is u
 
 Liner is an open-source toolkit for building curated AI context bundles called **mixtapes**.
 
-A mixtape is a project folder that contains:
+A Liner project is a folder. Its mixtape corpus lives under `mixtape/` in v2 projects and contains:
 
-- a recipe, `tape.yaml`
-- a curator synthesis, `synthesis.md`
-- extracted source files in `sources/`
-- optional working notes in `working/`
-- a compiled master file, `MIXTAPE.md`
+- a recipe, `mixtape/tape.yaml`
+- a curator synthesis, `mixtape/synthesis.md`
+- extracted source files in `mixtape/sources/`
+- optional working notes in `mixtape/working/`
+- a compiled master file, `mixtape/MIXTAPE.md`
 
 The point is simple: AI systems are much better when they are given a thoughtful, domain-specific context bundle instead of a pile of random links or whatever happens to be in the model's training data.
 
@@ -43,7 +43,7 @@ That is what Liner does.
 
 ### Tape
 
-A **tape** is the recipe. It lives in `tape.yaml`.
+A **tape** is the recipe. It lives in `mixtape/tape.yaml` in v2 projects.
 
 It names the mixtape, describes its purpose, identifies the curator, and lists the kept sources with notes, sections, and source metadata.
 
@@ -51,13 +51,13 @@ The tape is small and shareable. It can be edited by hand, stored in Git, review
 
 ### Mixtape
 
-A **mixtape** is the full project folder.
+A **mixtape** is the corpus inside the project folder.
 
 It includes the tape, the curator's synthesis, extracted source content, working notes, and compiled output.
 
 ### Consumable Mixtape
 
-The **consumable mixtape** is what an AI actually reads: `MIXTAPE.md` plus the referenced files in `sources/`.
+The **consumable mixtape** is what an AI actually reads: `mixtape/MIXTAPE.md` plus the referenced files in `mixtape/sources/`.
 
 `MIXTAPE.md` contains the curator synthesis, a source index, and links to the extracted source files.
 
@@ -73,24 +73,30 @@ A compiled project folder looks like this:
 
 ```text
 mobile-design-foundations/
-|-- MIXTAPE.md
-|-- tape.yaml
-|-- synthesis.md
-|-- sources/
-|   |-- 01-touch-target-size.md
-|   |-- 02-apple-gestures.md
-|   `-- ...
-|-- personal/
-|   `-- touch-target-paper.pdf
-`-- working/
-    |-- 01-jtbd-and-knowledge-map.md
-    |-- 02-candidate-longlist.md
-    |-- 03-evaluation.yaml
-    |-- 04-quality-checks.md
-    `-- 07-tape-draft.yaml
+|-- liner.yaml
+|-- LINER.md
+|-- SKILL.md
+|-- skills/
+|-- working/
+`-- mixtape/
+    |-- MIXTAPE.md
+    |-- tape.yaml
+    |-- synthesis.md
+    |-- sources/
+    |   |-- 01-touch-target-size.md
+    |   |-- 02-apple-gestures.md
+    |   `-- ...
+    |-- local-sources/
+    |   `-- touch-target-paper.pdf
+    `-- working/
+        |-- 01-jtbd-and-knowledge-map.md
+        |-- 02-candidate-longlist.md
+        |-- 03-evaluation.yaml
+        |-- 04-quality-checks.md
+        `-- 07-tape-draft.yaml
 ```
 
-`tape.yaml` is the source recipe. `synthesis.md` is the curator's distilled framing. `sources/` contains extracted content. `working/` contains the curation trace. `MIXTAPE.md` is the compiled entry point.
+`mixtape/tape.yaml` is the source recipe. `mixtape/synthesis.md` is the curator's distilled framing. `mixtape/sources/` contains extracted content. `mixtape/working/` contains the curation trace. `mixtape/MIXTAPE.md` is the compiled entry point.
 
 ## What Liner Is Good For
 
@@ -141,15 +147,15 @@ Use the Python CLI when you already have a project folder or prefer editing YAML
 
 ```sh
 liner init mobile-design-foundations
-# edit mobile-design-foundations/tape.yaml
-# write mobile-design-foundations/synthesis.md
+# edit mobile-design-foundations/mixtape/tape.yaml
+# write mobile-design-foundations/mixtape/synthesis.md
 liner compile mobile-design-foundations
 ```
 
 The compile step fetches and extracts sources, then writes:
 
-- `MIXTAPE.md`
-- `sources/NN-*.md`
+- `mixtape/MIXTAPE.md`
+- `mixtape/sources/NN-*.md`
 
 To share:
 
@@ -182,9 +188,9 @@ Use the `curating-mixtapes` skill when you want an AI assistant to run the curat
 
 The skill produces a project folder with:
 
-- `tape.yaml`
-- `synthesis.md`
-- `working/*` notes
+- `mixtape/tape.yaml`
+- `mixtape/synthesis.md`
+- `mixtape/working/*` notes
 
 The skill does not compile. After the skill finishes, run:
 
@@ -198,15 +204,17 @@ The current TUI-driven flow has six authoring phases plus Compile. The empirical
 
 ### Phase 1: Framing
 
-Define the job-to-be-done and sketch a knowledge map.
+Define the job-to-be-done, capability brief, knowledge map, and required source roles.
 
 The job-to-be-done is not the topic. "Mobile design" is a topic. *"When I'm designing the core UI of a consumer iOS app, I want to follow Apple's interaction conventions while choosing where to deviate visually, so I can ship something that feels native without looking generic"* is a job. The JTBD is written in Job Story form: `When [circumstance], I want [motivation], so I can [outcome].` See [CURATION.md](CURATION.md) Phase 1 and [JTBD-MASTER-PROMPT.md](JTBD-MASTER-PROMPT.md) for the full rubric.
 
+The capability brief says what the corpus should make a downstream AI agent better at. Required source roles name the evidence types the corpus must satisfy before source discovery can proceed.
+
 ### Phase 2: Candidate Discovery
 
 Gather more candidate sources than you expect to keep. This phase is about recall, not precision.
 
-Good tactics include following citations, mining expert reading lists, searching course syllabi, checking official docs, and asking AI to critique gaps rather than invent sources.
+Good tactics include following citations, mining expert reading lists, searching course syllabi, checking official docs, searching by required source role, and asking AI to critique gaps rather than invent sources.
 
 ### Phase 3: Evaluation
 
@@ -216,7 +224,7 @@ A kept source should have a specific role. The curator note should explain why t
 
 ### Phase 4: Quality Checks
 
-Run tests for redundancy, coverage, disagreement, framing gaps, and source-kind balance.
+Run tests for redundancy, coverage, disagreement, framing gaps, source-kind balance, and required source-role fit.
 
 This is where the methodology catches "good but narrow" corpora.
 
@@ -228,11 +236,11 @@ The synthesis is not a recap. It is the framing the AI should inherit before usi
 
 ### Phase 6: Assembly
 
-Write the final `tape.yaml`, order the sources, and prepare for compile.
+Write the final `mixtape/tape.yaml`, order the sources, and prepare for compile.
 
 ### Compile
 
-Fetch every kept source, extract readable content, write `sources/`, and produce `MIXTAPE.md`.
+Fetch every kept source, extract readable content, write `mixtape/sources/`, and produce `mixtape/MIXTAPE.md`.
 
 The TUI treats compilation as the completion milestone. A partial compile is still a usable finished state when `MIXTAPE.md` is written; the hub shows "Ready to use — compiled with warnings" and pressing Enter on Compile opens the existing compile result instead of fetching again. Recompile is explicit with `r` from the compile result screen.
 
@@ -248,13 +256,13 @@ This is a methodology practice, not a driven step in the TUI. As of v0.5.2 the T
 
 At a high level:
 
-1. Parse and validate `tape.yaml`.
-2. Read `synthesis.md`.
+1. Parse and validate `mixtape/tape.yaml`.
+2. Read `mixtape/synthesis.md`.
 3. Fetch or load every source.
 4. Extract readable content.
 5. Use cached content when valid.
-6. Write one file per source into `sources/`.
-7. Write `MIXTAPE.md`.
+6. Write one file per source into `mixtape/sources/`.
+7. Write `mixtape/MIXTAPE.md`.
 
 Supported source types:
 
@@ -274,7 +282,7 @@ If `trafilatura` itself crashes on a page, the web handlers now keep the source
 
 YouTube sources use transcript fetching first and fall back through `yt-dlp` where possible.
 
-Local files live under the project's `personal/` directory and can include Markdown, text, HTML, and PDFs.
+Local files live under the project's `local-sources/` directory or the legacy `personal/` directory and can include Markdown, text, HTML, and PDFs.
 
 ## How Sharing Works
 
@@ -286,9 +294,9 @@ The archive can include:
 - synthesis
 - source files
 - working notes
-- personal files, unless excluded
+- local source files, unless excluded
 
-Because compiled source content may include copyrighted or private material, a curator can share just the recipe or exclude personal/source content depending on the audience.
+Because compiled source content may include copyrighted or private material, a curator can share just the recipe or exclude local/source content depending on the audience.
 
 `liner import <archive>` unpacks a `.mixtape` and can refetch sources locally.
 
@@ -315,24 +323,27 @@ Important areas:
 - `src/liner/share.py` handles `.mixtape` archives.
 - `src/liner/manifest.py` aggregates process metadata from agent runs.
 
-The Python package is installable directly:
+The Python core can still be installed directly for development or fallback testing:
 
 ```sh
 pipx install linersh
 ```
 
-### TypeScript TUI
+### Terminal UI
 
-The TUI is a Node/React/Ink application in `packages/tui`.
+The active TUI is a Charm-based Go application in `packages/go-tui`.
+`packages/tui` is still the npm package/shim plus the TypeScript headless
+methodology runner; it is no longer the React/Ink TUI implementation. The old
+React/Ink UI is archived for reference under `ink/`.
 
 Important areas:
 
-- `packages/tui/src/App.tsx` owns screen routing.
-- `packages/tui/src/screens/` contains interactive screens.
+- `packages/go-tui/cmd/liner-tui/` starts the active terminal app.
+- `packages/go-tui/internal/app/` owns screen routing, key handling, and UI rendering.
 - `packages/tui/src/yaml-io.ts` reads and writes `tape.yaml`.
 - `packages/tui/src/bin-resolver.ts` finds the Python core.
 - `packages/tui/src/agents/` runs and parses agent-backed methodology phases.
-- `packages/tui/src/screens/CompileView.tsx` streams compile progress from the Python CLI.
+- `packages/go-tui/internal/core/` streams compile progress from the Python CLI.
 
 The TUI does not reimplement core compile/share/import behavior. It shells out to the Python core and reads structured progress events.
 
@@ -350,7 +361,7 @@ It contains the TUI plus a small `bin/liner.js` shim. Platform-specific Python b
 
 This follows the native-binary package pattern used by many developer tools: install the lightweight main package, let npm select the platform package that matches the host, then run the bundled binary.
 
-**Windows status as of 0.5.5:** npm support unblocked the Windows platform tarball and `linersh@0.5.5` includes `linersh-win32-x64` as an optional dependency alongside macOS and Linux packages.
+**Windows status:** npm support includes `linersh-win32-x64` as an optional dependency alongside macOS and Linux packages.
 
 The shim behavior:
 
@@ -375,11 +386,13 @@ Validation:
 python3 scripts/validate-platform-package.py --pack-dry-run
 ```
 
-The GitHub workflow `.github/workflows/platform-bundles.yml` builds and validates macOS, Linux, and Windows packages.
+The GitHub workflow `.github/workflows/platform-bundles.yml` builds platform
+package artifacts on manual dispatch. Publish manually only after all platform
+artifacts and the clean consumer release smoke pass.
 
 ### The Skill Bundle
 
-The skill bundle lives in `cli-update-docs/`.
+The tracked skill bundle lives in `docs/curation-skill/`.
 
 It encodes the curation methodology as executable instructions for an AI assistant. It is not the same thing as the CLI or TUI. It is one surface for producing Liner project folders.
 
@@ -448,7 +461,7 @@ sources:
     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,' Mobile HCI 2006."
     note: The canonical empirical study behind the 44pt minimum.
     section: evidence
@@ -461,8 +474,8 @@ sources:
 liner init mobile-design-foundations
 
 # Edit the recipe and synthesis.
-$EDITOR mobile-design-foundations/tape.yaml
-$EDITOR mobile-design-foundations/synthesis.md
+$EDITOR mobile-design-foundations/mixtape/tape.yaml
+$EDITOR mobile-design-foundations/mixtape/synthesis.md
 
 # Enable JS rendering if needed.
 liner setup-js
@@ -471,7 +484,7 @@ liner setup-js
 liner compile mobile-design-foundations
 
 # Use it in an AI conversation.
-# Paste MIXTAPE.md and selected files from sources/.
+# Paste mixtape/MIXTAPE.md and selected files from mixtape/sources/.
 
 # Share it.
 liner share mobile-design-foundations
@@ -524,23 +537,24 @@ Liner's methodology exists to catch these before compile.
 
 ## Project Status
 
-As of v0.5.5:
+As of v1.0.0:
 
 - The Python CLI is functional.
-- The TypeScript/Ink TUI is functional. The empirical-test phase has been removed from the driven flow — compilation is now the completion milestone (*compiled = complete*). The hub is a single summary view (status box + always-visible phase checklist), import auto-detects `.mixtape` files in the current folder, and completed/partial compiles open the existing compile result instead of rerunning by default.
+- The active Go TUI is functional. The old React/Ink TUI is decommissioned and archived under `ink/`. The empirical-test phase has been removed from the driven flow — compilation is now the completion milestone (*compiled = complete*). The hub is a single summary view (status box + always-visible phase checklist), import uses a file picker for `.mixtape` archives, and completed/partial compiles open the existing compile result instead of rerunning by default.
+- Phase 1 framing now validates the evidence plan before source discovery. The TUI requires a capability brief and required source roles with why/evidence/minimum coverage before advancing.
 - The npm distribution uses a main `linersh` package plus five optional platform packages (`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-x64`).
 - The release is installable via `npx linersh` on Mac, Linux, and Windows x64. `liner --version` reports the TUI version (and the bundled core version alongside it).
 - JavaScript-rendered web support is available through `liner setup-js`; the TUI prompts for it during first-run onboarding and from compile warnings when Chromium is missing.
 - `liner uninstall` exists for clean local reinstall tests.
-- The curation skill exists and is still being refined.
+- The curation skill exists, ships with the TUI package, and supports Claude or Codex as the local runner.
 - The MCP server, hosted web builder, and public library are planned.
 
 ## Where To Read Next
 
 - Root README: `README.md`
-- Curation methodology: `cli-update-docs/CURATION.md`
-- Mixtape format: `cli-update-docs/MIXTAPE-FORMAT.md`
-- Skill bundle: `cli-update-docs/SKILL.md`
+- Curation methodology: `docs/curation-skill/CURATION.md`
+- Mixtape format: `docs/curation-skill/MIXTAPE-FORMAT.md`
+- Skill bundle: `docs/curation-skill/SKILL.md`
 - TUI docs: `packages/tui/README.md`
 - Platform binary packaging: `packages/tui/PLATFORM-BUNDLES.md`
 - Publish checklist: `packages/tui/PUBLISH-CHECKLIST.md`