forgetrail 0.3.0

package/prompts/ux-cohesion-audit.md

@@ -0,0 +1,165 @@
+# UX Cohesion Audit
+
+Whole-app, fresh-eyes read of where a product **confuses, blocks, distracts, or fails to delight** — everything that stops a user from *falling in love* with the app. Unlike a single-surface usability pass, this audit looks at the product as **one experience** and surfaces the cross-cutting "feels like N apps stitched together" problems that are invisible when you review surfaces in isolation. Produces a prioritized findings spec that **points at existing specs instead of re-speccing them**.
+
+Use this when an app has matured enough that individual features are solid but the *whole* doesn't yet feel like one calm, trustworthy instrument — typically before a beta/launch, after a burst of feature work, or as a periodic "is this lovable yet?" check.
+
+> **Companion prompts:** `panel-usability-audit.md` goes deep on *one* surface; this goes wide across *all* of them. `pre-launch-audit.md` focuses on operational/launch readiness (legal, billing, backups, errors); this focuses on the *experiential* layer. Run them together for full coverage.
+
+---
+
+## How to Use
+
+1. Give this prompt to an AI assistant with **full codebase access**.
+2. Optionally name a focus or exclusions (`[SCOPE]` below). Default scope is the entire authenticated product experience.
+3. The assistant does a read-only pass over the app shell, navigation, onboarding, every primary surface, and the existing spec/doc corpus, then writes one findings spec.
+4. Save the spec at `specs/ux-cohesion-audit.md` (or `<area>-cohesion-audit.md` if scoped) and add a backlog entry.
+
+---
+
+## Instructions
+
+You are a product-minded design engineer doing a **whole-app UX cohesion audit**. The goal is to find everything that could confuse, block, distract, or otherwise prevent a user from falling in love with this app — and to capture it in a single, prioritized, honestly-scoped spec.
+
+Your north star: **"Does the whole thing feel like one calm, trustworthy instrument, or like N strong screens stitched together?"** You are looking for the gap between *competent* and *beloved*.
+
+### Step 0 — Avoid double-work (read the existing corpus first)
+
+Before auditing anything, inventory what's **already captured** so you do not re-spec owned work:
+
+- Read the spec folder(s) (`specs/`, `specs/partial/`, `specs/completed/`) and any docs index (`docs/`, design system, brand/product docs, test plan, code-health, backlog).
+- Build a map of which UX concerns **already have an owning spec** (e.g. visual consistency, information architecture, error handling, onboarding latency, keyboard shortcuts, save model).
+- For anything already owned, you will **point at it**, not rewrite it — note only the *experiential residue* or a reprioritization, not a fresh design.
+
+If a prior whole-app UX/cohesion audit already exists, treat this run as an **update**: reconcile against it, mark what shipped, and add only new findings.
+
+### Step 1 — Inventory the whole experience (read-only)
+
+Read enough to build a real mental model of the product as a user moves through it. Cover at minimum:
+
+- **App shell** — the root layout / main page: navigation, global chrome, panel/modal launching, URL state, loading and empty states.
+- **Entry & onboarding** — auth/landing, first-run wizard, the path from "signed up" to "first real artifact / first win." Note where the brand *promise* and the first-run *reality* diverge.
+- **Primary surfaces** — every major panel/page/drawer and its tabs/sub-tabs. Note nesting depth (panel → panel → modal) and wayfinding cost.
+- **The core object's detail view** — wherever the user spends the most time (the record/document/item workspace). Map its tabs, edit buffers, and save behavior.
+- **Cross-surface flows** — links that jump between surfaces; do they stack, replace, or orphan the user?
+- **System feedback** — how success, in-progress, failure, empty, and stale states are expressed across surfaces. Look specifically for **silent failures** (swallowed errors, no toast) and **inconsistent acknowledgement**.
+- **Async / AI / long-running work** — anywhere the app does background work; is "where did my thing go?" answered consistently?
+- **Mobile / responsive** — the top journeys at a narrow width.
+- **Accessibility (cohesion-relevant)** — focus management at panel/modal depth, keyboard model, color-only signaling.
+
+Ground everything in code: name the file, component, state variable, or template branch. Verify ambiguous claims against source.
+
+### Step 2 — Two lenses
+
+Analyze through **both** lenses. The first is what makes this audit different from a per-surface review.
+
+#### Lens A — Cross-cutting themes ("feels like N apps")
+
+These are meta-findings: individually small, collectively the difference between competent and loved. Hunt explicitly for:
+
+1. **Inconsistent interaction models for the same job** — e.g. some edits autosave, some need a Save button, some persist instantly, with nothing signaling which. Same for confirmation patterns, error display, progress UX.
+2. **Uneven or silent feedback** — operations that succeed loudly in one place and silently in another; swallowed `catch` blocks with no user signal; native `alert()`/`confirm()` next to polished dialogs.
+3. **Discoverability that depends on the user opting in** — high-value capabilities only findable via tour/tooltip/help, never taught by the UI itself.
+4. **Missing global affordances** — no keyboard model (`/`, new, `?`, `Esc` discipline), no command surface, for an audience that expects them.
+5. **Fragmented system legibility** — background work, AI runs, or multi-step processes whose status is expressed differently everywhere, so the user never builds one mental model.
+6. **Vocabulary / state drift** — the same concept (empty / loading / generating / stale / saved) rendered with different copy and chrome per surface.
+
+#### Lens B — Surface-by-surface findings
+
+Walk the product and capture concrete issues, organized by area (onboarding & first run; navigation & wayfinding; the core detail view; feedback/errors/trust; loading/empty/in-between states; visual & interaction craft; mobile; accessibility; **delight**). For each, ask:
+
+- **Confuse:** would a capable new user be unsure what to do or where they are?
+- **Block:** is there a dead end, a lost-work risk, or a step that fails without recovery?
+- **Distract:** does something pull attention from the task (noise, redundant info, competing weight)?
+- **Delight gap:** is there a moment the app *sets up* but doesn't cash in (first artifact, a milestone, "your single next best move")?
+
+### Step 3 — Severity & effort
+
+Rate every finding:
+
+- **Critical** — actively blocks, breaks trust, or makes the app feel broken/unsafe. Fix before broad beta.
+- **High** — recurring friction/confusion that erodes the product's core promise.
+- **Medium** — polish that compounds; the "good → loved" gap.
+- **Low** — nice-to-have / future delight.
+- **Effort:** XS / S / M / L.
+
+Treat **delight** as first-class, not filler: a few "turn good into loved" opportunities belong in every cohesion audit.
+
+### Step 4 — Write the spec
+
+Produce one spec with this shape (adapt headings to the app; keep it honest and skimmable):
+
+```
+# UX Cohesion Audit — friction, confusion, and delight gaps
+
+**Status:** Draft — not started
+**Audience:** Product + engineering — a whole-app read of where the experience
+confuses, blocks, distracts, or fails to delight.
+**Related:** [link every owning spec/doc you found in Step 0]
+
+## 1. Why this spec exists
+[What the app is, the cohesion risk, and that this catalogs gaps NOT already owned
+by other specs, plus cross-cutting themes. State the method.]
+
+## 2. How to read the severity
+[The Critical/High/Medium/Low + effort key.]
+
+## 3. Cross-cutting themes (the "feels like N apps" problem)
+[T1..Tn — the Lens A meta-findings. For each: what, why it matters, current state,
+recommendation. Where a theme is partly owned by another spec, say so and add only
+the residue.]
+
+## 4..N Surface areas
+[One section per area from Lens B. Each finding: ID, severity, what, why it matters,
+current state (with file/component references), recommendation, effort.]
+
+## Delight
+[D1..Dn — opportunities to convert "good" into "loved."]
+
+## Prioritized plan
+[Three tiers as tables: pre-beta (trust / "not broken") → early beta (cohesion) →
+beta iteration (loved). Each row: finding, effort.]
+
+## Relationship to existing specs (no double-spec)
+[Table: theme here | owned by | what this audit ADDS. Critical for not re-speccing.]
+
+## Open questions
+[Decisions needed before implementation: scope of first pass, ambition level,
+ownership of "addition" items, etc.]
+```
+
+### Rules
+
+- **Point, don't duplicate.** If a concern already has an owning spec, link it and add only the experiential residue or a reprioritization. The "Relationship to existing specs" table is mandatory.
+- **Ground every finding in code.** Name the file/component/state/branch. No vague "the UX could be better."
+- **Concrete recommendations.** Say what to change and roughly how, not "consider improving."
+- **Severity AND effort on every finding.** Readers prioritize with both.
+- **Lens A is the point.** A per-surface bug list alone is the *other* prompt; this one must surface the cross-cutting themes.
+- **Delight is required.** Include a few honest "good → loved" opportunities.
+- **Stay honest.** Don't manufacture findings; if a surface is strong, say so. If the app is in good shape overall, keep the spec short.
+- **Don't conflate audit with redesign.** Identify and recommend; do not propose a full UI overhaul unless findings demand it.
+- **Keep internal references out of UI copy.** Recommendations for user-facing text must not leak internal spec names or file paths into the product.
+
+---
+
+## Input
+
+```
+[SCOPE] (optional): default = entire authenticated product experience. Narrow if
+  desired, e.g. "everything except admin panels" or "the primary pipeline flows."
+
+Run the UX cohesion audit using the methodology above. Read the existing spec/doc
+corpus FIRST (Step 0) so you point at owned work instead of re-speccing it. Save the
+spec at specs/ux-cohesion-audit.md (or specs/<area>-cohesion-audit.md if scoped) and
+add a backlog entry linking it.
+```
+
+---
+
+## Run Logging
+
+After completing the audit:
+
+- Add a backlog entry (e.g. `TODO.md`, open `[ ]`): title **`UX cohesion audit`**, a one-line summary of the cross-cutting themes + top pre-beta items, and a link to the spec.
+- A brand-new audit spec lands in `specs/` (drafts). Once any finding is implemented, move it to `specs/partial/` per your spec-lifecycle convention.
+- If this run produced a generally-reusable lesson (a new cross-cutting pattern worth enforcing), consider running `propagate-to-forgetrail.md`.

