free-pi-cli 0.6.2 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-pi-cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Free, ad-supported distribution of the pi coding agent. Inference paid for by ads.",
   "license": "MIT",
   "type": "module",

package/skills/ux-flow/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: ux-flow
+description: Critiques an app's user experience for simplicity, clarity and redundancy. For each core journey it asks how it could be simpler and clearer, measures friction (actual vs ideal steps), and finds duplicated features, paths and information. Use when asked to simplify the ux, audit the flows, find redundancy, give a ux critique, or run ux-flow.
+---
+
+# UX Flow: simplicity and redundancy critique
+
+`ux-walker` asks whether each journey works and looks right. This skill asks
+whether each journey should exist in this shape at all. It is a critique, not a
+test: it measures friction per journey, looks for redundancy across journeys, and
+writes ranked simplification proposals. Every step, screen, choice and repeated
+piece of information must earn its place.
+
+This skill runs on the default model. Do not switch to a premium model for it.
+Judge screenshots only through the `look_at_image` tool, which uses a cheap
+vision model. You cannot see images yourself. Keep questions specific, prompts
+short and files compact to save credits. There are no helper agents: you critique
+one journey at a time in this session.
+
+## Parameters
+
+- URL: only needed for a live pass. Auto-detect from the user's message or the dev server.
+- Journeys: default 8 core journeys to critique in depth.
+- Focus topic: optional, restricts journeys to one topic.
+- Issues: optional. File GitHub issues only if the user wants them and `gh auth status` succeeds; otherwise write the issue text to `docs/ux-flow/issues.md`.
+
+## Output
+
+```
+docs/ux-flow/
+  report.md              # friction scorecards, redundancy map, ranked proposals
+  journeys/{ID}.md       # one critique per journey
+  redundancy.md          # cross-cutting redundancy and hierarchy findings
+```
+
+## Work from files, not memory
+
+Write each journey file as soon as that journey is done and keep only a one-line
+summary in context ("STORY-004: convoluted, 9 steps vs ideal 4"). If the session
+is compacted or restarted, list `docs/ux-flow/journeys/`, compare with the
+selected journey list (save it in `docs/ux-flow/plan.md`), and continue with the
+first journey that has no file. Use the `todo` tool for the list.
+
+## Step 0: preflight
+
+1. `docs/ux-paths/catalog.md` must exist. If not, stop and tell the user: "No UX story catalog found. Run ux-paths first, then re-run ux-flow."
+2. Choose the evidence source:
+   - Fresh `ux-walker` artifacts: if `docs/ux-walker/run-history.json` exists and UI source has no significant commits since (check `git log --since` on the UI folders), reuse the screenshots and `walk-report.md` files under `docs/ux-walker/stories/*/`; the screenshots are in `docs/ux-walker/shots/STORY-NNN/`. No browser needed.
+   - Otherwise a live pass (see below).
+3. `mkdir -p docs/ux-flow/journeys`
+
+### Live pass
+
+Find the browser tool: `command -v agent-browser || echo "use: npx -y agent-browser"`.
+Use whichever works as `agent-browser` below. On first use run `agent-browser install`
+(downloads Chromium). Check the app answers: `curl -sI <url> | head -1`; if it does
+not, start the dev server (from `package.json` scripts) in the background with a
+log file and wait once for it.
+
+Traverse one journey at a time and save one screenshot per distinct screen inside
+the project folder:
+
+```bash
+agent-browser open <url>
+agent-browser snapshot -i                 # interactive elements with @refs
+agent-browser click @e3                   # or: fill <sel> <text>, type, press, select, scroll
+agent-browser screenshot docs/ux-flow/journeys/{ID}-screens/01-home.png
+agent-browser set viewport 1280 800       # optional; also: set device <name>
+agent-browser get url                     # confirm where you are
+agent-browser close
+```
+
+Traversal only. Do not verify each step; that is `ux-walker`'s job.
+
+## Step 1: pick journeys
+
+Read `docs/ux-paths/catalog.md`. Select the journeys (default 8), preferring:
+
+1. Core jobs users run most (create the main entity, consume the main content, the money path).
+2. Coverage: together they touch every major feature area at least once.
+3. Long stories, because they expose cross-screen friction that short ones hide.
+4. Anything matching the focus topic.
+
+Copy the catalog's Redundancy Candidates section into `docs/ux-flow/plan.md` with
+the selected list. It is the lead list for Step 3.
+
+## Step 2: critique each journey (one at a time)
+
+First read `references/simplification-heuristics.md` once. Then for each journey,
+in order, ask: "how could this be simpler, and how could this be clearer?" Not
+"does it work?"
+
+Evidence: open each screenshot with
+`look_at_image(path="<screenshot path>", question="...")`. Ask one specific
+question per call, for example "List every button and link on this screen with its
+label, and say which looks like the primary action." Do not call it repeatedly on
+the same image. The answer comes from another model and can be wrong; confirm a
+claim that matters with `agent-browser eval` or `agent-browser get text <sel>`.
+
+Method:
+
+1. **Friction scorecard** for the whole journey:
+   - Steps: actual clicks, inputs and screens vs the story's Ideal path.
+   - Decisions: each point where the user chooses; which could a default carry?
+   - Re-entry: data the user types that the app already knows.
+   - Confirmations that guard nothing destructive.
+   - Dead ends: screens with no obvious next step.
+   - Hesitations: where a first-time user would stall (ambiguous label, hidden control).
+2. **Take-away pass, per screen**: for each visible element, would the user still succeed if it were removed? List what is removable, collapsible or deferrable. Is there exactly one primary action? Does visual weight match importance? Is anything stated more than once?
+3. **The simpler version**: write the journey as it should be, numbered, with the fewest steps a well-designed UI needs. Then list the concrete changes to get there (merge screens X and Y, default field Z, remove confirmation W).
+4. **Clarity pass**: labels that assume knowledge the persona lacks, jargon, names inconsistent with the rest of the app.
+
+Honesty rules:
+
+- Every claim points at evidence: a screenshot, a step number, a label. Do not invent UI or assume behavior.
+- If the journey is already minimal, say so. "No simplification found" is a valid and useful verdict. Do not manufacture friction.
+- Mark each finding "measured" (counted steps, seen screenshot) or "suspected" (needs a live check).
+
+Write `docs/ux-flow/journeys/{JOURNEY_ID}.md` with sections: Friction Scorecard,
+Take-away Pass, The Simpler Version, Clarity Issues, and a final line
+`Verdict: minimal | acceptable | convoluted`. Calibration is in the heuristics file.
+
+## Step 3: redundancy and information architecture (once, after all journeys)
+
+Start from the plan's Redundancy Candidates list. Look across screens, which no
+single-journey pass can do: use the saved screenshots, asking `look_at_image`
+targeted questions, and read the journey files (not the images again).
+
+1. **Duplicate paths**: the same goal reachable several ways. Deliberate shortcut or drift? Same result? Recommend keep both, mark one canonical, or remove one.
+2. **Duplicate information**: the same fact on several screens or twice on one screen. Does the repeat serve a new context? Recommend one canonical surface.
+3. **Overlapping features**: two features with substantially overlapping capabilities. Recommend merge, differentiate, or remove.
+4. **Hierarchy and IA**: does navigation match user priorities? Anything important 3 or more levels deep, or anything trivial at top level? Is one concept called one name everywhere?
+
+Every claim needs evidence (screenshot or catalog reference). If the app is
+clean, say so; an empty redundancy map is a pass.
+
+Write `docs/ux-flow/redundancy.md` with sections: Duplicate Paths, Duplicate
+Information, Overlapping Features, Hierarchy & IA.
+
+## Step 4: synthesis
+
+Read the journey files and `redundancy.md` and write `docs/ux-flow/report.md`:
+
+```markdown
+# UX Flow Critique - {DATE}
+
+## Run Summary
+| Metric | Value |
+|--------|-------|
+| Journeys critiqued | {N} |
+| Evidence source | {walker artifacts (run of {DATE}) / live pass} |
+| Verdicts | {X} minimal, {Y} acceptable, {Z} convoluted |
+
+## Friction Scorecard
+| Journey | Steps (actual/ideal) | Needless decisions | Re-entry | Dead ends | Verdict |
+|---------|----------------------|--------------------|----------|-----------|---------|
+
+## Redundancy Map
+{condensed from redundancy.md, each with its recommendation}
+
+## Simplification Proposals (ranked)
+### {N}. {Title}
+- **Now**: {current flow/screen, with evidence pointer}
+- **Proposed**: {the simpler version}
+- **Saves**: {steps/screens/decisions removed; journeys improved}
+- **Effort**: {S/M/L}
+- **Evidence**: {journey file + screenshot refs}
+
+## Already Minimal
+{journeys/areas that passed clean, so re-runs skip them}
+```
+
+Ranking: weight by how central the journey is. Removing one step from the
+most-used journey beats removing three from a rarely used settings flow.
+
+## Step 5: issues (optional)
+
+Only if the user wants issues. If `command -v gh` and `gh auth status` both
+succeed, check duplicates first with `gh issue list --label ux-flow --state open`,
+then `gh issue create --title "UX-flow: {title}" --body "{Now/Proposed/Saves/Effort/Evidence}" --label ux-flow`
+for each top proposal (maximum 10). If a label does not exist, drop `--label`.
+Otherwise write the same text to `docs/ux-flow/issues.md`. These are design
+changes: propose them, never auto-fix them.
+
+## Step 6: report to the user
+
+Verdict counts and the friction table; the top 3 proposals in one line each;
+redundancy counts by type; issues filed or the issues file path; and the path
+`docs/ux-flow/report.md`.
+
+## Guidance
+
+- Critique, do not test. A broken button or misaligned card is `ux-walker`'s job; note it in one line and move on.
+- The ideal path is a benchmark, not a fantasy. Fewer steps that hide needed information or remove user control is not simpler.
+- No manufactured findings. A minimal journey is praised and skipped.
+- One concept, one name. Naming drift ("workspace" here, "project" there) is a redundancy finding even when the feature is not duplicated.
+
+## References
+
+- `references/simplification-heuristics.md`: the question battery and verdict calibration. Read it once before Step 2.

