Service Manual All

Generate user manuals for every citizen-facing service in a country instance, plus a catalog index page.

Inputs

• MCP Server: $ARGUMENTS[0]

If missing, ask the user. Known servers: BPA-lesotho, BPA-cuba-test.

CRITICAL RULES

• READ ONLY — NEVER use create/update/delete MCP operations
• Use subagents for each manual — NEVER fetch service detail data in main context
• Main context handles ONLY: service list, filtering, catalog index, orchestration
• This prevents context saturation which killed previous sessions
• If a tool call fails 2x, STOP — report to user, do not retry in a loop

Phase 0: Configuration Wizard (Main Context)

Before any MCP calls, present the wizard using AskUserQuestion. Ask all four questions in a single call:

AskUserQuestion with questions:
[
  {
    "question": "UI Style — How should the manuals look?",
    "options": [
      {"value": "ds-match", "label": "DS Match (Recommended) — Extract design from the live DS site and match its visual identity exactly"},
      {"value": "basic", "label": "Basic — Clean built-in styling, fast, no dependencies"},
      {"value": "custom", "label": "Custom URL — Provide a website URL to extract its design system"}
    ]
  },
  {
    "question": "Scope — Which services to document?",
    "options": [
      {"value": "all", "label": "All services (Recommended) — Generate manuals for all active citizen-facing services"},
      {"value": "selection", "label": "Selection — Pick specific services from the filtered list"}
    ]
  },
  {
    "question": "Output — Where should the manuals go?",
    "options": [
      {"value": "local", "label": "Local files only (Recommended) — Generate files in the working directory"},
      {"value": "local-ghpages", "label": "Local + GitHub Pages — Generate locally AND deploy to GitHub Pages"},
      {"value": "local-ghpages-open", "label": "Local + GitHub Pages + Open — All of the above plus open the catalog in browser"}
    ]
  },
  {
    "question": "Content Depth — How detailed should each manual be?",
    "options": [
      {"value": "standard", "label": "Standard (Recommended) — All sections with moderate detail (~1200 lines per manual)"},
      {"value": "quick", "label": "Quick — Overview, requirements, basic steps only (~500 lines)"},
      {"value": "detailed", "label": "Detailed — Full field-level reference tables, all determinant logic explained (~1800 lines)"}
    ]
  }
]

Store the wizard results as variables:

• ui_style = "ds-match" | "basic" | "custom"
• scope = "all" | "selection"
• output_mode = "local" | "local-ghpages" | "local-ghpages-open"
• content_depth = "standard" | "quick" | "detailed"

If ui_style is "custom", ask the user for the URL in a follow-up message.

