# SmartStack CLI Documentation Generator

Generates the static HTML documentation served by `ss docs` from:

- **Skill metadata** — every `templates/skills/**/SKILL.md` YAML frontmatter
  (`name`, `description`, `argument-hint`, `allowed-tools`, `phase`, …)
- **Page narrative** — `docs-src/*.md` with frontmatter for slug, title, icon,
  breadcrumb and chosen page template
- **Sidebar layout** — `docs-src/_data/sidebar.json`
- **Package version** — `package.json:version` (auto-injected as the badge)

Output: `.documentation/*.html` (one page per `docs-src/*.md`) plus
`.documentation/manifest.json` (the page list `ss docs` reads at runtime),
committed to git so the npm package ships ready-to-view documentation.

## Commands

```bash
npm run build:docs          # one-shot regeneration
npm run build:docs:watch    # rebuild on change (chokidar)
npm run docs:check          # exit 1 on drift (CI gate)
npm run docs:dev            # build + serve at http://localhost:8080
```

The `prebuild` npm hook automatically runs `build:docs` before `npm run build`,
and `prepublishOnly` chains `docs:check && build` so a stale tree cannot ship.

## Architecture

```
scripts/generate-docs/
├── index.ts                # orchestrator
├── lib/
│   ├── skill-parser.ts     # walks templates/skills/**/SKILL.md
│   ├── markdown-parser.ts  # gray-matter + marked on docs-src/*.md
│   ├── sidebar-builder.ts  # loads + validates docs-src/_data/sidebar.json
│   ├── context-builder.ts  # per-page Handlebars context
│   ├── handlebars-setup.ts # helpers + partial registration
│   ├── stats.ts            # counts skills/agents/hooks/cli commands
│   └── version.ts          # reads package.json
├── templates/
│   ├── layout.hbs          # outer HTML shell
│   ├── partials/           # header, sidebar, skill-card, ...
│   └── pages/              # one .hbs per logical page kind
└── README.md               # this file
```

The generator NEVER touches `.documentation/css/styles.css` or
`.documentation/js/app.js` — those are hand-maintained shells.

## How do I…

### Add a new page

1. Create `docs-src/<slug>.md` with frontmatter (see existing pages).
2. Either reuse `pages/_generic.hbs` (set `page: _generic`) or add a custom
   template under `templates/pages/<slug>.hbs`.
3. Add an entry to `docs-src/_data/sidebar.json` (validation enforces this).
4. Run `npm run build:docs` and commit the new `.documentation/<slug>.html`.

### Rename a skill

1. Update the skill's `SKILL.md` frontmatter (`name:`) and rename the folder
   under `templates/skills/`.
2. The installer's deploy rule (`src/lib/installer.ts:remapSkillPath`) and the
   doc generator's identical mirror (`templates/skills/lib/skill-slug.ts`)
   both pick up the new slug — no other change needed.
3. `npm run build:docs` regenerates every page that lists the skill (commands,
   business-analyse, ba-develop, etc.).

### Add a new sidebar section

Edit `docs-src/_data/sidebar.json` → `sections[]`. Each item references a page
slug; missing slugs fail the build (see `sidebar-builder.ts:validateSidebar`).

### Debug a render

`{{json someValue}}` Handlebars helper dumps any context value. Useful when
extending partials. Remove before committing.

## Anti-patterns

- ❌ **Do not edit `.documentation/*.html` directly.** They carry an
  `AUTO-GENERATED` header comment; CI rejects hand-edits via `docs:check`.
- ❌ **Do not duplicate skill descriptions** in `docs-src/*.md`. The whole point
  is that the YAML frontmatter is the single source of truth.
- ❌ **Do not bake the version number** into any markdown — it is injected at
  build time from `package.json`.