forgetrail 0.3.0

package/content/FORGETRAIL_LITE_UPDATES.md

@@ -0,0 +1,13 @@
+# ForgeTrail Lite — local feedback log (starter)
+
+Copy into **`.forgetrail/FORGETRAIL_LITE_UPDATES.md`** on a bootstrapped project (gitignored). Use when a session finds a gap in **ForgeTrail Lite itself** — not routine app bugs.
+
+**How to use:** see **`FORGETRAIL_LITE.md` §1.6** and symlink **`forgetrail-updates-log.mdc`** into `.cursor/rules/` (§12.6).
+
+**Upstream:** merge accepted entries into `forgetrail/content/FORGETRAIL_LITE.md`, then trim or archive here.
+
+---
+
+## Entries
+
+_(Add numbered sections: what went wrong, suggested Lite change with § reference, optional repo pointer.)_

package/content/FORGETRAIL_PROGRESS.md

@@ -0,0 +1,26 @@
+# ForgeTrail progress
+
+_Human-readable snapshot for non-technical operators. **Source of truth:** `.forgetrail/workflow_tracking.json` — the agent updates that file; this doc is refreshed when you run **status.bat** / **status.sh** or **pnpm run forgetrail:status**._
+
+## Current phase
+
+- **Phase:** _(run status script to refresh)_
+- **Status:** —
+
+## What's done
+
+_(Populated from exit criteria marked true in tracking.)_
+
+## Still to do (this phase)
+
+_(Populated from exit criteria still false.)_
+
+## How to check progress anytime
+
+| Platform | Action |
+|----------|--------|
+| **Windows** | Double-click **`status.bat`** at the repo root |
+| **Mac / Linux** | Double-click **`status.sh`** or run `./status.sh` in Terminal |
+| **Terminal** | `pnpm run forgetrail:status` (after Phase 2 setup) |
+
+Cursor users also get phase footers from **`.cursor/rules/forgetrail-phase-status.mdc`** when using an agent.

package/content/GENESIS_SPEC_PROMPT.md