Derive country_slug from the MCP server name (e.g., BPA-lesotho -> lesotho, BPA-cuba-test -> cuba). Derive ds_url from the country slug (e.g., lesotho -> https://lesotho.eregistrations.dev).

Phase 1: Pre-flight & Service Discovery (Main Context)

1a. Auth Check

1. Call connection_status on the MCP server
2. If not authenticated -> run auth_login, wait for success

1b. List and Filter Services

1. Call service_list(limit=100) on the MCP server
2. Filter OUT non-citizen-facing services — exclude:
   • Names containing: "copy", "test", "prueba", "copia" (case-insensitive)
   • Names containing: "Registrar only", "SWR", "BO Registry" (internal admin)
   • Names containing personal names like "darek", "ando" (dev testing)
   • "Basic BPA" (template)
   • Any service with status "inactive" or "draft"

1c. Empty Service Detection

For each filtered service, run lightweight checks (these calls are small, safe in main context):

• form_get(service_id) — get component_count
• role_list(service_id) — get role total

Mark a service as empty if ALL of these are true:

• component_count <= 1 (form has no real fields, just the default container)
• role total == 0 (no workflow roles defined)

1d. Report to User

Present two lists:

Active services ({N}):

1. {name} — {component_count} components, {role_count} roles — ID: {id}
2. ...

Coming Soon — not yet configured ({M}):

1. {name} — empty form, no roles — ID: {id}
2. ...

If scope is "selection": ask user to pick which active services to include. If scope is "all": ask "Proceed with all {N} active services? ({M} empty services will show as 'Coming Soon' in the catalog)"

Wait for user confirmation before proceeding.

Phase 2: Template Preparation (Main Context)

Create Output Directory

mkdir -p {country_slug}-manuals

Template Handling

If ui_style is "ds-match":

1. Check if {country_slug}-manuals/TEMPLATE.html already exists
2. If yes: tell user "Found existing DS template, will reuse it" — skip extraction
3. If no: spawn a Playwright subagent to extract design tokens:

Subagent prompt for template extraction:

Navigate to {ds_url} using Playwright. Take a screenshot. Extract:
- Primary color, secondary color, accent color (from CSS custom properties or computed styles)
- Font family for headings and body
- Logo URL (the main header logo img src)
- Header background color/gradient
- Button styling (border-radius, colors)
- Any country-specific branding elements

Write a TEMPLATE.html file to {working_directory}/{country_slug}-manuals/TEMPLATE.html containing:
- A complete CSS stylesheet in a <style> tag with these extracted tokens as CSS variables
- A header template with the logo and country name
- A footer template with branding
- Placeholder markers: {{TITLE}}, {{CONTENT}}, {{TOC}}, {{VERSION}}

The template should NOT be a full manual — just the design shell that manual subagents will use.
Return the file path when done.

If ui_style is "basic": No template needed. Subagents use built-in styling.

If ui_style is "custom": Same as "ds-match" but use the user-provided URL instead of ds_url.

Store template_path variable (path to TEMPLATE.html, or empty string if "basic").

Phase 3: Generate Manuals (Subagents — PARALLEL batches)

For EACH active (non-empty) citizen-facing service, spawn a Task subagent.

Launch 3-4 subagents in parallel (multiple Task tool calls in one message). When a batch completes, launch the next batch.

Each subagent receives this prompt (fill in actual values):

You are generating an HTML user manual for an eRegistrations service.

**Service ID**: {service_id}
**MCP Server**: {mcp_server} (use MCP tools prefixed with mcp__{mcp_server}__)
**Service Name**: {service_name}
**Output file**: {working_directory}/{country_slug}-manuals/{service_slug}/index.html
**Template file**: {template_path} (read this first if non-empty, use its CSS/header/footer)
**Content Depth**: {content_depth}

### Step 1: Fetch ALL Data

Call these MCP tools in parallel:
1. `mcp__{mcp_server}__form_get(service_id="{service_id}")` — full form structure
2. `mcp__{mcp_server}__field_list(service_id="{service_id}", limit=500)` — all fields
3. `mcp__{mcp_server}__determinant_list(service_id="{service_id}")` — conditional logic
4. `mcp__{mcp_server}__role_list(service_id="{service_id}")` — workflow roles
5. `mcp__{mcp_server}__bot_list(service_id="{service_id}")` — automations
6. `mcp__{mcp_server}__analyze_service(service_id="{service_id}")` — overview with costs/requirements
7. `mcp__{mcp_server}__registration_list(service_id="{service_id}")` — registrations

If field_list has `has_more=true`, fetch additional pages with offset.

### Step 2: Map the Form Structure

From form_get, identify:
- **Top-level panels** = tabs (e.g., "Company", "Shareholders", "Documents")
- **Components within each panel** = fields, grids, uploads, radio buttons
- **Conditional visibility** from determinants (which fields/panels depend on other answers)

### Step 3: Generate HTML Manual

Create a single self-contained HTML file.

**If template_path is provided:** Read TEMPLATE.html, use its CSS and header/footer, replace placeholders.
**If no template:** Use built-in clean styling with light theme.

**Content Depth adjustments:**
- "quick": Sections 1-5 only (intro, prerequisites, steps overview). Skip field-by-field breakdowns, FAQ, and detailed workflow. ~500 lines.
- "standard": All sections with moderate detail. Explain each field briefly. Include FAQ (5-8 questions). ~1200 lines.
- "detailed": All sections plus field-level reference tables, determinant logic diagrams, all edge cases. FAQ (10-12 questions). ~1800 lines.

**Structure:**
1. Header with service name and country branding
2. Table of Contents with anchor links
3. Introduction — what this service is, who needs it
4. Prerequisites — documents/information to gather before starting
5. Step-by-step sections — one per form tab:
   - Step number + tab name
   - CSS form mockup mimicking the real interface
   - Plain-language explanation of every field
   - Tips, examples, common mistakes
6. Review & Submit section
7. What happens after submission (workflow roles)
8. Costs/fees breakdown
9. FAQ

**Writing Style:**
- Write for citizens, NOT administrators
- Simple, clear language — no jargon
- Explain WHY each field is needed
- Give realistic examples using local names/context
- Use "you" and "your"
- Mention common mistakes

**CSS Form Mockups** — styled mockups resembling the real form:
```html
<div class="form-mockup">
  <div class="form-mockup-bar"><span class="bar-title">{Service Name}</span></div>
  <div class="form-mockup-tabs">
    <span class="mtab">Tab 1</span>
    <span class="mtab active">Current Tab</span>
  </div>
  <div class="form-mockup-body">
    <!-- mock-field, mock-input, mock-select, mock-radio, mock-upload, mock-grid -->
  </div>
</div>
```

**Component Type Mapping:**
| Form.io Type | Manual Description |
|---|---|
| textfield | "Type your answer in the text box" |
| textarea | "Enter a detailed description" |
| select | "Select from the dropdown list" |
| radio | "Choose one option" |
| checkbox | "Tick the box if applicable" |
| datagrid | "Click 'Add' to add each entry" |
| file | "Click to upload your document (PDF, JPG)" |
| datetime | "Select the date from the calendar" |
| number | "Enter the number" |
| currency | "Enter the amount" |
| signature | "Sign using your mouse or finger" |
| content | (informational — explain what it tells the user) |
| panel | (becomes a section in the manual) |

**HTML Requirements:**
- Self-contained — all CSS inline in style tag (unless using template)
- Responsive — desktop and mobile
- Print-friendly
- Country-appropriate branding colors

**Manual Versioning (REQUIRED):**
```html
<footer class="manual-version">
  <p>Manual v1.0 — Generated {YYYY-MM-DD HH:MM UTC} — Source: {mcp_server}/{service_id}</p>
  <p>Generated by /service-manual-all skill v2.0.0</p>
</footer>
```

### Step 4: Write File

Create the directory and write the file:
```bash
mkdir -p {working_directory}/{country_slug}-manuals/{service_slug}
```
Write the HTML file using the Write tool.

Return ONLY this summary (do NOT return HTML content):
- file_path: the path written
- service_name: name of the service
- tabs_count: number of form tabs documented
- fields_count: number of fields documented
- file_size_kb: approximate file size

Progress tracking: Use TodoWrite to mark each service as pending/in_progress/completed. Update after each batch completes.

Collect from each subagent:

• service_name, file_path, tabs_count, fields_count, status (success/failed), error message if failed

Phase 4: Generate Catalog Index (Main Context)

After all manuals complete, generate {country_slug}-manuals/index.html — a catalog page.

This is the ONLY HTML generated in main context (small file, ~150-200 lines).

The catalog must include:

1. Header — Country name, instance branding, "Service Manuals" title
2. Search/filter bar — JavaScript text filter that hides non-matching cards on keyup:

   <input type="text" id="search" placeholder="Search services..." onkeyup="filterCards()">
   

3. Service cards grid — responsive grid of cards, each with:
   • Service name (linked to {service_slug}/index.html)
   • Number of steps and fields documented
   • Status badge:
     • Green "Available" if manual was generated successfully
     • Gray "Coming Soon" if service was empty (not configured in BPA)
     • Red "Error" if subagent failed (with error tooltip)
4. Category grouping — if services have natural groupings (e.g., "Business Registration", "Permits"), group them under subheadings. Otherwise, alphabetical order.
5. Footer — "Last updated: {YYYY-MM-DD}" timestamp, "Generated by /service-manual-all v2.0.0", total service count
6. Responsive styling — works on desktop and mobile
7. If template exists — match the template's color scheme and branding

Phase 5: Deliver (Main Context)

1. Summary table — report to user:

   #	Service	Status	Tabs	Fields	File
   1	...	Success	...	...	...
   2	...	Coming Soon	-	-	-

2. Totals: "{success}/{total_active} services documented. {empty_count} services marked as Coming Soon."

3. Open in browser (if output_mode is "local-ghpages-open"):

   open {country_slug}-manuals/index.html
   

4. Deploy to GitHub Pages (if output_mode includes "ghpages"): Proceed to Phase 6.

If output_mode is "local" only: tell user "To publish later, run /service-manual-all again and select the GitHub Pages output option."

Phase 6: Deploy to GitHub Pages (Conditional)

Only run if output_mode is "local-ghpages" or "local-ghpages-open".

6a. Prepare Repository

# Check if repo exists locally
if [ -d /tmp/eregistrations-manual ]; then
  cd /tmp/eregistrations-manual && git pull origin gh-pages
else
  gh repo clone UNCTAD-eRegistrations/eregistrations-manual /tmp/eregistrations-manual -- -b gh-pages
fi

6b. Copy and Deploy

# Copy generated manuals into the repo
cp -r {working_directory}/{country_slug}-manuals/ /tmp/eregistrations-manual/{country_slug}/

# Commit and push
cd /tmp/eregistrations-manual
git add {country_slug}/
git commit -m "Update {country_slug} service manuals — {success}/{total_active} services — $(date +%Y-%m-%d)"
git push origin gh-pages

6c. Verify Deployment

Wait up to 30 seconds for CDN propagation, then verify:

sleep 15
curl -s -o /dev/null -w "%{http_code}" https://unctad-eregistrations.github.io/eregistrations-manual/{country_slug}/

Expected: HTTP 200. If not 200, wait another 15 seconds and retry once.

Report live URLs to user:

• Catalog: https://unctad-eregistrations.github.io/eregistrations-manual/{country_slug}/
• Individual manuals: https://unctad-eregistrations.github.io/eregistrations-manual/{country_slug}/{service_slug}/