forgetrail 0.4.12 → 0.4.14

package/README.md

@@ -44,9 +44,9 @@ MCP: `npx -y forgetrail-mcp` with `FORGETRAIL_ROOT` set. Prefer `pnpm dlx` on Wi
 
 A 7-phase playbook, a live `.forgetrail/workflow_tracking.json`, and templates pre-loaded with first-party production lessons. Each project leaves a trail of decisions, gotchas, and breadcrumbs that future work follows. Those lesson notes are not independent adoption evidence. Flags, MCP, and the phase table live in the [docs](https://forgetrail.dev/docs).
 
-<!-- xfacts-nutrition-label -->
+<!-- xfacts-label -->
 
-## Nutrition label
+## xFacts label
 
 - **AppFacts:** [viewer](https://appfacts.dev/v#af1.eNp1Uk1r3DAQ_StiTg1o10mOPrUYcihJCCS3UsqsNNaqK2uENHbiLvvfi2x320tvg3hf8zRnmKC90xBxIGjhgbOjt4w-gAaZU30riYxqlDAHHx1oKIIyFmgBjfiJQEPwhmKp4C8JzZF29_vbFWhO0J4hYHQjugr4ihO-muyTaPU2J1pn0JDHKH4J8cyW9j9LTbB5tvDEloLqOAp9iHrJLGw4qE9P3csNaDhykRXYBR5tHzATXDRYSgXab2eI0MLnoYqYVSNtEk2xJ9CQ_u9RKE-UlR9SoIGioHiOcNGr6C-2G_3VHGlANWHwdsEojFbVEpWPPWWKhq6094zRBcob929qZSkFnqvRUvmV4Uh6HyhlKmVjPfhAuwMWsmrZKooaMKJbYsLlu4Yymev6_zSjIUP7pzSVMk_eUlY9Z_VOh-KFFvZh9MHW_0toTujox6peuSmmoRacKXHxwnmugiKptE3jvBzHw97w0HQoGOYiu-Wydo-PXdPXSZYbu_wGeaPbgQ) · [raw](https://github.com/Catalyst-Forge-LLC/forgetrail/blob/main/APP_FACTS.md)
 - **ToolFacts:** [viewer](https://toolfacts.dev/v#tf1.eNrFl8Fy2zYQhl9lhye7IymJL53RzVVjTxrV8shuc8hkPDC4pBCBAAuAUjWevHv_pUhJVdxceuCNAyyA_9tdLJYv2SabvhtlTlWcTbMbH0p-DMpY-n12Tw8cNhyyUZbzhq2v8T3NZiopu4uJWmNMwiQa7zD1dnI1ucJITCo1EQNKJ7MRG2s0uyhHXNdKr3h8NXmL4bVxOcYqXY9jf1ZoXDKi5iXjv1k3ab-39VrZcR285hhhloJysfYhYS6m3Pjs2yjTgXPGcmWjrA_8V2MwlE0_f8Esl0HWYiKx5YpT2GGx845bxJiMU3Ja7OyT97LP55fePRtlTa6SeEhDeimoJucnLgrWSYADq1wYGJByUGEsRziLK5Gp4UKZdpy2PqyPh3dYjC0KaGccjn2r2ifQZNMUGoZRE2rf-vDPTgdNColBkoC9kR0L67dPqVM3-Rq9owvjrHFMvz0s7sgH8rUgKktHaVSrtLokVSrjENeI-FSKlMupXqnIFBpYwr0HP9Svsncsr7N3k_-XfOadY0kqk3YEnXo9pcCpCS6SX49AoteqZOpyckQ3i-Xt-8fl9Yf503KxeBy1WNsVpxUH-rRYfryZLz5NKoypSIVvkI8noPDtvbjgtoG_neZhoJctICFhVz731pc7KjtBkBxIUXc_KyzvYnbxbvzz5SlKZBX0ao5jJcEH4XhoJRBcTyeFxraSCPmsnkX5847WvMNB55F4xM4WWT9oENSp9NzrpvV56qRREXwlw_HNT0iqUwCUtesmN2lg9REzGt-ckxI5hI2qOrV5JIHRTQhtFgX_FfroIvccyXkpC8q1JiIk4qIxmRTZFpdncZrJtbQmDo3aI-heT3dZKjk0YW_qmIvG2qPVedZ11fShrYqDIvXOf6XKdzU7cMEIHwrVvyGu8Sbeq5Q4DHX3O4T-xkj6QdO47kTtL44AnlS580ocfPuAo6P41WuJR46HaVCc7cqgoAHqUAEiJU9oQ6QYGEeiYV-Rz2DueHu_z8-PRq99UQzKAb-yKwzbnJ69TygSqsZburNe5cDQFqXClSgeKiBc1Ode-5geGopZEyJu1HfdwnoPeHs4Y6DXB2oIj_xrzqetSasOlPccS2CQ7NFCOg93BOwA_B_D3fn9-mEhv5PVEvomtXfsJFIUpZ1Ch_1f6flLnw-DJij-RsaFCajh0qLKEyZ9uty1NidR1U9SuC_8PTLa7p1k68nLbRyWiisC1_6M_Wg2NwN3G22rdOxg5x8e30uvKr896hnB68IsxMlrb39I8kct_wxxcCDRQs1ezKGkyNOMml9KnHoaKlWNy_ZFfvYap2Gf7zf-9g9m9jXP) · [raw](https://github.com/Catalyst-Forge-LLC/forgetrail/blob/main/mcp-server/TOOL_FACTS.md)

package/WORKFLOW.md

@@ -288,7 +288,7 @@ They are **never required**. Decline is success. Do not dump the shelf at kickof
 - Unpushed work you cannot lose → IngotVault
 - Spoken idea capture → DictaWhisper
 
-FilePress publishes Markdown. It does not replace Default-A for an interactive app. LocalSlip/LocalHelm are for two or more local apps, not a first single project.
+FilePress publishes Markdown. It does not replace Default-A for an interactive app. LocalSlip/LocalHelm are for two or more local apps, not a first single project. If they accept LocalSlip: FilePress claims then `filepress dev` (no `--port`); Vite uses CLI `get` and `strictPort`. Do not write `ensure-lease.mjs` or add the `localslip` package just to read a port. Recipes: `content/COMPANION_TOOLS.md`.
 
 ---
 
@@ -367,7 +367,7 @@ FilePress publishes Markdown. It does not replace Default-A for an interactive a
 - You can see your data on screen
 - The core action (scrape, create, view) completes without errors
 
-**Optional companions:** LocalSlip/LocalHelm if this machine already runs other local apps or ports collide; ollanet/Finetuna if the brief chose local Ollama; FilePress only for a Markdown `site/`, not as the app. See §1f.
+**Optional companions:** LocalSlip/LocalHelm if this machine already runs other local apps or ports collide; ollanet/Finetuna if the brief chose local Ollama; FilePress only for a Markdown `site/`, not as the app. If they accept LocalSlip, use the FilePress or Vite recipe in `content/COMPANION_TOOLS.md` — do not invent a lease helper. See §1f.
 
 **Example prompt (this worked):**
 

package/content/COMPANION_TOOLS.md

@@ -15,7 +15,7 @@ Public shelf (current versions and install): [catalystforge.com/tools](https://c
 1. Suggest at the moment of need. Decline is success.
 2. Do not dump this list at kickoff or in the first user-facing message.
 3. FilePress publishes **Markdown**. It does not replace an interactive SvelteKit app.
-4. LocalSlip and LocalHelm are for **two or more** local apps, not a first single project.
+4. LocalSlip and LocalHelm are for **two or more** local apps, not a first single project. If they accept LocalSlip, use the recipes below. Do not write `ensure-lease.mjs`.
 5. Practice skills: install the one that matches the current job, not the set.
 6. xFacts is the house standard for a **shipped** product (public URL or handoff). One-shots may skip.
 
@@ -31,6 +31,22 @@ Public shelf (current versions and install): [catalystforge.com/tools](https://c
 
 ---
 
+## Wire LocalSlip (agents)
+
+Human offer stays one sentence. Wire it this way:
+
+| Stack | Recipe |
+|-------|--------|
+| FilePress site | Lease name = site `package.json` `name` (or `FILEPRESS_LEASE`). `localslip claim NAME --port N && filepress dev`. FilePress reads the lease. Do not pass `--port`. |
+| Vite / SvelteKit app | `localslip get` in `vite.config`, `strictPort: true`. Claim once (README or `pnpm dev`). |
+| Table | `localslip ls` |
+
+Do not write `scripts/ensure-lease.mjs`. Do not add the `localslip` npm package just to read a port. `localslip/port` only if the app already depends on LocalSlip.
+
+Same recipes: [localslip.dev](https://localslip.dev) (FilePress + Vite pages) and FilePress `docs/LOCALSLIP.md`.
+
+---
+
 ## Default DNS and hosting (when unspecified)
 
 If the user has **not** already named a registrar, DNS, git host, or production host, prefer:

package/content/FORGETRAIL_LITE.md

@@ -1,6 +1,6 @@
 # ForgeTrail Lite — portable kickoff for any agentic chat
 
-> **ForgeTrail Lite v2.0.1**
+> **ForgeTrail Lite v2.0.2**
 > © Catalyst Forge, LLC — [www.catalystforge.com](https://www.catalystforge.com)
 > Part of the **ForgeTrail** open-source methodology ([Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) in the upstream ForgeTrail repo).
 >
@@ -98,6 +98,8 @@ When a boot surfaces a gap in **ForgeTrail Lite itself** (not a one-off app bug)
 
 **Optional companions:** when a job matches (Markdown site, two or more local apps, local Ollama, copy review, shipped-product label), you may offer a sibling from the Catalyst Forge shelf. Never required. Do not list them in the first message to the human. MCP: `getCompanionSuggestions`. Full mapping lives with ForgeTrail, not in this file.
 
+**Named ports (if they accept):** [LocalSlip](https://localslip.dev). FilePress: lease name = site `package.json` `name`. `localslip claim NAME --port N && filepress dev`. Do not pass `--port`. Vite: `localslip get` in `vite.config`, `strictPort`. Claim once. Do not write `ensure-lease.mjs`. Do not add the `localslip` package just to read a port.
+
 ### Who creates what
 
 The **human** only needs to do two things: copy ForgeTrail Lite into **`.forgetrail/`** (or paste this doc into chat), and tell the agent to follow it. **Everything else is created by the agent** as it works through the phases. You should never be asked to hand-write `.forgetrail/workflow_tracking.json`, `.forgetrail/AGENTS.md`, the brief, `CONTEXT_PROMPT.md`, or the Phase 2 baseline files — the agent writes them and shows them to you for review.
@@ -514,7 +516,7 @@ These are the **topics the agent needs to cover in Phase 1**, not a checklist to
 - **Existing assets** — repos, brand, content, APIs, schemas, or designs to reuse or integrate with.
 - **Live web / search** — does v1 need **up-to-date results from the public internet** (not just the model’s training cutoff)? If yes, the user may need a **search API** account (§4.4) before the spine can call real data.
 - **Registrar / DNS / git / hosting** — only what is still open. If unspecified: GitHub; Cloudflare for DNS (free plan); Cloudflare Pages for a static site; a droplet only if the app needs a server. Do not migrate a provider they already named.
-- **Other local apps / spoken notes** — if this machine will run two or more local apps, named ports help. If they capture ideas by voice, a local voice journal is a personal option. Neither is part of the first message.
+- **Other local apps / spoken notes** — if this machine will run two or more local apps, named ports help (LocalSlip: FilePress claims then `filepress dev`; Vite uses CLI `get` — see §2). If they capture ideas by voice, a local voice journal is a personal option. Neither is part of the first message.
 
 **Suggested rounds** (not a script — adapt to the user's energy):
 
@@ -636,7 +638,7 @@ Both defaults share the same foundation — **TypeScript + pnpm + ESM** — so t
 - Why this default: single-binary DB/auth/files (PocketBase), fast cold start, no cloud lock-in for v1, ships to a cheap VPS. Gets from zero to a runnable hero flow fastest.
 - Examples: internal tool, SaaS MVP, client portal, marketplace, dashboard, consulting deliverable builder.
 - **A-sub-question: does state need to outlive the browser?** Before locking PocketBase + auth, ask: *"Does any state need to outlive the browser — accounts, cross-device sync, shared data, admin views? Or is every user's state private and fine to live in `localStorage`?"*
-  - **A-local (per-user, browser-only):** drop PocketBase and auth. `adapter-static` becomes viable, no deploy-time secrets, no server-side DB. Persist via `localStorage` / `IndexedDB`. Many hobby/toy apps and single-session tools fit here — do not scaffold server infrastructure they will not use. An **interactive** A-local app stays on SvelteKit. [FilePress](https://getfilepress.com) is for a Markdown site or an optional `site/` beside the app (Cloudflare Pages + Wrangler), not a replacement for the app.
+  - **A-local (per-user, browser-only):** drop PocketBase and auth. `adapter-static` becomes viable, no deploy-time secrets, no server-side DB. Persist via `localStorage` / `IndexedDB`. Many hobby/toy apps and single-session tools fit here — do not scaffold server infrastructure they will not use. An **interactive** A-local app stays on SvelteKit. [FilePress](https://getfilepress.com) is for a Markdown site or an optional `site/` beside the app (Cloudflare Pages + Wrangler), not a replacement for the app. If LocalSlip is in play: `localslip claim` then `filepress dev`; FilePress reads the lease — do not pass `--port`.
   - **A-persistent (the existing Default A):** keep PocketBase, auth, and the full SvelteKit + adapter-auto defaults.
   - Record the choice in `decisions[]` and in `docs/PHASE_1_BRIEF.md` §4 so future sessions do not re-introduce a DB the project chose to skip.
 
@@ -1015,7 +1017,7 @@ Save this as `.forgetrail/AGENTS.md` so agents that auto-load it (Codex, Cursor,
 
 ```markdown
 <!--
-  Agent protocol based on ForgeTrail Lite v2.0.1.
+  Agent protocol based on ForgeTrail Lite v2.0.2.
   © Catalyst Forge, LLC — www.catalystforge.com
   Licensed under Apache License 2.0 (upstream ForgeTrail repo).
 -->
@@ -1207,4 +1209,4 @@ ForgeTrail Lite covers the shape of a project. The full **ForgeTrail MCP server*
 
 ---
 
-**ForgeTrail Lite v2.0.1** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+**ForgeTrail Lite v2.0.2** · © Catalyst Forge, LLC · [www.catalystforge.com](https://www.catalystforge.com) · [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

package/content/GREENFIELD_INTAKE.md

@@ -90,7 +90,7 @@ Record git host, DNS, registrar, and deploy target in **`PHASE_1_BRIEF.md` §4**
 
 Do **not** put these in the first user-facing message. Ask only if they did not already come up.
 
-- **Other local apps?** If this machine already runs (or will run) two or more local apps, offer **LocalSlip** (named ports) and **LocalHelm** (status board). Skip on a first single-app machine.
+- **Other local apps?** If this machine already runs (or will run) two or more local apps, offer **LocalSlip** (named ports) and **LocalHelm** (status board). Skip on a first single-app machine. If they accept LocalSlip: FilePress claims then reads; Vite uses CLI `get`. Do not write `ensure-lease.mjs`. Recipes: `COMPANION_TOOLS.md`.
 - **Spoken ideas?** If they capture ideas by voice or want a local journal beside the repo, offer **DictaWhisper**. Audio stays on their computer. It is a personal tool, not part of the app stack.
 
 These are optional companions (`getCompanionSuggestions`). Decline is success.

package/content/companion-tools.json

@@ -5,7 +5,8 @@
     "Suggest at the moment of need. Do not dump the shelf at kickoff or in the first user-facing message.",
     "Do not install, enroll, or publish unless the user asked.",
     "After a companion run that matters, persist the outcome in .forgetrail/workflow_tracking.json and the matching progressive doc.",
-    "Do not mention the mapping file, spec paths, or MCP tool names in human-facing offers."
+    "Do not mention the mapping file, spec paths, or MCP tool names in human-facing offers.",
+    "When wiring LocalSlip, follow that tool's how. Do not write ensure-lease.mjs. Do not add the localslip package just to read a port."
   ],
   "situations": [
     {
@@ -56,7 +57,8 @@
         {
           "name": "LocalSlip",
           "homepage": "https://localslip.dev",
-          "offer": "LocalSlip keeps a named port claim so startup order does not move the app."
+          "offer": "LocalSlip keeps a named port claim so startup order does not move the app.",
+          "how": "FilePress: lease name = site package.json name (or FILEPRESS_LEASE). `localslip claim NAME --port N && filepress dev`. Do not pass --port. Do not write ensure-lease.mjs. Vite: `localslip get` in vite.config with strictPort. Claim once (README or pnpm dev). Do not add the localslip package just to read a port. `localslip ls` is the table. `localslip/port` only if the app already depends on LocalSlip."
         },
         {
           "name": "LocalHelm",

package/content/skills/forgetrail/SKILL.md

@@ -62,7 +62,7 @@ You are operating under the ForgeTrail methodology. Your primary job is to give
    - Use `getAntiPatterns` for known failure modes.
 
 9. **Companion tools** (optional):
-   - When a trigger matches (Markdown site, two or more local apps, copy review, quality review, unclear cause, shipped product, spoken idea capture), call `getCompanionSuggestions` and *offer* the neighbor.
+   - When a trigger matches (Markdown site, two or more local apps, copy review, quality review, unclear cause, shipped product, spoken idea capture), call `getCompanionSuggestions` and *offer* the neighbor. LocalSlip how is on that tool: FilePress claims then `filepress dev`; Vite uses CLI `get`. Do not write `ensure-lease.mjs`.
    - Never block a phase on an install. Do not dump the shelf at kickoff or in the first user-facing message.
 
 ## Phase Transition Protocol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgetrail",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "private": false,
   "description": "ForgeTrail: a persistent development system for building software with AI agents. CLI, Lite protocol, and methodology templates.",
   "license": "Apache-2.0",

package/scripts/ensure-lease.mjs

@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-/**
- * Idempotent LocalSlip claim. Missing CLI → warn, exit 0.
- * Usage: node scripts/ensure-lease.mjs <name> <port>
- */
-import { spawnSync } from 'node:child_process';
-
-const name = process.argv[2];
-const port = process.argv[3];
-if (!name || !port) {
-	console.error('usage: node scripts/ensure-lease.mjs <name> <port>');
-	process.exit(1);
-}
-
-const opt = { encoding: 'utf8', timeout: 8000, windowsHide: true, shell: process.platform === 'win32' };
-const got = spawnSync('localslip', ['get', name], { ...opt, stdio: ['ignore', 'pipe', 'ignore'] });
-if (got.status === 0 && String(got.stdout || '').trim()) {
-	process.exit(0);
-}
-const claim = spawnSync('localslip', ['claim', name, '--port', port], { ...opt, stdio: 'inherit' });
-if (claim.error || claim.status !== 0) {
-	console.warn(`localslip: skip claim ${name} (install the CLI to pin this port to ${port})`);
-}