forgetrail 0.4.20 → 0.5.0

package/content/GREENFIELD_INTAKE.md

@@ -4,7 +4,7 @@ Use alongside **`getChecklist`** section `before-session-1`. That checklist cove
 
 **Already have a written spec (e.g. `docs/GENESIS.md`)?** Feed it into **`ingestPlanArtifact`** first, then use this document only to fill gaps (delivery, tenancy, compliance, live search) it may not cover. If the user has only an idea, **`getGenesisSpecPrompt`** (or human recipe **`TRY_FORGETRAIL.md`**) produces a portable spec via an external LLM chat before you run through these questions.
 
-**Agent:** Walk through these with the user (or infer from context and confirm). Record answers in **`docs/PHASE_1_BRIEF.md`** (§1–3, §6–8 as needed) and **`.forgetrail/workflow_tracking.json` → `decisions[]`**.
+**Agent:** Walk through these with the user (or infer from context and confirm). Record answers in **`docs/PHASE_1_BRIEF.md`** (§1–3, §6–8 as needed) and as **decision records in `appledger/`**. Do not write `workflow_tracking.json`.
 
 ---
 
@@ -19,7 +19,7 @@ Use alongside **`getChecklist`** section `before-session-1`. That checklist cove
 
 - **Is this a product, an internal tool, or a one-shot?** (product: others will use it, possibly pay; internal-tool: real recurring users, no market; one-shot: gift, event page, demo: one occasion, then done). Often obvious from the problem statement; confirm rather than interrogate.
 - The archetype **prunes the lifecycle**: internal tools make Phase 6 optional and drop payments/business-plan criteria from Phase 7; one-shots collapse phases 5–7 into a single polish-and-ship gate. See **WORKFLOW.md §1d**.
-- Record in **`PHASE_1_BRIEF.md`**, **`decisions[]`**, and **`project.archetype`** in the tracking file, then prune the tracking template's exit criteria to match (log the pruning as a decision).
+- Record it in **`PHASE_1_BRIEF.md`**, as a decision record, and as **`archetype`** on **`appledger/profiles/forgetrail.yaml`**. Prune non-applicable criteria on that profile. Do not write `workflow_tracking.json`.
 
 ## 1. Outputs and formats
 
