forgetrail 0.3.0

package/content/AGENT_INTEGRATION_claude.md

@@ -0,0 +1,38 @@
+# ForgeTrail Integration Guide for Claude Code / Claude agents
+
+Claude-based coding agents integrate with ForgeTrail through MCP, extended planning discipline, and optional parallel workers (where the host exposes them).
+
+## Primitives → ForgeTrail
+
+| Capability | ForgeTrail use |
+|------------|--------------|
+| ForgeTrail MCP | `getNewProjectKickoff`, `getPhaseGuidance`, `runAudit`, `searchLessons`, `validateTracking` |
+| Extended planning / "plan before code" | Phase 1 — produce a reviewable plan artifact; lock `PHASE_1_BRIEF.md` before scaffolding (`getPlanModePatterns`) |
+| gstack slash commands (optional) | Sprint execution inside phases — see WORKFLOW §1b; persist outcomes in tracking |
+| Subagents / agent teams (when available) | Parallel audits and research — `suggestSubagentDecomposition` |
+| Project `CLAUDE.md` / `AGENTS.md` | Trailer-ban + methodology pointers from kickoff `.forgetrail/` copies |
+
+## Session openers
+
+**New project:**
+```
+Call ForgeTrail getNewProjectKickoff, write .forgetrail/workflow_tracking.json, getGreenfieldIntakePrompt, getPhaseGuidance("1").
+No app code until PHASE_1_BRIEF.md is locked.
+```
+
+**Resume:**
+```
+getResumeSessionInstructions → read tracking + CONTEXT_PROMPT → continue current phase.
+```
+
+## gstack + ForgeTrail
+
+If [gstack](https://github.com/garrytan/gstack) is installed, use WORKFLOW §1b: gstack for inner-loop build/review/QA/ship; ForgeTrail for phase state and durable docs. After every gstack sprint, update tracking.
+
+## Subagents
+
+Call **`suggestSubagentDecomposition`** before spawning workers. Phase 7: parallel security, UX, and code-quality analysis; parent writes audit docs. Phase 4: parallel research subagents; parent picks approach and implements.
+
+## Tracking
+
+Run **`validateTracking`** after sessions. Log decisions with rationale in Phase 1 for cold-start Phase 2.

package/content/AGENT_INTEGRATION_cursor.md

@@ -0,0 +1,53 @@
+# ForgeTrail Integration Guide for Cursor
+
+Cursor agents (Composer, Agent mode) map well to ForgeTrail via MCP, **Cursor rules**, optional **subagents** (Task tool), and **Plan mode**.
+
+## Primitives → ForgeTrail
+
+| Cursor capability | ForgeTrail use |
+|-------------------|--------------|
+| ForgeTrail MCP tools | Methodology delivery — `getNewProjectKickoff`, `getPhaseGuidance`, `runAudit`, `validateTracking`, etc. |
+| `.cursor/rules/*.mdc` | Persistent phase + lessons discipline from kickoff (`forgetrail-phase-status`, `forgetrail-lessons-gate`, `forgetrail-lessons-mcp`) |
+| Plan mode (`SwitchMode` / plan) | Phase 1 architecture — explore before edits; export to `PHASE_1_BRIEF.md` on approval (`getPlanModePatterns`) |
+| Task / subagents (`explore`, `generalPurpose`, `shell`) | Parallel audits (Phase 7), research (Phase 4), spikes (Phase 5) — call `suggestSubagentDecomposition` first |
+| TodoWrite | Mirror open exit criteria from tracking (visible next actions) |
+
+## Recommended session openers
+
+**New project:**
+```
+Call ForgeTrail getNewProjectKickoff (includeCursorRule true), write .forgetrail/ and .cursor/rules/, then getPhaseGuidance("1").
+Use plan mode for Phase 1 if available. Lock PHASE_1_BRIEF.md before scaffolding.
+```
+
+**Resume:**
+```
+Call getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md.
+```
+
+## Subagent patterns
+
+**Phase 7 example:**
+```
+Call suggestSubagentDecomposition for phase 7 and task "black-hat, UX cohesion, code quality audits".
+
+Launch parallel explore subagents (readonly) for each audit type using runAudit + searchLessons.
+Parent synthesizes BLACK_HAT_REPORT.md and CODE_QUALITY.md, updates tracking gotchas/decisions.
+```
+
+Use `run_in_background` for long subagents when appropriate.
+
+## Tracking sync
+
+After subagent or feature work:
+- Update `.forgetrail/workflow_tracking.json` (exit criteria, decisions, gotchas, sessions).
+- Run **`validateTracking`**.
+- Update `CONTEXT_PROMPT.md` when architecture or patterns change.
+
+## Skills alternative
+
+Cursor users typically rely on **rules** from kickoff rather than Grok-style skills. Optional: add **`getForgeTrailSkill`** content as a global Cursor skill if your workflow supports it.
+
+## MCP setup
+
+Register the ForgeTrail MCP server in Cursor settings with `FORGETRAIL_ROOT` pointing at the ForgeTrail repo. Reconnect after server updates so new tools appear.

package/content/AGENT_INTEGRATION_generic.md

@@ -0,0 +1,50 @@
+# ForgeTrail Integration Guide (generic agents)
+
+Use this when no agent-specific guide is available. ForgeTrail is **agent-agnostic** — the lifecycle, tracking file, and MCP tools work with any capable coding agent.
+
+## Core integration model
+
+| Layer | Responsibility |
+|-------|----------------|
+| **ForgeTrail** | 7-phase lifecycle, `.forgetrail/workflow_tracking.json`, progressive docs, audits, lessons |
+| **Host agent** | Tool use, file edits, terminal, optional subagents/plan modes |
+
+ForgeTrail owns **what** and **when**. The host agent owns **execution**.
+
+## Session openers
+
+**New project:**
+```
+Call ForgeTrail getNewProjectKickoff, write .forgetrail/workflow_tracking.json, then getPhaseGuidance("1").
+Lock architecture in docs/PHASE_1_BRIEF.md before any app code.
+```
+
+**Resume:**
+```
+Call getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md.
+Continue from currentPhase.
+```
+
+## When the host supports subagents
+
+1. Call **`suggestSubagentDecomposition`** with phase + task.
+2. Spawn parallel workers for audits (Phase 7), research (Phase 4), or spikes (Phase 5).
+3. Parent synthesizes into ForgeTrail docs and updates tracking.
+
+Prefer **read-only** subagents for analysis; parent or a single write-capable worker for implementation.
+
+## When the host supports plan mode
+
+Use native plan mode for **Phase 1** only. On approval, export to `PHASE_1_BRIEF.md` + `decisions[]`. See **`getPlanModePatterns`**.
+
+## Persistent discipline
+
+- Install **`.cursor/rules/`** from kickoff (Cursor), or copy **`getForgeTrailSkill`** output to your agent's skill directory (Grok, etc.).
+- Call **`validateTracking`** after substantive work.
+- Call **`getAntiPatterns`** + **`searchLessons`** before large feature work.
+
+## MCP registration
+
+Point `FORGETRAIL_ROOT` at the ForgeTrail repo root. Run `mcp-server/dist/index.js` via stdio. Tools include `getPhaseGuidance`, `getTemplate`, `runAudit`, `validateTracking`, `suggestSubagentDecomposition`, and `getAgentIntegrationGuide`.
+
+Call **`getAgentIntegrationGuide({ agent: "grok" })`** (or `cursor`, `claude`) when using a supported host for tailored syntax.

package/content/AGENT_INTEGRATION_grok.md

@@ -0,0 +1,82 @@
+# ForgeTrail Integration Guide for Grok Build
+
+Grok Build (the agentic TUI/CLI from xAI) has excellent native primitives that map extremely well to ForgeTrail. Treat ForgeTrail as the **lifecycle + persistent memory layer** and Grok primitives as the **execution engine**.
+
+## Key Grok Primitives and ForgeTrail Mapping
+
+| Grok Primitive              | ForgeTrail Phase(s)          | How to Use |
+|-----------------------------|----------------------------|------------|
+| `/plan` + enter/exit_plan_mode + plan.md | Phase 1 (Architecture)    | Use native plan mode for all Phase 1 work. On approval, export to `PHASE_1_BRIEF.md` + `decisions[]`. See `PLAN_MODE_PATTERNS.md`. |
+| `spawn_subagent` (explore/plan/general, capability_mode, isolation: worktree, background, resume_from, personas) | All phases, especially 4, 5, 7 | Use for parallel audits (black-hat, UX, code quality), research, stabilize debugging, and exploratory spikes. Call `suggestSubagentDecomposition` first. Prefer read-only for analysis subagents. |
+| `todo_write` + TODO panel   | All phases                 | Mirror open exit criteria and next actions from `.forgetrail/workflow_tracking.json`. Use as the visible "what's next" while tracking.json is the durable record. |
+| Skills (`/create-skill`, SKILL.md) | All sessions             | Install the `forgetrail` skill (see `SKILL.md` in content/skills/forgetrail). It keeps phase discipline, tracking rules, and subagent patterns always active. |
+| Native MCP (search_tool + use_tool) | Methodology delivery    | Register the ForgeTrail MCP server. Tools appear as `forgetrail__*`. Use `getNewProjectKickoff`, `getPhaseGuidance`, `runAudit`, `searchLessons`, `validateTracking`, etc. |
+| Headless (`grok -p ... --output-format json`) | Automation / CI       | Call kickoff/resume tools and have the agent produce structured phase state. Add exit-criteria validation in pipelines. |
+| `docx` / `pptx` / `xlsx` skills + image/video gen | Phase 1 intake, Phase 6/7 deliverables | Use for exports (PDF/DOCX/PPTX), landing pages, brand assets, and marketing materials called out in greenfield intake. |
+| Sessions + memory + AGENTS.md | Cross-session continuity | `.forgetrail/workflow_tracking.json` + `CONTEXT_PROMPT.md` are the ForgeTrail equivalents. Update them at session end. |
+
+## Recommended Session Openers in Grok
+
+For a new project:
+```
+Call ForgeTrail getNewProjectKickoff (includeCursorRule false), write the tracking file, then start Phase 1 using native /plan mode. Read the generated plan on approval and produce PHASE_1_BRIEF.md + decisions.
+```
+
+For resuming:
+```
+Call ForgeTrail getResumeSessionInstructions. Read .forgetrail/workflow_tracking.json and CONTEXT_PROMPT.md. Continue from current phase.
+```
+
+## Subagent Patterns (Grok-specific)
+
+Example for Phase 7 Hardening:
+```
+Use suggestSubagentDecomposition for "black-hat security audit, UX cohesion review, and code quality audit of the current codebase".
+
+Then spawn three subagents in parallel:
+1. subagent_type: "explore", capability_mode: "read-only", persona: security-auditor, prompt: "Run the black-hat audit prompt from runAudit and searchLessons for security issues."
+2. Similar for ux-cohesion and code-quality.
+
+Main thread: synthesize results into BLACK_HAT_REPORT.md + CODE_QUALITY.md, update tracking gotchas/decisions, and present prioritized TODO items to user.
+```
+
+Use `background: true` for long-running subagents and retrieve with `get_command_or_subagent_output`.
+
+## Tracking Sync
+
+After meaningful work (especially subagent results or feature completion):
+- Update `.forgetrail/workflow_tracking.json` (exit criteria, decisions, gotchas, sessions).
+- Use `todo_write` to surface the next 3–5 open items from the tracking file.
+- Update `CONTEXT_PROMPT.md` when patterns or architecture change.
+
+## Skills Usage
+
+Install the forgetrail skill (copy from content/skills/forgetrail/SKILL.md to ~/.grok/skills/forgetrail/SKILL.md).
+
+Then simply say things like:
+- "/forgetrail kickoff new project"
+- "Use forgetrail discipline for this feature"
+
+The skill will remind you of phases, tracking, subagents, etc.
+
+## Headless / Automation Tips
+
+```bash
+grok -p "Call ForgeTrail getNewProjectKickoff and set up the project per the bundle. Then begin Phase 1." --output-format json --always-approve
+```
+
+Parse the JSON and continue sessions with `--resume` or named `--session-id`.
+
+## Dogfooding ForgeTrail on ForgeTrail
+
+Use this very repo as a test case. Run a full cycle or slices with Grok Build + the local MCP server registered. Capture results back into `specs/canonical/forgetrail-modern-agents-evolution.md`.
+
+## Registration (local dev)
+
+```bash
+grok mcp add forgetrail -- node "Z:\workspace\forgetrail\mcp-server\dist\index.js" --env FORGETRAIL_ROOT="Z:\workspace\forgetrail"
+```
+
+Or via `~/.grok/config.toml` under `[mcp_servers.forgetrail]`.
+
+After registration, tools are discoverable via the normal MCP search/use flow in Grok.

package/content/DEV_AUTOMATION_SCRIPTS.md

@@ -0,0 +1,103 @@
+# Dev automation scripts (app repo)
+
+Use **small `pnpm` scripts** (backed by files under `scripts/` when needed) so new contributors and future you don’t rely on memory, long READMEs, or dozens of IDE clicks. Prefer **idempotent** commands (safe to run twice).
+
+This guide lists **strong defaults** for a typical full-stack app. Names are examples—align with your stack.
+
+---
+
+## 1. Env readiness — `pnpm run env:check` (or `doctor`)
+
+**Problem:** “App won’t start” because a variable is missing or misnamed.
+
+**Script:** Read required keys from a single source of truth (e.g. list in `scripts/check-env.ts`, or parse `.env.example` for keys without default values). Exit **non-zero** if something required is missing. **Do not** print secret values—only names of missing vars.
+
+**User flow:** Copy `.env.example` → `.env`, fill secrets, run `pnpm run env:check` before `pnpm run dev`.
+
+---
+
+## 2. Generated types / API client — `pnpm run gen:types`
+
+**Problem:** Hand-written types drift from PocketBase collections, OpenAPI, or GraphQL.
+
+**Script:** Regenerate TypeScript types (or a thin client) from the real schema: PocketBase export, `openapi-typescript`, codegen, etc. Commit generated files or gitignore + CI generate—pick one policy and document it in **`README.md`**.
+
+**User flow:** After schema changes, run `pnpm run gen:types` (and commit if applicable).
+
+---
+
+## 3. Seed / fixture data — `pnpm run db:seed`
+
+**Problem:** Empty DB makes every demo “first create records by hand in the admin UI.”
+
+**Script:** Idempotent seed using the **same auth path** the app uses (user token) or admin API for dev only. Guard with `NODE_ENV=development` or an explicit `--force` so production never runs it by accident.
+
+**User flow:** After migrations/schema apply, `pnpm run db:seed` for local demo data.
+
+---
+
+## 4. End-to-end test browsers — `pnpm run test:e2e:install` (or postinstall)
+
+**Problem:** First `pnpm run test:e2e` fails with “install Playwright browsers.”
+
+**Script:** `pnpm exec playwright install` (or `playwright install --with-deps` on CI). Optionally wire **`pnpm run test:e2e`** to depend on install, or document **`pnpm run test:e2e:install`** once per machine.
+
+**User flow:** One command after clone or when Playwright upgrades.
+
+---
+
+## 5. Git hooks (lint/format on commit) — `pnpm prepare` + Husky (or similar)
+
+**Problem:** CI catches style issues late; contributors forget to run lint.
+
+**Script:** `pnpm prepare` runs `husky` install; `.husky/pre-commit` runs `lint-staged` or `pnpm run lint`. Keep it **fast** so people don’t `--no-verify` habitually.
+
+**User flow:** `pnpm install` once; hooks activate automatically.
+
+---
+
+## PocketBase-specific (already separate)
+
+Collection/schema apply from **`.env` admin credentials** is covered in **`POCKETBASE_SCHEMA_SCRIPT.md`** — combine with the above: bootstrap binary → schema script → env check → dev.
+
+**Isolated check:** `pnpm run test:pocketbase` or **test-pocketbase.bat** — see **`SYSTEM_HEALTH_CHECKS.md`**.
+
+---
+
+## Ollama (local LLM — runtime or build-time seed)
+
+When the brief uses **runtime LLM API** or **build-time LLM generation** with Ollama (see **FORGETRAIL_LITE** §7.1, README “LLM-backed content”):
+
+| Script | Purpose |
+|--------|---------|
+| `pnpm run setup:ollama` | Install Ollama if missing, detect VRAM, pull Granite 4.1 / Gemma 3 (non-thinking default) |
+| `pnpm run test:ollama` | Version + one completion — proves inference works |
+
+**`.env`:** `OLLAMA_BASE_URL`, `OLLAMA_MODEL`. Use **`OLLAMA_USE_THINKING=1`** only when the product needs reasoning models. See **FORGETRAIL_LITE.md** §4.8.
+
+---
+
+## 0. One-click launchers (non-technical operators)
+
+Before the terminal-heavy block below, agents should create **setup.bat** / **setup.sh**, **run.bat** / **run.sh**, **status.bat** / **status.sh** per **`ONE_CLICK_DEV_SETUP.md`** and **FORGETRAIL_LITE.md** §4.5–§4.6.
+
+**README “Quick start (no terminal)”** — three double-clicks: setup → run → status.
+
+---
+
+## README pattern (terminal / agents)
+
+Document a **single “first time” block** for contributors who prefer the shell:
+
+1. `cp .env.example .env` and fill values  
+2. `pnpm install`  
+3. `pnpm run setup:pocketbase` (or double-click **setup.bat** — resolves **latest** PocketBase unless `POCKETBASE_VERSION` is pinned)  
+4. `pnpm run pocketbase:schema` (if applicable)  
+5. `pnpm run env:check`  
+6. `pnpm run db:seed` (optional)  
+7. `pnpm run dev` (or **run.bat**)  
+8. `pnpm run forgetrail:status` — phase progress  
+9. `pnpm run test:pocketbase` — PocketBase only (troubleshooting)  
+10. `pnpm run setup:ollama` → `pnpm run test:ollama` — when local LLM is in scope  
+
+Adjust order to match your stack; link to **`ONE_CLICK_DEV_SETUP.md`**, **`SYSTEM_HEALTH_CHECKS.md`**, **`POCKETBASE_SCHEMA_SCRIPT.md`**, and **`FORGETRAIL_LITE.md`** §4.2.2–§4.8 from **`CONTEXT_PROMPT.md`** so agents don’t invent one-off instructions or hardcode old PocketBase versions.