package/scripts/ensure-lease.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Idempotent LocalBerth claim. Missing CLI → warn, exit 0.
+ * Usage: node scripts/ensure-lease.mjs <name> <port>
+ */
+import { spawnSync } from 'node:child_process';
+
+const name = process.argv[2];
+const port = process.argv[3];
+if (!name || !port) {
+	console.error('usage: node scripts/ensure-lease.mjs <name> <port>');
+	process.exit(1);
+}
+
+const opt = { encoding: 'utf8', timeout: 8000, windowsHide: true, shell: process.platform === 'win32' };
+const got = spawnSync('localberth', ['get', name], { ...opt, stdio: ['ignore', 'pipe', 'ignore'] });
+if (got.status === 0 && String(got.stdout || '').trim()) {
+	process.exit(0);
+}
+const claim = spawnSync('localberth', ['claim', name, '--port', port], { ...opt, stdio: 'inherit' });
+if (claim.error || claim.status !== 0) {
+	console.warn(`localberth: skip claim ${name} (install the CLI to pin this port to ${port})`);
+}

package/scripts/forgetrail-cli.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+import { cwd } from "node:process";
+import {
+  INSTALL_FULL_HELP,
+  INSTALL_LITE_HELP,
+  runInstallForgetrail,
+  runInstallLite,
+} from "./install.mjs";
+import { runMcpCommand } from "./mcp-status.mjs";
+
+const CLI_HELP = `
+ForgeTrail — bootstrap a project folder and run the MCP server
+
+Usage:
+  forgetrail install [--lite] [options]
+  forgetrail mcp <subcommand>        Build, status, ping, Cursor config
+
+Global link (one-time, from your forgetrail clone):
+  pnpm run link:global              # pnpm add -g . + PATH shim fix (Windows/Git Bash)
+
+Then from any project folder:
+  cd /path/to/your-app
+  forgetrail install --lite
+  forgetrail install
+
+From your forgetrail clone (MCP server):
+  forgetrail mcp build               Install deps + compile dist/
+  forgetrail mcp status [--ping]     Static checks + optional live ping
+  forgetrail mcp ping                Live ping (JSON)
+  forgetrail mcp cursor-config       Print recommended .cursor/mcp.json
+
+Install options:
+  --lite             Lite protocol only (.forgetrail/FORGETRAIL_LITE.md)
+  --with-genesis-stub  With --lite: also create docs/GENESIS.md stub
+  --force, -f        Overwrite existing files
+  --dry-run          Preview without writing
+  --skip-tracking    Skip workflow_tracking.json starter
+  --path, -p <dir>   Install elsewhere (default: current directory)
+  --help, -h         Show help
+
+First-time prove-it (no MCP): see TRY_FORGETRAIL.md in the ForgeTrail repo.
+Run \`forgetrail mcp --help\` for all MCP subcommands.
+`.trim();
+
+function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || ((argv.includes("--help") || argv.includes("-h")) && argv[0] !== "install" && argv[0] !== "mcp")) {
+    console.log(CLI_HELP);
+    process.exit(0);
+  }
+
+  const cmd = argv[0];
+
+  if (cmd === "mcp") {
+    runMcpCommand(argv.slice(1));
+    return;
+  }
+
+  if (cmd !== "install") {
+    console.error(`Unknown command: ${cmd ?? "(none)"}`);
+    console.error("Run forgetrail --help");
+    process.exit(1);
+  }
+
+  const rest = argv.slice(1);
+  const lite = rest.includes("--lite");
+  const passArgv = rest.filter((a) => a !== "--lite");
+
+  if (passArgv.includes("--help") || passArgv.includes("-h")) {
+    console.log(lite ? INSTALL_LITE_HELP : INSTALL_FULL_HELP);
+    process.exit(0);
+  }
+
+  console.log(`Target: ${cwd()}\n`);
+
+  if (lite) {
+    runInstallLite(passArgv, { defaultToCwd: true });
+  } else {
+    runInstallForgetrail(passArgv, { defaultToCwd: true });
+  }
+}
+
+main();