@@ -0,0 +1,70 @@
+# ForgeTrail — Genesis spec prompt (pre-Phase 1, external LLM chat)
+
+Use this **before** Phase 1, in **any** LLM chat — ChatGPT, Claude, Grok, a local Ollama window, whatever you have open — not inside ForgeTrail's MCP tools. It produces a **`GENESIS.md`**: a "what, not how" build spec, focused on requirements and behavior rather than implementation, that you can then hand to a coding agent.
+
+**Best fit:** ideas that wrap or extend an **existing app's data or file format** (plugins, converters, companion tools, importers/exporters). The shape generalizes to most "point an agent at this and build it" ideas even without that constraint.
+
+**Relationship to ForgeTrail's own Phase 1 tools:**
+
+- **`getGreenfieldIntakePrompt`** + `getChecklist(before-session-1)` are for **in-session** Phase 1 intake with the coding agent (exports, tenancy, hero flow, etc.) — use them when you're starting Phase 1 directly with no pre-written spec.
+- **This prompt** runs **earlier and elsewhere** — a separate LLM chat, before you've even opened the coding agent — and produces a **portable artifact** (`GENESIS.md`) instead of an interactive Q&A. Use it when the idea needs upfront market/format research that's better done as its own pass, or when you want a spec you can shop between different coding agents/stacks without rewriting it.
+- **They are complementary, not competing** — a `GENESIS.md` from this prompt is a perfectly good input to `getGreenfieldIntakePrompt`'s delivery questions (exports, tenancy, compliance) if those aren't already covered.
+
+## After you have `GENESIS.md`
+
+1. Save it in the project repo as **`docs/GENESIS.md`** (canonical path).
+2. Follow the human recipe in **`TRY_FORGETRAIL.md`** (ForgeTrail repo root), or feed the spec into ForgeTrail Phase 1:
+   - **Automatic draft:** call **`ingestPlanArtifact`** with the full `GENESIS.md` text as `planContent`. It maps headings like *Problem statement*, *Goals and non-goals*, *Required background on the data/file format*, *Core domain concepts*, *Edge cases*, *Milestones*, and *Open questions* into `docs/PHASE_1_BRIEF.md` sections, and extracts any `D1.`/`D2.`-style decisions into `decisions[]`. Sections without a clean home (e.g. **Acceptance criteria** — the brief has no dedicated section for it) land in a "Plan sections not auto-mapped" footer — fold that into **§12 Handoff checklist** or its own appendix by hand.
+   - **Manual walkthrough:** read `docs/GENESIS.md` together with the agent as context, then run **`getGreenfieldIntakePrompt`** + `getChecklist(before-session-1)` to confirm delivery details the spec might not cover (tenancy, compliance, live search, content-generation pattern).
+3. Either way, **lock `docs/PHASE_1_BRIEF.md`** before Phase 2 scaffolding, per the normal Phase 1 exit criteria.
+
+**Shape reference (fiction):** `content/examples/GENESIS_SAMPLE_mars-habitat-roster.md` — a Mars habitat duty roster (shared shift schedule in a sci-fi skin).
+
+---
+
+## Copy-paste prompt
+
+Copy this, fill in the bracketed parts, and send it to an LLM chat.
+
+---
+
+I want to build **[tool idea, one sentence]**.
+
+**The problem:** [what's currently painful, and what you're doing manually today as a workaround — e.g. "I export to CSV and diff in a spreadsheet"]
+
+**Before you write the spec:**
+
+1. Search for whether something like this already exists (tools, plugins, GitHub issues/feature requests for the underlying app, abandoned projects). Tell me what's out there, what it covers, and what it's missing. I want to know if I'm reinventing something or if this gap is real.
+2. Research the underlying data format / file structure this tool needs to work with (e.g. how [the app] actually stores its data on disk — file formats, folder layout, versioning quirks, any non-obvious serialization behavior). I need this documented in the spec itself so my build agents don't have to rediscover it.
+
+**Then write a detailed spec** for me to hand to coding agents, focused on **what** the tool does, not **how** to build it (leave stack/implementation choices to the builder unless a file format forces a specific approach). Structure it with:
+
+- Problem statement
+- Goals and explicit non-goals (v1 scope)
+- Required background on the underlying data/file format the builder needs to know
+- Core domain concepts/model
+- Numbered functional requirements, grouped logically, each with a decimal-numbered checklist of specifics
+- Non-functional requirements (performance, safety, platform, privacy)
+- Edge cases the builder must handle — be exhaustive here, this is where naive implementations fail
+- Suggested milestones (M1 = smallest usable version, building up)
+- Acceptance criteria — concrete, testable "given X, then Y" statements
+- Open questions for me to confirm before/during the build
+
+**Constraints:**
+
+- Local-only / [your privacy, platform, or stack constraints]
+- [Any must-have safety behavior — e.g. "never modify source files without a backup"]
+- [Any explicit out-of-scope items you already know you don't want]
+
+**Format:** Deliver it as a markdown file I can hand off directly, not just inline chat text.
+
+---
+
+### Why this prompt works
+
+- **Forces a validation step first** — you find out if the idea already exists before investing in a spec.
+- **Forces the format research up front** — the hardest bugs in these tools come from misunderstanding the underlying file format, so making that a required section catches problems early instead of during a rewrite.
+- **"What not how"** keeps the spec durable — you can hand it to different agents/stacks without rewriting it, and it won't go stale when a library changes.
+- **Non-goals section** stops scope creep before it starts — just as important as the goals.
+- **Edge cases + acceptance criteria** are what separate a spec that produces a demo from one that produces something you'll actually trust with real data.
+- **Milestones** give you a working v1 fast instead of a big-bang build.

package/content/GENESIS_STUB.md

@@ -0,0 +1,18 @@
+# GENESIS.md (stub)
+
+Replace this file with your **what, not how** build spec.
+
+## How to fill it
+
+1. Open the ForgeTrail Genesis prompt: in a clone of forgetrail see `content/GENESIS_SPEC_PROMPT.md`, or use the MCP tool `getGenesisSpecPrompt`.
+2. Paste the copy-paste section into any LLM chat (ChatGPT, Claude, Grok, Ollama UI, …).
+3. Iterate until you trust the markdown, then **overwrite this file** with the result.
+4. Optional shape reference (fiction): `content/examples/GENESIS_SAMPLE_mars-habitat-roster.md` in the ForgeTrail repo.
+
+## Then kick off your coding agent
+
+See **TRY_FORGETRAIL.md** in the ForgeTrail repo for the full recipe. Short version:
+
+> Follow `.forgetrail/FORGETRAIL_LITE.md` as the project protocol. Treat `docs/GENESIS.md` as the product spec (what, not how). Create `.forgetrail/workflow_tracking.json` and draft `docs/PHASE_1_BRIEF.md` from the Genesis file, asking me only about gaps. Do not scaffold application code until I explicitly approve the Phase 1 brief.
+
+Keep this file at **`docs/GENESIS.md`** (this path). Do not move it to the repo root.

package/content/GREENFIELD_INTAKE.md

@@ -0,0 +1,76 @@
+# Greenfield product intake (Phase 1 helper)
+
+Use alongside **`getChecklist`** section `before-session-1`. That checklist covers *problem, stack, assets, hero flow* at a high level. This document adds **delivery and product-shape** questions so Phase 1 does not miss exports, tenancy, or “how literal is the spec.”
+
+**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[]`**.
+
+---
+
+## 0. Project archetype (ask or infer first)
+
+- **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).
+
+## 1. Outputs and formats
+
+- **What must users be able to export or download?** (e.g. PDF, DOCX, PPTX, Markdown, CSV)
+- **Is the product primarily read in-app, or is export the primary deliverable?**
+
+## 2. Tenancy and users
+
+- **Single organization per deployment, or many?** (e.g. consultants with **many clients** → multi-tenant accounts, client workspaces, or org switcher)
+- **Who signs up / pays?** (consultant firm vs end-client org)
+- **Roles:** admin, editor, viewer — needed for v1 or later?
+
+## 3. How the “spec” becomes the product
+
+- **Full automation from a fixed spec**, **fully AI-generated**, or **hybrid** (structured sections + optional narrative; **skip sections** that do not apply per org)?
+- **Source of truth:** single canonical doc (e.g. DOCX/PDF) vs living templates in repo?
+
+## 4. Compliance and data sensitivity (even if “none yet”)
+
+- **Explicit “none at this phase”** is fine — still note it so Phase 7 hardening revisits.
+- Any **region**, **retention**, or **enterprise** expectations on the horizon?
+
+## 5. Hero flow (v1 success path)
+
+- **One sentence:** e.g. *Sign up → onboarding wizard → generated playbook v1 → view in app → export PDF / DOCX / PPTX.*
+- **What proves the spine works?** (first real export, first saved client, etc.)
+
+## 6. Live web search and current events
+
+- **Does v1 need answers grounded in the public internet** (not only the model’s training data)? Research assistants, RAG over fresh pages, news, and “what happened this week” flows usually do.
+- 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`).
+
+## 7. State persistence (web apps only)
+
+Ask this **before** locking PocketBase + auth into the stack. Wrong answer here = weeks of unused auth flow or, worse, a "local app" that silently depends on a backend that is inconvenient to run locally.
+
+- **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.
+- 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.
+
+## 8. Content-generation pattern (only if content is produced by an LLM)
+
+Skip this section entirely if content is hand-authored or pulled from a conventional (non-LLM) API. If an LLM **generates** content that the app displays, pick **one** of three patterns **in Phase 1** — it drives deploy model, cost, and secret management:
+
+- **Runtime LLM API** — server route (e.g. `src/routes/api/suggest/+server.ts`) calls the provider per request; rate-limit + streaming UX; server runtime required (not `adapter-static`). **Provider choice:**
+  - **Cloud** (OpenAI, Anthropic, …) — API key in `.env`; cost scales with traffic.
+  - **Local Ollama** — `OLLAMA_BASE_URL`, `OLLAMA_MODEL`; no cloud key. Phase 2: **`setup-ollama`** / **`test-ollama`** (VRAM-aware pull; default **ibm/granite4.1:8b** or **gemma3:4b** — avoid thinking/reasoning models unless **`OLLAMA_USE_THINKING=1`** and the brief requires it). See **SYSTEM_HEALTH_CHECKS.md**, **FORGETRAIL_LITE** §4.8.
+- **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.
+
+---
+
+## Why this exists
+
+`before-session-1` alone does not spell out **project archetype (product vs internal tool vs one-shot)**, **exports** (including slide decks), **multi-tenant consulting**, **hybrid vs full spec**, **live web search needs**, **state persistence (local vs accounts)**, or **LLM-content generation pattern** — common sources of rework if captured only late in Phase 1.

