forgetrail 0.3.0

package/content/cursor-rules/forgetrail-updates-log.mdc

@@ -0,0 +1,30 @@
+---
+description: Keep FORGETRAIL_LITE_UPDATES.md current with protocol gaps discovered in this repo
+alwaysApply: true
+---
+
+# ForgeTrail Lite feedback log (FORGETRAIL_LITE_UPDATES.md)
+
+This repo may carry **`FORGETRAIL_LITE.md`** (upstream protocol) plus **`FORGETRAIL_LITE_UPDATES.md`** (candidate patches) under **`.forgetrail/`** (gitignored when the repo is published).
+
+## When to update `FORGETRAIL_LITE_UPDATES.md`
+
+After substantive work, if you find something that **should be fixed or clarified in ForgeTrail Lite itself** — not just this app — add or extend an entry:
+
+- Missing steps (e.g. `.env` loading, pnpm native builds, Vite monorepo `loadEnv` paths).
+- Anti-patterns Lite doesn't warn about yet.
+- Errors in the Lite defaults for **pnpm + TypeScript + monorepos** or **Cursor/agent** workflows.
+- Doc structure suggestions (which § to patch).
+
+**Do not** log routine bug fixes or product-only notes; use `.forgetrail/workflow_tracking.json → gotchas[]` for session-local incidents. **Do** log items a **future agent bootstrapping any ForgeTrail Lite project** would benefit from if the upstream file were updated.
+
+## How to write an entry
+
+1. Prefer **adding a numbered section** (or bullet under an existing section) with: what went wrong, suggested Lite change (§ reference if possible), optional project pointer.
+2. Update the **summary table** at the bottom if the topic is new.
+3. Keep tone aimed at **FORGETRAIL_LITE.md maintainers**, not end users.
+4. If the same issue is already covered, **tighten or cross-link** instead of duplicating.
+
+## This rule
+
+The feedback loop is documented in **`.forgetrail/FORGETRAIL_LITE.md` §1.6** when Lite is present — so humans know why the file stays locally.

package/content/cursor-rules/spec-completion.mdc

@@ -0,0 +1,33 @@
+---
+description: Where delivery specs live after implementation — completed vs partial
+alwaysApply: true
+---
+
+# Spec Completion Protocol
+
+Applies to **delivery specs** only. Does **not** apply to **canonical** specs in `specs/canonical/` (they stay put). See `specs-and-todo.mdc`.
+
+After **any substantive implementation pass** tracked by a delivery spec, the file MUST live in **`specs/completed/`** (fully done) or **`specs/partial/`** (work remains). Do not leave in-progress delivery specs in the parent `specs/` folder.
+
+## When the spec is fully implemented
+
+1. Set **Status** to `Implemented` (add a Status line if missing).
+2. Append or fill **Implementation summary** at the end:
+   - `Implemented: YYYY-MM-DD`
+   - What shipped (by area or file), briefly
+   - Verification (tests, checks, manual walkthrough)
+3. Mark the matching **TODO.md** item `[x]` and point at `specs/completed/<file>.md`.
+4. **Move** the file to `specs/completed/` and update links across the repo.
+
+## When work is partial or phased
+
+1. Refresh **Status** (e.g. Partial; what remains).
+2. **Move** to `specs/partial/` if not already there.
+3. Update links to `specs/partial/<file>.md`.
+4. Keep TODO.md accurate and pointing at the partial path.
+
+Optional: short **Progress** notes with dates while partial. Full Implementation summary is required only for `completed/`.
+
+## New specs
+
+Brand-new **delivery** specs stay in **`specs/`** until implementation **starts**, then move to **`specs/partial/`**. Brand-new **canonical** specs go directly into **`specs/canonical/`**.

package/content/cursor-rules/specs-and-todo.mdc

