forgetrail 0.5.1 → 0.5.3

package/README.md

@@ -12,9 +12,9 @@
 
 ForgeTrail gives your next coding session a place to start. It keeps the phase, decisions, and handoff in your repository so an agent can read them when you resume. Start with Lite for a small project. You do not have to run all seven phases to try the method.
 
-ForgeTrail instructs the agent to read tracking, preserve approved decisions, and pause at approval gates. The agent must write the handoff. Those updates are not automatic. Optional hooks enforce the checks documented for their supported host.
+ForgeTrail instructs the agent to read the ledger, preserve approved decisions, and pause at approval gates. The agent must write the handoff. Those updates are not automatic. Optional hooks enforce the checks documented for their supported host.
 
-In session one, the agent drafts a Phase 1 brief, you approve it, and the agent logs the stack decision and a note for next time. In session two, a fresh chat reads that record, skips the settled questions, finishes the open Phase 1 item, and asks to move into Phase 2 with that phase's guidance. The record is `.forgetrail/workflow_tracking.json`. Labeled walk-through: [`content/examples/two-session-continuity.md`](content/examples/two-session-continuity.md).
+In session one, the agent drafts a Phase 1 brief, you approve it, and the agent logs the stack decision and a note for next time. In session two, a fresh chat reads that record, skips the settled questions, finishes the open Phase 1 item, and asks to move into Phase 2 with that phase's guidance. The record is the [AppLedger](https://appledger.dev) ledger in `appledger/`: the phase in `profiles/forgetrail.yaml`, plus decision, lesson, and session records. `pnpm dlx appledger init` creates it. Labeled walk-through: [`content/examples/two-session-continuity.md`](content/examples/two-session-continuity.md).
 
 **Docs:** [forgetrail.dev/docs](https://forgetrail.dev/docs) · **Site:** [forgetrail.dev](https://forgetrail.dev)
 
@@ -38,9 +38,10 @@ The shortest supported first task is: create `appledger/`, draft `docs/PHASE_1_B
 
 ```bash
 pnpm dlx forgetrail install --lite --with-genesis-stub
+pnpm dlx appledger init --name "Your app name"
 ```
 
-MCP: `npx -y forgetrail-mcp` with `FORGETRAIL_ROOT` set. Prefer `pnpm dlx` on Windows. Do not add `forgetrail` to an app's `dependencies`. Do not merge the two packages.
+MCP: `npx -y forgetrail-mcp` (0.4.2 or later finds the methodology without `FORGETRAIL_ROOT`). Prefer `pnpm dlx` on Windows. Do not add `forgetrail` to an app's `dependencies`. Do not merge the two packages.
 
 ## What you get
 

package/content/FORGETRAIL_LITE.md

@@ -1,6 +1,6 @@
 # ForgeTrail Lite — portable kickoff for any agentic chat
 
-> **ForgeTrail Lite v2.2.0**
+> **ForgeTrail Lite v2.2.1**
 > © Catalyst Forge, LLC — [www.catalystforge.com](https://www.catalystforge.com)
 > Part of the **ForgeTrail** open-source methodology ([Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) in the upstream ForgeTrail repo).
 >
@@ -320,7 +320,7 @@ Record anything non-obvious as a lesson in **`appledger/`** (for example, Playwr
    2. **`.forgetrail/cursor/rules/forgetrail-updates-log.mdc`** — use the §12.5 snippet verbatim. **Symlink or copy** into `.cursor/rules/` so Cursor reminds agents when to update `FORGETRAIL_LITE_UPDATES.md` (§1.6). Optional: copy the upstream **`FORGETRAIL_LITE_UPDATES.md`** starter into `.forgetrail/` when you expect protocol feedback during the project.
    3. **`.forgetrail/hooks/` and `.cursor/hooks.json`** — install host safety hooks (`content/hooks/`) into `.forgetrail/hooks/` and copy `cursor-hooks.json` to `.cursor/hooks.json`. On Cursor, this runs pre-commit verification, enforces pnpm lock consistency, gates git push at the tool level, and injects live phase context at session start. For Claude Code, add `claude-settings-hooks.json` into `.claude/settings.json`.
    If any of these already exists and its content conflicts with the Lite defaults, **do not overwrite** — flag the conflict to the user and ask how to reconcile. Record the reconciliation as a decision in `appledger/`.
-4. **Create `appledger/`** if it does not exist: `manifest.yaml`, `profiles/forgetrail.yaml` with the `plan` phase `in_progress`, an application record, and a session record. Do **not** create `.forgetrail/workflow_tracking.json`. Fill the application name and a one-line description from whatever the user has already said. Criteria stay `pending` until evidence exists.
+4. **Create `appledger/`** if it does not exist. Run `pnpm dlx appledger init --name "<application name>"` (or `appledger init` when it is installed globally), then `pnpm dlx appledger check`. Init writes `manifest.yaml`, `profiles/forgetrail.yaml` with the `plan` phase `in_progress`, an application record, and a session record. It does not overwrite existing files. Init leaves the purpose as "Not supplied." Write the one-line purpose into the application record from what the user has already said, then run `check` again. Do **not** create `.forgetrail/workflow_tracking.json`. Criteria stay `pending` until evidence exists. **Without Node:** write the same four files by hand in the shape of the [minimal example ledger](https://github.com/Catalyst-Forge-LLC/appledger/tree/main/examples/minimal/appledger), and run `appledger check` once Node is available. A hand-written ledger is not checked until then.
 5. **If git was initialized in step 2**, make the first commit now so the user has a clean baseline. **What lands in the commit depends on §1.5:** if **committing `.forgetrail/`**, steps 3–4 artifacts are included; if **gitignoring `.forgetrail/`**, only `.gitignore` (and any `.cursor/rules/` copies) — the workspace stays local-only and that is expected, not a mistake. Example: `git add -A && git commit -m "chore: ForgeTrail Lite bootstrap"`. Skip this step if the repo already had history — do not squash or amend what's there. Skip entirely if the user is in no-git mode (§4.1).
 6. **Ask the §5 intake questions.** Do not write any project code yet. For the first user-facing reply, follow §9 (plain product language, one clear "reply with," no methodology jargon).
 7. **Create `docs/`** (if missing) and **draft `docs/PHASE_1_BRIEF.md`** from the §6 template using the user's answers. Show it to the user, iterate, then **lock it**: mark the brief criteria met in `appledger/profiles/forgetrail.yaml` only when the user has approved them, and record major commitments as decision records.
@@ -1003,7 +1003,7 @@ Save this as `.forgetrail/AGENTS.md` so agents that auto-load it (Codex, Cursor,
 
 ```markdown
 <!--
-  Agent protocol based on ForgeTrail Lite v2.2.0.
+  Agent protocol based on ForgeTrail Lite v2.2.1.
   © Catalyst Forge, LLC — www.catalystforge.com
   Licensed under Apache License 2.0 (upstream ForgeTrail repo).
 -->
@@ -1179,4 +1179,4 @@ ForgeTrail Lite covers the shape of a project. The full **ForgeTrail MCP server*
 
 ---
 
-**ForgeTrail Lite v2.2.0** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+**ForgeTrail Lite v2.2.1** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

package/docs/NPM.md

@@ -10,12 +10,12 @@ Two public unscoped packages:
 
 | Package | This tree | On npm until you publish | From | What it is |
 | --- | --- | --- | --- | --- |
-| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.0 | 0.4.20 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
-| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.0 | 0.3.10 | `mcp-server/` | MCP bin. `pnpm dlx forgetrail-mcp` |
+| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.5.2 | 0.5.2 | repo root | CLI + Lite + templates. `pnpm dlx forgetrail install --lite` |
+| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.4.2 | 0.4.1 | `mcp-server/` | MCP bin. Depends on `forgetrail` for content. `pnpm dlx forgetrail-mcp` |
 
 These are **installer and MCP channels**, not a library. App repos should not add `forgetrail` to `dependencies`.
 
-`0.5.0` stops installing `workflow_tracking.json`. `0.4.0` tells kickoff to run `appledger init`. The registry copies above do not include that cutover. `pnpm run pack:check` is the gate. It does not publish.
+`forgetrail@0.5.2` is on npm. This tree has Lite v2.2.1 and a new installer `Next:` step that are not in `0.5.2`, so `forgetrail` needs a version bump before its next publish. `forgetrail-mcp@0.4.2` is this tree and is not published yet. It adds `forgetrail` as a dependency and returns an explicit error when content is missing. `0.4.1` remains the registry copy until you publish from `mcp-server/`. `pnpm run pack:check` is the gate. It does not publish.
 
 ---
 
@@ -59,11 +59,11 @@ The `Debugger listening` line on MCP `prepack` is Cursor attaching to a one-line
 
 ```bash
 # Prefer pnpm dlx. npm 12 `npx forgetrail --help` on Windows failed to spawn the bin.
-pnpm dlx forgetrail@0.5.0 --help
-pnpm dlx forgetrail@0.5.0 install --lite --dry-run
+pnpm dlx forgetrail@<version> --help
+pnpm dlx forgetrail@<version> install --lite --dry-run
 
-# MCP starts; needs content via FORGETRAIL_ROOT or a sibling forgetrail install
-pnpm dlx forgetrail-mcp@0.4.0
+# MCP starts and reads content from its forgetrail dependency. ping should not say "content missing".
+pnpm dlx forgetrail-mcp@0.4.2
 ```
 
 Optional Cursor MCP (content from a `forgetrail` install, or set the path):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",

package/scripts/install.mjs

@@ -88,6 +88,7 @@ export function runInstallForgetrail(rawArgv, { defaultToCwd = false } = {}) {
   console.log("  First chat:   _forgetrail/INITIAL_PROMPT.md");
   console.log("  Project record: appledger/ (not workflow_tracking.json)");
   console.log("  Hooks:        .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
+  printLedgerNext();
   return { target, mode: "full" };
 }
 
@@ -145,11 +146,18 @@ export function runInstallLite(rawArgv, { defaultToCwd = false } = {}) {
   console.log("  Hooks:     .forgetrail/hooks/ (enforced via .cursor/hooks.json)");
   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");
   }
+  printLedgerNext();
   return { target, mode: "lite", withGenesisStub: !!args.withGenesisStub };
 }
 
+function printLedgerNext() {
+  console.log("\nNext, create the ledger in the app folder (the agent can run these):");
+  console.log('  pnpm dlx appledger init --name "Your app name"');
+  console.log("  pnpm dlx appledger check");
+  console.log("Then paste the kickoff line from https://forgetrail.dev/docs/try");
+}
+
 export const INSTALL_FULL_HELP = `
 ForgeTrail template-in-repo install (offline / no MCP server required)
 

package/scripts/mcp-lib.mjs

@@ -125,21 +125,36 @@ export function posixPath(p) {
   return p.replace(/\\/g, "/");
 }
 
+/** True when this CLI runs from a clone that has mcp-server/ (the npm package does not ship it). */
+export function isClone() {
+  return existsSync(join(MCP_SERVER_DIR, "package.json"));
+}
+
+/** pnpm dlx and npx unpack into a cache that can be removed, so its path is not a stable FORGETRAIL_ROOT. */
+export function isTemporaryInstall(p = FORGETRAIL_ROOT) {
+  return /[\\/](dlx|_npx)[\\/]/i.test(p);
+}
+
 export function mcpClientConfigObject() {
-  return {
-    mcpServers: {
-      forgetrail: {
-        command: "node",
-        args: [posixPath(MCP_ENTRY)],
-        env: { FORGETRAIL_ROOT: posixPath(FORGETRAIL_ROOT) },
+  if (existsSync(MCP_ENTRY)) {
+    return {
+      mcpServers: {
+        forgetrail: {
+          command: "node",
+          args: [posixPath(MCP_ENTRY)],
+          env: { FORGETRAIL_ROOT: posixPath(FORGETRAIL_ROOT) },
+        },
       },
-    },
-  };
+    };
+  }
+  const server = { command: "npx", args: ["-y", "forgetrail-mcp"] };
+  if (!isTemporaryInstall()) server.env = { FORGETRAIL_ROOT: posixPath(FORGETRAIL_ROOT) };
+  return { mcpServers: { forgetrail: server } };
 }
 
 /** Copy-paste MCP client setup — shown after `forgetrail mcp build`. */
 export function printMcpClientSetupBanner({ showBuildComplete = true } = {}) {
-  const entry = posixPath(MCP_ENTRY);
+  const fromClone = existsSync(MCP_ENTRY);
 
   if (showBuildComplete) {
     console.log("\n✓ Build complete.\n");
@@ -149,8 +164,21 @@ export function printMcpClientSetupBanner({ showBuildComplete = true } = {}) {
   console.log("  Cursor — project .cursor/mcp.json or Settings → MCP → add server:");
   console.log(JSON.stringify(mcpClientConfigObject(), null, 2));
   console.log("");
+  if (!fromClone) {
+    if (isTemporaryInstall()) {
+      console.log("  This forgetrail copy is in a temporary pnpm dlx or npx cache, so FORGETRAIL_ROOT is not set.");
+      console.log("  forgetrail-mcp finds the forgetrail package it depends on. For a fixed path: pnpm add -g forgetrail, then rerun this command.");
+    } else {
+      console.log(`  FORGETRAIL_ROOT is this installed forgetrail package: ${posixPath(FORGETRAIL_ROOT)}`);
+    }
+    console.log("");
+  }
   console.log("  Claude Desktop — %APPDATA%\\Claude\\claude_desktop_config.json (same mcpServers block)");
-  console.log(`  Claude Code — claude mcp add forgetrail node ${entry}`);
+  console.log(
+    fromClone
+      ? `  Claude Code — claude mcp add forgetrail node ${posixPath(MCP_ENTRY)}`
+      : "  Claude Code — claude mcp add forgetrail -- npx -y forgetrail-mcp"
+  );
   console.log("");
   console.log("  Then reload MCP in Cursor (Settings → MCP) or restart Cursor.");
   console.log("  Verify: forgetrail mcp ping   |   Reprint: forgetrail mcp cursor-config");

package/scripts/mcp-status.mjs

@@ -8,6 +8,7 @@ import {
   MCP_SERVER_DIR,
   analyzeCursorMcpConfig,
   findCursorMcpJson,
+  isClone,
   staticMcpChecks,
   printCursorConfigTemplate,
   runMcpBuild,
@@ -121,6 +122,12 @@ export function runMcpCommand(argv) {
     return;
   }
 
+  if (cmd !== "cursor-config" && !isClone()) {
+    console.error(`forgetrail mcp ${cmd} runs from a ForgeTrail clone. This npm install does not include mcp-server/.`);
+    console.error("Use the published server instead: forgetrail mcp cursor-config prints a config that starts forgetrail-mcp.");
+    process.exit(1);
+  }
+
   switch (cmd) {
     case "build":
       runMcpBuild();

package/scripts/tracking-cutover.test.mjs

@@ -44,9 +44,34 @@ test("install does not create workflow_tracking.json", () => {
     assert.equal(result.status, 0, result.stderr || result.stdout);
     assert.doesNotMatch(result.stdout, /\\workflow_tracking\.json/);
     assert.match(result.stdout, /Project record: appledger/);
+    assert.match(result.stdout, /pnpm dlx appledger init --name/);
+    assert.match(result.stdout, /pnpm dlx appledger check/);
   }
 });
 
+test("Lite step 4 runs appledger init and check", () => {
+  const lite = readFileSync(join(root, "content", "FORGETRAIL_LITE.md"), "utf8");
+  const step = lite.split("\n").find((line) => line.startsWith("4. **Create `appledger/`**"));
+  assert.ok(step);
+  assert.match(step, /pnpm dlx appledger init --name/);
+  assert.match(step, /appledger check/);
+  assert.match(step, /examples\/minimal\/appledger/);
+});
+
+test("cursor-config from an npm install starts forgetrail-mcp, not a missing dist file", async () => {
+  const { mcpClientConfigObject, isTemporaryInstall } = await import("./mcp-lib.mjs");
+  const server = mcpClientConfigObject().mcpServers.forgetrail;
+  const hasDist = spawnSync(process.execPath, ["-e", "process.exit(require('node:fs').existsSync(process.argv[1]) ? 0 : 1)", join(root, "mcp-server", "dist", "index.js")]).status === 0;
+  if (hasDist) {
+    assert.equal(server.command, "node");
+  } else {
+    assert.deepEqual([server.command, ...server.args], ["npx", "-y", "forgetrail-mcp"]);
+  }
+  assert.equal(isTemporaryInstall("C:/Users/u/AppData/Local/pnpm-cache/dlx/abc/node_modules/forgetrail"), true);
+  assert.equal(isTemporaryInstall("/home/u/.npm/_npx/abc/node_modules/forgetrail"), true);
+  assert.equal(isTemporaryInstall("C:/Users/u/AppData/Local/pnpm/global/5/node_modules/forgetrail"), false);
+});
+
 test("session start warns on a legacy file and does not quote it as the live phase", () => {
   const dir = mkdtempSync(join(tmpdir(), "ft-session-"));
   mkdirSync(join(dir, ".forgetrail"), { recursive: true });
@@ -76,7 +101,7 @@ test("Lite and workflow instructions name the ledger", () => {
   assert.ok(legacyAt > 0 && resumeAt > legacyAt);
   const instructional = `${lite.slice(0, legacyAt)}\n${lite.slice(resumeAt)}`;
   assert.match(lite.slice(legacyAt, resumeAt), /"schemaVersion": "lite-1"/);
-  assert.match(instructional, /ForgeTrail Lite v2\.2\.0/);
+  assert.match(instructional, /ForgeTrail Lite v2\.2\.1/);
   for (const line of instructional.split("\n")) {
     if (!line.includes("workflow_tracking.json")) continue;
     assert.match(line, /[Dd]o not|does not|not the live phase|not recreate/, line);