package/scripts/install-forgetrail-lite.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { runInstallLite, INSTALL_LITE_HELP } from "./install.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(INSTALL_LITE_HELP);
+  process.exit(0);
+}
+
+runInstallLite(argv, { defaultToCwd: false });

package/scripts/install-forgetrail.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { runInstallForgetrail, INSTALL_FULL_HELP } from "./install.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(INSTALL_FULL_HELP);
+  process.exit(0);
+}
+
+runInstallForgetrail(argv, { defaultToCwd: false });

package/scripts/install-lib.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { cwd } from "node:process";
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const FORGETRAIL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function parseInstallArgs(argv) {
+  const args = {
+    target: process.env.FORGETRAIL_TARGET?.trim() || "",
+    force: false,
+    dryRun: false,
+    skipTracking: false,
+    withGenesisStub: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--path" || arg === "-p") {
+      args.target = argv[++i]?.trim() ?? "";
+    } else if (arg === "--force" || arg === "-f") {
+      args.force = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--skip-tracking") {
+      args.skipTracking = true;
+    } else if (arg === "--with-genesis-stub") {
+      args.withGenesisStub = true;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    } else if (!arg.startsWith("-") && !args.target) {
+      args.target = arg.trim();
+    }
+  }
+
+  return args;
+}
+
+export function resolveTarget(target, { defaultToCwd = false } = {}) {
+  const raw = target?.trim() || (defaultToCwd ? cwd() : "");
+  if (!raw) {
+    console.error("Missing target directory.");
+    console.error("Usage: forgetrail install   (from project folder after pnpm run link:global)");
+    console.error("   or: pnpm run install:forgetrail -- --path <project-root>");
+    console.error("   or: FORGETRAIL_TARGET=<project-root> pnpm run install:forgetrail");
+    process.exit(1);
+  }
+
+  const resolved = resolve(raw);
+  if (!existsSync(resolved)) {
+    console.error(`Target does not exist: ${resolved}`);
+    process.exit(1);
+  }
+  if (!statSync(resolved).isDirectory()) {
+    console.error(`Target is not a directory: ${resolved}`);
+    process.exit(1);
+  }
+  return resolved;
+}
+
+/** @deprecated use resolveTarget */
+export function requireTarget(target, opts) {
+  return resolveTarget(target, opts);
+}
+
+export function ensureDir(path, dryRun) {
+  if (existsSync(path)) return;
+  if (dryRun) {
+    console.log(`[dry-run] mkdir ${path}`);
+    return;
+  }
+  mkdirSync(path, { recursive: true });
+}
+
+export function copyPath(from, to, { force = false, dryRun = false } = {}) {
+  if (!existsSync(from)) {
+    throw new Error(`Missing source: ${from}`);
+  }
+  if (existsSync(to) && !force) {
+    console.log(`  skip (exists): ${to}`);
+    return false;
+  }
+  if (dryRun) {
+    console.log(`[dry-run] copy ${from} -> ${to}`);
+    return true;
+  }
+  ensureDir(dirname(to), dryRun);
+  cpSync(from, to, { recursive: true, force: true });
+  console.log(`  wrote ${to}`);
+  return true;
+}
+
+/** MCP-only content — not needed for offline template-in-repo. */
+export const MCP_ONLY_CONTENT = new Set([
+  "AGENT_INTEGRATION_claude.md",
+  "AGENT_INTEGRATION_cursor.md",
+  "AGENT_INTEGRATION_generic.md",
+  "AGENT_INTEGRATION_grok.md",
+  "PLAN_MODE_PATTERNS.md",
+  "NEW_PROJECT_BOOTSTRAP.md",
+  "SESSION_RESUME_MCP.md",
+  "KICKOFF_WITHOUT_MCP.md",
+  "POST_BOOTSTRAP_USER_MESSAGE.md",
+]);
+
+export function copyContentDir(fromDir, toDir, opts) {
+  ensureDir(toDir, opts.dryRun);
+  for (const name of readdirSync(fromDir)) {
+    if (name === "skills") continue;
+    if (MCP_ONLY_CONTENT.has(name)) continue;
+    copyPath(join(fromDir, name), join(toDir, name), opts);
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * Shared install logic — full template-in-repo and Lite bootstrap.
+ */
+
+import { join } from "node:path";
+import {
+  FORGETRAIL_ROOT,
+  copyContentDir,
+  copyPath,
+  ensureDir,
+  parseInstallArgs,
+  resolveTarget,
+} from "./install-lib.mjs";
+
+const ROOT_FILES = [
+  "WORKFLOW.md",
+  "TRACKING_SCHEMA.md",
+  "workflow_tracking.json",
+  "INITIAL_PROMPT.md",
+  "CONTINUATION_PROMPT.md",
+  "LICENSE",
+];
+
+const LITE_FILES = [
+  ["FORGETRAIL_LITE.md", "FORGETRAIL_LITE.md"],
+  ["forgetrail-workspace-README.md", "README.md"],
+  ["FORGETRAIL_LITE_UPDATES.md", "FORGETRAIL_LITE_UPDATES.md"],
+];
+
+const LITE_CURSOR_RULES = [
+  "forgetrail-no-trailer.mdc",
+  "forgetrail-updates-log.mdc",
+  "specs-and-todo.mdc",
+  "spec-completion.mdc",
+];
+
+export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
+  const args = parseInstallArgs(rawArgv);
+  if (args.help) return { help: INSTALL_FULL_HELP };
+
+  const target = resolveTarget(args.target, { defaultToCwd });
+  const opts = { force: args.force, dryRun: args.dryRun };
+  const forgetrailDir = join(target, "_forgetrail");
+  const contentSrc = join(FORGETRAIL_ROOT, "content");
+  const contentDest = join(forgetrailDir, "content");
+
+  console.log(`ForgeTrail full install → ${forgetrailDir}`);
+  if (args.dryRun) console.log("(dry run)\n");
+
+  ensureDir(forgetrailDir, args.dryRun);
+
+  for (const file of ROOT_FILES) {
+    copyPath(join(FORGETRAIL_ROOT, file), join(forgetrailDir, file), opts);
+  }
+
+  copyPath(join(FORGETRAIL_ROOT, "docs"), join(forgetrailDir, "docs"), opts);
+  copyPath(join(FORGETRAIL_ROOT, "prompts"), join(forgetrailDir, "prompts"), opts);
+  copyContentDir(contentSrc, contentDest, opts);
+
+  if (!args.skipTracking) {
+    copyPath(
+      join(FORGETRAIL_ROOT, "workflow_tracking.json"),
+      join(target, ".forgetrail", "workflow_tracking.json"),
+      { ...opts, force: args.force }
+    );
+  }
+
+  console.log("\nDone.");
+  console.log("  Methodology:  _forgetrail/WORKFLOW.md");
+  console.log("  First chat:   _forgetrail/INITIAL_PROMPT.md");
+  console.log("  Tracking:     .forgetrail/workflow_tracking.json");
+  return { target, mode: "full" };
+}
+
+export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
+  const args = parseInstallArgs(rawArgv);
+  if (args.help) return { help: INSTALL_LITE_HELP };
+
+  const target = resolveTarget(args.target, { defaultToCwd });
+  const opts = { force: args.force, dryRun: args.dryRun };
+  const contentDir = join(FORGETRAIL_ROOT, "content");
+  const forgetrailDir = join(target, ".forgetrail");
+
+  console.log(`ForgeTrail Lite install → ${forgetrailDir}`);
+  if (args.dryRun) console.log("(dry run)\n");
+
+  ensureDir(forgetrailDir, args.dryRun);
+  ensureDir(join(forgetrailDir, "cursor", "rules"), args.dryRun);
+
+  for (const [src, dest] of LITE_FILES) {
+    copyPath(join(contentDir, src), join(forgetrailDir, dest), opts);
+  }
+
+  for (const rule of LITE_CURSOR_RULES) {
+    copyPath(
+      join(contentDir, "cursor-rules", rule),
+      join(forgetrailDir, "cursor", "rules", rule),
+      opts
+    );
+  }
+
+  if (!args.skipTracking) {
+    copyPath(
+      join(contentDir, "LITE_WORKFLOW_TRACKING.json"),
+      join(forgetrailDir, "workflow_tracking.json"),
+      opts
+    );
+  }
+
+  if (args.withGenesisStub) {
+    const genesisDest = join(target, "docs", "GENESIS.md");
+    ensureDir(join(target, "docs"), args.dryRun);
+    copyPath(join(contentDir, "GENESIS_STUB.md"), genesisDest, opts);
+  }
+
+  console.log("\nDone.");
+  console.log("  Protocol:  .forgetrail/FORGETRAIL_LITE.md");
+  console.log("  Tracking:  .forgetrail/workflow_tracking.json (lite-1 schema)");
+  if (args.withGenesisStub) {
+    console.log("  Genesis:   docs/GENESIS.md (stub — replace with your spec)");
+    console.log("  Next:      see TRY_FORGETRAIL.md in the ForgeTrail repo");
+  }
+  return { target, mode: "lite", withGenesisStub: !!args.withGenesisStub };
+}
+
+export const INSTALL_FULL_HELP = `
+ForgeTrail template-in-repo install (offline / no MCP server required)
+
+Usage:
+  forgetrail install [options]          (from your project folder, after global link)
+  pnpm run install:forgetrail -- [options]
+
+Options:
+  --path, -p <dir>   Target project root (default: current directory for \`forgetrail\` CLI)
+  --force, -f        Overwrite existing files
+  --skip-tracking    Do not create .forgetrail/workflow_tracking.json
+  --dry-run          Print actions only
+
+Installs:
+  <target>/_forgetrail/   WORKFLOW, templates, prompts, content/ (curated)
+  <target>/.forgetrail/   workflow_tracking.json starter (unless skipped)
+`.trim();
+
+export const INSTALL_LITE_HELP = `
+ForgeTrail Lite install (portable protocol, no MCP)
+
+Usage:
+  forgetrail install --lite [options]
+  pnpm run install:lite -- [options]
+
+Options:
+  --path, -p <dir>        Target project root (default: current directory for \`forgetrail\` CLI)
+  --force, -f             Overwrite existing files
+  --skip-tracking         Do not create workflow_tracking.json starter
+  --with-genesis-stub     Also create docs/GENESIS.md stub (for the Try path)
+  --dry-run               Print actions only
+
+Installs into <target>/.forgetrail/ (FORGETRAIL_LITE.md, tracking starter, cursor rules).
+With --with-genesis-stub, also writes docs/GENESIS.md from content/GENESIS_STUB.md.
+See TRY_FORGETRAIL.md in the ForgeTrail repo for the no-MCP prove-it recipe.
+`.trim();