@@ -0,0 +1,26 @@
+---
+description: New specs must match ForgeTrail conventions and get a TODO.md entry
+alwaysApply: true
+---
+
+# Specs and TODO Backlog
+
+When **creating a new delivery spec** under `specs/`:
+
+1. **Start from the template:** copy `docs/SPEC_FEATURE_TEMPLATE.md` from ForgeTrail (MCP: `getTemplate({ name: "SPEC_FEATURE_TEMPLATE" })`), or the Lite skeleton in `.forgetrail/FORGETRAIL_LITE.md` §3.1. Match neighboring specs' naming (`kebab-case.md`).
+2. **Add or update `TODO.md`:** link the new spec with an open `[ ]` checklist item. Do not add a tracked delivery spec without a backlog entry.
+3. **Header:** set `Spec kind: Delivery` (or `Canonical reference`), `Status`, and Related links.
+
+## Where specs live
+
+**Delivery specs** (bounded work with acceptance criteria):
+
+- **`specs/`** — Drafts and **not-yet-started** proposals.
+- **`specs/partial/`** — Implementation **started** or **phased**; not all acceptance criteria met.
+- **`specs/completed/`** — Fully implemented (see each file's Implementation summary).
+
+**Canonical specs** (living reference / methodology, no delivery lifecycle):
+
+- **`specs/canonical/`** — Catalogs and references that **outlive one implementation pass**. Exempt from `partial/` → `completed/` moves. Header: `**Spec kind:** Canonical reference` and a `Status:` line for catalog state, not delivery state.
+
+Moving delivery specs and updating links: **Spec Completion Protocol** (`spec-completion.mdc`).

package/content/cursor-rules/url-host-matching.mdc

@@ -0,0 +1,31 @@
+---
+description: Prefer hostMatchesDomain over hostname.includes for board/ATS URL checks
+globs:
+  - src/**/*.{ts,js}
+  - outpost/**/*.{js,mjs}
+  - scripts/**/*.{js,mjs,ts}
+alwaysApply: false
+---
+
+# URL host matching
+
+## Prefer shared helpers
+
+- For board / ATS / “is this LinkedIn / Indeed / Greenhouse?” decisions, use **`hostMatchesDomain` / `urlMatchesHostDomain`** from `$lib/urlHost` (Outpost: `outpost/src/urlHost.js`, keep in sync).
+- **Do not** write `hostname.includes('linkedin.com')` or `url.includes('indeed.com')` for host allow/deny. Substring checks match lookalikes (`evil-linkedin.com`, `linkedin.com.attacker.example`) and trip CodeQL `js/incomplete-url-substring-sanitization`.
+
+## Parse first
+
+- Prefer `new URL(...)` then match on **`hostname`**. Keep path checks on **`pathname`** (e.g. `/jobs/view`), not on the full href string when tightening.
+
+## Outgoing fetch
+
+- App: `assertSafeUrl` at the boundary; follow redirects with re-check (`safeFetch`).
+- Outpost: `assertPublicHttpUrl` before slot acquisition / `goto`. Align blocked hosts (localhost, private IPs, `.local` / `.internal`, credentialed URLs).
+
+## Schemes and sanitization
+
+- Scheme checks: **allowlist** `http:` / `https:`; do not only deny `javascript:`.
+- Tag stripping / entity decode: use shared helpers (`stripMarkupTags`, amp-last entity decode) or a parser. If a regex is extraction-only, say so in a one-line comment.
+- GitHub Actions: always set top-level `permissions:` (least privilege).
+- Never return `err.stack` or raw exception text to HTTP clients; log server-side and return stable error codes.

package/content/cursor-rules/us-english.mdc

@@ -0,0 +1,9 @@
+---
+description: Default locale for product copy and LLM-facing prompts is US English
+alwaysApply: true
+---
+
+# US English Default
+
+- Use **US English** spelling and conventions for **user-visible product copy**, in-app help, marketing strings, and **prompts** that generate user-facing text (e.g. journal summaries, suggested copy), unless the user explicitly asks for another locale.
+- When editing or generating long-form project docs meant for the same audience as the product, default to US English unless context calls for otherwise.

package/content/cursor-rules/user-facing-content.mdc

@@ -0,0 +1,31 @@
+---
+description: User-visible UI copy must not reference internal specs or engineering jargon
+alwaysApply: true
+---
+
+# User-Facing Content
+
+## Internal vs external
+
+- **Help panel**, onboarding, tours, toasts, empty states, labels, and any other **end-user-facing** text must **not** mention internal specs, spec file names, or paths under `specs/`. Specs are for builders only.
+- It is fine to reference **in-app feature names** and menu paths users actually see.
+
+## Tone and clarity
+
+- Prefer **outcome-oriented** language (what the user gets or does), not implementation details.
+- Avoid engineering jargon in UI strings (e.g. storage format, schema field names, provider names) unless the user explicitly needs it for troubleshooting—and then keep it in expert/help contexts only.
+
+## Assertive capability copy
+
+When describing what **the product does**, use direct verbs — not hedging **can**:
+
+- **Do:** “Resume Forge **strengthens** your file.” / “The Prospect Engine **suggests** matching roles.” / “Foreman **proposes** a run plan.”
+- **Don't:** “…**can strengthen**…” / “…**can suggest**…” when stating a shipped capability.
+
+**Keep *can* when it means:**
+
+- **User permission or option** — “You can change it later.”
+- **Factual limit** — “what we can read from the listing automatically.”
+- **People, not features** — “connections who can help you.”
+
+Grep user-facing modules for `\bcan\b` after marketing or feature copy edits; fix capability hedges in the same pass.

package/content/examples/GENESIS_SAMPLE_mars-habitat-roster.md

@@ -0,0 +1,154 @@
+# GENESIS.md — Mars Habitat Duty Roster (sample)
+
+> **Fiction.** This is a made-up product for ForgeTrail demos. It is not a real NASA/SpaceX tool. The *problem shape* is deliberately ordinary: shared household / shift scheduling, with a Mars habitat skin so it is memorable.
+
+**Status:** sample for shape reference  
+**Canonical path in a real project:** `docs/GENESIS.md`
+
+---
+
+## Problem statement
+
+Six people share a pressurized habitat on Mars. Every sol (Martian day) someone must cover **galley**, **greenhouse**, **life-support walkthrough**, and **EVA prep**. Today the crew tracks this in a shared spreadsheet plus a group chat. Swaps happen in chat and never make it back into the sheet. Newcomers cannot tell who is on deck for the next three sols without pinging the commander.
+
+**Manual workaround today:** export the sheet to CSV, paste into a second tab labeled "truth," and argue in chat when the two disagree.
+
+---
+
+## Goals and explicit non-goals (v1 scope)
+
+**Goals**
+
+- One shared duty roster per habitat, visible to all crew.
+- Assign people to duty slots by sol; show the next 7 sols at a glance.
+- Request and accept a swap without leaving the app.
+- Keep a short audit trail of who changed what (name + sol + duty).
+
+**Non-goals (v1)**
+
+- No payroll, time clocks, or Earth-timezone conversion.
+- No integration with real habitat telemetry or suit systems.
+- No multi-habitat fleet management.
+- No mobile native apps (responsive web is enough).
+- No AI that auto-assigns duties (humans assign; the tool remembers).
+
+---
+
+## Required background on the underlying data / file format
+
+v1 is **local-first**. The builder may choose how to persist, but the domain export format is locked for handoff and backup:
+
+- **Export/import:** a single UTF-8 JSON file, `roster-export.json`.
+- **Top-level keys:** `habitatId` (string), `crew` (array), `duties` (array of duty type ids), `assignments` (array), `swapRequests` (array), `schemaVersion` (semver string, start at `"1.0.0"`).
+- **Assignment row:** `{ "sol": number, "dutyId": string, "personId": string, "updatedAt": ISO-8601, "updatedBy": string }`.
+- **Idempotent import:** importing a file replaces the local roster only after a confirmation step; never silent overwrite.
+- **No binary formats** in v1. Spreadsheet import is out of scope; CSV export of the current 7-sol view is nice-to-have, not required.
+
+Builders should document any chosen on-disk layout (e.g. one JSON file in the user data dir) in the Phase 1 brief; this Genesis only constrains the **portable** export shape.
+
+---
+
+## Core domain concepts / model
+
+- **Habitat** — one roster context (name + id).
+- **Crew member** — person with display name and optional role tag (commander, specialist, …). Role tags are labels only in v1.
+- **Duty type** — named slot kind (galley, greenhouse, life-support, eva-prep). Fixed list in v1; editable list is v2.
+- **Sol** — integer day index for the mission; the UI shows "Sol N" not Earth dates.
+- **Assignment** — one person on one duty type for one sol.
+- **Swap request** — from person A to person B for a specific assignment; states: `pending`, `accepted`, `declined`, `cancelled`.
+
+---
+
+## Functional requirements
+
+### 1. Roster board
+
+1.1 Show the next 7 sols as columns and duty types as rows (or equivalent clear grid).  
+1.2 Each cell shows the assigned person or "Unassigned."  
+1.3 Commander (or any crew in v1: no ACL yet) can set or clear an assignment in two clicks or fewer.  
+1.4 Changing an assignment appends an audit entry.
+
+### 2. Crew and duty setup
+
+2.1 Add / rename / deactivate crew (deactivated people cannot receive new assignments; historical cells stay).  
+2.2 Duty types ship as the four defaults above; renaming labels is allowed; adding/removing types is out of scope for v1.
+
+### 3. Swaps
+
+3.1 Assignee can request a swap with another crew member for one cell.  
+3.2 Target can accept or decline.  
+3.3 On accept, assignments swap and both sides see an audit entry.  
+3.4 Pending requests appear in a simple list; no email/push required for v1 (in-app only).
+
+### 4. Export / import
+
+4.1 Export current roster to `roster-export.json` matching the schema above.  
+4.2 Import with explicit confirm; reject unknown `schemaVersion` with a clear message.  
+4.3 Never modify the import file on disk.
+
+### 5. Empty and first-run states
+
+5.1 First launch offers "Create habitat" with name + add at least two crew before the board unlocks.  
+5.2 Unassigned cells are obvious; do not invent placeholder names.
+
+---
+
+## Non-functional requirements
+
+- **Local-only:** no accounts, no cloud sync in v1.  
+- **Privacy:** roster data stays on the device; no analytics.  
+- **Safety:** import never runs without confirmation; export is read-only relative to source data.  
+- **Performance:** board for 6 crew × 4 duties × 7 sols must feel instant on a mid-range laptop.  
+- **Platform:** desktop web or desktop-capable responsive UI; keyboard usable for assignment changes.
+
+---
+
+## Edge cases
+
+- Two people edit different cells "at once" on one shared machine (last write wins; audit shows both).  
+- Swap target is deactivated after request was sent → auto-cancel with message.  
+- Import file missing `assignments` array → reject with field path in the error.  
+- Sol numbers are not contiguous (crew skipped a sol in the sheet) → allow gaps; board still shows a 7-sol window from "today's sol" setting.  
+- Same person assigned to two duties on one sol → **allowed** in v1 (habitat life is busy); show both cells normally.  
+- Duplicate `personId` in import → reject.  
+- Very long display names → truncate in grid, full name in detail.  
+- User clears the only commander tag → allowed; tags are cosmetic.  
+- Browser refresh mid-swap → pending request must still be present after reload (persist before ack UI).  
+- Export while a pending swap exists → include `swapRequests` as-is.
+
+---
+
+## Suggested milestones
+
+- **M1.** Create habitat, crew, duty labels, 7-sol board, assign/clear, persist locally, audit log.  
+- **M2.** Swap request / accept / decline.  
+- **M3.** JSON export / import with confirmation.  
+- **M4.** Polish empty states + one-page README for crew.
+
+---
+
+## Acceptance criteria
+
+- Given a habitat with 6 crew and default duties, when I assign "Alex" to galley on Sol 104, then the board shows Alex in that cell after reload.  
+- Given Alex is on galley Sol 104, when Alex requests a swap with Sam and Sam accepts, then Sam is on galley Sol 104 and Alex is not.  
+- Given a valid `roster-export.json`, when I import it into an empty app and confirm, then the board matches the file.  
+- Given a file with `schemaVersion` `"99.0.0"`, when I import, then the app refuses and explains that the version is unsupported.  
+- Given I never confirm an import, when the file is selected, then on-disk app data is unchanged.
+
+---
+
+## Open questions
+
+| # | Question |
+|---|----------|
+| 1 | What is "today's sol" at first launch: user-entered mission sol, or start at 0? |
+| 2 | Should v1 allow printing a one-page "next 7 sols" view? |
+| 3 | Is a single shared browser profile enough, or do we need a simple device PIN? |
+
+---
+
+## Constraints
+
+- Local-only; no cloud accounts.  
+- Never overwrite local data on import without an explicit confirm step.  
+- No real spacecraft systems; this is a crew coordination toy with a Mars skin.

package/content/forgetrail-workspace-README.md

@@ -0,0 +1,43 @@
+# Local ForgeTrail workspace (`.forgetrail/`)
+
+This folder holds **ForgeTrail agent artifacts** — tracking, platform rules, and (for Lite boots) the protocol file. ForgeTrail upstream is **Apache 2.0**; you may commit this folder or **gitignore** it for a slimmer public app repo. Never commit secrets here.
+
+Used for **both** ForgeTrail Lite file bootstrap and **MCP greenfield** kickoff.
+
+## Contents
+
+| File | Purpose |
+|------|---------|
+| `workflow_tracking.json` | Phase / decisions / session tracking (all approaches) |
+| `FORGETRAIL_LITE.md` | Full Lite kickoff protocol (Lite file bootstrap only) |
+| `FORGETRAIL_LITE_UPDATES.md` | Optional local feedback log (§1.6) — merge accepted items upstream |
+| `AGENTS.md` | Agent instructions — cite or symlink for your IDE |
+| `CLAUDE.md` | Claude Code trailer override |
+| `IDEAS.md` | Backlog parking lot |
+| `cursor/rules/*.mdc` | Cursor rule snippets (no-trailer, updates-log, …) |
+
+## Wire up Cursor (one-time)
+
+From the **repo root**:
+
+**Git Bash / WSL:**
+
+```bash
+mkdir -p .cursor/rules
+ln -sf ../../.forgetrail/cursor/rules/forgetrail-no-trailer.mdc .cursor/rules/
+ln -sf ../../.forgetrail/cursor/rules/forgetrail-updates-log.mdc .cursor/rules/
+```
+
+**Windows cmd (junction):**
+
+```bat
+mkdir .cursor\rules 2>nul
+mklink .cursor\rules\forgetrail-no-trailer.mdc ..\.forgetrail\cursor\rules\forgetrail-no-trailer.mdc
+mklink .cursor\rules\forgetrail-updates-log.mdc ..\.forgetrail\cursor\rules\forgetrail-updates-log.mdc
+```
+
+Optional: symlink `.forgetrail/AGENTS.md` → `AGENTS.md` at repo root if a tool requires root placement (also gitignore root copies if you symlink).
+
+## Recovering after clone
+
+If `.forgetrail/` was gitignored, it is not in git. Copy from upstream Catalyst Forge (`content/`) or restore from backup; MCP-only projects can recreate tracking via **`getInitialWorkflowTracking`**.

package/content/scripts/forgetrail-dev-launcher.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/**
+ * Reference dev launcher — copy to app repo scripts/forgetrail-dev-launcher.mjs
+ * Wire repo-root setup.bat / run.bat / status.bat (Windows) and setup.sh / run.sh / status.sh (Mac/Linux).
+ *
+ * Commands: setup | run | status
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const trackingPath = join(repoRoot, ".forgetrail", "workflow_tracking.json");
+const progressPath = join(repoRoot, "docs", "FORGETRAIL_PROGRESS.md");
+const isWin = process.platform === "win32";
+
+const PHASE_LABELS = {
+  // Display names — see TRACKING_SCHEMA.md "Phase ID vocabulary (Lite vs MCP)"
+  "1": "Plan",
+  "2": "Build",
+  "3": "Stabilize",
+  "4": "Iterate",
+  "5": "Refine",
+  "6": "Align",
+  "7": "Harden",
+  "1-architecture": "Plan",
+  "2-scaffolding": "Build",
+  "3-stabilization": "Stabilize",
+  "4-feature-iteration": "Iterate",
+  "5-refactoring": "Refine",
+  "6-strategic-review": "Align",
+  "7-hardening": "Harden",
+};
+
+/** Lite schema: exitCriteria { key: boolean }. MCP schema: exitCriteriaMet / exitCriteriaRemaining arrays. */
+function getExitCriteriaStatus(phaseBlock) {
+  if (!phaseBlock) return { met: [], remaining: [] };
+
+  if (Array.isArray(phaseBlock.exitCriteriaMet) || Array.isArray(phaseBlock.exitCriteriaRemaining)) {
+    return {
+      met: Array.isArray(phaseBlock.exitCriteriaMet) ? phaseBlock.exitCriteriaMet : [],
+      remaining: Array.isArray(phaseBlock.exitCriteriaRemaining) ? phaseBlock.exitCriteriaRemaining : [],
+    };
+  }
+
+  const criteria = phaseBlock.exitCriteria;
+  if (criteria && typeof criteria === "object" && !Array.isArray(criteria)) {
+    const met = [];
+    const remaining = [];
+    for (const [key, value] of Object.entries(criteria)) {
+      if (value) met.push(key);
+      else remaining.push(key);
+    }
+    return { met, remaining };
+  }
+
+  return { met: [], remaining: [] };
+}
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: "inherit", cwd: repoRoot, shell: isWin, ...opts });
+    p.on("error", reject);
+    p.on("exit", (c) => (c === 0 ? resolve() : reject(new Error(`${cmd} exited ${c}`))));
+  });
+}
+
+function hasScript(name) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8"));
+    return Boolean(pkg.scripts?.[name]);
+  } catch {
+    return false;
+  }
+}
+
+async function cmdSetup() {
+  console.log("=== ForgeTrail setup (first time or refresh) ===\n");
+  if (!existsSync(join(repoRoot, "node_modules"))) {
+    console.log("Installing dependencies…");
+    await run("pnpm", ["install"]);
+  }
+  if (hasScript("setup:pocketbase")) {
+    await run("pnpm", ["run", "setup:pocketbase"]);
+  } else if (existsSync(join(repoRoot, "scripts", "setup-pocketbase.mjs"))) {
+    await run("node", ["scripts/setup-pocketbase.mjs"]);
+  }
+  if (hasScript("pocketbase:schema")) {
+    console.log("\nApplying PocketBase schema (needs PocketBase running + .env admin creds)…");
+    console.log("(If this fails, run setup again after starting PocketBase once.)\n");
+    try {
+      await run("pnpm", ["run", "pocketbase:schema"]);
+    } catch {
+      console.log("Schema step skipped or failed — you can run: pnpm run pocketbase:schema");
+    }
+  }
+  if (hasScript("env:check")) await run("pnpm", ["run", "env:check"]);
+  console.log("\nSetup pass complete. Next: double-click run.bat (or pnpm run dev).");
+}
+
+async function pbHealth() {
+  const env = {};
+  const envPath = join(repoRoot, ".env");
+  if (existsSync(envPath)) {
+    for (const line of readFileSync(envPath, "utf8").split(/\r?\n/)) {
+      const m = line.match(/^\s*PUBLIC_POCKETBASE_URL\s*=\s*(.+)/);
+      if (m) {
+        try {
+          const u = new URL(m[1].trim());
+          const res = await fetch(`${u.origin}/api/health`, { signal: AbortSignal.timeout(2000) });
+          return res.ok;
+        } catch {
+          return false;
+        }
+      }
+    }
+  }
+  return false;
+}
+
+async function cmdRun() {
+  console.log("=== Starting dev environment ===\n");
+  if (!(await pbHealth()) && hasScript("pocketbase")) {
+    console.log("Starting PocketBase in the background…");
+    const child = spawn("pnpm", ["run", "pocketbase"], {
+      cwd: repoRoot,
+      detached: true,
+      stdio: "ignore",
+      shell: isWin,
+    });
+    child.unref();
+    await new Promise((r) => setTimeout(r, 2500));
+  }
+  if (!hasScript("dev")) {
+    console.error("No pnpm run dev script — check README.md");
+    process.exit(1);
+  }
+  console.log("Starting app (Ctrl+C to stop)…\n");
+  await run("pnpm", ["run", "dev"]);
+}
+
+function renderProgress() {
+  if (!existsSync(trackingPath)) {
+    return { text: "No .forgetrail/workflow_tracking.json yet — agent bootstrap not finished.", md: null };
+  }
+  const t = JSON.parse(readFileSync(trackingPath, "utf8"));
+  const phase = t.currentPhase ?? "?";
+  const phaseId = String(phase);
+  const phaseBlock = t.phases?.[phaseId];
+  const label = PHASE_LABELS[phaseId] || phaseBlock?.name || `Phase ${phase}`;
+  const status = phaseBlock?.status || "unknown";
+  const { met, remaining } = getExitCriteriaStatus(phaseBlock);
+  const lines = [
+    `ForgeTrail phase: ${label} (${phaseId}) — ${status}`,
+    "",
+    met.length ? "Done (this phase):" : "",
+    ...met.map((k) => `  ✓ ${k}`),
+    met.length ? "" : "",
+    remaining.length ? "Still open:" : "Exit criteria for this phase look complete (confirm before advancing):",
+    ...remaining.map((k) => `  - ${k}`),
+  ];
+  if (t.sessions?.length) {
+    const last = t.sessions[t.sessions.length - 1];
+    lines.push("", `Last session: ${last.date} — ${last.summary || "(no summary)"}`);
+  }
+  const md = [
+    "# ForgeTrail progress",
+    "",
+    "_Human-readable snapshot. Source of truth: `.forgetrail/workflow_tracking.json`._",
+    "",
+    `**Current phase:** ${label} (\`${phaseId}\`) — **${status}**`,
+    "",
+    "## What's done (this phase)",
+    "",
+    ...(met.length ? met.map((k) => `- [x] ${k}`) : ["- _(none marked met yet)_"]),
+    "",
+    "## Still to do (this phase)",
+    "",
+    ...(remaining.length ? remaining.map((k) => `- [ ] ${k}`) : ["- _(none listed — verify before advancing)_"]),
+    "",
+    "## Refresh",
+    "",
+    "Double-click **status.bat** (Windows) or run **./status.sh** / **pnpm run forgetrail:status** anytime.",
+    "",
+  ].join("\n");
+  return { text: lines.join("\n"), md };
+}
+
+function cmdStatus() {
+  const { text, md } = renderProgress();
+  console.log(text);
+  if (md) {
+    mkdirSync(join(repoRoot, "docs"), { recursive: true });
+    writeFileSync(progressPath, md, "utf8");
+    console.log(`\nWrote ${progressPath}`);
+  }
+}
+
+const cmd = process.argv[2];
+if (cmd === "setup") cmdSetup().catch((e) => { console.error(e.message || e); process.exit(1); });
+else if (cmd === "run") cmdRun().catch((e) => { console.error(e.message || e); process.exit(1); });
+else if (cmd === "status") cmdStatus();
+else {
+  console.log("Usage: node scripts/forgetrail-dev-launcher.mjs setup|run|status");
+  process.exit(1);
+}