package/content/KICKOFF_WITHOUT_MCP.md

@@ -0,0 +1,16 @@
+# Greenfield kickoff when ForgeTrail MCP tools are not callable
+
+Some Cursor sessions **do not expose MCP tools** to the agent (or only a subset), even if ForgeTrail shows **connected** in MCP settings. That is a **client/session bridge** limitation—not proof that `getNewProjectKickoff` is undefined in the server.
+
+**Verify the server (in a chat that can call MCP):** invoke tool **`ping`**. Check **`forgetrail-mcp version`** is **≥ 0.2.1** (kickoff tools registered with correct names) or **≥ 0.2.2** (clearer `ping` text). **`ping` does not run `tools/list`**—it only confirms this process, version, and paths; the kickoff tool names in the response are a static hint, not proof your client exposes them.
+
+**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)  
+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)  
+6. `content/USER_REPLY_FORMAT.md` — numbered vs bullet vs letter lists (also summarized inside the phase `.mdc` rule)
+
+**Prefer:** switch to a Cursor mode that exposes ForgeTrail MCP to the agent, or call **`kickoffGreenfield`** (no parameters) if **`getNewProjectKickoff`** does not appear in the tool list.

package/content/LITE_WORKFLOW_TRACKING.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "lite-1",
+  "project": {
+    "name": "",
+    "created": "",
+    "description": "",
+    "sourceControl": "git",
+    "archetype": "product",
+    "status": "active"
+  },
+  "currentPhase": 1,
+  "phases": {
+    "1": {
+      "name": "Plan",
+      "status": "in_progress",
+      "exitCriteria": {
+        "phase1BriefLocked": false,
+        "stackLocked": false,
+        "heroFlowAgreed": false,
+        "v1ScopeAgreed": false
+      }
+    },
+    "2": {
+      "name": "Build",
+      "status": "pending",
+      "exitCriteria": {
+        "runnableSpine": false,
+        "heroFlowEndToEnd": false,
+        "contextPromptWritten": false
+      }
+    },
+    "3": { "name": "Stabilize", "status": "pending", "exitCriteria": {} },
+    "4": { "name": "Iterate", "status": "pending", "exitCriteria": {} },
+    "5": { "name": "Refine", "status": "pending", "exitCriteria": {} },
+    "6": { "name": "Align", "status": "pending", "exitCriteria": {} },
+    "7": { "name": "Harden", "status": "pending", "exitCriteria": {} }
+  },
+  "decisions": [],
+  "gotchas": [],
+  "sessions": [],
+  "openQuestions": []
+}

