create-appystack 0.1.0

package/template/.claude/skills/recipe/domains/youtube-launch-optimizer.md

@@ -0,0 +1,154 @@
+# Sample: YouTube Launch Optimizer
+
+A content production tool for YouTube creators. Manages the full lifecycle of a video from idea through launch — scripts, thumbnails, SEO, and launch checklist tasks.
+
+**Use with**: `file-crud` recipe. Optionally combine with `nav-shell` recipe.
+
+---
+
+## Entities
+
+### Channel
+A YouTube channel being managed. Most users will have one; power users may manage several.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `name` | string | **namish field** — channel display name |
+| `handle` | string | e.g. `@AppyDave` |
+| `niche` | string | e.g. 'AI Tools', 'Coding Tutorials' |
+| `targetAudience` | string | brief description |
+| `contentPillars` | string[] | e.g. ['Claude Code', 'BMAD Method', 'AppyStack'] |
+
+Namish field: `name`
+Example filename: `appydave-a1b2c.json`
+
+---
+
+### Video
+A video being produced. Central entity — most other entities link to a video.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `title` | string | **namish field** — working title |
+| `channelId` | string | FK → Channel |
+| `status` | string | 'idea' / 'scripting' / 'recorded' / 'editing' / 'ready' / 'published' |
+| `publishDate` | string | ISO date, optional |
+| `youtubeId` | string | once published |
+| `hooks` | string[] | attention-grabbing opening lines |
+| `seoKeyword` | string | primary keyword |
+| `description` | string | YouTube description |
+| `tags` | string[] | |
+
+Namish field: `title`
+Example filename: `how-to-build-your-first-appystack-app-k3p7r.json`
+Relationship: `channelId` → Channel
+
+---
+
+### Script
+The script or detailed outline for a video.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `title` | string | **namish field** — usually matches video title |
+| `videoId` | string | FK → Video |
+| `version` | number | allows multiple script iterations |
+| `hook` | string | opening line |
+| `sections` | object[] | array of `{ heading, content, duration }` |
+| `cta` | string | call to action |
+| `totalDuration` | number | estimated minutes |
+
+Namish field: `title` + version composite → `how-to-build-appystack-v2-m9x4k.json`
+Relationship: `videoId` → Video
+
+---
+
+### ThumbnailVariant
+A thumbnail concept or A/B test variant for a video.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `label` | string | **namish field** — e.g. 'Face + text', 'Curiosity gap', 'Before/After' |
+| `videoId` | string | FK → Video |
+| `concept` | string | description of the visual idea |
+| `mainText` | string | large text on thumbnail |
+| `subText` | string | smaller supporting text |
+| `emotion` | string | the feeling to convey |
+| `selected` | boolean | which variant was used |
+| `ctrEstimate` | number | optional estimated CTR % |
+
+Namish field: `label`
+Example filename: `face-plus-text-variant-p2m8n.json`
+Relationship: `videoId` → Video
+
+---
+
+### LaunchTask
+A checklist item to complete before or after publishing a video.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `title` | string | **namish field** — task description |
+| `videoId` | string | FK → Video |
+| `category` | string | 'pre-launch' / 'day-of' / 'post-launch' |
+| `completed` | boolean | |
+| `dueDate` | string | optional |
+| `notes` | string | optional |
+
+Namish field: `title`
+Example filename: `upload-thumbnail-to-youtube-studio-r7k2m.json`
+Relationship: `videoId` → Video
+
+---
+
+## Entity Classification
+
+| Entity | Type | Notes |
+|--------|------|-------|
+| Channel | System / configuration | Set up once |
+| Video | Domain / operational | Core working entity |
+| Script | Domain / operational | Created per video, iterated |
+| ThumbnailVariant | Domain / operational | Multiple per video for A/B |
+| LaunchTask | Domain / operational | Checklist items per video |
+
+---
+
+## Suggested Nav Mapping (for nav-shell recipe)
+
+| Nav Item | View Key | Entity | Tier |
+|----------|----------|--------|------|
+| Dashboard | `dashboard` | — (videos by status) | primary |
+| Videos | `videos` | Video | primary |
+| Scripts | `scripts` | Script | primary |
+| Thumbnails | `thumbnails` | ThumbnailVariant | primary |
+| Launch | `launch` | LaunchTask | primary |
+| Channels | `channels` | Channel | secondary |
+
+**Context-aware nav suggestion**: When viewing a specific Video, the sidebar could switch to show Script, Thumbnails, and LaunchTasks for that video (context-aware menu pattern from nav-shell recipe).
+
+---
+
+## Data Folder Structure
+
+```
+data/
+├── channels/
+│   └── appydave-a1b2c.json
+├── videos/
+│   └── how-to-build-your-first-appystack-app-k3p7r.json
+├── scripts/
+│   └── how-to-build-appystack-v2-m9x4k.json
+├── thumbnail-variants/
+│   └── face-plus-text-variant-p2m8n.json
+└── launch-tasks/
+    └── upload-thumbnail-to-youtube-studio-r7k2m.json
+```
+
+---
+
+## Notes
+
+- Videos are the central entity. Most other entities have a `videoId` FK — consider always showing which video context you're in.
+- The context-aware menu pattern from `nav-shell` is especially useful here: when you open a Video's detail view, the sidebar can switch to show that video's Scripts, Thumbnails, and LaunchTasks directly.
+- `LaunchTask` items could be seeded from a template for every new video (same checklist each time). This is a developer-implemented pattern; the recipe scaffolds the entity, not the seeding logic.
+- `ThumbnailVariant` with `selected: true` indicates which variant was actually used. Only one should be selected per video.

