forgetrail 0.4.16 → 0.4.18

package/README.md

@@ -10,9 +10,9 @@
 
 **Forge the path. Keep the trail.**
 
-Keep project decisions, development state, and lessons in the repository so your next AI-assisted session can continue with context.
+ForgeTrail gives your coding agent a method: seven phases, each with exit criteria, and a pause for your approval before the agent moves on. As it works, the agent records the phase, decisions, and gotchas in your repository, so a new chat days later starts from that record instead of from zero.
 
-After one sitting you should have `.forgetrail/workflow_tracking.json` with the phase you are in, a decision, and a `nextSession` line. A labeled two-session walk-through is in [`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 `.forgetrail/workflow_tracking.json`. 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)
 
@@ -31,8 +31,8 @@ The shortest supported first task is: create tracking, draft `docs/PHASE_1_BRIEF
 | Path | Who uses it | What it is |
 | --- | --- | --- |
 | **Lite** | First path | One protocol file. The agent writes tracking. |
-| **CLI** (`forgetrail`) | Node.js 20+ | Installer. Writes Lite or the full template tree. Does not run the agent. |
-| **MCP** (`forgetrail-mcp`) | Cursor or Claude | Methodology tools. Tracking still lives in the app repo. |
+| **CLI** (`forgetrail`) | Node.js 20+ | Installer. Writes Lite with a starter tracking file and Cursor hooks, or the full template tree. Skips files that already exist. Does not run the agent. |
+| **MCP** (`forgetrail-mcp`) | Cursor or Claude | Phase guidance, templates, and lessons search. Tracking still lives in the app repo. |
 
 ```bash
 pnpm dlx forgetrail install --lite --with-genesis-stub
@@ -42,7 +42,9 @@ MCP: `npx -y forgetrail-mcp` with `FORGETRAIL_ROOT` set. Prefer `pnpm dlx` on Wi
 
 ## What you get
 
-A 7-phase playbook, a live `.forgetrail/workflow_tracking.json`, and templates pre-loaded with first-party production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work follows. Those lesson notes are not independent adoption evidence. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
+A 7-phase playbook, a live `.forgetrail/workflow_tracking.json`, and templates pre-loaded with first-party production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work follows. Those lesson notes are not independent adoption evidence.
+
+Optional hooks in [`content/hooks/`](content/hooks/README.md) load the current phase at session start in Cursor or Claude Code, validate tracking edits, and check for a session note at session stop. The agent still does the writing. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
 
 <!-- xfacts-label -->
 
@@ -63,3 +65,5 @@ pnpm site:dev
 Site (FilePress + docs mount): `pnpm ship`.
 
 Apache-2.0 · [Catalyst Forge LLC](https://catalystforge.com)
+
+[See the rest of the Catalyst Forge shelf.](https://catalystforge.com/tools/)

package/TRY_FORGETRAIL.md

@@ -26,9 +26,10 @@ Prove ForgeTrail in one sitting: write a **what, not how** spec in any AI chat,
 4. **Add ForgeTrail Lite**  
    - **Copy:** save [`content/FORGETRAIL_LITE.md`](content/FORGETRAIL_LITE.md) as `.forgetrail/FORGETRAIL_LITE.md` in your project, **or**  
    - **CLI** (Node 20+):  
-     `npx forgetrail install --lite`  
+     `pnpm dlx forgetrail install --lite`  
      Stub for Genesis too:  
-     `npx forgetrail install --lite --with-genesis-stub`
+     `pnpm dlx forgetrail install --lite --with-genesis-stub`  
+     The CLI also writes a starter tracking file and Cursor hooks, and skips files that already exist.
 
 5. **Save your spec as `docs/GENESIS.md`**  
    Create `docs/` if needed. That path is the canonical handoff for ForgeTrail (not the repo root).
@@ -66,7 +67,7 @@ Already have a long PRD? Save it as `docs/GENESIS.md` and use the kickoff line a
 Once you have verified the protocol on a first project, connecting the **ForgeTrail MCP server** is the natural upgrade:
 
 1. **Token efficiency:** Instead of pasting or re-reading the 28k-token Lite file, the agent pulls phase playbooks, templates, checklists, and anti-patterns on demand via MCP tools. Your prompt stays clean and focused on your app code.
-2. **Dynamic lessons:** The agent queries `searchLessons` and `getAntiPatterns` before large tasks, avoiding known traps across hundreds of prior sessions.
+2. **Dynamic lessons:** The agent queries `searchLessons` and `getAntiPatterns` before large tasks, avoiding traps recorded in first-party Catalyst Forge projects.
 3. **Structured validation:** `validateTracking` catches schema errors immediately.
 
 ### How to connect (Cursor)

package/content/examples/two-session-continuity.md

@@ -19,7 +19,7 @@ The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.
 3. Logged one decision and one gotcha.
 4. Stopped after the human approved the brief. No application scaffold yet.
 
-The CLI, if used instead of a hand copy, only writes the Lite file and an optional Genesis stub. It does not update tracking, decisions, or sessions. Those writes depend on the agent following the protocol.
+The CLI, if used instead of a hand copy, writes the Lite file, a starter tracking file, hook scripts, and an optional Genesis stub. It does not fill in phases, decisions, or sessions. Those writes depend on the agent following the protocol.
 
 ### What was left unfinished
 
@@ -99,7 +99,7 @@ That is the trail: phase flags, a decision, a gotcha, and a `nextSession` line.
 | --- | --- | --- |
 | `.forgetrail/FORGETRAIL_LITE.md` | Human copy, or `forgetrail install --lite` | The file copy is automatic once you run install. Following it is not. |
 | `docs/GENESIS.md` | Human, or `--with-genesis-stub` plus later edits | Stub only if you asked the CLI for it. |
-| `.forgetrail/workflow_tracking.json` | The agent, on first kickoff and after substantive work | No. Empty tracking after a busy session is a protocol miss. |
+| `.forgetrail/workflow_tracking.json` | The agent, on first kickoff and after substantive work. `forgetrail install --lite` places an empty starter. | No. Empty tracking after a busy session is a protocol miss. |
 | `docs/PHASE_1_BRIEF.md` | The agent, then the human approves | No. |
 | `decisions[]`, `gotchas[]`, `sessions[]` | The agent | No. The protocol tells the agent to append. The host does not enforce it. |
 

package/package.json

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