package/skills/ux-flow/references/simplification-heuristics.md

@@ -0,0 +1,103 @@
+# Simplification Heuristics
+
+The question battery for `/ux-flow` critics. Each heuristic: the question, how
+to detect a violation, and the typical fix. These are established interaction-
+design principles (step/decision economy, progressive disclosure, recognition
+over recall, consistency) applied as concrete checks — not novel rules.
+
+## Flow heuristics (per journey)
+
+### 1. Step economy
+**Ask**: Could this goal be reached in fewer steps without hiding information the user needs?
+**Detect**: Count actual clicks/inputs/screens; compare to the story's Ideal path.
+**Fix**: Merge screens, combine confirm+submit, deep-link past hub pages, batch inputs.
+
+### 2. Decision economy
+**Ask**: Does every choice the user makes actually matter to them?
+**Detect**: List each decision point; for each, would 90% of users pick the same option?
+**Fix**: Make that option the default, move the choice to settings or an "advanced" disclosure.
+
+### 3. Don't ask for what you know
+**Ask**: Is the user re-entering data the app already has?
+**Detect**: Any input pre-fillable from account, context, or a previous step but empty.
+**Fix**: Prefill, infer, or drop the field.
+
+### 4. Confirmation budget
+**Ask**: Does each confirmation guard something destructive or irreversible?
+**Detect**: Confirmations on safe/undoable actions; double confirmations.
+**Fix**: Remove the dialog; prefer undo over confirm.
+
+### 5. Dead-end audit
+**Ask**: After every action, is the next step obvious from the resulting screen?
+**Detect**: Success screens with no onward action; flows ending at a bare toast; back-button-only exits.
+**Fix**: Every terminal screen offers the likely next action ("View it", "Create another", "Back to list").
+
+### 6. Shortest path to value
+**Ask**: How many steps from first arrival to the first moment of real value?
+**Detect**: Walk the new-user story counting steps before the user has DONE the core thing once.
+**Fix**: Defer setup (profile, preferences, invites) until after first success.
+
+### 7. Recognition over recall
+**Ask**: Must the user remember anything from a previous screen to succeed here?
+**Detect**: IDs/names/values that must be memorized or re-typed across screens; codes with no copy affordance.
+**Fix**: Carry context forward; show, don't quiz.
+
+## Screen heuristics (per screen)
+
+### 8. Take-away test
+**Ask**: For each visible element — if removed, would the user still succeed?
+**Detect**: Elements no story step ever uses; decoration competing with content.
+**Fix**: Remove, collapse behind disclosure, or move to an advanced section. Removal is the default; keeping needs the justification.
+
+### 9. One primary action
+**Ask**: Squinting at the screen, is exactly one action visually dominant — and is it the right one?
+**Detect**: Zero or 2+ equally-weighted primary buttons; the visually loudest element isn't the next step.
+**Fix**: One primary style per screen; demote the rest to secondary/tertiary.
+
+### 10. Hierarchy matches importance
+**Ask**: Does visual weight (size, color, position) track how much the user cares?
+**Detect**: Key info smaller/quieter than chrome, badges, or metadata; everything bold (emphasis inflation).
+**Fix**: Re-weight: important things big and first, trivia small and last; spend emphasis sparingly.
+
+### 11. Progressive disclosure
+**Ask**: Is anything shown before the user needs it?
+**Detect**: Long forms where later fields depend on earlier answers; advanced options mixed with basics; help paragraphs above the action.
+**Fix**: Stage it — show the next thing when the previous thing is done.
+
+### 12. Once and only once (information)
+**Ask**: Is each fact stated exactly once per screen?
+**Detect**: Same title/status/metadata in header AND breadcrumb AND card AND sidebar.
+**Fix**: Pick the canonical surface; the rest reference it or drop it.
+
+## App heuristics (cross-journey — redundancy critic)
+
+### 13. One way to do one thing
+**Ask**: Is each duplicate route to a goal a deliberate shortcut, or drift?
+**Detect**: Alternate paths fields in the catalog; same verb in two menus; two screens that both edit the same entity.
+**Fix**: Mark one route canonical; keep shortcuts only when they're accelerators of the canonical route, not parallel implementations.
+
+### 14. One concept, one name
+**Ask**: Is every concept called the same thing everywhere?
+**Detect**: "Workspace" vs "project" vs "space" for the same entity across screens, docs, and buttons.
+**Fix**: Pick one term; rename all surfaces.
+
+### 15. Feature overlap
+**Ask**: Do two features substantially do the same job?
+**Detect**: Two tools/panels/reports whose capabilities overlap enough that users won't know which to use.
+**Fix**: Merge, sharply differentiate, or remove one.
+
+### 16. Navigation depth vs. importance
+**Ask**: Is anything users need often buried 3+ levels deep? Anything rare sitting at top level?
+**Detect**: Map each core-story destination to its click depth from home.
+**Fix**: Promote the frequent, demote the rare.
+
+## Verdict calibration
+
+| Verdict | Meaning |
+|---------|---------|
+| **minimal** | Actual ≈ ideal steps; take-away pass finds little; no redundancy involving this journey |
+| **acceptable** | 1-2 extra steps or a few removable elements; nothing structural |
+| **convoluted** | 3+ extra steps, forced detours, duplicated surfaces, or a screen failing 3+ heuristics |
+
+Do not grade on a curve. If everything is minimal, the report says so — that is
+a useful result, not a failed critique.