package/template/.claude/skills/recipe/references/file-crud.md

@@ -0,0 +1,295 @@
+# Recipe: File-Based JSON Persistence
+
+Multiple entities stored as individual JSON files on the server filesystem. Socket.IO bridges client actions to the filesystem and broadcasts changes back to all connected clients in real time. No database required — the `data/` folder IS the database.
+
+This recipe suits local tools, small-team apps, and rapid prototyping. It also enables a **local-first workflow**: users work with local files, then publish to a central database when ready (see Local-First Pattern below).
+
+---
+
+## Recipe Anatomy
+
+**Intent**
+Scaffold server-side JSON file persistence for one or more domain entities, with real-time Socket.io sync to connected clients. Each record is a human-readable JSON file. All clients see updates live.
+
+**Type**: Seed for initial entities. Migration-friendly for adding new entities (additive, non-destructive). Run once with all entities upfront, or entity-by-entity.
+
+**Stack Assumptions**
+- Express 5, Socket.io, TypeScript, Node.js `fs/promises`
+- chokidar (verify in `server/package.json`; add if missing)
+- `data/` folder at repo root
+
+**Idempotency Check**
+Does `server/src/data/fileStore.ts` exist? If yes → infrastructure is already installed. Only generate entity-specific route and type files for new entities.
+
+**Does Not Touch**
+- `client/` — client-side views are the shell recipe's or developer's concern
+- `server/src/index.ts` — instructs developer to mount the generated routes; does not rewrite it
+- Authentication or authorization
+- Entity relationships (foreign keys, join queries) — flagged as TODOs in generated type stubs
+- Contents of `data/` — creates folder structure only
+
+**Composes With**
+- `nav-shell` recipe — each entity can have a nav item; views switch to entity CRUD screens
+- `domain-preparation` step — before combining shell + persistence, collect entity definitions once
+
+---
+
+## Folder Structure
+
+```
+project-root/
+├── data/                              ← at repo root (not inside client or server)
+│   └── {entity-plural}/               ← one folder per entity (e.g. companies/, sites/)
+│       └── {name-slug}-{5char}.json   ← individual records
+├── server/src/
+│   ├── data/
+│   │   ├── fileStore.ts               ← read/write/delete individual record files
+│   │   ├── idgen.ts                   ← 5-char alphanum ID generator
+│   │   └── watcher.ts                 ← chokidar watcher, emits Socket.io events on change
+│   ├── routes/
+│   │   └── {entity}.ts                ← REST endpoints (initial loads + server-to-server)
+│   └── sockets/
+│       └── {entity}Handlers.ts        ← Socket.io event handlers per entity
+└── shared/src/types/
+    ├── entity.ts                      ← base EntityRecord, EntityIndex types
+    └── {entity}.ts                    ← entity-specific field types (generated stubs)
+```
+
+---
+
+## File Naming Convention and Primary Key
+
+**The 5-char alphanumeric ID is the record's primary key.** It is embedded in the filename, generated once at creation, and never changes — even when the record's name changes.
+
+```
+File name pattern:  {name-slug}-{5char-id}.json
+
+Examples:
+  name = "NERO Banana"          → nero-banana-a7k3p.json
+  name = "David Kruwys"         → david-kruwys-a1f4q.json  (ID: a1f4q)
+  name corrected to "David Cruwys" → david-cruwys-a1f4q.json  (same ID, new slug)
+  name = "Acme Corp"            → acme-corp-x9q2m.json
+  name = "St. Mary's Group Home" → st-marys-group-home-k3p7r.json
+```
+
+**Why this matters**: If the name changes, the slug prefix in the filename changes but the 5-char suffix stays constant. The ID is how you find, update, and delete a record regardless of what the name is. This is the stable identity; the slug is the human label.
+
+**Why this avoids Git merge conflicts**: Two users creating different records produce two different files. No shared file is written per-operation (unlike a stored `index.json`). Two users can create, rename, or delete different records simultaneously and push to the same Git branch with zero conflicts.
+
+### Slug Rules
+
+```
+- Take the entity's "namish" field (usually `name`; sometimes a composite or alternative field)
+- Lowercase
+- Replace spaces and special characters with hyphens
+- Collapse multiple hyphens to one
+- Strip leading/trailing hyphens
+- Maximum 40 characters (truncate without breaking mid-word where possible)
+```
+
+### ID Generation
+
+```typescript
+// server/src/data/idgen.ts
+export function generateId(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
+  return Array.from({ length: 5 }, () =>
+    chars[Math.floor(Math.random() * chars.length)]
+  ).join('')
+}
+// Collision probability at 1,000 records: ~0.015% — acceptable for local/small-team use
+```
+
+---
+
+## Index Strategy: Inferred (Not Stored)
+
+**There is no `index.json` file.** The list of records is built by reading the entity folder at request time and optionally reading each file for summary fields. This is inferred, not stored.
+
+**Why**: A stored `index.json` is written on every create, rename, and delete — it becomes a conflict magnet when multiple users work simultaneously on Git. With inferred indexing, each user's changes touch only their own files.
+
+**Performance**: Folder scan at 1,000 records = ~5-20ms (filenames only). Reading all files for summary fields = ~50-200ms. Acceptable for local/small-team tools. Cache mitigates repeated calls.
+
+### In-Memory Cache
+
+The server maintains a per-entity index cache. chokidar invalidates it on any file change.
+
+```typescript
+// server/src/data/fileStore.ts
+
+const indexCache = new Map<string, EntityIndex[]>()
+
+export async function listRecords(entity: string): Promise<EntityIndex[]> {
+  if (indexCache.has(entity)) return indexCache.get(entity)!
+
+  const folder = path.join('./data', entity)
+  const files = (await fs.readdir(folder)).filter(f => f.endsWith('.json'))
+
+  const index = await Promise.all(files.map(async (filename) => {
+    const id = extractId(filename)              // last segment before .json
+    const slug = extractSlug(filename)           // everything before the last -xxxxx
+    const content = JSON.parse(await fs.readFile(path.join(folder, filename), 'utf-8'))
+    return { id, name: content.name ?? slugToName(slug), filename }
+  }))
+
+  indexCache.set(entity, index)
+  return index
+}
+
+// Called by chokidar on any change in data/
+export function invalidateCache(entity: string) {
+  indexCache.delete(entity)
+}
+```
+
+---
+
+## Shared Types
+
+```typescript
+// shared/src/types/entity.ts
+
+export interface EntityRecord {
+  id: string      // extracted from filename (primary key), NOT stored in the file body
+  name: string    // the "namish" field — used to derive the filename slug
+  [key: string]: unknown
+}
+
+export interface EntityIndex {
+  id: string
+  name: string
+  filename: string
+}
+
+export function extractId(filename: string): string {
+  return filename.replace(/\.json$/, '').split('-').pop() ?? ''
+}
+```
+
+Entity-specific types extend `EntityRecord`:
+
+```typescript
+// shared/src/types/company.ts
+export interface Company extends EntityRecord {
+  name: string
+  // TODO: add domain-specific fields
+  // TODO: add relationship FKs if needed (e.g. siteIds: string[])
+}
+```
+
+---
+
+## Socket.io Events
+
+```typescript
+// Client → Server (commands)
+socket.emit('entity:list',   { entity: 'company' })
+socket.emit('entity:get',    { entity: 'company', id: 'a7k3p' })
+socket.emit('entity:save',   { entity: 'company', record: { name: 'NERO Banana', ...fields } })
+  // record.id present → update; record.id absent → create
+socket.emit('entity:delete', { entity: 'company', id: 'a7k3p' })
+
+// Server → requesting client
+socket.emit('entity:list:result', { entity: 'company', records: EntityIndex[] })
+socket.emit('entity:get:result',  { entity: 'company', record: EntityRecord })
+
+// Server → ALL clients (broadcast on state change)
+io.emit('entity:created', { entity: 'company', record: EntityRecord, index: EntityIndex })
+io.emit('entity:updated', { entity: 'company', record: EntityRecord, index: EntityIndex })
+io.emit('entity:deleted', { entity: 'company', id: string })
+
+// Server → ALL clients (chokidar: external file change detected)
+io.emit('entity:external-change', { entity: 'company', changeType: 'add'|'change'|'unlink', id: string })
+```
+
+**`entity:created` vs `entity:updated` are separate events.** The client UI often treats them differently — scroll to new record, highlight on update, different toast messages.
+
+**REST endpoints** (`server/src/routes/{entity}.ts`) are generated alongside Socket.io handlers. REST is useful for initial page loads, debugging, health checks, and server-to-server calls. Socket.io is the primary real-time path.
+
+---
+
+## CRUD Operations Summary
+
+| Operation | Client emits | Server does | Server broadcasts |
+|-----------|-------------|-------------|-------------------|
+| List | `entity:list` | reads folder, builds index (cached) | `entity:list:result` to requester |
+| Get | `entity:get` | reads record file | `entity:get:result` to requester |
+| Create | `entity:save` (no id) | generates id, writes file, invalidates cache | `entity:created` to all |
+| Update | `entity:save` (with id) | renames file if name changed, writes, invalidates cache | `entity:updated` to all |
+| Delete | `entity:delete` | deletes file, invalidates cache | `entity:deleted` to all |
+| External change | — | chokidar detects file change | `entity:external-change` to all |
+
+---
+
+## Multi-Entity Support
+
+When the recipe is applied for multiple entities (e.g. Company, Site, User, Incident):
+
+**What the recipe generates:**
+- `server/src/data/fileStore.ts` — entity-agnostic (handles any entity name as a string param)
+- `server/src/data/idgen.ts` — shared ID generator
+- `server/src/data/watcher.ts` — watches `data/` folder, entity-agnostic
+- Per entity: `server/src/sockets/{entity}Handlers.ts`
+- Per entity: `server/src/routes/{entity}.ts`
+- Per entity: `shared/src/types/{entity}.ts` — stub with TODO comments
+
+**What remains the developer's job:**
+- Define actual field shapes in entity type stubs
+- Implement entity relationship lookups (foreign key references)
+- Mount generated routes in `server/src/index.ts`
+- Add validation rules for entity-specific business logic
+- Build client-side view components (`useEntity` hook is generated; views are not — unless shell recipe ran first)
+
+---
+
+## Local-First Pattern
+
+The file-based persistence layer also enables a local-first workflow:
+
+**The pattern:**
+1. Users run the app locally — all data lives in `data/` as JSON files
+2. Multiple users can work simultaneously (different records = different files = no conflicts)
+3. When ready, a **publish** action pushes the local JSON data to a central database or API
+4. This can be triggered manually (publish button) or automatically on save
+
+**The use case:** Build all application screens and let stakeholders interact with real data shapes before the backend database exists. When the backend is ready, wire up a publish step that sends the local JSON records to it. The frontend never changes — only the persistence layer swaps out.
+
+**What the recipe provides:** The local file layer. The publish-to-database step is a separate recipe (`publish-to-db`) that wraps the file layer and adds the sync mechanism. Not included in this recipe.
+
+---
+
+## Sample Data Patterns
+
+Domain-specific entity setups for common application types. See the `samples/` folder:
+
+- [`samples/support-signal.md`](../samples/support-signal.md) — NDIS/disability support: Company, Site, User, Incident, MomentThatMatters
+- [`samples/youtube-launch-optimizer.md`](../samples/youtube-launch-optimizer.md) — YouTube content: Channel, Video, Script, ThumbnailVariant, LaunchTask
+
+Each sample defines: entity names, namish fields, key domain fields, relationships, and suggested nav mapping. Use a sample as the input to the recipe's entity questions.
+
+---
+
+## Alternative Persistence Recipes
+
+These are separate recipes for when file-based JSON is not the right fit:
+
+| Recipe | When to Use |
+|--------|-------------|
+| `file-csv` | Humans need to edit data in Excel/Numbers; export to external systems; compliance reporting |
+| `sqlite-drizzle` | Entity count grows large (thousands+); complex queries; referential integrity required |
+| `in-memory` | Development and testing only; full Socket.io loop without touching the filesystem |
+
+The Socket.io event spec is identical across all persistence recipes. The client never knows whether the server is reading files, a database, or memory. Persistence is swappable.
+
+---
+
+## What to Generate in the Build Prompt
+
+When generating the prompt for this recipe, collect:
+
+1. **Entity names** — what entities does the app need? (e.g. Company, Site, User)
+2. **Namish field** — for each entity, what field is used to name/slug the file? (usually `name`; sometimes a composite)
+3. **Key fields** — domain-specific fields per entity
+4. **Relationships** — which entities reference others? → adds TODO FK comments to type stubs
+5. **Status field?** — does each entity need an active/inactive or draft/published status?
+6. **Gitignore `data/`?** — recommended: yes for production data, no for seeded sample data