package/content/scripts/forgetrail-env.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Shared env + repo root helpers for ForgeTrail reference scripts.
+ * Copy to app repo scripts/forgetrail-env.mjs alongside other forgetrail scripts.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function repoRootFromImportMeta(importMetaUrl) {
+  return join(dirname(fileURLToPath(importMetaUrl)), "..");
+}
+
+export function loadEnv(repoRoot) {
+  const envPath = join(repoRoot, ".env");
+  if (!existsSync(envPath)) return {};
+  const out = {};
+  for (const line of readFileSync(envPath, "utf8").split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const i = t.indexOf("=");
+    if (i < 1) continue;
+    out[t.slice(0, i).trim()] = t.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+export function pocketBaseUrlFromEnv(env) {
+  const raw =
+    env.PUBLIC_POCKETBASE_URL ||
+    env.POCKETBASE_URL ||
+    (env.POCKETBASE_HTTP_HOST && env.POCKETBASE_HTTP_PORT
+      ? `http://${env.POCKETBASE_HTTP_HOST}:${env.POCKETBASE_HTTP_PORT}`
+      : "");
+  if (!raw) return null;
+  try {
+    const u = new URL(raw.startsWith("http") ? raw : `http://${raw}`);
+    return u;
+  } catch {
+    return null;
+  }
+}
+
+export function ollamaBaseUrlFromEnv(env) {
+  const raw = env.OLLAMA_BASE_URL || env.OLLAMA_HOST || "http://127.0.0.1:11434";
+  try {
+    return new URL(raw.startsWith("http") ? raw : `http://${raw}`);
+  } catch {
+    return new URL("http://127.0.0.1:11434");
+  }
+}