forgetrail 0.3.0

package/CONTINUATION_PROMPT.md

@@ -0,0 +1,42 @@
+> **App projects only.** Paste this file into a coding-agent chat to **resume an app** that already uses ForgeTrail.
+> If you are working in the **ForgeTrail methodology repo** itself, stop and read `RESUME.md` (and `TODO.md`). Do not follow the steps below here.
+
+## Instructions
+
+I'm continuing work on [APP NAME]. You are following ForgeTrail, a structured phase-based development workflow. Your job is to track progress and pause at phase transitions for my approval before advancing.
+
+### MCP-first (no `_forgetrail/` in this repo)
+
+**Before doing anything else:**
+
+1. Call ForgeTrail MCP **`getResumeSessionInstructions`** and follow it.
+2. Read **`.forgetrail/workflow_tracking.json`**. If phase is **1-architecture**, read **`docs/PHASE_1_BRIEF.md`**. Otherwise read **`CONTEXT_PROMPT.md`** (if Phase 2+ but CONTEXT is missing and the brief exists, **merge the brief into CONTEXT** first per the CONTEXT_PROMPT template).
+3. Use **`getPhaseGuidance`** for the current phase, **`getTrackingSchema`** when updating tracking, and other ForgeTrail MCP tools as needed.
+
+### Local `_forgetrail/` folder
+
+> **Path note:** ForgeTrail files live in `_forgetrail/` by default. If the folder is elsewhere (e.g., a sibling `forgetrail/` directory), adjust paths accordingly.
+
+**Before doing anything else:**
+
+1. Read **`.forgetrail/workflow_tracking.json`** to see where we left off.
+2. Read `_forgetrail/WORKFLOW.md` for the full phase map, playbooks, and patterns.
+3. Read `_forgetrail/TRACKING_SCHEMA.md` to understand how to update the tracking file.
+4. Read `CONTEXT_PROMPT.md` for the current architecture and project state — or **`docs/PHASE_1_BRIEF.md`** if still in Phase 1; if Phase 2+ and CONTEXT is empty but the brief exists, merge brief → CONTEXT first.
+
+**Rules for this session:**
+
+- When you believe a phase's exit criteria are met, tell me explicitly: "I think we've completed [Phase X]. The exit criteria are met because [reasons]. Ready to move to [Phase Y]?" Wait for my confirmation.
+- After completing work, update **`.forgetrail/workflow_tracking.json`** following the structure in `_forgetrail/TRACKING_SCHEMA.md`: move satisfied exit criteria, add decisions to the `decisions` array (with rationale), log issues to the `gotchas` array, and add session notes.
+- Keep `CONTEXT_PROMPT.md` updated as the source of truth for project architecture.
+- If something isn't working after 5 turns, propose a fundamentally different approach rather than continuing to patch.
+
+---
+
+## Session Context
+
+**Last session we completed:** _______________
+
+**Today I want to focus on:** _______________
+
+**Any new context or changes since last session:** _______________

package/INITIAL_PROMPT.md