package/skills/ux-paths/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: ux-paths
+description: Generates a catalog of realistic user journey stories (short feature exercises and long end-to-end flows) by reading the codebase. Use when asked to create stories, map user journeys, walk or map the app, generate ux paths or test scenarios, or find out what users can do.
+---
+
+# UX Paths: user journey story generator
+
+Read the codebase and write a catalog of realistic user journeys: short stories
+(one feature) and long stories (a complete workflow). The catalog feeds `ux-walker`
+(walks stories in a browser) and `ux-flow` (critiques simplicity and redundancy).
+
+This skill runs on the default model. Do not switch to a premium model for it.
+Keep notes and files compact to save credits. There are no helper agents: you do
+every step yourself, one unit at a time, in this one session.
+
+## Parameters
+
+- Focus area: optional text from the user (for example "checkout"). Still map the
+  whole app, but write more stories for the focus.
+- Output directory: `docs/ux-paths/`.
+- Depth: `quick` = 5 topics, 3-5 stories each. `deep` (default) = 8-12 topics, 5-15 stories each.
+
+## Work from files, not memory
+
+The work is long, so the files are the state. After each unit, write its file
+immediately and keep only a one-line summary in context (for example
+"auth: 9 stories, 2 gaps"). If the session is compacted or restarted, do not start
+over: list `docs/ux-paths/topics/`, compare with the topic list in
+`discovery.md`, and continue with the first topic that has no file. Use the `todo`
+tool to track the topic list.
+
+## Step 0: setup
+
+```bash
+mkdir -p docs/ux-paths/topics
+ls docs/ux-paths docs/ux-paths/topics   # resume if files already exist
+```
+
+## Step 1: discovery
+
+Scan the code (grep, find, ls, read) and write `docs/ux-paths/discovery.md`.
+Read `references/path-categories.md` (in this skill's folder) for the category list.
+Find:
+
+1. Application type (web app, mobile, desktop, CLI, API, library).
+2. Entry points: routes, pages, screens, commands, endpoints.
+3. Features: everything a user can do.
+4. User roles (admin, member, guest, free, paid).
+5. Navigation structure.
+6. State transitions: login, logout, onboarding, setup, subscription changes.
+7. Data entities and their create, read, update, delete actions.
+8. Integrations: OAuth providers, external services, webhooks.
+9. Error, empty and loading states.
+10. Feature flags and permission-gated UI.
+
+Search by framework: router config, page components, nav components, forms,
+dialogs and confirmations, API routes, auth guards, config and env flags.
+
+Use this format:
+
+```markdown
+# App Discovery: {App Name}
+
+## Application Type
+## Tech Stack
+## User Roles
+- {role}: {what they can do}
+## Feature Map
+### {Feature Area}
+- {capability}
+## Navigation Structure
+## Data Entities
+- {entity}: create / read / update / delete
+## Integrations
+- {service}: {what it does}
+## Recommended Story Topics
+1. {Topic} - {rationale}
+(8-12 topics that together cover the whole app)
+```
+
+The Recommended Story Topics list is the work list for Step 2.
+
+## Step 2: stories, one topic at a time
+
+For each topic in order: read the code for that topic (components, routes,
+handlers), write 5-15 stories to `docs/ux-paths/topics/{topic-slug}.md`, then move
+to the next topic. Write the file before starting the next topic. Do not re-read
+earlier topic files; the discovery file is enough context.
+
+Story format:
+
+```markdown
+## STORY-{NNN}: {Descriptive Title}
+
+**Type**: short | medium | long
+**Topic**: {topic}
+**Persona**: {who is doing this}
+**Goal**: {what they want to accomplish}
+**Preconditions**: {state that must exist first}
+**Ideal path**: {fewest steps a well-designed UI could need: an integer plus one line of reasoning. ux-walker and ux-flow measure friction against this.}
+**Alternate paths**: {other routes in the code to the same goal (different menu, shortcut, duplicate feature), or "none found"}
+
+### Steps
+1. {User action} -> {Expected result}
+
+### Variations
+- {Variation}: {what changes and why}
+
+### Edge Cases
+- {Edge case}: {what happens}
+```
+
+Number stories per topic file with temporary ids (STORY-001 within the file);
+Step 3 renumbers them.
+
+Sizes:
+
+- Short (2-5 steps): one feature in isolation (change a setting, delete an item, search).
+- Medium (5-15 steps): one workflow (create a resource and check it appears; hit an error, recover, finish).
+- Long (15-40 steps): an end-to-end journey (discover, sign up, onboard, use the core feature, customize).
+
+Realism rules:
+
+- Reference only UI elements, routes and features that exist in the code, with the real button labels, menu items and page titles. Do not invent features.
+- Use specific personas and plausible data. Good: "Maria, a team lead, adds 3 new hires before standup." Bad: "User clicks settings."
+- Include moments where the user hesitates, errs or changes their mind.
+- When the code has more than one route to the same goal, list all of them in **Alternate paths**. Duplicate paths are a redundancy signal for `ux-flow`; do not silently pick one. "None found" is a valid answer; an invented alternate path is not.
+- Note when the same information shows on several surfaces (list, detail, sidebar). This feeds the Redundancy Candidates section.
+
+## Step 3: consolidate
+
+Read the topic files one at a time and build `docs/ux-paths/catalog.md`:
+
+1. Assign sequential ids (STORY-001, STORY-002, ...) across all topics.
+2. Merge near-duplicate stories.
+3. Note cross-topic overlaps and add a few cross-topic stories.
+4. Add a dependency graph (which stories must run before others).
+5. Check coverage: every feature in `discovery.md` appears in at least one story. List gaps.
+6. Build the Redundancy Candidates section from the Alternate paths fields and multi-surface notes.
+
+If the topic files are too large to hold at once, append each topic's stories to
+`catalog.md` as you read it and write the summary sections last.
+
+Catalog format:
+
+````markdown
+# UX Path Catalog: {App Name}
+
+Generated: {date}
+Total Stories: {count}
+Coverage: {features covered} / {total features} ({percentage})
+
+## Summary
+| Type | Count |
+|------|-------|
+| Short | {n} |
+| Medium | {n} |
+| Long | {n} |
+
+## Coverage Matrix
+| Feature Area | Stories | Gaps |
+|--------------|---------|------|
+
+## Story Dependency Graph
+```text
+STORY-001 (Create Account)
+├── STORY-005 (Configure Settings)
+└── STORY-008 (Create First Project)
+```
+
+## All Stories
+### {Topic}
+{stories}
+
+## Redundancy Candidates
+### Duplicate paths (same goal, multiple routes)
+- {goal}: via {path A} and {path B}; {same result, or divergent?}
+### Duplicate information (same fact, multiple surfaces)
+- {info}: shown on {screen 1}, {screen 2}
+### Overlapping features/tools
+- {feature X} and {feature Y} both {capability}
+
+## Gaps & Recommendations
+````
+
+## Step 4: report
+
+Tell the user: total stories, counts by type, coverage percentage, notable gaps,
+and the path `docs/ux-paths/catalog.md`.
+
+## Tips
+
+- Discovery is the foundation. A missed feature area becomes a gap in the whole catalog.
+- Let the code decide the topics; do not force a fixed list.
+- The happy path is one story. Error paths, edge cases and mobile viewports are worth capturing as variations.
+- Re-run when the app changes; the catalog is a living document.

package/skills/ux-paths/references/path-categories.md

@@ -0,0 +1,169 @@
+# UX Path Categories Reference
+
+Use this reference to ensure comprehensive coverage across any application type. Not all categories apply to every app — the discovery agent should select the relevant ones.
+
+## Universal Categories (apply to almost any app)
+
+### Authentication & Identity
+- Sign up (email, OAuth, SSO, magic link)
+- Log in / log out
+- Password reset / change
+- Session management (timeout, refresh, multi-device)
+- Account deletion / deactivation
+- Profile management
+
+### Onboarding & First-Time Experience
+- First launch / empty state
+- Setup wizard / guided tour
+- Feature discovery
+- Import existing data
+- Invite flow (being invited vs inviting others)
+
+### Core CRUD Operations
+- Create primary entities
+- Read / browse / search entities
+- Update / edit entities
+- Delete / archive entities
+- Bulk operations (select all, batch delete, batch edit)
+
+### Navigation & Discovery
+- Primary navigation (sidebar, tab bar, menu)
+- Search and filtering
+- Breadcrumbs / back navigation
+- Deep linking / direct URL access
+- Keyboard navigation / shortcuts
+
+### Settings & Configuration
+- User preferences (theme, language, notifications)
+- App configuration (integrations, API keys, webhooks)
+- Permission / role management
+- Billing / subscription management
+
+### Error States & Recovery
+- Network failure mid-operation
+- Invalid input / validation errors
+- 404 / not found pages
+- Permission denied
+- Rate limiting
+- Session expiration during work
+- Undo / revert actions
+
+### Data Management
+- Import / export
+- Backup / restore
+- Pagination / infinite scroll
+- Sorting / filtering
+- Data visualization (charts, graphs, tables)
+
+## Web App Categories
+
+### Responsive / Multi-Device
+- Desktop viewport workflows
+- Mobile viewport workflows
+- Tablet viewport workflows
+- Touch vs mouse interactions
+
+### Real-time Features
+- Live updates / WebSocket events
+- Collaborative editing
+- Notifications (in-app, push, email)
+- Presence indicators
+
+### Content Management
+- Rich text editing
+- File / image upload
+- Media preview
+- Version history
+
+## Mobile App Categories
+
+### Platform-Specific
+- iOS-specific interactions (swipe, force touch, share sheet)
+- Android-specific (back button, notifications, intents)
+- Permissions (camera, location, contacts, notifications)
+- Offline mode / sync
+
+### Gestures & Interactions
+- Pull to refresh
+- Swipe actions
+- Long press menus
+- Drag and drop
+
+## CLI / Terminal App Categories
+
+### Command Patterns
+- Help / usage display
+- Flag / argument parsing
+- Interactive prompts
+- Pipe / stdin input
+- Output formatting (JSON, table, plain)
+- Verbose / debug modes
+
+### Session Management
+- Config file management
+- Environment variable usage
+- Authentication tokens
+
+## API / Backend Categories
+
+### Endpoint Patterns
+- CRUD endpoint usage
+- Authentication flows (API keys, OAuth tokens)
+- Pagination through results
+- Error response handling
+- Rate limit behavior
+- Webhook delivery / retry
+
+## Desktop App Categories
+
+### Window Management
+- Multi-window workflows
+- Menu bar interactions
+- System tray
+- Keyboard shortcuts
+- File system integration (open, save, drag-drop)
+
+### OS Integration
+- Native notifications
+- File associations
+- Auto-update flow
+- Deep link handling
+
+## Cross-Cutting Concerns (apply to multiple categories)
+
+### Collaboration
+- Sharing / permissions
+- Comments / annotations
+- Activity feed / audit log
+- Team management
+
+### Performance & Loading
+- Slow network behavior
+- Large dataset handling
+- Background processing feedback
+- Progress indicators
+
+### Accessibility
+- Screen reader navigation
+- Keyboard-only operation
+- High contrast / reduced motion
+
+## Story Complexity Heuristics
+
+| Type | Steps | Scope | Example |
+|------|-------|-------|---------|
+| Short | 2-5 | Single feature | Toggle dark mode |
+| Medium | 5-15 | One workflow | Create and share a document |
+| Long | 15-40 | Cross-feature journey | New user onboards, creates project, invites team, completes first task |
+
+## Persona Templates
+
+Adapt these to the specific app:
+
+- **New User**: Never seen the app. Needs onboarding. May be confused.
+- **Regular User**: Uses the app daily. Knows the basics. Has preferences set.
+- **Power User**: Uses advanced features. Keyboard shortcuts. Custom workflows.
+- **Admin**: Manages other users. Configures the system. Handles edge cases.
+- **Returning User**: Used the app months ago. Forgot some things. Has old data.
+- **Impatient User**: Wants to accomplish something fast. Skips tutorials. Gets frustrated by friction.
+- **Cautious User**: Reads everything. Wants confirmation before destructive actions. Worries about data loss.