helpgenai — AI-assisted in-app help generator

License: Polyform Free Trial 1.0.0. Free to evaluate for 32 consecutive days from first install. After that, any continued use (commercial, internal, personal — all of it) requires a paid license. Contact [email protected]. See LICENSE.

helpgenai is the content-authoring side of an inline-help system. The runtime side (the ? button in the header, the /help and /help/<page-key> routes, breadcrumb, tabs, typed reference panels) lives in the host app — helpgenai produces the files that the runtime reads: per-page metadata.json, prose <page>.md, typed reference JSON (icons, cell states, statuses, FAQ), and screenshots.

Design goal: the same scaffold works across projects and frameworks. Today the only framework-specific piece is pass1/extract-razor.md. Adding React means adding pass1/extract-jsx.md. The schemas, prompts, hints, and workflow are framework-agnostic.

Model goal: the prompts are written for any capable LLM. The agent protocol (exit 75 + JSON, documented in CLI.md) is the host-agnostic interface; consumers can drive the engine from any LLM host that implements the protocol. Today's reference host is packages/helpgenai-host-claude-code/; other hosts (Cursor, custom MCP) can be added as peer packages.

When to use

• You added a new page and want help content for it.
• An existing page's UI changed and you want to refresh its help (drift run).
• You're starting a new project and want to lay down the runtime + first page in one pass.

How to use

helpgen is driven by a single CLI binary plus an agent host (Claude Code today, MCP-compatible hosts in the future). The CLI handles every deterministic step. When LLM work is needed, the CLI exits with code 75 and a JSON payload telling the host what to do; the host runs the prompts and re-invokes the CLI to continue. The protocol is documented in CLI.md.

From zero on a new project

# 1. Install helpgen (or symlink the dev checkout to a stable path).

# 2. cd to your project repo and create a helpgen workspace:
mkdir -p tools/helpgen
cd tools/helpgen

# 3. Author the bare-minimum config:
#    - helpmap.yaml: a TOC of pages worth documenting.
#    - styleguide.yaml: design tokens + host components.
#    - hints/<page>.yaml: per-page intent (audience, pain points).
#    The schemas under `schemas/` are the contracts; start by copying
#    the examples shipped with the tool.

# 4. (Optional) Author a CONTENT-STYLE.md at this root if you want to
#    override the tool's default voice/audience/ordering rules.
#    See CLI.md → "Overriding the content contract".

# 5. (Optional but recommended) Index your background docs so Pass 2
#    can ground briefs in real context:
helpgen context index

# 6. Authenticate against your app so capture (Pass 4) can sign in:
helpgen auth <profile>     # interactive — save storage state per role

# 7. Build the help bundle for one page:
helpgen build <page-key>
#    The first invocation exits 75; the agent host runs Pass 1/2/3,
#    then resumes the build automatically. Capture, search-index,
#    schema-validate, and lint all run in the deterministic tail.

Day-to-day

• A page's UI changed → helpgen build <page-key> --regenerate-prose re-runs Pass 2/3 with the new source. Locked sections survive.
• A new context doc was added under context_paths → helpgen context index re-classifies; the next page build picks it up.
• An author wants to nudge the AI's voice for a specific section → drop guidance into guidance/<page>/<anchor>.md (or use the in-app Guidance button if your runtime adapter ships the editor). The next regeneration honors it. See CLI.md → guidance show.
• Verify the engine → helpgen smoke runs the deterministic-gate test suite. CI should run this on every PR that touches the engine.

Verbs at a glance

| Verb | What it does | |-----------------------------|---------------------------------------------------------------| | helpgen build <page> | Full pipeline for one page; agent loop for LLM passes. | | helpgen build all | Deterministic refresh (capture+index+validate+lint, no LLM). | | helpgen build prep <page> | Just produce inputs.json so an agent can drive Pass 1-3. | | helpgen capture <page> | Re-capture screenshots only. | | helpgen capture all | Re-capture every published page. | | helpgen context index | Walk + classify docs under context_paths. | | helpgen context list | Show the indexed-docs summary. | | helpgen guidance list | Show which pages have author-supplied guidance. | | helpgen guidance show | Print one page's or section's guidance. | | helpgen anchors discover | Update hints YAML's selectors from data-help-id on the page.| | helpgen anchors annotate | Walk the LLM through adding data-help-id to source. | | helpgen lint | Run every content-contract check. | | helpgen validate | JSON-schema-check helpmap, hints, metadata, etc. | | helpgen smoke | Run the engine's deterministic-gate test suite. |