@@ -53,7 +53,7 @@ Use alongside **`getChecklist`** section `before-session-1`. That checklist cove
 - If **yes**, the human will likely need a **search API** key before the spine can return real data. **Common developer starting points** (verify current free tiers and limits on the vendor site):
   - **[Tavily](https://tavily.com/)** — built for LLM/agent retrieval; [docs](https://docs.tavily.com/) · [pricing](https://tavily.com/pricing)
   - **[Brave Search API](https://api-dashboard.search.brave.com/)** — web, news, and more; [pricing](https://api-dashboard.search.brave.com/documentation/pricing) (renewable **monthly credits** for new accounts — set usage caps in the dashboard)
-- Record **which provider** and **env var names** in `PHASE_1_BRIEF` / `decisions[]`. **ForgeTrail Lite** §4.4 mirrors this for copy-paste (`content/FORGETRAIL_LITE.md`).
+- Record **which provider** and **env var names** in `PHASE_1_BRIEF` and as a decision record. **ForgeTrail Lite** §4.4 mirrors this for copy-paste (`content/FORGETRAIL_LITE.md`).
 
 ## 7. State persistence (web apps only)
 
@@ -62,7 +62,7 @@ Ask this **before** locking PocketBase + auth into the stack. Wrong answer here
 - **Does any state need to outlive the current browser?** Accounts, cross-device sync, shared data between users, admin/curator editing a catalog multiple users read — **yes**. Personal notes, offline-first tools, a single-user dashboard that reloads the same local data — **no**.
 - If **no** (A-local): drop PocketBase + auth; `localStorage` / `IndexedDB` for persistence; **`adapter-static`** is viable; no runtime secrets; deploy on free static hosts. An **interactive** A-local app still uses SvelteKit. **FilePress** is for a Markdown site (docs, writing, event page) or an optional `site/` beside the app, not a replacement for the app.
 - If **yes** (A-persistent): full Default-A stack — SvelteKit + PocketBase + `adapter-node`; accounts, sessions, server-only writes.
-- Record the choice in **`PHASE_1_BRIEF.md` §4** (`State persistence:` row) and **`decisions[]`**. **ForgeTrail Lite** §7 (A-local vs A-persistent) has the longer write-up.
+- Record the choice in **`PHASE_1_BRIEF.md` §4** (`State persistence:` row) and as a decision record. **ForgeTrail Lite** §7 (A-local vs A-persistent) has the longer write-up.
 
 ## 8. Content-generation pattern (only if content is produced by an LLM)
 
@@ -74,7 +74,7 @@ Skip this section entirely if content is hand-authored or pulled from a conventi
 - **Build-time LLM generation** — `scripts/seed.ts` via `pnpm run seed` calls the provider once, writes JSON into `data/`, commits it. Zero runtime LLM cost; pairs well with A-local + `adapter-static`. Seed script may use **cloud** or **Ollama** (same env vars; only needed when running seed).
 - **BYO-LLM paste pattern** — prompt in the repo; user runs it in **their own** LLM (ChatGPT, Claude, local Ollama chat, etc.); pastes JSON into e.g. `data/seed.json`; Zod validates at app start. Zero project-level API keys.
 
-Ask which **provider and model** (e.g. `ollama/ibm/granite4.1:8b`, `openai/gpt-4o-mini`, or BYO only). Record pattern, provider, env var names, paths, and validator in **`PHASE_1_BRIEF.md`** (content-generation section) and **`decisions[]`**. **ForgeTrail Lite** §7.1 has skeletons for OpenAI, Ollama, seed, and BYO-LLM.
+Ask which **provider and model** (e.g. `ollama/ibm/granite4.1:8b`, `openai/gpt-4o-mini`, or BYO only). Record pattern, provider, env var names, paths, and validator in **`PHASE_1_BRIEF.md`** (content-generation section) and as a decision record. **ForgeTrail Lite** §7.1 has skeletons for OpenAI, Ollama, seed, and BYO-LLM.
 
 If the choice is **local Ollama**, you may offer **ollanet** (host manager) and later **Finetuna** (runtime tuner). Keep **`setup-ollama`** / **`test-ollama`** as the in-repo health path. Optional: `getCompanionSuggestions` situations `local-ollama` / `ollama-vram`.
 
@@ -89,7 +89,7 @@ Ask only what is still open. If the user already named a provider, record it and
 - **DNS** — if unspecified, prefer **Cloudflare** (free plan: DNS, edge TLS, basic protection). Typical pattern: domain at any registrar, nameservers pointed at Cloudflare.
 - **Production host** — static site (FilePress or `adapter-static`): **Cloudflare Pages** + Wrangler, $0. App that needs a server: DigitalOcean (or similar) origin **behind** Cloudflare DNS.
 
-Record git host, DNS, registrar, and deploy target in **`PHASE_1_BRIEF.md` §4** and **`decisions[]`**.
+Record git host, DNS, registrar, and deploy target in **`PHASE_1_BRIEF.md` §4** and as a decision record.
 
 ---
 

package/content/KICKOFF_WITHOUT_MCP.md

@@ -7,7 +7,7 @@ Some Cursor sessions **do not expose MCP tools** to the agent (or only a subset)
 **If you must replicate the kickoff bundle from this repo** (same sources as `buildNewProjectKickoff` in `mcp-server/src/index.ts`), read and apply in order:
 
 1. `content/NEW_PROJECT_BOOTSTRAP.md` — methodology and next steps  
-2. `workflow_tracking.json` at the **ForgeTrail repo root** — copy JSON to the **customer** repo as **`.forgetrail/workflow_tracking.json`**, then apply the MCP path rewrites described in `getInitialWorkflowTracking` (or use the MCP tool when available)  
+2. If `appledger` is installed, run **`appledger init`** in the customer repo (pass **`--name`** when the name is known). Otherwise create the manifest, `profiles/forgetrail.yaml`, an application record, and a session record by hand. Do **not** copy root `workflow_tracking.json`. `getInitialWorkflowTracking` does not return a file to write.  
 3. `content/POST_BOOTSTRAP_USER_MESSAGE.md` — how the first user-facing reply should read  
 4. `content/cursor-rules/forgetrail-phase-status.mdc` — write to `.cursor/rules/forgetrail-phase-status.mdc` in the customer repo (Cursor only)  
 5. `content/cursor-rules/forgetrail-lessons-gate.mdc` and `forgetrail-lessons-mcp.mdc` — write to `.cursor/rules/` (lessons + anti-patterns gate before large work)  

package/content/NEW_PROJECT_BOOTSTRAP.md

@@ -1,6 +1,6 @@
 # ForgeTrail — New project bootstrap (MCP-first)
 
-Use this when **ForgeTrail is available via the MCP server** (recommended). The customer repo should **not** contain a copied `_forgetrail/` methodology tree — templates, audits, phase playbooks, and lessons are retrieved through MCP tools from the open-source ForgeTrail install. Only **project-local state** (chiefly **`.forgetrail/workflow_tracking.json`**) lives in the app repo.
+Use this when **ForgeTrail is available via the MCP server** (recommended). The customer repo should **not** contain a copied `_forgetrail/` methodology tree — templates, audits, phase playbooks, and lessons are retrieved through MCP tools from the open-source ForgeTrail install. Project state lives in **`appledger/`**. Do **not** create **`.forgetrail/workflow_tracking.json`**. `.forgetrail/` is hooks and host rules.
 
 ---
 
@@ -8,7 +8,7 @@ Use this when **ForgeTrail is available via the MCP server** (recommended). The
 
 1. Follow the **7-phase lifecycle** (Plan → Build → Stabilize → Iterate → Refine → Align → Harden).
 2. **Pause at phase transitions** for explicit user approval before advancing.
-3. **Persist ForgeTrail state in `.forgetrail/`** at the repo root — **same folder for MCP greenfield and Lite file bootstrap.** Write **`.forgetrail/workflow_tracking.json`** first; add **`.forgetrail/AGENTS.md`**, **`.forgetrail/CLAUDE.md`**, and **`.forgetrail/cursor/rules/`** (symlink `.mdc` files into **`.cursor/rules/`**). Product docs (**`docs/`**, **`CONTEXT_PROMPT.md`**, **`README.md`**, **`TODO.md`**) stay at repo root. **Optionally gitignore `.forgetrail/`** if you want a cleaner public history or use MCP-only without a vendored Lite file (see **`FORGETRAIL_LITE.md` §1.5**). For **Cursor**, add **`.cursor/rules/forgetrail-phase-status.mdc`** from **`getNewProjectKickoff`** (bundled) or **`getForgeTrailCursorPhaseRule`** — it reads **`.forgetrail/workflow_tracking.json`**. Also add **`forgetrail-lessons-gate.mdc`** and **`forgetrail-lessons-mcp.mdc`** from the same bundle or **`getForgeTrailCursorLessonsRules`** so agents call **`getAntiPatterns`** + **`searchLessons`** before substantial feature work.
+3. **Persist ForgeTrail state in `appledger/`** — manifest, `profiles/forgetrail.yaml`, and records. Do **not** write **`.forgetrail/workflow_tracking.json`**. Add **`.forgetrail/AGENTS.md`**, **`.forgetrail/CLAUDE.md`**, and **`.forgetrail/cursor/rules/`** (symlink `.mdc` files into **`.cursor/rules/`**) for host rules. Product docs (**`docs/`**, **`CONTEXT_PROMPT.md`**, **`README.md`**, **`TODO.md`**) stay at repo root. **Optionally gitignore `.forgetrail/`** if you want a cleaner public history or use MCP-only without a vendored Lite file (see **`FORGETRAIL_LITE.md` §1.5**). Commit **`appledger/`**. For **Cursor**, add **`.cursor/rules/forgetrail-phase-status.mdc`** from **`getNewProjectKickoff`** (bundled) or **`getForgeTrailCursorPhaseRule`** — it reads **`appledger/profiles/forgetrail.yaml`**. Also add **`forgetrail-lessons-gate.mdc`** and **`forgetrail-lessons-mcp.mdc`** from the same bundle or **`getForgeTrailCursorLessonsRules`** so agents call **`getAntiPatterns`** + **`searchLessons`** before substantial feature work.
 4. **Pull methodology on demand** via ForgeTrail MCP tools (below). Do not ask the user to paste entire ForgeTrail files.
 5. **User-facing replies:** After bootstrap files exist, **`getPostBootstrapUserMessage`** defines the **first** reply—plain language only: what you did, what happens next, and a **concrete “reply with”** (problem, audience, hero workflow, constraints, v1 scope). **No** MCP/tool names, methodology jargon, ForgeTrail footers, file inventories, or “reference only” tracking dumps unless the user asks for internals.
 6. **Lists and choices:** When offering several next steps or options, follow **`USER_REPLY_FORMAT.md`** (ForgeTrail): **numbers** for ordered pipelines, **bullets** for parallel items, **letters** for pick-one / “which first—A/B/C?”—never hide multiple paths in one long sentence.
@@ -21,7 +21,7 @@ On a **new project folder**, commands like `git status`, `git log`, or `git rev-
 
 **You** initialize git after bootstrap files exist (unless the user chose **no-git mode** — see **`FORGETRAIL_LITE.md` §4.1**):
 
-1. Write kickoff artifacts first: **`.forgetrail/workflow_tracking.json`**, guardrails, optional Cursor rules.
+1. Write kickoff artifacts first: **`appledger/`**, guardrails, optional Cursor rules. Do not write **`workflow_tracking.json`**.
 2. Check with `git rev-parse --is-inside-work-tree`. If it returns false or errors, run **`git init -b main`** at the repo root (or `git init` + `git branch -m main` on older Git). **Never** re-init an existing repo.
 3. Write a **minimal** `.gitignore` now — at least `node_modules/`, `.env`, `.DS_Store`. Add `.forgetrail/` **only** if you chose the gitignore branch in **`FORGETRAIL_LITE.md` §1.5** (default MCP greenfield: **commit `.forgetrail/`**).
 4. Make a **first commit** when steps 1–3 are done so the user has a clean baseline (plain `-m` or `-F`). Skip if the repo already had history; skip entirely in no-git mode.
@@ -32,10 +32,10 @@ Do **not** treat an early missing-repo git error as blocking. Prefer **`git rev-
 
 ## Progressive scaffolding (important)
 
-- **Phase 1:** Create and lock **`docs/PHASE_1_BRIEF.md`** (`getTemplate({ name: "PHASE_1_BRIEF" })`). Log major commitments in **`.forgetrail/workflow_tracking.json` → `decisions[]`**. If the host supports **native plan mode**, use **`getPlanModePatterns`** and WORKFLOW §1c — plan first, export to the brief on approval (no app code during planning).
+- **Phase 1:** Create and lock **`docs/PHASE_1_BRIEF.md`** (`getTemplate({ name: "PHASE_1_BRIEF" })`). Log major commitments as **decision records in `appledger/`**. If the host supports **native plan mode**, use **`getPlanModePatterns`** and WORKFLOW §1c — plan first, export to the brief on approval (no app code during planning).
 - **App/code:** Phase 2 still means the **full runnable spine** in one pass: init, deps, data path, routes, components, hero flow **end-to-end**. Do **not** defer that spine.
-- **Project archetype (Phase 1):** classify the project as **`product`** (default), **`internal-tool`**, or **`one-shot`** (gift / event / demo) — often inferable from the problem statement; confirm rather than interrogate. Record in **`PHASE_1_BRIEF.md`**, **`decisions[]`**, and **`project.archetype`** in the tracking file, then **prune** the non-applicable exit criteria from the tracking template (internal tools: Phase 6 optional, no payments/business-plan rows; one-shots: phases 5–7 collapse into one polish-and-ship gate). Log the pruning as a decision. See **WORKFLOW §1d** and **`GREENFIELD_INTAKE.md`** §0.
-- **Web-app sub-question (Phase 1, when app type = web app):** before locking PocketBase + auth, ask *"Does any state need to outlive the browser — accounts, cross-device sync, shared data — or is every user's state private and fine in `localStorage`?"* If local-only → **drop PocketBase and auth**, `adapter-static` becomes viable, no deploy-time secrets; persist via `localStorage` / `IndexedDB`. If persistent → the full Default-A stack applies. Record the choice in `decisions[]` and in **`PHASE_1_BRIEF.md` §4 (`State persistence:` row)**. See **`FORGETRAIL_LITE.md` §7** (A-local vs A-persistent) and **`GREENFIELD_INTAKE.md`** §7.
+- **Project archetype (Phase 1):** classify the project as **`product`** (default), **`internal-tool`**, or **`one-shot`** (gift / event / demo) — often inferable from the problem statement; confirm rather than interrogate. Record it in **`PHASE_1_BRIEF.md`**, as a decision record, and as **`archetype`** on **`appledger/profiles/forgetrail.yaml`**. Prune non-applicable criteria on that profile (internal tools: Phase 6 optional, no payments/business-plan rows; one-shots: phases 5–7 collapse into one polish-and-ship gate). Log the pruning as a decision. Do not write `workflow_tracking.json`. See **WORKFLOW §1d** and **`GREENFIELD_INTAKE.md`** §0.
+- **Web-app sub-question (Phase 1, when app type = web app):** before locking PocketBase + auth, ask *"Does any state need to outlive the browser — accounts, cross-device sync, shared data — or is every user's state private and fine in `localStorage`?"* If local-only → **drop PocketBase and auth**, `adapter-static` becomes viable, no deploy-time secrets; persist via `localStorage` / `IndexedDB`. If persistent → the full Default-A stack applies. Record the choice as a decision record and in **`PHASE_1_BRIEF.md` §4 (`State persistence:` row)**. See **`FORGETRAIL_LITE.md` §7** (A-local vs A-persistent) and **`GREENFIELD_INTAKE.md`** §7.
 - **Initial data (optional):** The user may create **JSON files** for seed, fixtures, or imports by using **any** LLM chat (including **local Ollama**) with the copy-paste prompt in **`FORGETRAIL_LITE.md` §4.3** (structured JSON only; save to `data/` or `fixtures/`). The agent **validates** shape before import; the user can repeat for multiple datasets. Not a replacement for the Phase 1 brief — only for bulk structured content.
 - **Web search (optional):** If v1 needs **live internet search**, the user can sign up for **[Tavily](https://tavily.com/)** and/or the **[Brave Search API](https://api-dashboard.search.brave.com/)** (free or entry-level credits per vendor terms), add keys to **`.env`**, and the agent wires **server-side** clients. See **`FORGETRAIL_LITE.md` §4.4** and **`GREENFIELD_INTAKE.md`** §6.
 - **Content-generation pattern (optional, if content is LLM-produced):** if any v1 content is produced by an LLM rather than hand-authored or pulled from a non-LLM API, pick **one** of three patterns up front — it drives deploy model, cost, and secret management:
@@ -43,7 +43,7 @@ Do **not** treat an early missing-repo git error as blocking. Prefer **`git rev-
   - **Build-time LLM generation** — `pnpm run seed` once → JSON in `data/`; zero runtime LLM cost; seed may use cloud or Ollama.
   - **BYO-LLM paste** — prompt in repo; user runs any LLM (including Ollama UI); pastes JSON; Zod at import; zero project API keys.
 
-  Record pattern, provider, and env vars in `decisions[]` and **`PHASE_1_BRIEF.md`** (content-generation section / §6a in full template). See **`FORGETRAIL_LITE.md` §7.1** (OpenAI, Ollama, seed, BYO skeletons).
+  Record pattern, provider, and env vars as a decision record and in **`PHASE_1_BRIEF.md`** (content-generation section / §6a in full template). See **`FORGETRAIL_LITE.md` §7.1** (OpenAI, Ollama, seed, BYO skeletons).
 - **Phase 2 stack-conditional deps:** At Phase 2 entry, run **`FORGETRAIL_LITE.md` §4.1.2** — PocketBase/Ollama health scripts, `.env` keys, Playwright install, native `node-gyp` tooling, etc., **only for what the locked brief requires** (not universal preflight).
 - **Documentation:** Do **not** generate every ForgeTrail template at once. Phase 2 creates **`CONTEXT_PROMPT.md`** (by **merging the brief** into it — see CONTEXT_PROMPT template), plus **`README.md`**, **`TODO.md`**, **`.forgetrail/IDEAS.md`**. Add `TECHNICAL_REFERENCE`, `TEST_PLAN`, `DESIGN_SYSTEM`, `BRAND_AND_PRODUCT`, hardening docs, etc. **in the phase that needs them**.
 
@@ -57,15 +57,15 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
    - If **`docs/GENESIS.md`** already exists (Try path / human brought a what-not-how spec), call **`ingestPlanArtifact`** with that file’s contents as `planContent`, review the draft brief, then continue intake for gaps only (`getGreenfieldIntakePrompt`). Do **not** re-run a full blank Genesis prompt unless the user asks.
    - If the user only has an **idea** (no file yet), especially one that wraps an existing app’s data/file format, offer **`getGenesisSpecPrompt`**: they paste it into an **external** LLM chat, save the result as **`docs/GENESIS.md`**, then you ingest as above. Humans without MCP can follow repo-root **`TRY_FORGETRAIL.md`** instead.
    - Skip this step if the user wants straight Lite/MCP intake questions with no Genesis file.
-1. Call **`getNewProjectKickoff`** (`includeCursorRule: false` if not using **Cursor**). It bundles this document, starter **`.forgetrail/workflow_tracking.json`**, post-bootstrap user-message guidance, and optionally the Cursor rules (phase status + lessons gate + lessons MCP detail)—**or** call **`getNewProjectBootstrap`**, **`getInitialWorkflowTracking`**, **`getPostBootstrapUserMessage`**, **`getForgeTrailCursorPhaseRule`**, and **`getForgeTrailCursorLessonsRules`** separately if you need only one piece. Create **`.forgetrail/`**, write files there; the **next message to the user** follows **`getPostBootstrapUserMessage`** (product-facing, no methodology leak).
+1. Call **`getNewProjectKickoff`** (`includeCursorRule: false` if not using **Cursor**). It bundles this document, **`appledger/`** initialization, post-bootstrap user-message guidance, and optionally the Cursor rules (phase status + lessons gate + lessons MCP detail)—**or** call **`getNewProjectBootstrap`**, **`getInitialWorkflowTracking`**, **`getPostBootstrapUserMessage`**, **`getForgeTrailCursorPhaseRule`**, and **`getForgeTrailCursorLessonsRules`** separately if you need only one piece. **`getInitialWorkflowTracking` does not return a JSON file.** Write **`appledger/`**. Do not write **`workflow_tracking.json`**. The **next message to the user** follows **`getPostBootstrapUserMessage`** (product-facing, no methodology leak).
 2. **Initialize git if needed** (see **Greenfield git** above): after bootstrap files exist, `git init -b main` when `git rev-parse --is-inside-work-tree` fails; minimal `.gitignore`; optional first commit. Do not ask the user to run `git init`.
 3. Call **`getProgressiveDocSchedule`** and keep it in mind for every phase transition.
 4. Call **`getChecklist`** with section `before-session-1` — complete those items with the user (problem statement, stack, assets, hero flow).
-5. Call **`getGreenfieldIntakePrompt`** — product/delivery questions: exports (PDF / DOCX / PPTX, etc.), tenancy (e.g. consultants × clients), hybrid vs full spec, compliance tier (even if “none yet”), hero flow, and registrar/DNS/git/hosting if still open. Capture answers in **`PHASE_1_BRIEF.md`** and **`decisions[]`**. If using native plan mode, include these questions in the plan context (`getPlanModePatterns`). When a companion trigger is true later, call **`getCompanionSuggestions`**. Do not name companions in the first user-facing message.
-6. Call **`getTrackingSchema`** — you will maintain **`.forgetrail/workflow_tracking.json`** accordingly. Optionally call **`getAgentIntegrationGuide`** for your host (`grok`, `cursor`, `claude`, `generic`) and **`getForgeTrailSkill`** if the agent supports persistent skills.
+5. Call **`getGreenfieldIntakePrompt`** — product/delivery questions: exports (PDF / DOCX / PPTX, etc.), tenancy (e.g. consultants × clients), hybrid vs full spec, compliance tier (even if “none yet”), hero flow, and registrar/DNS/git/hosting if still open. Capture answers in **`PHASE_1_BRIEF.md`** and as decision records. If using native plan mode, include these questions in the plan context (`getPlanModePatterns`). When a companion trigger is true later, call **`getCompanionSuggestions`**. Do not name companions in the first user-facing message.
+6. Call **`getTrackingSchema`** — you will maintain **`appledger/`**. Do not maintain a tracking JSON file. Optionally call **`getAgentIntegrationGuide`** for your host (`grok`, `cursor`, `claude`, `generic`) and **`getForgeTrailSkill`** if the agent supports persistent skills.
 7. Call **`getPhaseGuidance`** with phase `1` (architecture). Summarize understanding and propose structure, data model, integrations, and v1 scope **before** writing app code.
-8. During Phase 1, create **`docs/PHASE_1_BRIEF.md`** from **`getTemplate({ name: "PHASE_1_BRIEF" })`**, fill every section, and **lock** it; mirror major decisions in **`.forgetrail/workflow_tracking.json`**.
-9. After architecture is confirmed and the brief is locked, call **`getPhaseGuidance`** with phase `2` (scaffolding). Read the brief + **`.forgetrail/workflow_tracking.json`**, **merge the brief into `CONTEXT_PROMPT.md`**, then execute a **single-pass app skeleton** and the rest of the Phase 2 doc set (`README`, `TODO`, `.forgetrail/IDEAS.md`).
+8. During Phase 1, create **`docs/PHASE_1_BRIEF.md`** from **`getTemplate({ name: "PHASE_1_BRIEF" })`**, fill every section, and **lock** it; mirror major decisions as **appledger decision records**.
+9. After architecture is confirmed and the brief is locked, call **`getPhaseGuidance`** with phase `2` (scaffolding). Read the brief and **`appledger/profiles/forgetrail.yaml`**, **merge the brief into `CONTEXT_PROMPT.md`**, then execute a **single-pass app skeleton** and the rest of the Phase 2 doc set (`README`, `TODO`, `.forgetrail/IDEAS.md`).
 
 ---
 
@@ -89,13 +89,13 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 | **Native plan mode as Phase 1** | **`getPlanModePatterns`** — use before scaffolding when the host supports plan-before-code |
 | **Agent-specific integration** (Grok, Cursor, Claude) | **`getAgentIntegrationGuide`** — primitive mappings and session openers |
 | **Installable forgetrail skill** (Grok etc.) | **`getForgeTrailSkill`** — copy to host skill directory |
-| **Tracking file health check** | **`validateTracking`** — after substantive work or phase transitions |
+| **Legacy tracking classification** | **`validateTracking`** — reports a writable `workflow_tracking.json` as a conflict. A missing file is expected |
 | **Optional companion tools** (FilePress, LocalSlip, skills, xFacts, …) | **`getCompanionSuggestions`** — `phase` or `situation`; never required; not in the first user-facing message (WORKFLOW §1f) |
 | **Parallel subagent recommendations** | **`suggestSubagentDecomposition`** — before spawning audits/research (WORKFLOW §1c) |
-| **Starter tracking file** for a greenfield repo | `getInitialWorkflowTracking` — write the returned JSON to **`.forgetrail/workflow_tracking.json`** |
+| **Ledger initialization** for a greenfield repo | `getInitialWorkflowTracking` — does **not** return JSON. Create **`appledger/`** |
 | **First reply to the human** after tracking exists (short; no tool dump) | **`getPostBootstrapUserMessage`** |
 | **Numbered vs bullet vs letter lists** when offering options | **`getUserReplyFormat`** — also in Cursor **`forgetrail-phase-status.mdc`** |
-| **Cursor IDE:** phase / next-action footers from tracking | **`getForgeTrailCursorPhaseRule`** — write to `.cursor/rules/forgetrail-phase-status.mdc` (reads **`.forgetrail/workflow_tracking.json`**; Phase 1; optional if not using Cursor) |
+| **Cursor IDE:** phase / next-action footers | **`getForgeTrailCursorPhaseRule`** — write to `.cursor/rules/forgetrail-phase-status.mdc` (reads **`appledger/profiles/forgetrail.yaml`**; optional if not using Cursor) |
 | **Cursor IDE:** lessons gate (`getAntiPatterns` + `searchLessons` before large work) | **`getForgeTrailCursorLessonsRules`** — writes `forgetrail-lessons-gate.mdc` + `forgetrail-lessons-mcp.mdc` (also in **`getNewProjectKickoff`**) |
 | **Phase 2:** PocketBase scripted install defaults (port, version, dirs) + optional **schema-from-.env** pattern | **`getScaffoldInstallParams`** — keep app `scaffold-defaults.json` in sync; see **`schemaAutomation`** in the JSON and **`POCKETBASE_SCHEMA_SCRIPT.md`** in ForgeTrail |
 | **Phase 2+:** repeatable dev scripts (env check, codegen, seed, E2E browsers, git hooks) | **`DEV_AUTOMATION_SCRIPTS.md`** in ForgeTrail; **`devAutomation`** in **`getScaffoldInstallParams`** JSON |
@@ -106,14 +106,14 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 
 **Immediately (greenfield):**
 
-- **`.forgetrail/`** — create the directory. Write **`.forgetrail/workflow_tracking.json`** inside it (output from **`getInitialWorkflowTracking`**), then fill `project.name`, `project.created`, `project.description`, and update phases as you work. Add **`.forgetrail/`** to **`.gitignore`** if the repo may be published.
+- **`appledger/`** — if the `appledger` command is installed, run **`appledger init`** and pass **`--name`** when the name is known. Init writes the manifest, profile, application record, and session record, and does not overwrite them. If the command is not installed, write those four files by hand. Do **not** write **`workflow_tracking.json`**. Commit **`appledger/`**.
 - **`docs/GENESIS.md`** (optional but preferred on the Try path) — what-not-how product spec from **`getGenesisSpecPrompt`** / **`TRY_FORGETRAIL.md`**. If present at kickoff, ingest with **`ingestPlanArtifact`** before locking the brief.
 - **Git repo** — if `git rev-parse --is-inside-work-tree` fails, **`git init -b main`** after bootstrap files exist (see **Greenfield git**). A failed early `git status` on an empty folder is **not** an error. Add minimal **`.gitignore`** and an optional first commit before Phase 1 intake.
 - **Cursor users:** `.cursor/rules/forgetrail-phase-status.mdc` — from **`getForgeTrailCursorPhaseRule`**. **`forgetrail-lessons-gate.mdc`** + **`forgetrail-lessons-mcp.mdc`** — from **`getForgeTrailCursorLessonsRules`** or **`getNewProjectKickoff`** (lessons workflow before substantial changes).
 
 **End of Phase 1 (before scaffolding):**
 
-- **`docs/PHASE_1_BRIEF.md`** — complete and locked; **`.forgetrail/workflow_tracking.json`** — `decisions[]` + phase 1 notes updated.
+- **`docs/PHASE_1_BRIEF.md`** — complete and locked; **`appledger/`** — decision records and the plan phase updated. Do not mark criteria met without evidence.
 
 **During Phase 2 (scaffolding), after architecture lock:**
 
@@ -138,11 +138,11 @@ Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WOR
 
 ## Rules (same as methodology, MCP-adjusted)
 
-- At **each session start**, read the repo’s `.forgetrail/workflow_tracking.json` and `CONTEXT_PROMPT.md` (if present). Use **`getPhaseGuidance`** for the **current** phase from `.forgetrail/workflow_tracking.json` → `currentPhase`.
-- When exit criteria for a phase appear satisfied, **state that explicitly** and **wait for user confirmation** before treating the next phase as active; update `currentPhase` only after approval.
-- After substantive work, **update `.forgetrail/workflow_tracking.json`**: exit criteria, `decisions`, `gotchas`, `sessions` per **`getTrackingSchema`**. Run **`validateTracking`** to catch structural drift.
+- At **each session start**, read **`appledger/profiles/forgetrail.yaml`**, the latest session record, and `CONTEXT_PROMPT.md` (if present). Use **`getPhaseGuidance`** for the current phase.
+- When exit criteria for a phase appear satisfied, **state that explicitly** and **wait for user confirmation** before treating the next phase as active; change `current_phase_instance` only after approval.
+- After substantive work, update **`appledger/`** (criteria, decision records, lessons, the session). Do not write **`workflow_tracking.json`**. If that file exists and is not a pointer, **`validateTracking`** reports the conflict.
 - If a problem does not converge after **~5 turns**, propose a **different approach**, not more patches.
-- **When the project ends** (shipped, delivered, shelved), run the **wrap protocol** (WORKFLOW §1e): sweep `gotchas[]` + `decisions[]` for generalizable lessons, run the propagation prompt in **Harvest mode**, set `project.status` to `"wrapped"`, and add a final `sessions[]` entry with end state and handoff pointers.
+- **When the project ends** (shipped, delivered, shelved), run the **wrap protocol** (WORKFLOW §1e): sweep lesson and decision records for generalizable lessons, run the propagation prompt in **Harvest mode**, set **`project_status`** to **`wrapped`** on the profile, and add a final session record with end state and handoff pointers. Do not write `workflow_tracking.json`.
 - **Git commits:** `git commit -F <file>` or plain `-m` at natural stopping points with concise summaries. Run verification checks prior to commit.
 
 ---
@@ -157,24 +157,24 @@ ForgeTrail’s reference implementation used **SvelteKit (Svelte 5), TypeScript,
 
 If the user has [gstack](https://github.com/garrytan/gstack) installed (Claude Code slash-command skills), ForgeTrail and gstack are **complementary** — ForgeTrail provides the lifecycle methodology, project memory, and business/brand layer; gstack provides sprint execution, browser-based QA, and deploy automation. Use both:
 
-**ForgeTrail owns the lifecycle.** Phase transitions, exit criteria, `.forgetrail/workflow_tracking.json`, progressive docs, lessons, and audits all come from ForgeTrail MCP.
+**ForgeTrail owns the lifecycle.** Phase transitions, exit criteria, `appledger/`, progressive docs, lessons, and audits all come from ForgeTrail MCP. Do not write `workflow_tracking.json`.
 
 **gstack owns the sprint inner loop.** Within a ForgeTrail phase, use gstack skills for the build → review → test → ship cycle:
 
 | ForgeTrail phase | gstack skills to use | How they connect |
 |---------------|---------------------|------------------|
-| **Phase 1** (Plan) | `/office-hours` for product framing, `/plan-ceo-review` for scope | Capture outputs in **`PHASE_1_BRIEF.md`** and **`.forgetrail/workflow_tracking.json` → `decisions[]`** — gstack doesn't persist these, ForgeTrail does. |
+| **Phase 1** (Plan) | `/office-hours` for product framing, `/plan-ceo-review` for scope | Capture outputs in **`PHASE_1_BRIEF.md`** and **decision records in `appledger/`** — gstack doesn't persist these, ForgeTrail does. |
 | **Phase 2** (Build) | `/plan-eng-review` for technical spine review | After building the skeleton, run `/review` on the initial commit. Merge the brief into `CONTEXT_PROMPT.md` per ForgeTrail's template. |
-| **Phase 3** (Stabilize) | `/investigate` for systematic root-cause debugging | Log every gotcha in **`.forgetrail/workflow_tracking.json` → `gotchas[]`** and update `CONTEXT_PROMPT.md` — gstack fixes bugs but doesn't persist lessons. |
-| **Phase 4** (Iterate) | `/plan-eng-review` per feature → build → `/review` → `/qa` → `/ship` | After each `/ship`, update **`TODO.md`** (mark done), **`CONTEXT_PROMPT.md`** (if patterns changed), and **`.forgetrail/workflow_tracking.json`** (exit criteria, session notes). |
+| **Phase 3** (Stabilize) | `/investigate` for systematic root-cause debugging | Log each lesson or open question in **`appledger/`** and update `CONTEXT_PROMPT.md` — gstack fixes bugs but doesn't persist lessons. |
+| **Phase 4** (Iterate) | `/plan-eng-review` per feature → build → `/review` → `/qa` → `/ship` | After each `/ship`, update **`TODO.md`** (mark done), **`CONTEXT_PROMPT.md`** (if patterns changed), and **`appledger/`** (criteria and the session). |
 | **Phase 5** (Refine) | `/review` on refactor branches | Update `CONTEXT_PROMPT.md` and `TECHNICAL_REFERENCE.md` to match the new structure. |
 | **Phase 6** (Align) | `/design-consultation` for design system, `/plan-ceo-review` for scope check | Create **`BRAND_AND_PRODUCT.md`** and restructure **`TODO.md`** via ForgeTrail templates — gstack doesn't have brand/strategy tooling. |
 | **Phase 7** (Harden) | `/cso` for security audit, `/qa` for full regression, `/ship` + `/land-and-deploy` + `/canary` for production | ForgeTrail's `runAudit("black-hat")` and gstack's `/cso` are complementary — run both. ForgeTrail produces **`BLACK_HAT_REPORT.md`** and **`CODE_QUALITY.md`** as persistent docs; gstack's `/cso` catches runtime exploits. Use `/land-and-deploy` → `/canary` for the actual deploy pipeline, then fill ForgeTrail's **`DEPLOYMENT.md`** to document the process. |
 
-**Key rule:** After every gstack sprint that completes meaningful work, **update `.forgetrail/workflow_tracking.json`** (move exit criteria, add decisions/gotchas, update session notes). gstack persists some sprint artifacts (design docs from `/office-hours` in `~/.gstack/projects/`, retro snapshots in `.context/retros/`, review overrides, skill analytics), but it has **no lifecycle state, no decision rationale log, and no architecture context document**. ForgeTrail's `.forgetrail/workflow_tracking.json` + `CONTEXT_PROMPT.md` are the system of record for what phase you're in, what's been decided and why, what gotchas have been hit, and what the architecture looks like — none of which gstack tracks.
+**Key rule:** After every gstack sprint that completes meaningful work, **update `appledger/`** (criteria when evidence exists, decision records, lessons or questions, the session). Do not write `workflow_tracking.json`. gstack persists some sprint artifacts (design docs from `/office-hours` in `~/.gstack/projects/`, retro snapshots in `.context/retros/`, review overrides, skill analytics), but it has **no lifecycle state, no decision rationale log, and no architecture context document**. ForgeTrail's `appledger/` plus `CONTEXT_PROMPT.md` are the system of record for the phase, the decisions, the lessons, and the architecture — none of which gstack tracks.
 
 ---
 
 ## IP / distribution note
 
-This bootstrap is designed for **MCP delivery**: deep methodology stays in the ForgeTrail distribution or hosted MCP; the customer repository holds **their** app, **their** filled docs, and **their** tracking file — not a vendored copy of ForgeTrail itself.
+This bootstrap is designed for **MCP delivery**: deep methodology stays in the ForgeTrail distribution or hosted MCP; the customer repository holds **their** app, **their** filled docs, and **their** `appledger/` ledger — not a vendored copy of ForgeTrail itself.

package/content/PLAN_MODE_PATTERNS.md

@@ -14,10 +14,10 @@ When your host agent supports a first-class plan mode (Grok Build `/plan` + ente
 3. On user approval (the agent's `exit_plan_mode` or equivalent):
    - Immediately call `getTemplate({ name: "PHASE_1_BRIEF", mode: "full" })`.
    - Map/synthesize the approved plan content into the brief template (especially sections on architecture, data model, state persistence, content generation, and v1 scope).
-   - Log every major decision into `.forgetrail/workflow_tracking.json` → `decisions[]` (with id, timestamp, phase: "1-architecture", decision, rationale, alternatives_considered).
-   - Optionally call `ingestPlanArtifact` with the full approved plan text to produce a `PHASE_1_BRIEF.md` draft and `decisions[]` entries (review and lock before Phase 2).
+   - Write each major decision as a decision record in `appledger/`. Do not write `.forgetrail/workflow_tracking.json`.
+   - Optionally call `ingestPlanArtifact` with the full approved plan text to produce a `PHASE_1_BRIEF.md` draft and decision records (review and lock before Phase 2).
 
-4. The approved `docs/PHASE_1_BRIEF.md` + tracking decisions now become the handoff so Phase 2 can begin "cold" without replaying the entire planning conversation.
+4. The approved `docs/PHASE_1_BRIEF.md` and those decision records become the handoff so Phase 2 can begin "cold" without replaying the entire planning conversation.
 
 ## Grok Build Specifics
 
@@ -35,7 +35,7 @@ When your host agent supports a first-class plan mode (Grok Build `/plan` + ente
 ## Artifacts That Must Result from Phase 1 (Plan or Not)
 
 - `docs/PHASE_1_BRIEF.md` (locked)
-- `.forgetrail/workflow_tracking.json` with `currentPhase: "1-architecture"` (or advancing), `decisions[]` populated, and exit criteria updated
+- `appledger/` with the `plan` phase in progress and those decision records. Do not create `.forgetrail/workflow_tracking.json`.
 - (Later) `CONTEXT_PROMPT.md` will merge the brief in Phase 2
 
 Never proceed to scaffolding until the user confirms the plan/brief is locked.

package/content/POST_BOOTSTRAP_USER_MESSAGE.md

@@ -1,6 +1,6 @@
 # Post-bootstrap: first reply to the user
 
-**When:** Right after project tracking files exist (repo root tracking JSON +, for Cursor, the phase rule file if you use it).
+**When:** Right after `appledger/` exists (and, for Cursor, the phase rule file if you use it). Do not mention `workflow_tracking.json` to the user.
 
 **Purpose:** Confirm what happened in **plain language** and give **one clear ask**—what the human should do or answer next. This is not an implementation report.
 

package/content/SESSION_RESUME_MCP.md

@@ -6,11 +6,11 @@ The user is **continuing** a project that uses ForgeTrail via the **MCP server**
 
 ## Before doing anything else
 
-1. Read **`.forgetrail/workflow_tracking.json`** — current phase, exit criteria, notes, decisions.
-2. If **`currentPhase`** is **`1-architecture`**, read **`docs/PHASE_1_BRIEF.md`** and continue planning toward a locked brief. Otherwise read **`CONTEXT_PROMPT.md`**. If Phase 2+ but CONTEXT is missing and **`PHASE_1_BRIEF.md`** exists, **merge the brief into CONTEXT** first (see CONTEXT_PROMPT template).
-3. Call **`getPhaseGuidance`** for the phase matching `.forgetrail/workflow_tracking.json` → `currentPhase` (e.g. `4` for feature iteration, or keyword `features`). When a companion trigger is true, call **`getCompanionSuggestions`** for that phase or situation. Do not install unless the user asked.
+1. Read **`appledger/profiles/forgetrail.yaml`** — current phase instance and criteria — and the latest session record (`left_off`, `next_steps`).
+2. If the current phase is **`plan`**, read **`docs/PHASE_1_BRIEF.md`** and continue planning toward a locked brief. Otherwise read **`CONTEXT_PROMPT.md`**. If a later phase is current but CONTEXT is missing and **`PHASE_1_BRIEF.md`** exists, **merge the brief into CONTEXT** first (see CONTEXT_PROMPT template).
+3. Call **`getPhaseGuidance`** for that phase (`plan` through `harden`, or `1`–`7`). When a companion trigger is true, call **`getCompanionSuggestions`** for that phase or situation. Do not install unless the user asked.
 4. If you need checklist context, call **`getChecklist`** (e.g. `every-session` or `full`).
-5. If unsure how to update tracking fields, call **`getTrackingSchema`**.
+5. If a **`workflow_tracking.json`** file exists and is not a pointer, do not update it. Run **`appledger migrate preview`**, then apply. Call **`validateTracking`** only to classify that file.
 
 Do **not** require `_forgetrail/WORKFLOW.md` or `_forgetrail/TRACKING_SCHEMA.md` on disk — use the MCP tools above.
 
@@ -18,11 +18,11 @@ Do **not** require `_forgetrail/WORKFLOW.md` or `_forgetrail/TRACKING_SCHEMA.md`
 
 ## Rules for this session
 
-- When exit criteria for the current phase appear met, say so explicitly and **wait for user confirmation** before advancing `currentPhase`.
-- After work, **update `.forgetrail/workflow_tracking.json`** (criteria, `decisions`, `gotchas`, `sessions`) per **`getTrackingSchema`**.
+- When exit criteria for the current phase appear met, say so explicitly and **wait for user confirmation** before changing `current_phase_instance`.
+- After work, update the **session record** and any new **decision records** in **`appledger/`**. Do not write **`workflow_tracking.json`**.
 - Keep **`CONTEXT_PROMPT.md`** the source of truth for architecture; edit it when decisions change.
 - If stuck after **~5 turns** on one issue, propose a **fundamentally different approach**.
-- If the repo has **gstack** installed, use its skills for sprint execution (build/review/qa/ship) within ForgeTrail phases — see **WORKFLOW.md §1b** or call **`getPhaseGuidance`** for phase-specific gstack integration. After each gstack sprint, update `.forgetrail/workflow_tracking.json`.
+- If the repo has **gstack** installed, use its skills for sprint execution (build/review/qa/ship) within ForgeTrail phases — see **WORKFLOW.md §1b** or call **`getPhaseGuidance`** for phase-specific gstack integration. After each gstack sprint, update the **appledger** session.
 
 ---
 

package/content/companion-tools.json

@@ -4,7 +4,7 @@
     "Companions are optional. Decline is success. Never block a phase on an install.",
     "Suggest at the moment of need. Do not dump the shelf at kickoff or in the first user-facing message.",
     "Do not install, enroll, or publish unless the user asked.",
-    "After a companion run that matters, persist the outcome in .forgetrail/workflow_tracking.json and the matching progressive doc.",
+    "After a companion run that matters, persist the outcome on the appledger session as data.companion_outcomes and in the matching progressive doc. Do not write workflow_tracking.json.",
     "Do not mention the mapping file, spec paths, or MCP tool names in human-facing offers.",
     "When wiring LocalSlip, follow that tool's how. Do not write ensure-lease.mjs. Do not add the localslip package just to read a port."
   ],

package/content/cursor-rules/forgetrail-phase-status.mdc

@@ -1,11 +1,11 @@
 ---
-description: Show ForgeTrail phase, next actions, and doc gaps from workflow_tracking.json (esp. bookends & what's next)
+description: Show ForgeTrail phase and next actions from appledger/profiles/forgetrail.yaml
 alwaysApply: true
 ---
 
 # ForgeTrail phase awareness
 
-This repo uses **ForgeTrail** lifecycle tracking. **Source of truth:** `.forgetrail/workflow_tracking.json` (`currentPhase`, `phases`, `decisions`).
+This repo uses **ForgeTrail**. **Source of truth:** `appledger/profiles/forgetrail.yaml` and the latest session record. Do **not** read or write `.forgetrail/workflow_tracking.json`. If that file exists and is not a pointer, it is a legacy conflict: run `appledger migrate preview`, then apply.
 
 ## When to surface status
 
@@ -19,17 +19,16 @@ Include a short **ForgeTrail** footer in replies when it helps orientation—esp
 
 Skip the footer for trivial one-line answers (typos, single-token replies) unless the user asked for status.
 
-**Product-facing / non-technical users:** Do **not** show ForgeTrail footers, phase IDs, MCP/tool names, or internal checklists unless they ask how the workflow is wired up. Plain language only. For phase progress without an agent, point them to **`status.bat`** / **`status.sh`**, **`pnpm run forgetrail:status`**, or **`docs/FORGETRAIL_PROGRESS.md`** (regenerated from `.forgetrail/workflow_tracking.json`).
+**Product-facing / non-technical users:** Do **not** show ForgeTrail footers, phase IDs, MCP/tool names, or internal checklists unless they ask how the workflow is wired up. Plain language only. For phase progress without an agent, point them to **`docs/FORGETRAIL_PROGRESS.md`**. The durable phase is `appledger/profiles/forgetrail.yaml`, not `.forgetrail/workflow_tracking.json`.
 
 **Right after bootstrap:** **Omit** the footer entirely—user should get a simple “what’s done + what I need from you next,” not methodology. If you already followed **`getPostBootstrapUserMessage`** in the same turn, do not duplicate status blocks.
 
 ## What to read
 
-1. Open **`.forgetrail/workflow_tracking.json`** (or use known state from the same turn).
-2. Report **`currentPhase`** using friendly names:  
-   `1-architecture` → Plan · `2-scaffolding` → Build · `3-stabilization` → Stabilize · `4-feature-iteration` → Iterate · `5-refactoring` → Refine · `6-strategic-review` → Align · `7-hardening` → Harden.
-3. For that phase, note **`status`** (`not_started` | `in_progress` | `completed`) and **1–3 items** from **`exitCriteriaRemaining`** as **likely next actions** (truncate with “…” if long).
-4. If Phase 2+ docs are expected but missing, mention once: e.g. no **`CONTEXT_PROMPT.md`** / **`TODO.md`** at repo root when `currentPhase` is `2-scaffolding` or later.
+1. Open **`appledger/profiles/forgetrail.yaml`** and the latest session record (or use known state from the same turn).
+2. Report the current phase id: `plan`, `build`, `stabilize`, `iterate`, `refine`, `align`, or `harden`.
+3. For that phase instance, note **`status`** and **1–3 pending criteria** as **likely next actions** (truncate with “…” if long).
+4. If later-phase docs are expected but missing, mention once: e.g. no **`CONTEXT_PROMPT.md`** / **`TODO.md`** at repo root when the phase is past `plan`.
 
 ## Footer format (compact, copy-paste)
 
@@ -58,4 +57,4 @@ Do **not** bury three or more paths in a single long sentence—**list them**, t
 
 ## Phase transitions
 
-Do **not** advance `currentPhase` or mark phases complete without **explicit user confirmation** (ForgeTrail rule). If exit criteria look satisfied, say so and ask before updating tracking.
+Do **not** advance `current_phase_instance` or mark a phase completed without **explicit user confirmation**. If criteria look satisfied, say so and ask before updating the profile. Do not write `workflow_tracking.json`.

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

@@ -1,8 +1,8 @@
 # Two-session continuity (illustrative)
 
-This is a labeled example. The project is fictional. It shows how ForgeTrail Lite state survives a closed chat, and how the next session is supposed to consume it. File names match ForgeTrail `0.4.6` / Lite `schemaVersion: "lite-1"`.
+This is a labeled example. The project is fictional. It shows how ForgeTrail Lite state survives a closed chat, and how the next session is supposed to consume it.
 
-Nothing here is a benchmark, an adoption claim, or a client record.
+Nothing here is a benchmark, an adoption claim, or a client record. The record shape matches `appledger/` records, not the legacy `workflow_tracking.json` starter.
 
 ## The job
 
@@ -14,84 +14,46 @@ The human created an empty folder, wrote `docs/GENESIS.md`, and added Lite by co
 
 The human pasted the kickoff line from [TRY_FORGETRAIL.md](../../TRY_FORGETRAIL.md). The **agent** (not the CLI) then:
 
-1. Created `.forgetrail/workflow_tracking.json` from the Lite starter in `FORGETRAIL_LITE.md` §11.
+1. Created `appledger/` with a manifest, a ForgeTrail profile, an application record, and a session record. It did not create `.forgetrail/workflow_tracking.json`.
 2. Drafted `docs/PHASE_1_BRIEF.md`.
-3. Logged one decision and one gotcha.
+3. Recorded one decision and one lesson.
 4. Stopped after the human approved the brief. No application scaffold yet.
 
-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.
+The CLI, if used instead of a hand copy, writes the Lite file, hook scripts, and an optional Genesis stub. It does not write a tracking JSON file and it does not fill in the phase, decisions, or session. Those writes depend on the agent following the protocol.
 
 ### What was left unfinished
 
-Phase 1 exit criteria `phase1BriefLocked` and `stackLocked` are true. `heroFlowAgreed` is still false. `currentPhase` is still `1`. The next session still has to agree the first stamp command, then scaffold.
+The `plan` phase is `in_progress`. The brief is approved and the stack is locked. The first stamp command is not agreed. The next session still has to agree that command, then scaffold.
 
 ### Persisted excerpt
 
-Labeled excerpt of `.forgetrail/workflow_tracking.json` at the end of session 1. Shape matches the Lite starter, not the MCP string-phase starter.
-
-```json
-{
-  "schemaVersion": "lite-1",
-  "project": {
-    "name": "desk-stamp",
-    "created": "2026-09-08",
-    "description": "Local CLI that stamps today's date on markdown notes",
-    "sourceControl": "git",
-    "archetype": "one-shot",
-    "status": "active"
-  },
-  "currentPhase": 1,
-  "phases": {
-    "1": {
-      "name": "Plan",
-      "status": "in_progress",
-      "exitCriteria": {
-        "phase1BriefLocked": true,
-        "stackLocked": true,
-        "heroFlowAgreed": false,
-        "v1ScopeAgreed": false
-      }
-    }
-  },
-  "decisions": [
-    {
-      "date": "2026-09-08",
-      "phase": 1,
-      "decision": "TypeScript CLI, files on disk only, no hosted store",
-      "why": "Weekend tool. A database would be a second product.",
-      "alternatives": ["Python script", "SQLite index"]
-    }
-  ],
-  "gotchas": [
-    {
-      "date": "2026-09-08",
-      "phase": 1,
-      "gotcha": "On Windows, npm 12 npx forgetrail failed to spawn the bin",
-      "fix": "Use pnpm dlx forgetrail, or copy FORGETRAIL_LITE.md by hand"
-    }
-  ],
-  "sessions": [
-    {
-      "date": "2026-09-08",
-      "phase": 1,
-      "summary": "Genesis plus Lite in place. Phase 1 brief drafted and approved. Stack locked. Hero flow not agreed.",
-      "nextSession": "Agree the first stamp command, then scaffold the CLI. Do not reopen the no-database decision."
-    }
-  ]
-}
+Labeled excerpt at the end of session 1. Fields match ledger records. This is not a complete file.
+
+```yaml
+phase: plan
+status: in_progress
+choice: TypeScript CLI, files on disk only, no hosted store
+rationale: Weekend tool. A database would be a second product.
+problem: On Windows, npm 12 npx forgetrail failed to spawn the bin
+resolution: Use pnpm dlx forgetrail, or copy FORGETRAIL_LITE.md by hand
+left_off: Phase 1 brief approved. Stack locked. Hero flow not agreed.
+next_steps:
+  - Agree the first stamp command, then scaffold. Do not reopen the no-database decision.
 ```
 
-## Session 2 (new chat, same repo)
+`appledger orient` prints the phase, decision choices, lessons, and the latest session time and next steps. The view can omit a fact that was stored only inside an older session body.
 
-The human opened a new agent chat in the same folder and said: follow `.forgetrail/FORGETRAIL_LITE.md` and continue from tracking.
+## Session 2 (new chat, same folder)
 
-The agent read `.forgetrail/workflow_tracking.json` first. Visible consequences:
+The human opened a new agent chat in the same folder and said: follow `.forgetrail/FORGETRAIL_LITE.md` and continue from `appledger/`.
 
-- It did not re-ask whether to add a database. That decision is already in `decisions[]`.
-- It used `pnpm dlx` on Windows instead of `npx forgetrail`, because `gotchas[]` already recorded the spawn failure.
+The agent read the profile and the latest session first. Visible consequences:
+
+- It did not re-ask whether to add a database. That choice is already a decision record.
+- It used `pnpm dlx` on Windows instead of `npx forgetrail`, because a lesson already recorded the spawn failure.
 - It treated `docs/PHASE_1_BRIEF.md` as locked and asked only about the unfinished hero flow, the first stamp command, before writing application code.
 
-That is the trail: phase flags, a decision, a gotcha, and a `nextSession` line. The next chat does not have to reconstruct them from memory.
+That is the trail: a phase, a decision, a lesson, and a next step. The next chat does not have to reconstruct them from memory.
 
 ## What persists, and who writes it
 
@@ -99,12 +61,14 @@ 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. `forgetrail install --lite` places an empty starter. | No. Empty tracking after a busy session is a protocol miss. |
+| `appledger/` | The agent, on first kickoff and after substantive work. The installer does not write it. | No. An empty ledger 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. |
+| Decision, lesson, and session records | The agent | No. The protocol tells the agent to write them. The host does not enforce the prose. |
 
 MCP tools can hand the agent the same protocol and a lessons search. They do not replace the files in the app repo.
 
+An existing writable `.forgetrail/workflow_tracking.json` is legacy. `appledger migrate preview` writes nothing. `apply` imports decisions, sessions, resolved gotchas as lessons, unresolved gotchas as open questions, and `IDEAS.md` / `BUGS.md` from the repository root and from `.forgetrail/`, then replaces the file with a pointer. The `appledger` package is not a published npm release. Use the [repository](https://github.com/Catalyst-Forge-LLC/appledger).
+
 ## Catalog excerpt
 
-Keep project decisions, development state, and lessons in the repository so the next session can continue. After one sitting you should see `.forgetrail/workflow_tracking.json` with a phase, a decision, and a `nextSession` line. Full walk-through: this file, and the [continuity](https://forgetrail.dev/docs/continuity) page.
+Keep project decisions, development state, and lessons in the repository so the next session can continue. After one sitting you should see `appledger/` with a phase, a decision, and a session next step. Full walk-through: this file, and the [continuity](https://forgetrail.dev/docs/continuity) page. The live site still shows the previous pages until it is redeployed.

package/content/forgetrail-workspace-README.md

@@ -1,6 +1,6 @@
 # Local ForgeTrail workspace (`.forgetrail/`)
 
-This folder holds **ForgeTrail agent artifacts** — tracking, platform rules, and (for Lite boots) the protocol file. ForgeTrail upstream is **Apache 2.0**; you may commit this folder or **gitignore** it for a slimmer public app repo. Never commit secrets here.
+This folder holds **ForgeTrail host artifacts** — protocol, platform rules, and hooks. Project phase, decisions, and sessions live in **`appledger/`**, not in this folder. ForgeTrail upstream is **Apache 2.0**; you may commit this folder or **gitignore** it for a slimmer public app repo. Never commit secrets here. Do not add `workflow_tracking.json`.
 
 Used for **both** ForgeTrail Lite file bootstrap and **MCP greenfield** kickoff.
 
@@ -8,7 +8,7 @@ Used for **both** ForgeTrail Lite file bootstrap and **MCP greenfield** kickoff.
 
 | File | Purpose |
 |------|---------|
-| `workflow_tracking.json` | Phase / decisions / session tracking (all approaches) |
+| `hooks/` | Host safety hooks. They do not store project phase or decisions |
 | `FORGETRAIL_LITE.md` | Full Lite kickoff protocol (Lite file bootstrap only) |
 | `FORGETRAIL_LITE_UPDATES.md` | Optional local feedback log (§1.6) — merge accepted items upstream |
 | `AGENTS.md` | Agent instructions — cite or symlink for your IDE |

package/content/hooks/README.md

@@ -6,10 +6,10 @@ Enforces ForgeTrail rules and guards at the host tool level, rather than relying
 
 - `guard-shell.mjs`: runs pre-commit verification (`pnpm run verify`), prevents npm/yarn when `pnpm-lock.yaml` is present, gates `git push` to upstream remotes (pushing to IngotVault or local backup mirrors is allowed automatically), and prompts on destructive git or filesystem operations.
 - `guard-edit.mjs`: guards `.env*` secrets files and `specs/completed/**` or `specs/canonical/**` records against accidental mutation.
-- `session-start.mjs`: on session start, reads `.forgetrail/workflow_tracking.json` and injects live phase status, open exit criteria, and last session notes into agent context.
-- `validate-tracking.mjs`: after editing `workflow_tracking.json`, runs structural validation and returns any issues as context.
+- `session-start.mjs`: on session start, points the session at `appledger/`. A writable `workflow_tracking.json` is reported as a legacy conflict, not the live phase.
+- `validate-tracking.mjs`: after editing `workflow_tracking.json`, runs structural validation. A pointer is accepted. A legacy writable document is a conflict.
 - `validate-tracking-core.mjs`: standalone zero-dependency tracking validator.
-- `session-stop.mjs`: on session stop, checks that session notes were added to tracking.
+- `session-stop.mjs`: on session stop, reminds the agent to update the appledger session record. It does not ask for a new JSON session entry.
 - `cursor-hooks.json`: standard Cursor hooks configuration.
 - `claude-settings-hooks.json`: standard Claude Code configuration fragment.