package/template/.claude/skills/recipe/references/nav-shell.md

@@ -0,0 +1,233 @@
+# Recipe: Visual Shell
+
+A collapsible left-sidebar navigation shell with header, main content area, and optional footer/status bar. Clicking a nav item switches the tool rendered in the content area. Menus can change dynamically when a sub-tool is active. Domain-agnostic — the shell knows about layout and navigation only.
+
+---
+
+## Recipe Anatomy
+
+**Intent**
+Scaffold the application's structural container. The shell provides layout, navigation state, and view switching. It has no knowledge of data, entities, or business logic — those are filled in later.
+
+**Type**: Seed — apply once to a new project. Re-applying is guarded by idempotency check.
+
+**Stack Assumptions**
+- React 19, TypeScript, TailwindCSS v4
+- No additional libraries required beyond what AppyStack ships with
+
+**Idempotency Check**
+Does `client/src/components/AppShell.tsx` exist? If yes → PRESENT, skip unless `--force`.
+
+**Does Not Touch**
+- `client/src/App.tsx` beyond mounting AppShell
+- `server/` — this is client-only
+- `data/` folder
+- Domain logic inside view components (stubs only)
+- Socket.io wiring (belongs to a data or feature recipe)
+
+**Composes With**
+- `file-crud` recipe — persistence recipe populates view stubs with real data
+- `domain-preparation` step — before combining shell + persistence, collect domain context once
+
+---
+
+## Layout Structure
+
+```
+┌────────────────────────────────────────────────────────┐
+│  Header (app name left │ right: actions, settings cog) │
+├──────────────────┬─────────────────────────────────────┤
+│ [≡] Sidebar      │                                     │
+│                  │  Content Panel                      │
+│  ▼ Group Label   │  (active view renders here)         │
+│    ● Primary     │                                     │
+│    ● Primary     │                                     │
+│    · Secondary   │                                     │
+│                  │                                     │
+│  ▼ Group Label   │                                     │
+│    ● Primary     │                                     │
+│                  │                                     │
+│  [collapse ◀]    │                                     │
+├──────────────────┴─────────────────────────────────────┤
+│  Footer / Status Bar (optional)                        │
+└────────────────────────────────────────────────────────┘
+```
+
+When the sidebar is collapsed, it shrinks to an icon strip (or zero width). A toggle handle is always visible.
+
+---
+
+## Component Structure
+
+```
+client/src/
+├── components/
+│   ├── AppShell.tsx          ← outer layout, composes header + sidebar + content
+│   ├── Header.tsx            ← app title left, actions right (cog, user, etc.)
+│   ├── Sidebar.tsx           ← collapsible, renders nav groups and items
+│   ├── SidebarGroup.tsx      ← one group: primary items + optional secondary items
+│   └── ContentPanel.tsx      ← renders the active view via viewMap
+├── views/                    ← one stub per nav item destination
+│   └── [ViewName]View.tsx
+├── config/
+│   └── nav.ts                ← static nav config (root-level default nav)
+└── contexts/
+    └── NavContext.tsx        ← shell state: activeView, collapsed, contextNav
+```
+
+---
+
+## Nav Config Shape
+
+Define nav structure as data, not hardcoded JSX:
+
+```typescript
+// client/src/config/nav.ts
+
+export type NavItemTier = 'primary' | 'secondary'
+
+export interface NavItem {
+  key: string            // unique view key, used by ContentPanel
+  label: string          // display text
+  icon?: string          // optional icon identifier
+  tier?: NavItemTier     // defaults to 'primary' if omitted
+}
+
+export interface NavGroup {
+  label: string
+  items: NavItem[]
+}
+
+export type NavConfig = NavGroup[]
+
+export const navConfig: NavConfig = [
+  {
+    label: 'Main',
+    items: [
+      { key: 'dashboard', label: 'Dashboard', tier: 'primary' },
+      { key: 'settings',  label: 'Settings',  tier: 'secondary' },
+    ],
+  },
+]
+```
+
+**Primary items** are the main actions — rendered prominently. **Secondary items** render smaller or in a visual sub-cluster within the group, for less-frequently-used actions.
+
+---
+
+## State Model
+
+All shell state lives in `NavContext`:
+
+```typescript
+// client/src/contexts/NavContext.tsx
+
+interface NavContextValue {
+  activeView: string             // which view is currently rendering
+  collapsed: boolean             // is the sidebar collapsed?
+  contextNav: NavConfig | null   // sub-tool override nav; null = use static navConfig
+
+  navigate: (viewKey: string) => void
+  toggleCollapsed: () => void
+  setContextNav: (nav: NavConfig | null) => void
+}
+```
+
+The `collapsed` state controls sidebar width: `collapsed ? 'w-12' : 'w-56'`. Use Tailwind transition utilities for smooth animation. A collapse toggle handle renders at the sidebar bottom (or top) — always visible even when collapsed.
+
+---
+
+## Content Panel Switching
+
+```typescript
+// ContentPanel.tsx
+const viewMap: Record<string, React.ComponentType> = {
+  dashboard: DashboardView,
+  settings:  SettingsView,
+  // one entry per nav item key
+}
+
+const View = viewMap[activeView] ?? viewMap['dashboard']
+return <View />
+```
+
+View stubs are generated empty. Domain logic is filled in separately (by the developer, a data recipe, or a compound recipe step).
+
+---
+
+## Context-Aware Menus
+
+When a sub-tool needs its own nav items, it replaces the sidebar temporarily using `setContextNav`. When the user navigates away, the view unmounts and clears the context nav automatically.
+
+```typescript
+// Inside a sub-tool view component
+const { setContextNav } = useNav()
+
+useEffect(() => {
+  setContextNav([
+    {
+      label: 'Incident Tools',
+      items: [
+        { key: 'incident-list',   label: 'All Incidents', tier: 'primary' },
+        { key: 'incident-create', label: 'New Incident',  tier: 'primary' },
+        { key: 'incident-export', label: 'Export',        tier: 'secondary' },
+      ],
+    },
+  ])
+  return () => setContextNav(null)   // cleanup: restore static nav on unmount
+}, [])
+```
+
+The Sidebar renders `contextNav ?? navConfig` — context nav wins when set, falls back to static config when cleared.
+
+---
+
+## Optional Footer / Status Bar
+
+If the app has a footer (connection status, version number, last-sync time, etc.), add a `Footer.tsx` component and include it in `AppShell`. The recipe generates a stub if requested. If not needed, `AppShell` simply omits it.
+
+```
+client/src/components/Footer.tsx   ← optional; only generated if requested
+```
+
+---
+
+## What the Recipe Asks at Use-Time
+
+Before generating the build prompt, collect:
+
+1. **App name** — displayed in the Header
+2. **Main tools / pages** (2–6) — generates view stubs and initial nav items
+3. **Nav groups** — which items group together, what each group is called
+4. **Primary vs secondary** — for each item, is it a primary action or secondary?
+5. **Default view** — which view loads on startup
+6. **Context-aware nav?** — does any tool need its own sidebar menu when active? (Yes → adds `setContextNav` scaffolding to that view stub)
+7. **Footer / status bar?** — yes or no → generates Footer stub if yes
+
+The recipe does **not** ask about data models, API calls, or business logic. Those are not its concern.
+
+---
+
+## Other Shell Patterns (Future Recipe Ideas)
+
+These are identified but not yet built. Noted here so they're visible when planning.
+
+**Top-Nav Shell**
+Horizontal tab or link bar across the top. No sidebar. For apps with 3–5 flat sections of equal weight. Navigation is shallow; no hierarchy needed.
+
+**Workspace Shell** (VS Code style)
+Activity bar (icon strip, far left) selects a panel type. The panel area changes completely per activity — not just nav items but full tool panels, file trees, form widgets. Two levels of state: `activeActivity` + `activeView`. Best for tool-heavy apps where each "mode" has its own set of controls (e.g. FliHub's recording workflow vs settings vs file browser).
+
+**Dashboard Shell**
+A fixed or responsive grid of widget panels. Each widget independently fetches and displays data. No single `activeView` — multiple views live simultaneously. Per-widget Socket.io subscriptions. Best for monitoring, ops tools, reporting apps where seeing multiple things at once is the goal.
+
+---
+
+## Styling Notes
+
+- Sidebar width: `w-56` expanded, `w-12` collapsed (icon-only or just toggle handle)
+- Header height: `h-14`
+- Content panel: fills remaining space, independently scrollable
+- Active nav item: distinct background highlight (CSS variable for theming)
+- Transitions: `transition-all duration-200` on sidebar width change
+- Use TailwindCSS v4 CSS variables for sidebar/header colours — define in `client/src/styles/index.css`