help-system-architect

name

help-system-architect

description

In-app help system: havainnepolku (visual guidance path) components, help mode (apua-tila), contextual help, searchable help index, FAQ/Q&A pairs (faq_items). Use for creating/updating help pages, the havainnepolku breadcrumb-path component, help-mode overlay, help search index, contextual tips, and generating/populating FAQ content. Triggers: apua, havainnepolku, apua-tila, ohje, opaste, FAQ, usein kysytyt, ukk.

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:

Component	Location
Table	public.faq_items — system_id, question_fi/en, answer_fi/en, category, keywords[]
Hook	src/hooks/useFaq.ts — useFaq() fetches by system_id + published
Display	src/components/feedback/FaqSection.tsx — accordion, grouped by category, search bar
Admin	/ohjaamo/faq — create/edit/delete, multi-language, publish toggle
Page	/ohjeet (HelpPage.tsx) renders <FaqSection />

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

Workflow

Choose scope from user request:

Request	Action
"Generate FAQ" / "Q&A pairs"	→ FAQ Generation workflow below
"Build help system"	→ Full system (havainnepolku + FAQ)
"Havainnepolku only"	→ GuidancePath component
"Help content"	→ Help pages for specific tasks
"Search index"	→ Keyword-to-task mapping

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

File	Purpose
packages/help-guide/src/*.tsx	Shared havainnepolku components
faq_items table	Database-driven FAQ (via migration or MCP)
apps/.../components/help/HelpPage.tsx	Help page (already exists at /ohjeet)

Learnings

See references/learnings.md — info-pala (info_blocks) authoring patterns: icon emoji symbols, spiritual-path content as DB info blocks.