forgetrail 0.3.0

package/docs/NAMING_EXPLORATION.md

@@ -0,0 +1,406 @@
+# [App Name]: Naming Exploration
+
+**Status:** [Active exploration / Name selected / Parked]  
+**Current name:** [Current name, if renaming]  
+**Scope:** This document explores naming only. Implementation of a name change (codebase, domains, branding assets, redirects) belongs in a separate spec once a name is chosen.  
+**Related:** [BRAND_AND_PRODUCT.md](BRAND_AND_PRODUCT.md), origin story (if applicable), design system, competitive landscape
+
+_Instructions: This is a structured methodology for naming or renaming a product. It works for greenfield naming and for renaming an existing product. Complete each section in order — later sections depend on earlier ones. The process is: understand the identity (§1-2), extract themes from your own language (§3), expand your vocabulary (§4), generate candidates (§5), stress-test against real copy (§6), verify availability (§7), score (§8), and act (§9)._
+
+_Run this after your brand voice, positioning, and target audience are defined (BRAND_AND_PRODUCT.md should exist or be in progress). A name chosen before brand clarity tends to drift from the product it represents._
+
+---
+
+## 1. Why name / rename
+
+_What is driving this exercise? Be specific about the problem with the current name (if renaming) or the constraints on a new name (if greenfield)._
+
+### The naming problem
+
+[Describe what is not working. For a rename: what does the current name signal that is wrong, ambiguous, or limiting? For greenfield: what must the name accomplish that a placeholder cannot?]
+
+> 📝 **Example (rename):**
+> "Prime Contender" reads as sports/boxing/MMA before it reads as career. For someone encountering the name cold, the extra cognitive step costs clicks. The product is a job search preparation platform — the name should make that legible within two seconds.
+
+> 📝 **Example (greenfield):**
+> We need a name for an AI-powered contract review tool targeting in-house legal teams at mid-market companies. The name must signal "legal" without sounding like a law firm, and "technology" without sounding like a developer tool.
+
+### Names already considered and rejected
+
+| Name | Reason rejected |
+|------|-----------------|
+| [Name] | [Specific reason: .com taken, namespace crowded, wrong connotation, etc.] |
+
+---
+
+## 2. What the name must do
+
+_Derive these criteria from your BRAND_AND_PRODUCT.md, not from abstract naming theory. Every criterion should trace to a real product decision or audience insight._
+
+### Non-negotiable criteria
+
+| Job | Why | Source |
+|-----|-----|--------|
+| **[Criterion 1: Category signal]** | [Why a cold reader must understand the category instantly] | [Which doc or user feedback this comes from] |
+| **[Criterion 2: Audience signal]** | [Why the name must convey who the product is for] | [Source] |
+| **[Criterion 3: Positioning signal]** | [Why the name must imply the product's approach — e.g. preparation vs automation, simplicity vs power] | [Source] |
+| **[Criterion 4: Speakability]** | [Why word-of-mouth matters for this product's acquisition model] | [Source] |
+| **[Criterion 5: Domain availability]** | [Why .com (or specific TLD) matters for this audience and price point] | [Source] |
+| **[Criterion 6: Competitive clearance]** | [Which existing tools or brands the name must not conflict with] | [Source] |
+
+> 📝 **Guidance:** 4-7 criteria is the sweet spot. Fewer than 4 and you have not constrained the problem; more than 7 and every candidate fails on something. Weight them in §8.
+
+### Nice-to-haves
+
+- [Echoes something from the current name or brand history]
+- [Works as a verb / action]
+- [Fits the existing visual identity without a full redesign]
+- [The legal entity name does not need to match]
+
+---
+
+## 3. Naming themes
+
+_This is the most important section. Themes are not random brainstorming — they are extracted from your own product's language. Read your BRAND_AND_PRODUCT.md, origin story, marketing copy, and in-app copy. Highlight words and phrases that appear repeatedly or carry emotional weight. Each theme becomes a direction to explore._
+
+_Aim for 4-8 themes. Each should have:_
+- _Source phrases (actual quotes from your docs)_
+- _A one-line explanation of why this direction works_
+- _3-6 energy/tone keywords_
+
+### Theme [Letter]: [Theme name] ([short description])
+
+**Source phrases:** "[exact quote from docs]," "[another quote]," "[another]."
+
+[1-3 sentences explaining why this word/concept resonates for your product. What does it signal to the target audience? What connotation does it carry?]
+
+**Energy:** [3-6 tone keywords]. [e.g. Deliberate. Forward-moving. Owned.]
+
+> 📝 **Guidance on finding themes:**
+>
+> - **Grep your brand doc** for words that appear 3+ times. Frequency = resonance.
+> - **Read your origin story** (if you have one). The emotional climax often contains naming energy.
+> - **Read your "We say / We don't say" pairs.** The "We say" column is a goldmine.
+> - **Read your differentiator statements.** "We are X, not Y" — the X words are candidate themes.
+> - **Check your feature names.** If a feature is already branded (e.g. "Resume Forge," "Intel Dossier"), the brand word may extend to the product name.
+> - **Consider audience-as-theme.** Instead of describing what the product does, name who it is for (e.g. "Exec," "Founder," "Counsel"). The audience self-selects.
+> - **Consider the transformation.** "From [before state] to [after state]" — both states are themes.
+>
+> **Anti-pattern:** Generating themes from a thesaurus or abstract brainstorming without anchoring in your own copy. Names that sound good in isolation but do not connect to the brand voice will feel foreign in context.
+
+### Theme A: [Name]
+
+**Source phrases:** [...]
+
+[...]
+
+**Energy:** [...]
+
+### Theme B: [Name]
+
+**Source phrases:** [...]
+
+[...]
+
+**Energy:** [...]
+
+_[Continue for each theme — typically 4-8]_
+
+---
+
+## 4. Vocabulary expansion (brainstorm then bucket)
+
+_Before combining themes into two-word names, build a rich vocabulary. This step prevents tunnel vision — going directly from theme to name tends to produce a narrow set of obvious combinations. A broader word pool surfaces unexpected pairings._
+
+### Step 1: Generate a domain vocabulary
+
+Ask for a large, unstructured list of words related to your product's **domain** — not your themes, not your brand, just the space you operate in.
+
+> 📝 **Example prompt:** "Generate 150-200 single words associated with [your domain — e.g. executive job search, career transitions, senior professional hiring]. Include nouns, verbs, adjectives, and metaphors. Cover the full emotional and practical range: the process, the people, the stakes, the tools, the outcomes, the feelings, the environment."
+
+The goal is volume and diversity. Do not filter yet. You want words you would not have thought of — alongside the obvious ones.
+
+> 📝 **Guidance on scoping:** The initial ask can be broad (all of "executive career search") or narrow (just "the emotional experience of job searching," or "words associated with preparation and readiness"). Narrower prompts produce more focused vocabularies; broader prompts surface more unexpected connections. Consider running 2-3 narrower prompts rather than one broad one if the domain is large:
+> - Domain-specific actions and artifacts (e.g. for career: resume, tailor, submit, pipeline, shortlist)
+> - Emotional landscape (e.g. for career: confidence, doubt, momentum, weight, clarity)
+> - Metaphorical frames (e.g. for career: forge, runway, bridge, edge, armor, signal)
+
+### Step 2: Bucket words against themes
+
+Take the vocabulary list and score each word against the themes defined in §3. For each word, ask: **which theme(s) does this word's energy strongly fit?**
+
+A word may land in:
+- **One theme** — it is tightly associated (e.g. "forge" → Theme C only)
+- **Multiple themes** — its energy spans several directions (e.g. "primed" → readiness + preparation + edge)
+- **No theme** — discard it or note it as a potential new theme signal
+
+> 📝 **Example prompt:** "Here are my naming themes with their energy keywords: [paste themes from §3]. Here is a vocabulary of [N] words: [paste list]. For each word, assign it to every theme where the association is strong (not forced). Output as a table: Word | Themes | Notes. Skip words that don't strongly fit any theme."
+
+### Step 3: Review the bucketed results
+
+For each theme, you now have a richer pool of associated words beyond the obvious theme word itself. Review for:
+
+- **Surprising additions** — words you would not have considered for a theme but that fit its energy. These are the most valuable.
+- **High-overlap words** — words that land in 3+ themes. These are strong name candidates because they carry multiple signals simultaneously.
+- **Theme gaps** — themes with very few words may be too narrow, or the vocabulary prompt missed their domain. Consider a targeted follow-up vocabulary generation.
+- **New theme signals** — clusters of discarded words that share an energy not captured by existing themes. Consider adding a new theme.
+
+### Step 4: Feed into name generation
+
+Use the bucketed vocabulary (not just the theme keywords) as the input for the combination methods below. This is what makes the difference — instead of combining "Pursuit" + "Primed" (two theme keywords), you are combining any word from Theme A's bucket with any word from Theme D's bucket.
+
+---
+
+## 5. Name candidates
+
+_Generate candidates by combining words from the theme-bucketed vocabulary (§4). A two-word name typically pairs words from different themes. Test single words, two-word combinations, and occasional three-word phrases._
+
+### Generation method
+
+For each theme bucket, generate candidates by:
+
+1. **Theme keyword alone** — Can the core theme word stand alone? (Usually only if domain is available.)
+2. **Bucket word + bucket word** — Combine words from **different** theme buckets. This is the primary method and the reason §4 exists — it produces combinations the theme-keyword-only approach would miss.
+3. **Theme keyword + bucket word** — Pair a theme's keyword with a non-obvious word from another theme's bucket.
+4. **Reversed pairs** — Try both word orders; they read differently ("Pursuit Forge" vs "Forge Pursuit").
+5. **Audience word + bucket word** — [Audience word] + [word from any bucket] (e.g. Exec + Primed, Counsel + Edge).
+6. **High-overlap words as anchors** — Words that scored into 3+ themes carry multiple signals; try them as the anchor word paired with more specific words.
+7. **Coined portmanteaus** — Combine syllable fragments from different words to create a new word that carries both signals (like Microsoft = micro + software, or Pinterest = pin + interest). This dramatically expands the domain-available namespace since coined words are rarely registered.
+
+#### Portmanteau generation method
+
+Take the favorite words from Steps 1-6 — the ones that keep appearing in strong candidates — and decompose them into syllable fragments. Then combine fragments from different words to create new coinages.
+
+**Fragment extraction:** For each favorite word, list its syllable parts:
+
+> 📝 **Example:** pursuit → "pur" / "suit"; forge → "forge" / "for"; prime → "prim" / "prime"; edge → "edge" / "edg"; helm → "helm"; foundry → "found" / "foun"; velocity → "vel" / "velo" / "veloci"
+
+**Combination patterns:**
+
+- **Compress two words at their boundary** — drop overlapping or redundant syllables to fuse two words into one (e.g. pursuit + forge → "pursforge," prime + edge → "primedge"). The result should read as one word, not a forced concatenation.
+- **First-half + second-half** — take the opening syllables of one word and the closing syllables of another (e.g. velocity + forge → "velociforge," prime + helm → "primhelm").
+- **Root word + archetype suffix** — pair a root with a suffix that carries meaning: "-wright" (craftsman — playwright, shipwright), "-works" (factory/output), "-point" (destination), "-craft" (skill/discipline), "-vault" (secure container), "-anvil" (where shaping happens). These suffixes create real-word associations without being common in the product-naming space.
+- **Latin/Greek hybrid** — if a word has a classical root, use the Latin or Greek form for a premium feel (e.g. momentum → "momenta" [Latin plural], velocity → "velox" [Latin adjective], apex → "apexis"). Classical forms read as premium and educated — appropriate for executive-audience products.
+
+**Evaluation criteria for coined words:**
+
+- **Pronounceable on first read** — if someone hesitates or splits it wrong, it fails the word-of-mouth test
+- **Spellable after hearing it once** — the phone test: can you spell it to a customer service agent without clarification?
+- **Carries both source signals** — both root words should be recoverable from the coinage, even subconsciously
+- **Doesn't trigger wrong associations** — "veloci-" triggers "velociraptor" for many; "prim-" could read as "prim and proper"; test for unintended readings
+- **Domain available** — coined words have much higher .com availability than real-word combinations, which is a key advantage of this approach
+
+> 📝 **Guidance:** Coined words trade recognition for distinctiveness. A two-word name like "Pursuit Forge" is instantly parsed; a coined word like "Pursforge" requires a beat. The trade-off is worth it when: (1) all strong two-word .coms are taken, (2) you want a single-word brand that feels owned and distinctive, or (3) your product is premium enough that a slightly opaque name works (think: Accenture, Verizon, Spotify). For products where category clarity is the top criterion, stick to two-word real-word names.
+
+### Tier 1: Strongest candidates
+
+_Names that score highest across §2 criteria and have likely-available domains. Include 5-12 names._
+
+| Name | Themes | Domain status | Why it works | Risks / considerations |
+|------|--------|---------------|--------------|------------------------|
+| **[Name]** | [Theme letters] | `[domain]` [status] | [2-3 sentences on why this name serves the criteria] | [Honest assessment of weaknesses] |
+
+> 📝 **Guidance:** "Why it works" should reference specific criteria from §2, not just "sounds good." "Risks" should be real — connotation problems, spelling ambiguity, confusable neighbors, length.
+
+### Tier 2: Strong but with caveats
+
+_Names that work well on some criteria but have a known weakness. Include 8-15 names. These are the bench — they may become Tier 1 if a top candidate falls through on trademark or testing._
+
+| Name | Themes | Domain status | Notes |
+|------|--------|---------------|-------|
+| **[Name]** | [Letters] | `[domain]` [status] | [One-line on strength + caveat] |
+
+### Tier 3: Single-word explorations
+
+_Premium single-word names are almost always taken as .com. Note them for creative direction and potential prefix/suffix treatment (get[word].com, [word]app.com, [word]hq.com, etc.)._
+
+| Concept | Notes |
+|---------|-------|
+| [Word] | [Domain status; why it captures the brand] |
+
+### Competitive clearance check
+
+_Search for each Tier 1 candidate + your product category to verify no active competitor uses the name._
+
+| Name checked | Conflicts found | Verdict |
+|--------------|-----------------|---------|
+| [Name] | [None / Company X at domain Y — different category / Direct conflict] | [Clear / Caution / Blocked] |
+
+### Names explicitly ruled out
+
+| Name | Reason |
+|------|--------|
+| [Name] | [Specific reason] |
+
+---
+
+## 6. Brand copy stress tests
+
+_The best way to evaluate a name is to drop it into your actual brand copy. For each Tier 1 candidate, rewrite 4-6 key brand artifacts. If the name feels forced or breaks the sentence rhythm, it is probably wrong._
+
+_Test these surfaces for each finalist:_
+
+### [Candidate name]
+
+- **Tagline:** [Adapt your existing tagline or write a new one that fits]
+- **Origin story closing:** [Rewrite the last 1-2 sentences of the origin story with this name]
+- **Positioning statement:** "[Name] is the [category] for [audience]."
+- **Virality / referral copy:** "Managed my [thing] with [Name]" / "Prepped with @[Handle]"
+- **Verb form:** Can you verb it? "[Name]'d my application" — natural or forced?
+- **Coach/partner referral:** "You should check out [Name] — it's a [one-line description]."
+
+> 📝 **Guidance:** The referral test is the most important. Say it out loud as if texting a friend: "Check out [Name] — it [does thing] for [audience]." If you hesitate, stumble on pronunciation, or feel the need to explain the name before explaining the product, the name is adding friction.
+
+_[Repeat for each Tier 1 candidate]_
+
+---
+
+## 7. Domain and handle availability
+
+### Method
+
+_Describe the method used and its limitations._
+
+> 📝 **Standard method:** DNS `nslookup` against a public resolver (e.g. Cloudflare 1.1.1.1). NXDOMAIN (non-existent domain) strongly suggests the domain is unregistered, but is not a guarantee — some domains are registered and parked without DNS records. Always confirm at a registrar (Namecheap, Cloudflare Registrar, Google Domains, etc.) before committing.
+>
+> To check: `nslookup -timeout=3 [domain] 2>&1` — look for "Non-existent domain" or "NXDOMAIN."
+>
+> For batch checking:
+> ```bash
+> for domain in candidate1.com candidate2.com candidate3.com; do
+>   echo -n "$domain: "
+>   nslookup -timeout=2 $domain 2>&1 | grep -c "NXDOMAIN\|server can't find\|Non-existent"
+> done
+> ```
+> Output `1` = NXDOMAIN (likely available). Output `0` = resolves (taken or parked).
+
+### TLD strategy
+
+[Which TLDs are acceptable for your audience and price point? .com is standard for premium B2B SaaS. Consider whether .io, .co, .app, etc. are acceptable or whether they undermine credibility for your specific buyer.]
+
+### Confirmed likely-available domains
+
+```
+[domain1.com]          [domain2.com]          [domain3.com]
+[...]
+```
+
+### Confirmed taken / resolving domains
+
+```
+[domain1.com]          [domain2.com]          [domain3.com]
+[...]
+```
+
+### Social handle availability
+
+_Check for each Tier 1 finalist. Note the platform and availability._
+
+| Name | X / Twitter | LinkedIn | Instagram | Facebook |
+|------|-------------|----------|-----------|----------|
+| [Name] | [Available / Taken / Close variant] | [...] | [...] | [...] |
+
+---
+
+## 8. Evaluation framework
+
+_Score each Tier 1 candidate 1-5 on each criterion. Weights should reflect §2 priorities._
+
+| Criterion | Weight | Notes |
+|-----------|--------|-------|
+| **[Criterion from §2]** | [%] | [Scoring guidance: what does a 5 vs a 1 look like?] |
+| **[Criterion]** | [%] | [...] |
+| **[Criterion]** | [%] | [...] |
+| **[Criterion]** | [%] | [...] |
+| **[Criterion]** | [%] | [...] |
+| **[Criterion]** | [%] | [...] |
+| **[Criterion]** | [%] | [...] |
+
+> 📝 **Guidance:** Weights should sum to 100%. Category clarity and audience signal typically deserve the highest weights (20-25% each). Brand story continuity is usually lowest (5%) because the story adapts to any good name. Adjust based on what matters most for your acquisition model.
+
+### Scorecard
+
+| Name | [C1] | [C2] | [C3] | [C4] | [C5] | [C6] | [C7] | **Weighted** |
+|------|------|------|------|------|------|------|------|-------------|
+| [Name 1] | | | | | | | | |
+| [Name 2] | | | | | | | | |
+| [Name 3] | | | | | | | | |
+
+_Fill this in collaboratively — founder/team scores, not AI scores. The framework creates structured conversation, not an algorithm._
+
+---
+
+## 9. Decision process and next steps
+
+### Before selecting
+
+1. **Register top 3-5 domains immediately.** Domains are $10-15/yr. Do not wait for consensus — register anything you might want. This is insurance, not commitment.
+2. **Say them out loud.** In a referral text: "Check out [Name] — it's [one-line description] for [audience]." Record which one you hesitate on.
+3. **Test with 3-5 people in the target audience.** Show the name + one-line description, zero context. Ask: "What do you think this product does?" and "Who do you think this is for?"
+4. **Check trademark (USPTO TESS or equivalent).** Search each finalist for live marks in relevant classes (typically Class 42 for SaaS, Class 35 for employment/business services, Class 9 for software). International: check WIPO if targeting non-US markets.
+5. **Check social handles.** @[Name] on LinkedIn, X/Twitter, Instagram, Facebook. Minor variations (underscores, "get" prefix) are acceptable but not ideal.
+
+### After selecting
+
+1. **Write an implementation spec** (separate document) covering:
+   - Codebase rename (package.json, imports, env vars, internal references)
+   - Domain registration and DNS migration
+   - SSL certificates for new domain
+   - Redirect strategy (301 from old domain; preserve SEO equity)
+   - Asset regeneration (logos, favicons, OG images, email templates)
+   - In-app copy sweep (grep for old name in all user-facing strings)
+   - Marketing surface update (landing, About, Help, social profiles, app store listings)
+   - Legal (entity name alignment if needed; terms of service; privacy policy)
+   - Notification to existing users (email, in-app banner)
+   - Timeline and phasing (can be done in one sprint or staged)
+
+2. **Update BRAND_AND_PRODUCT.md** with the new name, adapted tagline, and updated origin story closing.
+
+3. **Update CONTEXT_PROMPT.md** so AI assistants use the new name.
+
+---
+
+## 10. What does not change
+
+_Regardless of the name, these elements of the brand remain constant. Listing them explicitly prevents scope creep during the rename._
+
+- **Brand voice** — [tone keywords from BRAND_AND_PRODUCT.md]
+- **Visual identity** — [colors, design sensibility from DESIGN_SYSTEM.md]
+- **Category** — [product category from BRAND_AND_PRODUCT.md]
+- **Core tagline structure** — [the pattern, even if the words adapt]
+- **Origin story** — [the narrative is the narrative; only the closing line changes]
+- **Legal entity** — [entity name does not need to match product name, if applicable]
+
+---
+
+## Appendix: Naming anti-patterns
+
+> 🔧 **Guidance:** Common failure modes in product naming, observed across projects.
+
+### Naming before brand clarity
+
+Choosing a name before BRAND_AND_PRODUCT.md exists means the name is not anchored to anything. It will drift as the product evolves, and you will end up here again in 6-12 months. Define voice, audience, positioning, and differentiators first.
+
+### Thesaurus naming
+
+Generating candidates from a thesaurus or random word lists without grounding them in the product's own language. The result sounds clever in isolation but feels foreign in the product's actual copy. Always extract themes from your own docs first (§3). The §4 vocabulary expansion process channels the brainstorming energy productively — you still generate a broad word list, but you bucket it against your themes rather than combining words at random.
+
+### Falling in love with unavailable names
+
+Spending emotional energy on a name before checking domain + trademark + social handle availability. Check availability early and often. A great name you cannot own is not a great name.
+
+### Optimizing for cleverness over clarity
+
+A name that requires explanation adds friction at every touchpoint: ads, referrals, cold outreach, search results. For most B2B products, **clear beats clever**. "What does this product do?" should be answerable from the name alone, or at minimum, the name should not actively mislead.
+
+### Ignoring how the name sounds in speech
+
+Many names are evaluated visually (on a slide, in a doc) but experienced aurally (in a meeting, on a call, in a podcast). Say every candidate out loud. Spell it to an imaginary customer service agent over the phone. If it requires clarification ("that's one word, no hyphen, C-A-L-I-B-E-R"), factor that cost in.
+
+### Two-word names where both words say the same thing
+
+"SmartGenius," "QuickFast," "PrepReady" — redundant pairs waste a word. The strongest two-word names combine two **different** signals: audience + state, action + quality, category + differentiator.
+
+### Naming by committee without a framework
+
+Without explicit criteria and weights (§8), naming discussions become aesthetic arguments with no resolution mechanism. The framework does not make the decision — the founder/team does — but it ensures the conversation is structured around what matters.

package/docs/NPM.md

@@ -0,0 +1,98 @@
+# Publishing ForgeTrail to npm
+
+You run `pnpm publish`. The gate does not log in or publish.
+
+Two public unscoped packages:
+
+| Package | Version | From | What it is |
+| --- | --- | --- | --- |
+| [`forgetrail`](https://www.npmjs.com/package/forgetrail) | 0.3.0 | repo root | CLI + Lite + templates. `npx forgetrail install --lite` |
+| [`forgetrail-mcp`](https://www.npmjs.com/package/forgetrail-mcp) | 0.2.2 | `mcp-server/` | MCP bin. `npx -y forgetrail-mcp` |
+
+These are **installer and MCP channels**, not a library. App repos should not add `forgetrail` to `dependencies`.
+
+`pnpm run pack:check` already passed on this tree (2026-08-20). Root dry-run packed `forgetrail@0.3.0` (98 files, no `site/` or `specs/`).
+
+---
+
+## Once (this machine)
+
+```bash
+pnpm login
+pnpm whoami
+```
+
+Use an npm account that can publish **unscoped** public packages.
+
+---
+
+## First publish (paste in order)
+
+From the repo root, on `main`, **clean working tree** (pnpm refuses `publish` if git is dirty). Push first if you want the published tarball to match GitHub.
+
+```bash
+# 1. Gate (rebuilds mcp-server/dist)
+pnpm run pack:check
+
+# 2. CLI + methodology
+pnpm publish --dry-run --access public
+pnpm publish --access public
+
+# 3. MCP server (prepublishOnly runs tsc)
+pnpm --dir mcp-server publish --dry-run --access public
+pnpm --dir mcp-server publish --access public
+```
+
+`prepublishOnly` on the root re-runs the pack check. It refuses `private: true` and a tarball that includes `site/` or `specs/`.
+
+---
+
+## After publish (verify)
+
+```bash
+# fresh npx, not your clone
+npx --yes forgetrail@0.3.0 --help
+npx --yes forgetrail@0.3.0 install --lite --dry-run
+
+# MCP starts; needs content via FORGETRAIL_ROOT or a sibling forgetrail install
+npx --yes forgetrail-mcp@0.2.2
+```
+
+Optional Cursor MCP (content from a `forgetrail` install, or set the path):
+
+```json
+{
+  "mcpServers": {
+    "forgetrail": {
+      "command": "npx",
+      "args": ["-y", "forgetrail-mcp"],
+      "env": {
+        "FORGETRAIL_ROOT": "/path/to/node_modules/forgetrail"
+      }
+    }
+  }
+}
+```
+
+If `forgetrail` is installed in the same tree, `forgetrail-mcp` finds `WORKFLOW.md` without `FORGETRAIL_ROOT`.
+
+Registry pages to confirm:
+
+- https://www.npmjs.com/package/forgetrail
+- https://www.npmjs.com/package/forgetrail-mcp
+
+---
+
+## Later releases
+
+1. Bump `version` in `package.json` and/or `mcp-server/package.json` (independent versions are OK).
+2. Repeat the three publish blocks above.
+3. GitHub `main` stays canonical. npm versions are snapshots.
+
+---
+
+## Do not publish
+
+- `site/` (FilePress marketing app)
+- `specs/` (methodology-repo meta-specs)
+- `.cursor/`

package/docs/PHASE_1_BRIEF.md

@@ -0,0 +1,161 @@
+# [App Name] — Phase 1 architecture brief
+
+_Structured capture of planning and architecture **before** code scaffolding. Goal: Phase 2 (or a new agent/session) can start from this file + `.forgetrail/workflow_tracking.json` without re-reading the whole Phase 1 chat._
+
+**Status:** `[draft | locked]`  
+**Last updated:** `[ISO date]`  
+**Phase 1 exit:** Do not mark Phase 1 complete in `.forgetrail/workflow_tracking.json` until this brief is **locked** and major commitments are in `decisions[]`.
+
+---
+
+## 1. Problem and outcome
+
+**What we are building (2–4 sentences):**
+
+
+**Project archetype:** `[product | internal-tool | one-shot]` _(WORKFLOW.md §1d — non-`product` archetypes prune later-phase exit criteria in the tracking file; log the pruning in `decisions[]`)_
+
+**What “done” looks like for v1 (measurable where possible):**
+
+
+---
+
+## 2. Users and hero flow
+
+**Primary user(s):**
+
+
+**The single most important workflow (hero flow) end-to-end:**
+
+
+**Secondary workflows (if any) for v1:**
+
+
+---
+
+## 3. Constraints
+
+_Hard requirements the stack and design must respect._
+
+- **Technical:** (e.g. must run on X, offline, no PII region, etc.)
+- **Business / timeline:**
+- **Explicit non-goals for v1:** (link to section 9 for detail)
+
+---
+
+## 4. Stack and tooling
+
+_Confirmed choices only after user sign-off. Mirror the same choices into `CONTEXT_PROMPT.md` → Tech Stack in Phase 2._
+
+| Area            | Choice   | Status (proposed / confirmed) | Notes / WHY |
+| --------------- | -------- | ----------------------------- | ----------- |
+| Framework       |          |                               |             |
+| Language        |          |                               |             |
+| DB / backend    |          |                               |             |
+| Auth / storage  |          |                               |             |
+| Styling         |          |                               |             |
+| Deploy / CI     |          |                               |             |
+| Package manager |          |                               |             |
+
+---
+
+## 5. Data model (sketch)
+
+_Entities and relationships — not full schemas. Enough for Phase 2 scaffolding._
+
+**Core entities:**
+
+
+**Relationships:**
+
+
+**Existing data / migration:** _(none | describe import path)_
+
+
+---
+
+## 6. Integrations and external systems
+
+_APIs, webhooks, LLM, payments, email, analytics, etc._
+
+| Integration | Purpose | Auth / secrets | Risk notes |
+| ------------- | ------- | -------------- | ---------- |
+| LLM (if any)  | Content generation | Cloud: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, … **or** local: `OLLAMA_BASE_URL`, `OLLAMA_MODEL` (no cloud key) | Rate limits; field size limits; validate JSON at boundary |
+
+---
+
+## 6a. Content-generation pattern (only if LLM-produced content)
+
+_Skip if content is hand-authored or from a non-LLM API._
+
+| Field | Value |
+| ----- | ----- |
+| **Pattern** | _runtime API \| build-time seed \| BYO-LLM paste_ |
+| **Provider / model** | _e.g. `openai/gpt-4o-mini`, `anthropic/claude-sonnet`, `ollama/ibm/granite4.1:8b`, `ollama/gemma3:4b`, BYO only_ |
+| **Env vars** | _cloud keys and/or `OLLAMA_BASE_URL`, `OLLAMA_MODEL`_ |
+| **Ollama launchers** (local runtime) | _setup-ollama.bat, test-ollama.bat after Phase 2 scaffold_ |
+| **Validator / paths** | _e.g. Zod at `src/lib/...`, `data/seed.json`, prompt in `prompts/seed.md`_ |
+
+> 💡 **Lesson learned:** **Local Ollama** fits the same three patterns as cloud — runtime routes call `/api/generate`; build-time seed calls Ollama once; BYO-LLM can mean the user runs a prompt in the Ollama desktop app and pastes JSON. Prefer **Granite 4.1** or **Gemma 3** for general product features; avoid reasoning-only models unless v1 explicitly needs chain-of-thought. See **ForgeTrail Lite** §7.1 and §4.8.
+
+---
+
+## 7. Hardest problems and risks
+
+_What could blow schedule or architecture — honest list._
+
+1.
+2.
+3.
+
+---
+
+## 8. Architectural decisions (numbered)
+
+_Each decision should include **WHY** and what was rejected. **Also** add each major commitment to `.forgetrail/workflow_tracking.json` → `decisions[]` (id, timestamp, phase, decision, rationale, alternatives_considered)._
+
+**D1.**
+
+
+**D2.**
+
+
+**D3.**
+
+
+_(Add D4+ as needed.)_
+
+---
+
+## 9. Open questions (before or during Phase 2)
+
+_Items that are not yet decided. Resolve or explicitly defer._
+
+| # | Question | Owner / resolve by |
+| - | -------- | ------------------ |
+|   |          |                    |
+
+---
+
+## 10. Explicitly out of scope (v1)
+
+_Bullet list — prevents scope creep during scaffold._
+
+
+---
+
+## 11. First feature batch (post-scaffold)
+
+_Ordered list of what to build after the spine runs — aligns with initial `TODO.md`._
+
+
+---
+
+## 12. Handoff checklist (before leaving Phase 1)
+
+- [ ] User has confirmed stack, folder shape, data sketch, hero flow, and v1 boundaries
+- [ ] This brief is **locked** (no `[draft]` ambiguity) or remaining items are only in §9 Open questions
+- [ ] `.forgetrail/workflow_tracking.json` updated: `decisions[]` for each major D#; `phases["1-architecture"]` notes summarize sign-off
+- [ ] Phase 2 opener will read **this file** + `.forgetrail/workflow_tracking.json` first
+
+> 💡 **Lesson learned:** Treat the brief and `decisions[]` as a pair: JSON is great for machine-structured history; the brief is great for the next human or agent to read in one pass. Duplicated rationale is OK — drift between them is not. After Phase 2 starts, **merge** this content into `CONTEXT_PROMPT.md` per the mapping in that template’s “Handoff from Phase 1” section.