forgetrail 0.3.0

package/docs/README.md

@@ -0,0 +1,75 @@
+# [App Name]
+
+*[One-line description. What it does, who it's for.]*
+
+*Instructions: Create this during Phase 2 (Scaffolding). Keep it focused on "how to get running" for a new developer. Feature documentation belongs in TECHNICAL_REFERENCE.md, not here.*
+
+## Setup
+
+### Prerequisites
+
+- [Runtime]: [version] (e.g., Node.js 18+)
+- [Package manager]: [version] (e.g., pnpm 8+)
+- [Database]: [version] (e.g., PocketBase 0.23+)
+- [Other]: [if applicable]
+
+### Installation
+
+```bash
+# Clone the repo
+git clone [repo-url]
+cd [project-name]
+
+# Install dependencies
+[package-manager] install
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your values (see Environment Variables below)
+
+# Start development server
+[package-manager] dev
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| [VAR] | [yes/no] | [what it does, where to get the value] |
+
+## Project Structure
+
+```
+[project-root]/
+  src/
+    lib/
+      components/     [UI components]
+      server/         [Backend services]
+      types/          [TypeScript types]
+    routes/
+      api/            [API endpoints]
+      [pages]/        [App pages]
+  static/             [Static assets]
+  docs/               [Project documentation]
+```
+
+## Features
+
+| Feature | Description | Location |
+|---------|-------------|----------|
+| [Feature] | [What it does] | [Where in the app] |
+
+## Tech Stack
+
+- **Framework:** [name + version]
+- **Language:** [name]
+- **Styling:** [name]
+- **Database:** [name]
+- **AI:** [name, or "none"]
+
+## Documentation
+
+- [TECHNICAL_REFERENCE.md](docs/TECHNICAL_REFERENCE.md) - How features work
+- [BRAND_AND_PRODUCT.md](docs/BRAND_AND_PRODUCT.md) - Positioning and messaging
+- [DEPLOYMENT.md](docs/DEPLOYMENT.md) - Production deployment
+- [TODO.md](docs/TODO.md) - Feature backlog

package/docs/SPEC_FEATURE_TEMPLATE.md

@@ -0,0 +1,155 @@
+# [Feature name] — feature spec
+
+_Copy into your app repo as `specs/[feature-name].md` (kebab-case). Fill bracketed placeholders. Delete guidance blockquotes before locking the draft if you want a lean file. For MCP: `getTemplate({ name: "SPEC_FEATURE_TEMPLATE" })`._
+
+**Spec kind:** `[Delivery | Canonical reference]`  
+**Status:** `[Draft | Partial | Implemented | Canonical; …]`  
+**Date:** `[YYYY-MM-DD]`  
+**Related:** `[TODO.md item, PHASE_1_BRIEF, other specs, issues]`  
+**Surfaces (optional):** `[components, routes, scripts this touches]`
+
+> 🔧 **Guidance:** Use **Delivery** for time-boxed feature work (lifecycle: `specs/` → `partial/` → `completed/`). Use **Canonical reference** only for living catalogs that stay in `specs/canonical/` and never move for “done.” See ForgeTrail WORKFLOW.md Phase 4 and `.cursor/rules/specs-and-todo.mdc` when present.
+
+> 🔧 **Lite cut:** For a small change, keep header + §1–§3 + §5 (proposed behavior only) + §8 + §9. Skip data/API/UI subsections that do not apply. Still require testable acceptance criteria.
+
+---
+
+## 1. Problem
+
+**What is painful today:**
+
+
+**Friction / current workaround (if any):**
+
+
+---
+
+## 2. Goals
+
+1.
+2.
+3.
+
+### Non-goals
+
+_What this pass will not do. Prevents scope creep._
+
+-
+-
+
+---
+
+## 3. Background / current state
+
+_Optional. What exists today (code, data, UX) that the builder must know. Link files; do not paste large dumps._
+
+
+---
+
+## 4. Core concepts / definitions
+
+_Optional. Domain terms, enums, or mental model unique to this feature._
+
+
+---
+
+## 5. Proposed approach / Design
+
+_Prefer **what** the system does over **how** to implement it, unless a format or existing module forces a path. Delete subsections that do not apply._
+
+### 5.1 Behavior
+
+_When the user does X, the system does Y. Step-by-step or bullets._
+
+
+### 5.2 Data model
+
+_Entities, fields, migrations, PocketBase collections, local storage keys, etc._
+
+
+### 5.3 API / integrations
+
+_Routes, webhooks, LLM calls, external APIs, env vars._
+
+
+### 5.4 UI / UX
+
+_Surfaces, empty/loading/error states, copy notes, a11y._
+
+
+### 5.5 Files (optional)
+
+| New | Modified |
+| --- | -------- |
+|     |          |
+
+---
+
+## 6. Edge cases and risks
+
+-
+-
+
+| Risk | Mitigation |
+| ---- | ---------- |
+|      |            |
+
+---
+
+## 7. Milestones / phasing (optional)
+
+| Milestone | Outcome |
+| --------- | ------- |
+| M1        | Smallest usable slice |
+| M2        |                         |
+
+---
+
+## 8. Acceptance criteria
+
+_Testable. Prefer “Given / when / then” or checkbox style. The feature is not done until these pass._
+
+1. Given …, when …, then …
+2. Given …, when …, then …
+
+---
+
+## 9. Open questions
+
+| # | Question | Blocking? | Owner |
+| - | -------- | --------- | ----- |
+| 1 |          | yes/no    |       |
+
+---
+
+## 10. Decisions (optional)
+
+_Lock choices here (and mirror major ones into `.forgetrail/workflow_tracking.json` → `decisions[]` when they are architectural)._
+
+**D1.**
+
+
+---
+
+## Progress (while Partial)
+
+_Date-stamped notes while work is in `specs/partial/`. Remove or fold into Implementation summary when completed._
+
+- `[YYYY-MM-DD]:` …
+
+---
+
+## Implementation summary
+
+_Required when moving a **Delivery** spec to `specs/completed/`. Leave empty until then._
+
+**Implemented:** `[YYYY-MM-DD]`
+
+1. …
+2. …
+
+**Verification:** `[e.g. pnpm check / test / manual walkthrough]`
+
+---
+
+> 💡 **Lesson learned:** Specs are session anchors. When the agent context resets, a filled spec plus `TODO.md` beats rediscovering intent from chat. Write the spec **before** multi-file implementation; move it to `partial/` when work starts; append this summary and move to `completed/` when acceptance criteria are met.

package/docs/SPEC_UI_CHROME_NAV_TEMPLATE.md

@@ -0,0 +1,48 @@
+# Spec: UI Chrome, Layout & Nav Flyouts (template)
+
+_Copy this file into your app as e.g. `docs/SPEC_UI_CHROME_NAV.md` when you ship substantial nav, typography, or nested-menu work. Fill `[BRACKETED]` placeholders and remove this header._
+
+**Purpose:** Capture **invariants** for typography roles, app shell height, interactive rounding, and nested dropdown flyouts so future sessions do not re-litigate the same layout and hover bugs.
+
+---
+
+## Typography
+
+- **Chrome / UI:** `[sans stack]` — nav, filters, column headers, short labels.
+- **Reading / long-form:** `[serif or alternate stack]` — `[where it applies: e.g. narrative panels, prep content]`.
+
+---
+
+## App shell
+
+- Outer: `[e.g. flex flex-col h-screen overflow-hidden]`
+- Nav: `shrink-0`
+- Main: `flex-1 min-h-0` + scroll **inside** main where needed  
+**Invariant:** Avoid `[calc(100vh − X)]` unless `[nav height]` is verified per breakpoint.
+
+---
+
+## Interactive controls
+
+- Default radius for buttons/inputs/pills: `[e.g. rounded-lg]`
+- Document exceptions (cards, modals) explicitly.
+
+---
+
+## Nested menu flyouts
+
+| Topic | Rule |
+|-------|------|
+| Shared chrome | One CSS class for surface/border/shadow on secondary panels |
+| Padding context | `[Describe: padded vs full-width menu rows]` — `absolute` children measure from different boxes; test gaps side by side |
+| Large panels | Center vertically on trigger + `max-height` + internal scroll; do not clip off-screen with `bottom: 0` only |
+| Hover state | Stable **id** per flyout; re-enter same id → cancel timers only; reset all when **parent menu** closes |
+| Anti-pattern | Do not clear all flyouts on every `mouseenter` |
+
+---
+
+## Revision history
+
+| Date | Notes |
+|------|--------|
+| `[ISO date]` | Initial spec |