linersh 1.1.3 → 1.2.1

package/README.md

@@ -1,21 +1,13 @@
-# Liner NPM Shim And Runner Package
+# Liner npm package
 
-This package is still named `linersh` because it owns the published `liner`
-binary. It is no longer the React/Ink TUI implementation.
+This package is named `linersh` because it owns the published `liner` binary.
 
-Active responsibilities:
+- `bin/liner.js`: the launcher. It opens the navigator, or forwards a subcommand
+  to Core.
+- Optional per-platform packages hold the native CLI and navigator binaries.
 
-- `bin/liner.js`: npm binary shim
-- Go TUI launcher for `packages/go-tui/` in development
-- TypeScript headless methodology runner under `src/agents/`
-- packaged curation skill bundle copied from `../../docs/curation-skill/` into
-  `cli-update-docs/`
-- optional per-platform packages that contain the native CLI and Go TUI
-  binaries for installed users
-
-The old React/Ink TUI has been decommissioned and is no longer part of the
-active package shape. `LINER_TUI=ink` intentionally fails with a decommissioning
-message.
+Every Core command has to be listed in `bin/liner.js`, or the launcher opens the
+navigator instead. A test in `tests/test_library_view.py` checks this.
 
 ## Install
 
@@ -25,7 +17,7 @@ npm install -g linersh
 liner
 ```
 
-With no arguments, `liner` launches the Go TUI. CLI subcommands such as
+With no arguments, `liner` opens the navigator. CLI subcommands such as
 `liner compile`, `liner share`, `liner import`, `liner project`,
 `liner sources`, `liner adapters`, `liner status`, and `liner setup-js` pass
 through to the Python core. If you are using one-shot
@@ -46,7 +38,7 @@ liner sources add <project> --type web --url <url> --note <note>
 liner project rename <project> --name <name>
 ```
 
-The Go TUI's `Maintain project` command uses the same contract. Optional Codex
+Optional Codex
 and Claude Maintenance Adapters are explicit CLI-delegating installations:
 
 ```sh
@@ -74,47 +66,17 @@ HOME="$home" npm_config_cache="$cache" LINER_DIR="$projects" npx --yes linersh@l
 rm -rf "$tmp"
 ```
 
-The second command opens the Go TUI. Create a test Liner Project, build the
-corpus with your configured OpenAI (Codex CLI) or Claude (Claude Code) runner,
-then run Create Operating Layer. Because `HOME`, the npm cache, and `LINER_DIR`
-all point inside `$tmp`, cleanup is just `rm -rf "$tmp"`.
+The second command opens the navigator, which is read-only. Ask your agent to
+build a test liner with `liner research`, using the same `LINER_DIR`, and watch
+it appear in the navigator. Because `HOME`, the npm cache, and `LINER_DIR` all
+point inside `$tmp`, cleanup is just `rm -rf "$tmp"`.
 
 ## Run Locally
 
-For normal repository testing, use the isolated launch so Projects and Settings
-cannot write to the production Liner library or profile:
-
 ```sh
 npm --prefix packages/tui run dev:isolated
 ```
 