package/scripts/link-global.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * Register the forgetrail CLI on PATH for pnpm global installs.
+ *
+ * pnpm 10: prefer `pnpm add -g .` over deprecated `pnpm link --global`.
+ * Linked packages get shims under global/.../node_modules/.bin with paths
+ * relative to that folder — copying them to $PNPM_HOME breaks resolution.
+ * This script writes shims with absolute paths to this repo's CLI entry.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { FORGETRAIL_ROOT } from "./install-lib.mjs";
+
+const CLI_ENTRY = join(FORGETRAIL_ROOT, "scripts", "forgetrail-cli.mjs");
+const BIN_NAME = "forgetrail";
+
+function run(cmd, args, { cwd = FORGETRAIL_ROOT } = {}) {
+  const r = spawnSync(cmd, args, { cwd, stdio: "inherit", shell: true, env: process.env });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+}
+
+function pnpmPath(args) {
+  const r = spawnSync("pnpm", args, {
+    cwd: FORGETRAIL_ROOT,
+    encoding: "utf-8",
+    shell: true,
+    env: process.env,
+  });
+  if (r.status !== 0) {
+    console.error(`pnpm ${args.join(" ")} failed`);
+    process.exit(r.status ?? 1);
+  }
+  return (r.stdout ?? "").trim();
+}
+
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+
+function writeGlobalBinShims() {
+  const globalBinDir = pnpmPath(["bin", "-g"]);
+  const cliPosix = toPosix(CLI_ENTRY);
+  const cliWin = CLI_ENTRY.replace(/\//g, "\\");
+
+  const shShim = `#!/bin/sh
+exec node "${cliPosix}" "$@"
+`;
+  const cmdShim = `@ECHO off
+node "${cliWin}" %*
+`;
+  const ps1Shim = `#!/usr/bin/env pwsh
+& node "${cliWin}" @args
+exit $LASTEXITCODE
+`;
+
+  const targets = [
+    [join(globalBinDir, BIN_NAME), shShim],
+    [join(globalBinDir, `${BIN_NAME}.CMD`), cmdShim],
+    [join(globalBinDir, `${BIN_NAME}.ps1`), ps1Shim],
+  ];
+
+  for (const [path, content] of targets) {
+    writeFileSync(path, content, { mode: 0o755 });
+    console.log(`  wrote ${path}`);
+  }
+
+  return globalBinDir;
+}
+
+function verify(globalBinDir) {
+  const r = spawnSync(process.execPath, [CLI_ENTRY, "--help"], {
+    stdio: "pipe",
+    encoding: "utf-8",
+    env: process.env,
+  });
+
+  if (r.status !== 0) {
+    console.error(`\nShim did not run. Try in a new terminal:\n  ${BIN_NAME} --help`);
+    console.error(`Or:\n  node ${CLI_ENTRY} --help`);
+    process.exit(1);
+  }
+
+  console.log(`\n✓ ${BIN_NAME} is available (${globalBinDir})`);
+}
+
+console.log("Registering forgetrail globally (pnpm add -g .)…\n");
+run("pnpm", ["add", "-g", "."]);
+
+console.log("\nWriting PATH shims (absolute paths)…");
+const globalBinDir = writeGlobalBinShims();
+
+console.log("\nVerifying…");
+verify(globalBinDir);
+
+console.log("\nFrom any project folder:");
+console.log("  forgetrail install --lite");
+console.log("  forgetrail install");