package/content/NEW_PROJECT_BOOTSTRAP.md

@@ -0,0 +1,180 @@
+# 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.
+
+---
+
+## Your job as the agent
+
+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.
+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.
+
+---
+
+## Greenfield git (no `.git` yet is normal)
+
+On a **new project folder**, commands like `git status`, `git log`, or `git rev-parse` may fail with **`fatal: not a git repository`**. **That is expected—not a setup failure.** Do **not** stop kickoff, panic, or ask the user to run `git init` manually.
+
+**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.
+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`; no attribution trailers — see Rules below). Skip if the repo already had history; skip entirely in no-git mode.
+
+Do **not** treat an early missing-repo git error as blocking. Prefer **`git rev-parse --is-inside-work-tree`** over blind `git status` when you only need to know whether init is required.
+
+---
+
+## 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).
+- **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.
+- **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:
+  - **Runtime LLM API** — server route per request; rate limits + streaming UX. **Cloud** keys in `.env`, or **local Ollama** (`OLLAMA_BASE_URL`, `OLLAMA_MODEL`) with Phase 2 **`setup-ollama`** / **`test-ollama`** (Lite §4.8; Granite 4.1 / Gemma 3 defaults).
+  - **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).
+- **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**.
+
+Call **`getProgressiveDocSchedule`** for the canonical phase → doc matrix (WORKFLOW §1a).
+
+---
+
+## First actions (in order)
+
+0. **Pre-written spec or idea only:**
+   - 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).
+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”), and hero flow. Capture answers in **`PHASE_1_BRIEF.md`** and **`decisions[]`**. If using native plan mode, include these questions in the plan context (`getPlanModePatterns`).
+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.
+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`).
+
+---
+
+## MCP tool map (what to call when)
+
+| Need | MCP tool |
+|------|-----------|
+| **Pre-Phase-1 build spec (external LLM chat)** | **`getGenesisSpecPrompt`** → user saves **`docs/GENESIS.md`**; or human recipe **`TRY_FORGETRAIL.md`** (no MCP) |
+| **Feature delivery SPEC template (Phase 4+)** | **`getTemplate({ name: "SPEC_FEATURE_TEMPLATE" })`** → write `specs/[feature].md`; lifecycle in WORKFLOW Phase 4 |
+| **Approved Genesis / plan → brief + decisions** | **`ingestPlanArtifact`** — after plan approval or when `docs/GENESIS.md` exists |
+| **One-call greenfield setup** (bootstrap + tracking JSON + post-bootstrap guidance + optional Cursor rules) | **`getNewProjectKickoff`** — prefer over calling the granular tools separately |
+| **Which docs in which phase** | **`getProgressiveDocSchedule`** (WORKFLOW §1a) |
+| Phase playbooks, entry/exit criteria, patterns | `getPhaseGuidance` (phases 1–7 or keywords like `scaffolding`, `hardening`) |
+| Milestone checklists | `getChecklist` (`before-session-1`, `session-1`, `session-2`, `full`, …) |
+| **Exports, multi-tenant, hybrid spec, compliance, hero flow** (Phase 1) | **`getGreenfieldIntakePrompt`** — use with `before-session-1` so delivery shape is captured early |
+| How to update tracking | `getTrackingSchema` |
+| Doc structure vs full lessons | `getTemplate` — `mode: "shell"` for placeholders/headings only (💡📝🔧 blockquotes stripped from single-source `docs/*.md`); `mode: "full"` when you need every example and lesson. Use `name: "list"` to discover template names |
+| Security, pre-launch, marketing, docs audits | `runAudit` — use `type: "list"` for available prompts |
+| Keyword search across lesson callouts | `searchLessons` |
+| Consolidated anti-patterns | `getAntiPatterns` |
+| **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 |
+| **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`** |
+| **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:** 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 |
+
+---
+
+## Files to create in the **customer repo** (no `_forgetrail/`)
+
+**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.
+- **`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.
+- **Trailer-ban guardrails — create unconditionally, regardless of current agent.** Users switch tools mid-project. Write **`AGENTS.md`**, **`CLAUDE.md`**, and **`.forgetrail/cursor/rules/forgetrail-no-trailer.mdc`** under **`.forgetrail/`**; **symlink or copy** the `.mdc` into **`.cursor/rules/`**. Core text: no unrequested attribution in commit messages. **`git commit --trailer`** is normal on **Git 2.32+**; pre-2.32 may need a shell hop if the wrapper injects `--trailer` — see **`FORGETRAIL_LITE.md` §4.2 step 3, §8.9, §12.5**.
+- **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.
+
+**During Phase 2 (scaffolding), after architecture lock:**
+
+- `.env.example`, `.gitignore`
+- **Scripted local services (recommended):** call **`getScaffoldInstallParams`** and align app install scripts with the returned JSON. **Never hardcode a stale PocketBase semver** — install scripts resolve **`POCKETBASE_VERSION=latest`** from GitHub at setup time (§**FORGETRAIL_LITE.md** §4.2.2, **`ONE_CLICK_DEV_SETUP.md`**). Create **setup.bat** / **setup.sh**, **run.bat** / **run.sh**, **status.bat** / **status.sh**, plus **test-pocketbase.bat** (§4.7, **`SYSTEM_HEALTH_CHECKS.md`**) so non-technical users are not given a wall of terminal commands. If the brief uses **local Ollama**, add **setup-ollama.bat** / **test-ollama.bat** (§4.8 — Granite 4.1 / Gemma 3, not thinking models by default). The agent runs first-time setup when possible; launchers are for repeat use. PocketBase lands in **`./pocketbase/`**, data in **`pb_data`**, port explicit in **`.env`** (default **8096** in reference defaults — change if **8090** or another project is already listening).
+- **PocketBase collections:** prefer a **schema script** (admin auth from **`POCKETBASE_ADMIN_EMAIL` / `POCKETBASE_ADMIN_PASSWORD`** in `.env`) that idempotently creates/updates collections per **`docs/pocketbase-setup.md`** — see **`POCKETBASE_SCHEMA_SCRIPT.md`** (ForgeTrail) and **`schemaAutomation`** in **`getScaffoldInstallParams`** output — instead of manual Admin UI steps for each collection.
+- **Dev automation (recommended):** add **`pnpm`** scripts for anything you’d otherwise ask the user to do repeatedly: **env validation** (`env:check`), **generated types** (`gen:types`), **seed data** (`db:seed`), **Playwright browser install** (`test:e2e:install`), **git hooks** (`prepare` + Husky). See **`DEV_AUTOMATION_SCRIPTS.md`** (ForgeTrail) and **`devAutomation`** in **`getScaffoldInstallParams`** — no cloud “infrastructure as code” required; these run on the developer machine.
+- App skeleton per confirmed stack (full spine + hero flow). **SvelteKit:** if using `sv create`, pass **fully non-interactive** flags (e.g. `tailwindcss="plugins:none"` so Tailwind plugin prompts do not appear). **Target a new path** (e.g. `app/` or `web/`) that **does not exist yet** — **not** `.` — if the repo root already has files; otherwise `sv` may prompt **`Directory not empty. Continue?`** and **hang** the agent (no reliable auto-answer). See **ForgeTrail Lite** §4.2 step 10. Interactive CLIs **hang** when the agent holds a read-only terminal — see Svelte CLI `sv create --help` (“skip prompts”). Do not re-run `sv create` in an already-initialized app folder.
+- **`CONTEXT_PROMPT.md`** — create from **`getTemplate`**, then **merge** `PHASE_1_BRIEF.md` per the template’s “Handoff from Phase 1” table; use **`mode: "full"`** when you need embedded patterns/anti-patterns after the merge.
+- **`README.md`**, **`TODO.md`** (seed from brief §11), **`.forgetrail/IDEAS.md`** via **`getTemplate`** — do **not** add the rest of the template library here unless the user explicitly needs a file to complete the spine
+- **`getTemplate({ name: "README", mode: "shell" })`** (or default shell) for structure; **`mode: "full"`** when lessons in that template are needed
+
+**Phases 3–7:**
+
+- Follow **`getProgressiveDocSchedule`**: e.g. `TECHNICAL_REFERENCE` / `TEST_PLAN` / `DESIGN_SYSTEM` in Phase 4+ as warranted; `BRAND_AND_PRODUCT` and pillar TODO in Phase 6; `CODE_QUALITY`, `BLACK_HAT_REPORT`, `DEPLOYMENT`, `BUGS`, etc. in Phase 7.
+
+**Never required in the customer repo:**
+
+- A copy of the full ForgeTrail tree (`_forgetrail/`, internal `WORKFLOW.md` mirror, etc.)
+
+---
+
+## 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.
+- 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.
+- **Git commits:** `git commit -F <file>` or plain `-m`; no unrequested attribution trailers. **Git 2.32.0+** supports `--trailer` — focus on message policy, not Git version anxiety. **Pre-2.32 only:** `unknown option 'trailer'` → `bash -c "git commit -F …"` or upgrade Git. See **`FORGETRAIL_LITE.md` §8.9** and **`.cursor/rules/commit-messages.mdc`**.
+
+---
+
+## Default stack hint (override per user)
+
+ForgeTrail’s reference implementation used **SvelteKit (Svelte 5), TypeScript, Tailwind, PocketBase, pnpm** — but the methodology is **stack-agnostic**. Lock the stack in Phase 1 with the user; do not silently substitute your own defaults.
+
+---
+
+## Using ForgeTrail with gstack
+
+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.
+
+**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 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 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.
+
+---
+
+## 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.