-See [../../docs/development.md](../../docs/development.md) for explicit
-authenticated provider-home options and the offline runner-preferences smoke.
-
-From the repo root:
-
-```sh
-npm --prefix packages/tui run dev
-```
-
-From this package:
-
-```sh
-npm run dev
-```
-
-Override the projects folder:
-
-```sh
-LINER_DIR=/path/to/projects node bin/liner.js
-```
-
-Override the Python/core binary:
-
-```sh
-LINER_BIN=/absolute/path/to/liner node bin/liner.js
-```
-
 ## Build And Test
 
 ```sh
@@ -126,7 +88,7 @@ npm test
 
 Notes:
 
-- `build` compiles the TypeScript headless runner and shared runner utilities.
+- `build` compiles the version helper.
 - `build:go` compiles `../go-tui/cmd/liner-tui` into `bin/liner-tui` for local
   development.
 - `build:package` runs both.
@@ -141,20 +103,12 @@ Notes:
 
 - `LINER_DIR=/path/to/projects`: change the projects folder.
 - `LINER_BIN=/path/to/liner`: force the Python/core binary.
-- `LINER_GO_TUI_BIN=/path/to/liner-tui`: force the Go TUI binary.
-- `LINER_HEADLESS_RUNNER=/path/to/headless-runner.js`: force the methodology
-  runner script.
-- `LINER_AGENT=codex|claude`: override the agent selected by Liner config.
+- `LINER_GO_TUI_BIN=/path/to/liner-tui`: force the navigator binary.
 - `LINER_TUI=go`: accepted for compatibility, but no longer required.
 
 ## Developer Gotchas
 
 - Rebuild `bin/liner-tui` after Go changes or the npm shim may launch an older
   binary.
-- Rebuild `dist/` after TypeScript runner changes or methodology will fail.
 - The published main package intentionally excludes `bin/liner-tui`; installed
   users get the native TUI from `linersh-<platform>-<arch>`.
-- If Project Health says `status failed`, check the resolved core. Older bundled
-  cores may reject `--no-write`; the Go wrapper has a fallback, but direct
-  `node bin/liner.js status ... --no-write` can still fail until platform cores
-  are refreshed.

package/bin/liner.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // Entry shim for `npx linersh` / `liner`.
 //
-// No args: launch the selected TUI.
-//   unset         -> launch the Charm Go TUI
-//   LINER_TUI=go  -> launch the Charm Go TUI explicitly
-// CLI args: forward to the bundled Python core (or LINER_BIN/dev fallback).
+// No args: open the navigator (the Charm Go TUI).
+//   unset         -> open the navigator
+//   LINER_TUI=go  -> open the navigator explicitly
+// A known command: forward to the bundled Python core (or LINER_BIN/dev fallback).
+// Anything else: print an error instead of opening the navigator.
 //
 // This lets the npm package expose one binary name while still supporting
 // mechanical commands like `liner setup-js`, `liner compile`, and `liner status`.
@@ -43,6 +44,21 @@ const COMMAND_GROUPS = [
       { name: "status", description: "Show Liner Project status", owner: "core" },
       { name: "setup-js", description: "Set up JavaScript rendering support", owner: "core" },
       { name: "uninstall", description: "Remove local Liner state and caches", owner: "launcher" },
+      { name: "catalog", description: "List every liner in your library", owner: "core" },
+      { name: "search", description: "Search your liners", owner: "core" },
+      { name: "find-sources", description: "Find sources already in your library", owner: "core" },
+      { name: "library", description: "Report your whole library as JSON", owner: "core" },
+      { name: "handoff", description: "Write prompts for your agent", owner: "core" },
+      { name: "research", description: "Build a liner step by step with an agent", owner: "core" },
+      { name: "fetch", description: "Save a web page to a file in a liner", owner: "core" },
+      { name: "citations", description: "List a synthesis's citations", owner: "core" },
+      { name: "refresh", description: "Report what changed online", owner: "core" },
+      { name: "gaps", description: "Record what a liner couldn't answer", owner: "core" },
+      { name: "findings", description: "Review what real work learned", owner: "core" },
+      { name: "test", description: "Record with-and-without tests", owner: "core" },
+      { name: "use", description: "Point a repository at a liner", owner: "core" },
+      { name: "agent-skill", description: "Manage the liner skill", owner: "core" },
+      { name: "mcp", description: "Serve your liners over MCP", owner: "core" },
       {
         name: "--version",
         description: "Show installed launcher and core versions (-v)",
@@ -91,7 +107,11 @@ const CLI_COMMANDS = new Set(
   ),
 );
 
-if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+// Help wins anywhere unless a command owns the arguments
+// (`liner compile --help` and `liner uninstall --help` print their own help).
+const HELP_ARGS = new Set(["--help", "-h", "help"]);
+const ownsHelp = CLI_COMMANDS.has(argv[0]) || argv[0] === "uninstall";
+if (argv.length > 0 && !ownsHelp && argv.some((arg) => HELP_ARGS.has(arg))) {
   printHelp();
   process.exit(0);
 }
@@ -130,6 +150,9 @@ if (wantsCli(argv)) {
     }
     process.exit(code ?? 1);
   });
+} else if (argv.length > 0) {
+  printUnknownCommand(argv[0]);
+  process.exit(2);
 } else {
   const tui = (process.env.LINER_TUI || "go").toLowerCase();
   if (tui !== "go") {
@@ -145,14 +168,12 @@ if (wantsCli(argv)) {
   }
 
   const resolved = resolveGoTuiBinary();
-  const headlessRunner = tryResolveHeadlessRunnerScript();
   const child = spawn(resolved.command, resolved.args, {
     stdio: "inherit",
     cwd: resolved.cwd || process.cwd(),
     env: {
       ...process.env,
       LINER_BIN: process.env.LINER_BIN || tryResolveCliCommand() || "",
-      LINER_HEADLESS_RUNNER: process.env.LINER_HEADLESS_RUNNER || headlessRunner || "",
     },
   });
   child.on("exit", (code, signal) => {
@@ -441,13 +462,13 @@ function readTuiVersion() {
 
 function printHelp() {
   const lines = [
-    "Liner — build and use source-grounded Liner Projects.",
+    "Liner — a personal library of reusable research.",
     "",
     "Usage:",
-    "  liner                         Open the Go TUI",
+    "  liner                         Open the navigator",
     "  liner <command> [options]     Run a command",
     "",
-    "liner with no arguments opens the Go TUI.",
+    "liner with no arguments opens the navigator.",
     "Run `liner <command> --help` for detailed command help.",
     "",
   ];
@@ -466,6 +487,34 @@ function printHelp() {
   console.log(lines.join("\n"));
 }
 
+// A typo such as `liner compil` used to open the navigator silently. Name the
+// closest command instead, when one is a likely match.
+function printUnknownCommand(name) {
+  const known = [...COMMAND_GROUPS.flatMap((group) => group.commands.map((command) => command.name)), "--help"];
+  const typed = name.toLowerCase();
+  const suggestion = known
+    .map((command) => ({ command, distance: editDistance(typed, command) }))
+    .filter(({ command, distance }) => distance <= Math.max(1, Math.floor(command.length / 3)))
+    .sort((a, b) => a.distance - b.distance)[0];
+  const lines = [`Unknown command: ${name}`];
+  if (suggestion) lines.push(`Did you mean \`liner ${suggestion.command}\`?`);
+  lines.push("Run `liner --help` for the commands, or `liner` alone to open the navigator.");
+  console.error(lines.join("\n"));
+}
+
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current.push(Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + cost));
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+
 // Like resolveCliBinary() but non-fatal: returns null instead of exiting when
 // no core binary is found, so `--version` still prints the TUI version on a
 // host where the bundled core is missing (e.g. Windows pre-unblock).