Full reference in CLI.md.

What ships with the tool vs. what belongs to the consuming project

The tool's distribution (everything that ships when helpgen is installed):

• README.md, ARCHITECTURE.md, CLI.md, CONTENT-STYLE.md
• helpgen.mjs (CLI entry point)
• lib/*.mjs
• schemas/*.json
• prompts/*.md
• pass1/extract-<framework>.md
• capture/{auth-save.mjs, capture-page.mjs, package.json, README.md}
• discover/anchors.mjs
• smoke/run.mjs

Consumer-owned files that live in the consumer repo's helpgen workspace and ARE committed (these are intent, not artifacts):

• helpmap.yaml — TOC of pages worth documenting.
• styleguide.yaml — design tokens + host components.
• hints/<page>.yaml — per-page strategic intent (audience, pain points, exclusion list).
• guidance/<page>.md and guidance/<page>/<anchor>.md — author- supplied STYLE DIRECTION the AI applies on every regeneration.
• CONTENT-STYLE.md (optional) — if present, replaces the tool's bundled default. Use to override voice/audience/ordering rules.

Generated outputs that the consumer commits (these are the end-user-facing help bundle):

• <output_root>/<page-key>/metadata.json
• <output_root>/<page-key>/<page-key>.md
• <output_root>/<page-key>/icons.json, cell-states.json, etc.
• <output_root>/<page-key>/screenshots/*.png

Transient working files (gitignored):

• .build/<page-key>/* — Pass 1/2 working files, prompt inputs.
• .helpgen/context-index.json — context-doc catalog (regenerated by helpgen context index).

The example versions of these files that live in this repo are artifacts of this consumer project, not part of the tool itself.

Folder layout

<consumer-repo>/
  tools/helpgen/                      ← the helpgen workspace
    README.md                         ← this file (tool ships it)
    ARCHITECTURE.md                   ← engine design + decisions (tool)
    CLI.md                            ← full verb reference (tool)
    CONTENT-STYLE.md                  ← default content contract (tool)
    helpgen.mjs                       ← CLI entry point (tool)
    schemas/*.json                    ← shape contracts (tool)
    prompts/*.md                      ← LLM prompts (tool)
    pass1/extract-<framework>.md      ← per-framework extractor (tool)
    capture/*.mjs                     ← Playwright runners (tool)
    smoke/run.mjs                     ← engine test suite (tool)

    helpmap.yaml                      ← page TOC (consumer)
    styleguide.yaml                   ← design tokens (consumer)
    hints/<page>.yaml                 ← per-page strategic intent (consumer)
    guidance/<page>.md                ← page-level AI direction (consumer)
    guidance/<page>/<anchor>.md       ← per-section AI direction (consumer)
    CONTENT-STYLE.md  (optional)      ← override the default contract (consumer)

    .build/<page>/                    ← Pass 1/2 working files (gitignored)
    .helpgen/context-index.json       ← indexed-doc catalog (gitignored)

  <output_root>/<page>/               ← help-runtime bundle (consumer-served)
    metadata.json
    <page>.md
    icons.json (if applicable)
    cell-states.json (if applicable)
    screenshots/*.png

<output_root> is configured in helpmap.yaml — typically wwwroot/help for ASP.NET apps, public/help for many JS frameworks. The tool produces; the host serves.

Non-goals (today)

• Not a runtime. The ? button, the /help index, the /help/<key> per-page renderer, and the typed reference panels are all separate concerns — they live in the host app.
• Not a hosted SaaS scanner. CLI / agent-only for now.
• Not a markdown editor. Output MD is edited in your normal editor.
• Not a wiki/help-center. Page-by-page only; a central /help route is a separate concern that consumes the same files.

Versioning

Schemas and prompts are versioned with $version fields. Breaking changes bump the version; the runtime checks metadata.json's $schemaVersion so older content keeps rendering as the format evolves.