package/content/ONE_CLICK_DEV_SETUP.md

@@ -0,0 +1,142 @@
+# One-click dev setup (ForgeTrail / Lite Phase 2)
+
+**Goal:** A non-technical operator never copies a dozen terminal commands. The **agent** creates safe, idempotent launchers; the human **double-clicks** (or runs one `pnpm` script).
+
+Upstream reference scripts: `content/scripts/` (`forgetrail-dev-launcher.mjs`, `setup-pocketbase.mjs`, `test-pocketbase.mjs`, `setup-ollama.mjs`, `test-ollama.mjs`, `forgetrail-env.mjs`). Isolated checks: **`SYSTEM_HEALTH_CHECKS.md`**.
+
+---
+
+## Agent obligations
+
+1. **Do not** paste long manual command lists to the user for routine setup — **create** the files below in Phase 2.
+2. **Do not** hardcode PocketBase (or any tool) versions in ForgeTrail docs alone — resolve **latest at install** unless the user locked a version in `.env` (see **FORGETRAIL_LITE.md** §4.2.2).
+3. **Run** `pnpm install` and script creation yourself when possible; launchers are for **repeat** runs and non-agent operators.
+4. After every phase transition, refresh **`docs/FORGETRAIL_PROGRESS.md`** (or tell the user to double-click **status.bat**).
+
+---
+
+## Files to create at repo root (Phase 2)
+
+| File | Purpose |
+|------|---------|
+| `setup.bat` / `setup.sh` | First-time (or refresh) install — deps, PocketBase binary, optional schema |
+| `run.bat` / `run.sh` | Start PocketBase if needed + app dev server |
+| `status.bat` / `status.sh` | Print ForgeTrail phase + write `docs/FORGETRAIL_PROGRESS.md` |
+| `test-pocketbase.bat` / `.sh` | PocketBase health only (no app) — **`SYSTEM_HEALTH_CHECKS.md`** |
+| `setup-ollama.bat` / `.sh` | Install Ollama + pull VRAM-sized model (when local LLM) |
+| `test-ollama.bat` / `.sh` | Ollama version + one completion smoke test |
+| `scripts/forgetrail-dev-launcher.mjs` | Shared logic (copy from ForgeTrail upstream) |
+| `scripts/setup-pocketbase.mjs` | PB download with **latest** release resolution (if no `setup:pocketbase` yet) |
+| `scripts/test-pocketbase.mjs`, `scripts/setup-ollama.mjs`, `scripts/test-ollama.mjs` | Isolated service checks |
+| `docs/FORGETRAIL_PROGRESS.md` | Human-readable progress (template: **FORGETRAIL_PROGRESS.md**) |
+
+**`package.json` scripts (add):**
+
+```json
+"setup:pocketbase": "node scripts/setup-pocketbase.mjs",
+"forgetrail:status": "node scripts/forgetrail-dev-launcher.mjs status",
+"test:pocketbase": "node scripts/test-pocketbase.mjs",
+"setup:ollama": "node scripts/setup-ollama.mjs",
+"test:ollama": "node scripts/test-ollama.mjs"
+```
+
+---
+
+## Windows `setup.bat` (copy block)
+
+```bat
+@echo off
+cd /d "%~dp0"
+where node >nul 2>&1 || (echo Install Node.js LTS from https://nodejs.org/ && pause && exit /b 1)
+where npm >nul 2>&1 || (echo Reinstall Node.js LTS — npm should ship with Node && pause && exit /b 1)
+where pnpm >nul 2>&1 || (echo Run: corepack enable && corepack prepare pnpm@latest --activate   OR: npm install -g pnpm && pause && exit /b 1)
+node scripts/forgetrail-dev-launcher.mjs setup
+if errorlevel 1 pause
+```
+
+## Windows `run.bat`
+
+```bat
+@echo off
+cd /d "%~dp0"
+where node >nul 2>&1 || (echo Install Node.js from https://nodejs.org/ && pause && exit /b 1)
+node scripts/forgetrail-dev-launcher.mjs run
+pause
+```
+
+## Windows `status.bat`
+
+```bat
+@echo off
+cd /d "%~dp0"
+node scripts/forgetrail-dev-launcher.mjs status
+pause
+```
+
+## Mac/Linux `setup.sh` / `run.sh` / `status.sh`
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")"
+command -v node >/dev/null || { echo "Install Node.js LTS from https://nodejs.org/"; exit 1; }
+command -v pnpm >/dev/null || { echo "Run: corepack enable && corepack prepare pnpm@latest --activate"; exit 1; }
+node scripts/forgetrail-dev-launcher.mjs "${1:-setup}"
+```
+
+Use `setup.sh`, `run.sh`, `status.sh` as thin wrappers calling `forgetrail-dev-launcher.mjs` with `setup`, `run`, or `status`. `chmod +x` all three.
+
+---
+
+## README block for non-technical users
+
+```markdown
+## Quick start (no terminal required)
+
+1. Install [Node.js LTS](https://nodejs.org/) once (includes **npm**; use it to enable **pnpm** via corepack or `npm install -g pnpm`).
+2. Copy `.env.example` → `.env` and fill in any passwords shown in the example.
+3. **First time:** double-click **setup.bat** (Windows) or run **setup.sh** (Mac/Linux).
+4. **Every day:** double-click **run.bat** / **run.sh** to start the app.
+5. **Where are we?** double-click **status.bat** / **status.sh** — also opens **docs/FORGETRAIL_PROGRESS.md**.
+
+### Troubleshooting (one service at a time)
+
+- **PocketBase:** double-click **test-pocketbase.bat**
+- **Local AI (Ollama):** run **setup-ollama.bat** once, then **test-ollama.bat**
+```
+
+## Windows `test-pocketbase.bat`
+
+```bat
+@echo off
+cd /d "%~dp0"
+node scripts/test-pocketbase.mjs
+if errorlevel 1 pause
+```
+
+## Windows `setup-ollama.bat` / `test-ollama.bat`
+
+```bat
+@echo off
+cd /d "%~dp0"
+node scripts/setup-ollama.mjs
+if errorlevel 1 pause
+```
+
+```bat
+@echo off
+cd /d "%~dp0"
+node scripts/test-ollama.mjs
+if errorlevel 1 pause
+```
+
+---
+
+## PocketBase version policy
+
+See **FORGETRAIL_LITE.md** §4.2.2 and **`SCAFFOLD_INSTALL.json`** (`versionPolicy`). Install scripts read `POCKETBASE_VERSION` from `.env`:
+
+- unset or `latest` → resolve from GitHub **releases/latest** at setup time
+- `0.26.2` (example) → pin that release; record in `decisions[]` when the user confirms a good boot
+
+Never ship a stale semver only in methodology docs without an env override path.