@@ -475,11 +524,6 @@ function tryResolveCliCommand() {
   return findRepoVenvBinary() || findBundledBinary() || findPathBinary() || null;
 }
 
-function tryResolveHeadlessRunnerScript() {
-  const candidate = join(packageRoot, "dist", "agents", "headless-runner.js");
-  return existsSync(candidate) ? candidate : null;
-}
-
 function printVersion() {
   const tui = readTuiVersion();
   let coreVer = null;
@@ -490,5 +534,5 @@ function printVersion() {
       coreVer = r.stdout.trim().replace(/^liner\s+/i, "") || null;
     }
   }
-  console.log(coreVer ? `liner ${tui} (tui)  ·  ${coreVer} (core)` : `liner ${tui} (tui)`);
+  console.log(coreVer ? `liner ${tui} (tui) · ${coreVer} (core)` : `liner ${tui} (tui)`);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "linersh",
-  "version": "1.1.3",
-  "description": "Liner — npm shim, Go TUI launcher, and headless methodology runner.",
+  "version": "1.2.1",
+  "description": "Liner — npm launcher for the terminal navigator and Core CLI.",
   "type": "module",
   "license": "MIT",
   "author": "cmdux-sh",
@@ -17,10 +17,7 @@
     "liner": "bin/liner.js"
   },
   "files": [
-    "bin/liner.js",
-    "dist/",
-    "cli-update-docs/",
-    "maintenance-skill/"
+    "bin/liner.js"
   ],
   "scripts": {
     "build": "tsc",
@@ -31,8 +28,7 @@
     "dev:go": "node bin/liner.js",
     "predev:isolated": "node scripts/unhide-venv.mjs && npm run build:package",
     "dev:isolated": "node scripts/dev-isolated.mjs",
-    "smoke:runner-preferences": "node scripts/runner-preferences-smoke.mjs",
-    "prepack": "npm run release:check && node scripts/copy-skill-bundle.mjs && npm run build:package",
+    "prepack": "npm run release:check && npm run build:package",
     "release:check": "uv run python ../../scripts/release-version.py --check",
     "release:check:publish": "uv run python ../../scripts/release-version.py --check --check-registry --registry-package linersh",
     "prepublishOnly": "npm run release:check:publish && npm run typecheck && npm test && npm run build:package",
@@ -44,20 +40,17 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
-  "dependencies": {
-    "yaml": "^2.6.1"
-  },
   "optionalDependencies": {
-    "linersh-darwin-arm64": "1.1.3",
-    "linersh-darwin-x64": "1.1.3",
-    "linersh-linux-arm64": "1.1.3",
-    "linersh-linux-x64": "1.1.3",
-    "linersh-win32-x64": "1.1.3"
+    "linersh-darwin-arm64": "1.2.1",
+    "linersh-darwin-x64": "1.2.1",
+    "linersh-linux-arm64": "1.2.1",
+    "linersh-linux-x64": "1.2.1",
+    "linersh-win32-x64": "1.2.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.7.2",
-    "vitest": "^3.2.6"
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=18"

package/cli-update-docs/README.md

@@ -1,129 +0,0 @@
-# Curating Mixtapes — Skill Bundle
-
-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 authoring surfaces, alongside the CLI and TUI. The skill is
-the surface for Claude-Code-native and TUI-subprocess curation. Methodology-mode
-curators can also use it directly when working in a Claude Code session. It is
-not the Project Skill or the optional Maintenance Adapter.
-
-## Bundle contents
-
-Six files in one directory:
-
-```
-curating-mixtapes/
-├── SKILL.md                       # the orchestrator
-├── source-finding-tactics.md       # Phase 2
-├── source-quality-hierarchy.md     # Phase 4
-├── curator-notes.md                # Phase 4
-├── quality-check-tests.md          # Phase 5
-└── synthesis-guidance.md           # Phase 6
-```
-
-`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.
-
-The split is deliberate. Every invocation pulls SKILL.md's ~2,300 words into context regardless. Companion files add 1,000–1,500 words each but only at the phase that needs them, so total context cost scales with where the user is in the lifecycle rather than with the bundle's full size.
-
-## Where the bundle lives
-
-**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 `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.
-
-**TUI subprocess.** The Liner TUI bundles the skill internally and invokes it via the local Claude or Codex CLI in quick mode. The user doesn't see the skill directly; they see the TUI's wizard UI. The methodology being applied is this skill's.
-
-The same file contents work in every location. Don't fork between a local-test version and the package-shipped version.
-
-## Runtime requirements
-
-Filesystem access is required, not optional. The skill reads its own companion files at specific phases and writes mixtape artifacts to a project folder. It is designed for execution inside Claude Code or as a TUI subprocess, both of which have filesystem access by default. It is not designed for pure-chat (claude.ai) use.
-
-No MCP server is required. v1 uses Claude's own web search for candidate discovery and URL verification. When the Liner MCP server ships, a future skill version will use it for fetching and cache operations; v1 doesn't depend on it.
-
-## How invocation works
-
-The user says something the description matches. Claude loads SKILL.md. Claude reads it, identifies which mode applies (quick by default unless the user says otherwise or asks for library contribution), and begins the lifecycle.
-
-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 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.
-
-When all phases complete, the user runs `liner compile <project-folder>` themselves. The skill never compiles.
-
-## How to test the bundle
-
-Pick a small topic the curator hasn't already researched. "Writing better LLM evals," "Notion API patterns," "designing for color blindness" — narrow, technical, with enough source material that the corpus has shape but not so much that the run takes hours. Run the skill end-to-end in quick mode. Note where Claude struggles, where the methodology produces friction, where the gates fire awkwardly.
-
-Run again in methodology mode on the same topic. Compare the artifacts. The two modes should produce same-shape folders with different depth of curator engagement showing through. If the methodology-mode output looks indistinguishable from the quick-mode output, that's a signal the skill isn't asking enough of methodology-mode curators.
-
-For higher signal: run the skill in quick mode on a topic that already has a hand-curated mixtape (the CLI/TUI corpus is the obvious one). Compare the skill's tape file and synthesis against the hand-curated version. This is the empirical test for the skill itself, structurally identical to the methodology's Phase 8 test for mixtapes. If the skill's quick-mode output is meaningfully worse than the hand-curated version, that's expected — quick mode targets "good enough for personal use." If the gap is larger than expected, the skill needs work.
-
-## How to update or extend the bundle
-
-Three kinds of changes happen, each with a different shape.
-
-**Tightening SKILL.md.** Phase descriptions, gate behavior, trigger description, the AI-biases list, the failure-modes list. Edit in place. SKILL.md is the source of truth for the bundle's structure; everything else conforms to what SKILL.md says.
-
-**Editing a companion file.** Refinements to the tactics, hierarchy, notes guidance, tests, or synthesis advice. Edit in place. Keep the orchestrator references in SKILL.md unchanged unless the change affects when or how a companion gets read.
-
-**Adding a new companion file.** Two questions to answer first. Is the content concretely better than what could fit in SKILL.md? (Worked examples and pattern catalogs are the usual reasons.) Does the content apply to one specific phase rather than the whole lifecycle? If yes to both, add the companion and reference it from SKILL.md's lifecycle section. If no to either, the content probably belongs in SKILL.md itself or in CURATION.md.
-
-When adding a companion, update this README's "Bundle contents" section and the load-profile note in SKILL.md. Don't let the bundle's structure drift from how the README describes it.
-
-## Current status
-
-The bundle is functional and ships inside the npm TUI package so agent-backed phases can run from `npx linersh` without a separate skill install. The TUI copies this directory into the package during `prepack` and resolves it from the installed package root.
-
-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.
-
-In the local `1.1.0` release candidate, compilation is the Corpus Ready
-milestone and Create Operating Layer is the Project Complete milestone. A
-project can be usable when `MIXTAPE.md` is written but some Sources are missing
-or soft-failed after review. The TUI opens the existing compile result and
-requires an explicit retry or rerun. Phase 1 must produce a Capability Brief and
-Required source roles before discovery can proceed.
-
-## Three Skill Surfaces
-
-- The **curating-mixtapes skill** authors the initial corpus recipe, synthesis,
-  and working notes. It never performs post-creation maintenance.
-- The root **Project Skill** is created by the Operating Layer and teaches future
-  sessions how to use one completed Project.
-- The optional **Maintenance Adapter** is installed explicitly for Codex or
-  Claude and delegates supported changes to the installed CLI's current
-  guidance. A `type: skill` Source remains inert evidence and is not installed.
-
-## Versioning
-
-The skill bundle has its own version, independent of the CLI, TUI, and methodology document. Three version numbers track separately:
-
-- **Methodology version** is tracked in CURATION.md (`Current version: 2.0`).
-- **Skill bundle version** is the bundle's own — currently v0.3 internally, not yet stamped into SKILL.md frontmatter. Adding a `version` field to the frontmatter is a small open decision; the convention isn't established yet across Liner's surfaces.
-- **Methodology compatibility** is asserted by the `methodology_version` field the skill writes into generated `tape.yaml` files. The skill claims compatibility with the methodology version it was built against.
-
-When CURATION.md updates, the skill bundle may need a corresponding update. The question to ask: does the methodology change affect what the running AI should do, or just how a human reader explains the work? If the former, the skill needs an update; if the latter, the skill is fine as-is. Bias toward updating both together when in doubt.
-
-## Relationship to other Liner pieces
-
-The skill is the methodology made executable. It sits alongside Liner's other surfaces and shares the format and methodology with them.
-
-**CURATION.md** is the methodology described to humans. The skill bundle implements it for an AI executor. The two are paired artifacts that update together when the methodology changes substantively.
-
-**The Liner CLI** runs `liner compile` against the project folder this skill
-produces and owns supported post-creation maintenance. The curation skill never
-compiles and never bypasses the Core maintenance contract.
-
-**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.
-
-**The Liner library** publishes methodology-mode mixtapes. The skill can produce library-eligible output if run in methodology mode and the empirical test passes — but the bar for library contribution is real curator engagement, not the skill's quick-mode default.
-
-Treat changes to the bundle the way you'd treat changes to the methodology: deliberately, with examples, with a clear reason. The skill is the methodology executed at scale; drift in the skill is drift in the methodology.