Help System Architect

Design and generate the in-app help system for Raamattu Nyt and IdeaMachina.

Authority

• Consumes Docs/ai/core-user-model.json as the single source of truth for tasks and paths
• NEVER redefines tasks or paths — only explains, guides, and contextualizes them
• The core-ux-detective skill owns task/path definitions; this skill owns help presentation

Two Systems

1. Havainnepolku (Visual Guidance Path)

Interactive step-by-step navigation bar. See references/component-specs.md for specs.

Package: packages/help-guide/ with GuidancePath.tsx, HelpModeProvider.tsx, useHelpMode.ts, HelpTooltip.tsx, HelpSearchIndex.ts.

2. Database FAQ System (faq_items)

Database-driven Q&A pairs with search, per app. Already built:

Categories: general, account, billing, features, troubleshooting, privacy, audio, ai

Workflow

Choose scope from user request:

FAQ Generation Workflow

See references/faq-generator.md for the complete FAQ generation guide including:

• Schema reference and insert patterns
• Feature discovery workflow (scan routes, pages, tabs)
• Category mapping templates
• Starter Q&A sets for Raamattu Nyt (31 pairs) and IdeaMachina (13 pairs)
• Keyword optimization for search

Quick steps:

1. Discover — Scan app routes and pages to list features
2. Categorize — Map features to FAQ categories
3. Generate — Create Q&A pairs (2-4 per feature, fi + en)
4. Keywords — Add 3-6 search keywords per pair (fi + en)
5. Insert — SQL migration or direct execute_sql
6. Verify — Count by system_id + category, target 30-60 per app

Havainnepolku Workflow

1. Read Docs/ai/core-user-model.json (run core-ux-detective if missing)
2. Generate GuidancePath data from user_paths
3. Build components per references/component-specs.md

Help Content Generation

For each task/path, generate content in Finnish:

{
  "task_id": "create_reel",
  "title": "Reelsin luominen",
  "what": "Luo kaunis kuvajae Raamatun jakeesta.",
  "when": "Kun haluat jakaa jakeen someen kuvana.",
  "steps": ["Valitse jae", "Paina 'Luo reels'", "Valitse tyyli", "Julkaise"]
}

Rules

• All user-facing text in Finnish (with English translations in _en fields)
• Calm, supportive, non-technical tone
• Short answers: 2-4 sentences max
• Keywords: include both Finnish and English terms
• FAQ search works via question, answer, and keywords[] fields
• Help mode is non-blocking — user can always dismiss
• Components in packages/help-guide/, FAQ data in faq_items table

Output Files