@@ -0,0 +1,214 @@
+> **App projects only.** Paste this file into a coding-agent chat to **start an app** that uses ForgeTrail.
+> If you are working in the **ForgeTrail methodology repo** itself, stop and read `RESUME.md` (and `TODO.md`). Do not follow the steps below here.
+
+## Instructions
+
+You are helping me build a full-stack web application. I use ForgeTrail, a structured phase-based development workflow refined across multiple projects. Your job is to follow this workflow, track progress, and pause at phase transitions for my approval before advancing.
+
+---
+
+### MCP-first (recommended — no `_forgetrail/` copy in this repo)
+
+If **ForgeTrail is connected as an MCP server**, do **not** require a local `_forgetrail/` folder. Methodology, templates, and audits stay in the MCP server (open-source ForgeTrail install); persist only **`.forgetrail/workflow_tracking.json`** and optional Cursor rules in this repo.
+
+**Before doing anything else:**
+
+0. If **`docs/GENESIS.md`** exists, call **`ingestPlanArtifact`** with its contents and review the draft brief before scaffolding. If the user only has an idea, offer **`getGenesisSpecPrompt`** (they save as `docs/GENESIS.md`) or point them at **TRY_FORGETRAIL.md** when MCP is not the entry path.
+1. Call the ForgeTrail MCP tool **`getNewProjectKickoff`** (set **`includeCursorRule`** to **false** if not using Cursor). Write **`.forgetrail/workflow_tracking.json`** and the Cursor rule when included; keep the **first reply to the user** short per the bundle’s post-bootstrap section (no MCP tool list or raw JSON dump). **Alternatively:** call **`getNewProjectBootstrap`**, **`getInitialWorkflowTracking`**, **`getPostBootstrapUserMessage`**, and **`getForgeTrailCursorPhaseRule`** separately.
+2. In Phase 1, call **`getGreenfieldIntakePrompt`** alongside **`getChecklist`** (`before-session-1`) so exports (PDF / DOCX / PPTX, etc.), tenancy (e.g. consultants × clients), hybrid vs full spec, compliance tier, and hero flow are captured early in **`PHASE_1_BRIEF.md`** and **`decisions[]`** (skip questions already answered in Genesis).
+3. Use **`getProgressiveDocSchedule`**, **`getPhaseGuidance`**, **`getChecklist`**, **`getTemplate`** (include **`PHASE_1_BRIEF`** in Phase 1; use `mode: "shell"` or `full` as needed), **`getTrackingSchema`**, **`runAudit`**, **`searchLessons`**, and **`getAntiPatterns`** as that bootstrap describes.
+4. We're starting with Phase 1 (Architecture + Planning).
+
+**Replies to me:** When presenting several options or a default order of work, follow ForgeTrail **`USER_REPLY_FORMAT.md`** (or MCP **`getUserReplyFormat`**): **numbered** lists for pipelines, **bullets** for parallel items, **letters** for pick-one—don’t bury multiple paths in one long sentence.
+
+**Phase 2 scaffolding (when you reach it):** If the stack includes **scripted PocketBase setup**, call **`getScaffoldInstallParams`** and align **`scripts/scaffold-defaults.json`** with the returned JSON — then have the user run **`pnpm install && pnpm run setup:pocketbase`** (or **`pnpm run bootstrap`**) **in the terminal** instead of generating many small files in the IDE. Put the **PocketBase HTTP port and public URL in `.env` / `.env.example`** (e.g. `PUBLIC_POCKETBASE_URL=http://127.0.0.1:8096`); the user may have **other PocketBase processes** (other projects) already on the default **8090**, so a fixed port in env keeps the `serve` script, the SvelteKit client, and schema scripts in sync. Prefer a **`pocketbase:schema`** (or similar) script that applies collections using **`POCKETBASE_ADMIN_EMAIL` / `POCKETBASE_ADMIN_PASSWORD`** from `.env` (see ForgeTrail **`POCKETBASE_SCHEMA_SCRIPT.md`** via the scaffold JSON **`schemaAutomation`** block) instead of manual Admin UI for each collection. For **repeatable dev setup** (env check, codegen, seed, E2E browsers, git hooks), follow ForgeTrail **`DEV_AUTOMATION_SCRIPTS.md`** and the **`devAutomation`** block in the same **`getScaffoldInstallParams`** output.
+
+**Optional — JSON seed/fixture data from any LLM:** The user can generate structured JSON in **another** LLM chat (or the same one), save it under e.g. `data/` or `fixtures/`, and ask you to validate and import. Use the copy-paste prompt in **`content/FORGETRAIL_LITE.md` §4.3** (template-in-repo: `_forgetrail/content/FORGETRAIL_LITE.md`); **validate** all such JSON at the boundary before writing to a DB.
+
+**Optional — web search (live data):** If the app needs **up-to-date web 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 — see vendor pricing), add the key to **`.env`**, and ask you to wire **server-side** calls only. **`FORGETRAIL_LITE.md` §4.4** has the full note; log provider choice in **`decisions[]`**.
+
+**Phase 1 — project archetype:** classify the project as **`product`** (default — full 7-phase lifecycle), **`internal-tool`** (Phase 6 optional; Phase 7 drops payments/business-plan/marketing criteria), or **`one-shot`** (gift / event / demo — phases 5–7 collapse into one polish-and-ship gate). Infer from my description and confirm rather than interrogate. Record in **`PHASE_1_BRIEF.md`**, **`decisions[]`**, and **`project.archetype`** in the tracking file; **prune** the non-applicable exit criteria from the tracking template and log the pruning as a decision. See **WORKFLOW.md §1d**. When the project **ends**, run the **wrap protocol** (WORKFLOW.md §1e): harvest `gotchas[]` + `decisions[]` for generalizable lessons, propagate them, set `project.status` to `"wrapped"`.
+
+**Phase 1 — state persistence (web apps):** before locking PocketBase + auth, ask me *"Does any state need to outlive this browser — accounts, cross-device sync, shared data — or is per-user state fine in `localStorage`?"* If **local-only**: drop PocketBase + auth, target `adapter-static`, no deploy-time secrets. If **persistent**: full Default-A stack. Record the answer in **`PHASE_1_BRIEF.md` §4 (`State persistence:`)** and **`decisions[]`**. See **`FORGETRAIL_LITE.md` §7** (A-local vs A-persistent).
+
+**Phase 1 — content-generation pattern (only if content is LLM-produced):** if any v1 content is produced by an LLM (rather than hand-authored or from a conventional non-LLM API), pick **one** of three patterns **before scaffolding** — it drives deploy model, cost, and secret management:
+
+- **Runtime LLM API** — server route calls the provider per request; rate limits + streaming UX; requires server runtime. **Cloud** (OpenAI, Anthropic, …): API key in `.env`. **Local Ollama:** `OLLAMA_BASE_URL` + `OLLAMA_MODEL` — Phase 2 adds **`setup-ollama`** / **`test-ollama`** (see **`SYSTEM_HEALTH_CHECKS.md`**, **`FORGETRAIL_LITE.md` §4.8**); default Granite 4.1 / Gemma 3, not thinking models unless I explicitly need them.
+- **Build-time LLM generation** — `pnpm run seed` calls the provider once, writes JSON into `data/`, commits it; zero runtime LLM cost; pairs with `adapter-static`. Seed may use cloud APIs or the same Ollama env.
+- **BYO-LLM paste** — prompt in the repo; I run it in any LLM chat (including local Ollama) and paste JSON into `data/seed.json`; Zod validates at app start; zero project-level API keys.
+
+Record pattern, provider (e.g. `ollama/ibm/granite4.1:8b`), env var names, paths, and validator in **`PHASE_1_BRIEF.md`** (content-generation section) and **`decisions[]`**. See **`FORGETRAIL_LITE.md` §7.1** for OpenAI, Ollama, seed, and BYO skeletons.
+
+**External listing/article URLs (if the hero flow imports from pasted URLs):** follow **`FORGETRAIL_LITE.md` §7.2** — layered fetch and parse, **don’t blame users** for correct URLs when selectors rot, optional **single** structured **verbatim** recover from stripped page text (env-gated). Expand into **`docs/TECHNICAL_REFERENCE.md`** using the ForgeTrail template subsection on deterministic extractors vs markup drift.
+
+**Git commits:** use `git commit -F <file>` or plain `-m`; no unrequested attribution trailers (`Made-with:`, `Co-Authored-By:`, etc.). **Git 2.32.0+** (2021) supports `--trailer` natively — not a compatibility problem on current Git. **Pre-2.32 only:** if commit fails with `unknown option 'trailer'`, use `bash -c "git commit -F path/to/msg.txt"` or upgrade Git. See **`FORGETRAIL_LITE.md` §8.9**.
+
+Skip the **“copy-paste paths”** section below unless we are using a **local** ForgeTrail folder.
+
+---
+
+### Local `_forgetrail/` folder (template-in-repo mode)
+
+> **Path note:** ForgeTrail files live in `_forgetrail/` by default. If you placed the folder elsewhere (e.g., a sibling `forgetrail/` directory), adjust paths accordingly.
+
+**Before doing anything else:**
+
+1. Read `_forgetrail/WORKFLOW.md` to understand the full phase map, playbooks, and patterns.
+2. Read `_forgetrail/TRACKING_SCHEMA.md` to understand the tracking file structure before updating it.
+3. Read **`.forgetrail/workflow_tracking.json`** to see current project state.
+4. If using **Cursor**, copy **`_forgetrail/content/cursor-rules/forgetrail-phase-status.mdc`** to **`.cursor/rules/forgetrail-phase-status.mdc`** (create folders if needed) so agents surface phase / next actions from `.forgetrail/workflow_tracking.json`.
+5. We're starting with Phase 1 (Architecture + Planning).
+
+**Rules for every session:**
+
+- At the start of each session, read `.forgetrail/workflow_tracking.json` and `CONTEXT_PROMPT.md` (if it exists).
+- When you believe a phase's exit criteria are met, tell me explicitly: "I think we've completed [Phase X]. The exit criteria are met because [reasons]. Ready to move to [Phase Y]?" Wait for my confirmation.
+- After completing work, update `.forgetrail/workflow_tracking.json` following the structure in `TRACKING_SCHEMA.md`: move satisfied exit criteria, add decisions to the `decisions` array (with rationale), log issues to the `gotchas` array, and add session notes.
+- During Phase 1, create and lock **`docs/PHASE_1_BRIEF.md`**; mirror major decisions in **`decisions[]`**.
+- When we create `CONTEXT_PROMPT.md` (Phase 2), **merge `PHASE_1_BRIEF.md` into it** first (see template), then keep it updated as the source of truth.
+- If something isn't working after 5 turns, propose a fundamentally different approach rather than continuing to patch.
+
+---
+
+## About This Project
+
+### What I'm Building
+
+**App name:** **\*\***\_\_\_**\*\***
+
+**One-sentence description:** **\*\***\_\_\_**\*\***
+
+**The problem it solves:** **\*\***\_\_\_**\*\***
+
+**Who it's for:** **\*\***\_\_\_**\*\***
+
+**The single most important workflow it must support (the "hero flow"):**
+
+---
+
+### What Exists Already
+
+_Delete any that don't apply._
+
+- **Existing data/content that needs importing:** **\*\***\_\_\_**\*\***
+- **Existing templates or assets:** **\*\***\_\_\_**\*\***
+- **Existing systems this replaces or integrates with:** **\*\***\_\_\_**\*\***
+- **Nothing. Greenfield project.**
+
+### Tech Stack
+
+_These are my defaults. Use them unless the project specifically demands something else, and if so, explain why._
+
+**Framework:** SvelteKit (Svelte 5)
+
+**Language:** TypeScript (strict, no implicit any)
+
+**Package manager:** pnpm
+
+**Styling:** Tailwind CSS
+
+**Icons:** Iconify (@iconify/svelte) with Lucide icon set. No emoji in UI.
+
+**Database/Authentication/File Storage:** PocketBase
+
+**AI/LLM integration:** Claude API via @anthropic-ai/sdk _(or note deviation)_
+
+**Deployment:** DigitalOcean + GitHub Actions + Caddy reverse proxy
+
+**Deviations from defaults (if any):**
+
+---
+
+**Additional dependencies or constraints:**
+
+---
+
+### Code Conventions
+
+_These apply to every project. Claude should follow these without being reminded._
+
+- Create a `config.ts` to centralize all hardcoded values (app name, file conventions, brand colors, etc.). One edit, one place.
+- Consolidate shared constants (status color maps, enums) into type files with both Tailwind classes and hex values. Import everywhere, duplicate nowhere.
+- Custom SVG favicon, never emoji.
+- API error responses must include actual error details (paths, messages, context), not just status codes or counts.
+- Server modules in `src/lib/server/`, API routes in `src/routes/api/`, components in `src/lib/components/`, types in `src/lib/types/`.
+
+### Aesthetic Direction
+
+_Defaults below. Override per-project as needed._
+
+- Dark theme by default, with light mode toggle
+- Clean, functional UI. No component library; build custom with Tailwind.
+- Empty states should have personality, not just "No items found."
+
+**Additional aesthetic notes for this project:**
+
+---
+
+### V1 Scope Boundaries
+
+**Must have for v1:**
+
+- ***
+- ***
+- ***
+
+**Explicitly NOT in v1:**
+
+- ***
+- ***
+
+**Constraints:**
+
+---
+
+---
+
+## First Session: What Should Happen
+
+Phase 1 (Architecture + Planning):
+
+- Summarize your understanding of the project and make suggestions before building anything.
+- Propose: folder structure, data model, tech choices, migration path for existing data (if any).
+- Identify the hardest integration points.
+- Recommend what to skip for v1.
+- Wait for my confirmation on every architectural decision.
+- Create **`docs/PHASE_1_BRIEF.md`** from the ForgeTrail template (`_forgetrail/docs/` or MCP **`getTemplate("PHASE_1_BRIEF")`**). Fill and **lock** it before we exit Phase 1.
+- Record major commitments in **`.forgetrail/workflow_tracking.json`** → **`decisions[]`** (and phase notes) so the next session does not depend on chat history.
+
+Phase 2 (Scaffolding + Core Build):
+
+- Only after I've confirmed the architecture and the brief is locked.
+- Read **`PHASE_1_BRIEF.md`** and **`.forgetrail/workflow_tracking.json`** first.
+- Build the **entire app skeleton in one pass**: project init, dependencies, services, routes, components — **do not defer the runnable spine or hero flow**.
+- Include an import script if there's existing data.
+- Wire up the hero flow end to end.
+- Create `.env.example`, `.gitignore`.
+- **Documentation (progressive — see WORKFLOW.md §1a or ForgeTrail MCP `getProgressiveDocSchedule`):** In Phase 2, create **only** these four from ForgeTrail templates — **either** copy from `_forgetrail/docs/` **or** use MCP **`getTemplate`** (`CONTEXT_PROMPT`, `README`, `TODO`, `IDEAS`):
+  - `CONTEXT_PROMPT.md` — **merge content from `PHASE_1_BRIEF.md`** into the appropriate sections using the “Handoff from Phase 1” table in the template, then add patterns as needed.
+  - `README.md` (setup instructions)
+  - `TODO.md` (initial backlog; seed from brief §11)
+  - `.forgetrail/IDEAS.md` (parking lot — capture ideas here instead of cluttering the backlog)
+- **Do not** create the rest of the ForgeTrail doc library in Phase 2 (e.g. `BRAND_AND_PRODUCT`, `CODE_QUALITY`, `DEPLOYMENT`) unless I explicitly need one to finish the spine. Add other templates **in later phases** when that work starts (`TECHNICAL_REFERENCE`, `TEST_PLAN`, `DESIGN_SYSTEM` in Phase 4+ as warranted; brand/strategy docs in Phase 6; hardening docs in Phase 7). Phase 6 may add an optional internal **`FEATURE_CATALOG.md`** and periodic **`user-facing-content-sync-audit`** when the product map is large.
+- Reusable audit prompts: `_forgetrail/prompts/` **or** ForgeTrail MCP **`runAudit`** (security, pre-launch, docs alignment, user-facing content sync, brand copy, landing page, Cialdini, competitor, propagate-to-forgetrail, engineering-skill-library).
+
+Then pause and ask if I want to continue to Phase 3 (Bug Fixing + Environment Stabilization).
+
+---
+
+## Phase Transition Reference
+
+Quick reference for when you're deciding whether to approve a phase transition:
+
+| From              | To                | You should feel...                                                         |
+| ----------------- | ----------------- | -------------------------------------------------------------------------- |
+| Architecture      | Scaffolding       | Confident in tech choices, data model, and folder structure                |
+| Scaffolding       | Stabilization     | App runs, shows real data, hero flow works roughly                         |
+| Stabilization     | Feature Iteration | Core workflow completes without infrastructure errors                      |
+| Feature Iteration | Strategic Review  | Core features are functionally complete, TODO has 20+ items                |
+| Feature Iteration | Refactoring       | A file exceeds ~500 lines, or you're editing the same pattern in 3+ places |
+| Refactoring       | Feature Iteration | Build passes, no stale references, shared utilities extracted              |
+| Strategic Review  | Feature Iteration | TODO is reorganized by priority, you know what to build next               |
+| Any phase         | Hardening         | Features are stable, you're thinking about other people using it           |
+
+**Note:** Phases 4 (Feature Iteration) and 5 (Refactoring) commonly alternate. A typical path: 4 -> 5 -> 4 -> 6 -> 4 -> 7. This is normal, not a sign of problems.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works, within the Source form or
+          documentation, if provided along with the Derivative Works, or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Catalyst Forge, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,198 @@
+# ForgeTrail
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/forgetrail.svg)](https://www.npmjs.com/package/forgetrail)
+[![npm mcp](https://img.shields.io/npm/v/forgetrail-mcp.svg?label=forgetrail-mcp)](https://www.npmjs.com/package/forgetrail-mcp)
+
+**Forge the path. Keep the trail.**
+
+A persistent development system for building software with AI agents.
+
+**ForgeTrail** gives solo developers (and small teams) a 7-phase playbook so agents plan before they build, keep the trail of decisions across sessions, and leave structured knowledge that improves the next project.
+
+**Who it is for:** builders using Cursor, Claude Code, Codex, or similar agents who want structure without a heavyweight process.
+
+**Why it works:** phases with exit criteria, a live `.forgetrail/workflow_tracking.json`, and templates pre-loaded with production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work can follow.
+
+**Try it now (no MCP):** [TRY_FORGETRAIL.md](TRY_FORGETRAIL.md): write a `docs/GENESIS.md` in any AI chat, drop in ForgeTrail Lite, paste one kickoff line into your coding agent.
+
+Site: [forgetrail.dev](https://forgetrail.dev). Open source under [Apache License 2.0](LICENSE). Distilled from [Exec Foundry](https://execfoundry.com) and refined across about a dozen further projects. Built by [Catalyst Forge](https://catalystforge.com).
+
+---
+
+## Quickstart (ranked)
+
+### 1. Try (no MCP): start here
+
+Follow **[TRY_FORGETRAIL.md](TRY_FORGETRAIL.md)** (~15 minutes of setup, plus time to iterate your spec):
+
+1. Paste the [Genesis prompt](content/GENESIS_SPEC_PROMPT.md) into ChatGPT, Claude, Grok, or a local Ollama UI.
+2. Save the result as `docs/GENESIS.md` in a **new empty project folder**.
+3. Add [ForgeTrail Lite](content/FORGETRAIL_LITE.md) as `.forgetrail/FORGETRAIL_LITE.md`. If you have Node 20+: `npx forgetrail install --lite --with-genesis-stub`.
+4. Paste the kickoff line from TRY_FORGETRAIL.md into your coding agent. Approve the Phase 1 brief before any scaffold.
+
+Optional shape reference (fiction): [Mars habitat duty roster](content/examples/GENESIS_SAMPLE_mars-habitat-roster.md).
+
+Stuck? Use the [Try ForgeTrail checklist](https://github.com/Catalyst-Forge-LLC/forgetrail/issues/new?template=try-forgetrail-checklist.md) issue template.
+
+### 2. MCP (Cursor / Claude power users)
+
+Installer and MCP bins are on npm. This is a channel, not a library: do not add `forgetrail` to an app’s `dependencies`.
+
+```json
+{
+  "mcpServers": {
+    "forgetrail": {
+      "command": "npx",
+      "args": ["-y", "forgetrail-mcp"],
+      "env": {
+        "FORGETRAIL_ROOT": "/absolute/path/to/forgetrail-or-node_modules/forgetrail"
+      }
+    }
+  }
+}
+```
+
+If `forgetrail` is installed in the same tree as the MCP package, you can omit `FORGETRAIL_ROOT`. From a clone instead: `pnpm run mcp:build`. Details: [mcp-server/README.md](mcp-server/README.md).
+
+First chat: *"Call `getNewProjectKickoff` and set up the project."* Resume later with *"Call `getResumeSessionInstructions`."*
+
+### 3. Full / vendored methodology
+
+Need the whole template tree on disk (offline, no MCP):
+
+```bash
+npx forgetrail install --lite --with-genesis-stub
+npx forgetrail install
+```
+
+From a clone: `pnpm run link:global`, then the same `forgetrail install` commands. Or copy this repo into the app as `_forgetrail/` and use [INITIAL_PROMPT.md](INITIAL_PROMPT.md).
+
+**Graduation:** Try (copy Lite) → `npx forgetrail install --lite` → `npx -y forgetrail-mcp` → full `_forgetrail/` only when you need vendored templates. Details in [TRY_FORGETRAIL.md](TRY_FORGETRAIL.md).
+
+---
+
+## The 7 phases (short)
+
+| Phase | Name | What happens |
+| ----- | ---- | ------------ |
+| 1 | **Plan** | Lock architecture in `PHASE_1_BRIEF.md` before code |
+| 2 | **Build** | Full runnable spine in one pass |
+| 3 | **Stabilize** | Env, paths, auth: make the foundation solid |
+| 4 | **Iterate** | Feature by feature with real data |
+| 5 | **Refine** | Systematic cleanup before complexity owns you |
+| 6 | **Align** | Cut what does not serve the product vision |
+| 7 | **Harden** | Security, performance, production docs |
+
+Phases 4 and 5 often alternate. Full playbooks: [WORKFLOW.md](WORKFLOW.md). Docs arrive progressively (brief first; no empty boilerplate day one).
+
+---
+
+## Why ForgeTrail
+
+Most AI chats forget. ForgeTrail keeps **phase state**, **decisions**, and **gotchas** in the repo, and leaves a trail of lessons the next build can follow via [prompts/propagate-to-forgetrail.md](prompts/propagate-to-forgetrail.md) ([update-log.md](update-log.md)).
+
+| Framework | Core idea | Where ForgeTrail differs |
+|-----------|-----------|------------------------|
+| **GitHub Spec Kit** | Gated specify → plan → tasks | Templates arrive **pre-loaded with production lessons** and keep absorbing new ones |
+| **BMAD-Method** | Many agent personas | One developer + one agent; invests in **lifecycle memory**, not persona breadth |
+| **OpenSpec** | Change deltas in an existing repo | Complementary: OpenSpec for changes; ForgeTrail for the **whole product lifecycle** |
+| **Per-project retros** | Lessons in one repo's instruction file | ForgeTrail propagation is **cross-project** |
+
+ForgeTrail earns its weight when you build **repeatedly**. For a single gated change, Spec Kit or OpenSpec may be enough.
+
+---
+
+## How to use it (deeper)
+
+### MCP details
+
+The MCP server exposes methodology to Cursor, Claude Desktop, Claude Code, Windsurf, and other MCP clients without copying ForgeTrail into the app repo.
+
+1. Enable the server ([mcp-server/README.md](mcp-server/README.md)).
+2. Call `getNewProjectKickoff` (or use Genesis + `ingestPlanArtifact` if you already have `docs/GENESIS.md`).
+3. In Phase 1, use `getGreenfieldIntakePrompt` with `getChecklist(before-session-1)` for exports, tenancy, compliance, and hero flow.
+4. Your app repo keeps **your code**, **your docs**, and **`.forgetrail/workflow_tracking.json`**.
+
+### Template-in-repo
+
+1. Copy this folder as `_forgetrail/` (or keep it as a sibling and adjust paths in `INITIAL_PROMPT.md`).
+2. Paste `INITIAL_PROMPT.md` into the first agent chat; fill bracketed placeholders.
+3. Resume later with `CONTINUATION_PROMPT.md`.
+
+### Optional patterns (when your brief needs them)
+
+- **Seed / fixture JSON from any LLM:** [FORGETRAIL_LITE.md](content/FORGETRAIL_LITE.md) §4.3; also WORKFLOW.md Phase 2.
+- **Live web search (Tavily, Brave, …):** [FORGETRAIL_LITE.md](content/FORGETRAIL_LITE.md) §4.4.
+- **LLM-backed content (runtime / build-time / BYO-LLM):** [FORGETRAIL_LITE.md](content/FORGETRAIL_LITE.md) §7.1; local Ollama: §4.8 and [SYSTEM_HEALTH_CHECKS.md](content/SYSTEM_HEALTH_CHECKS.md).
+- **URL import / markup drift:** Lite §7.2; [docs/TECHNICAL_REFERENCE.md](docs/TECHNICAL_REFERENCE.md).
+- **Web app state: local vs accounts:** Lite §7 (A-local vs A-persistent).
+- **Local PocketBase:** port in `.env`; version at install ([ONE_CLICK_DEV_SETUP.md](content/ONE_CLICK_DEV_SETUP.md)).
+- **gstack:** ForgeTrail owns lifecycle; gstack owns sprint skills. WORKFLOW.md §1b.
+- **Propagate lessons back:** [prompts/propagate-to-forgetrail.md](prompts/propagate-to-forgetrail.md); wrap protocol in WORKFLOW.md §1e.
+
+---
+
+## What your project looks like
+
+After Phase 2, a typical app repo:
+
+```
+my-app/
+  .forgetrail/
+    workflow_tracking.json   ← Live progress (AI-updated)
+    FORGETRAIL_LITE.md         ← If you used the Try / Lite path
+    IDEAS.md
+  CONTEXT_PROMPT.md
+  docs/
+    GENESIS.md               ← Optional pre-Phase-1 "what, not how" spec
+    PHASE_1_BRIEF.md
+  README.md
+  TODO.md
+  src/
+```
+
+Later phases add docs only when needed (`TECHNICAL_REFERENCE`, `DESIGN_SYSTEM`, `BRAND_AND_PRODUCT`, hardening docs, …).
+
+---
+
+## What's in the box
+
+```
+forgetrail/                  ← clone folder; product name is ForgeTrail
+  RESUME.md                ← Resume *this* methodology repo (not an app)
+  TRY_FORGETRAIL.md          ← Human prove-it path (start here)
+  WORKFLOW.md              ← 7-phase lifecycle
+  INITIAL_PROMPT.md        ← App starter prompt (do not use on this repo)
+  CONTINUATION_PROMPT.md   ← App resume prompt (do not use on this repo)
+  site/                    ← forgetrail.dev (FilePress + Wrangler)
+  TRACKING_SCHEMA.md
+  update-log.md
+  content/
+    GENESIS_SPEC_PROMPT.md ← Paste into any LLM chat
+    FORGETRAIL_LITE.md       ← Portable single-file protocol
+    examples/              ← Sample Genesis (Mars roster, fiction)
+  docs/                    ← Phase templates (brief, SPEC_FEATURE_TEMPLATE, audits, …)
+  prompts/                 ← Audits, marketing, propagate-to-forgetrail, …
+  mcp-server/              ← MCP server (see mcp-server/README.md)
+  specs/                   ← ForgeTrail meta-specs (including NUX)
+```
+
+Doc templates use `[BRACKETED]` placeholders and callouts (💡 lesson, 📝 example, 🔧 guidance). MCP can serve **shell** or **full** mode: [mcp-server/TEMPLATE_STRIPPING.md](mcp-server/TEMPLATE_STRIPPING.md). Methodology is **stack-agnostic**; embedded lessons lean SvelteKit + PocketBase + common LLM providers (including local Ollama).
+
+---
+
+## Prerequisites
+
+- **Try path:** any LLM chat + any file-reading coding agent. No Node/MCP required to start.
+- **MCP:** Node.js to run the server; Cursor, Claude Desktop, Claude Code, Windsurf, or other MCP clients.
+- **Lite / full greenfield (when the agent scaffolds):** Git, Node.js 20+, npm, pnpm (Lite §4.1). Phase 2 adds stack-specific checks (PocketBase, Ollama, Playwright, …) per [FORGETRAIL_LITE.md](content/FORGETRAIL_LITE.md) §4.1.2.
+- **gstack (optional):** [gstack](https://github.com/garrytan/gstack) for sprint skills inside ForgeTrail phases.
+
+---
+
+## License and support
+
+**Apache License 2.0.** See [LICENSE](LICENSE). Contribute via [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md).
+
+**Support:** community best-effort via GitHub issues (including the [Try checklist](https://github.com/Catalyst-Forge-LLC/forgetrail/issues/new?template=try-forgetrail-checklist.md)). No SLA or paid support bundled with the license.