Keeping the help guide current

How the help guide is built from content/help, checked, and kept true to the code when a feature changes.

Updated 17 Oct 2026

The help guide is one set of files read two ways. People read it at /help and in the ? drawer. The KAL Assist AI reads it from /api/help, /help/llms.txt and /help/llms-full.txt. Every topic is a markdown file in content/help/. The format is in docs/help-format.md.

How a change reaches the guide

Edit or add a file in content/help/. The file name is the topic's web address, so never rename it once it ships.
Run npm run help:gen. It writes src/lib/help/content.generated.ts and src/lib/help/routes.generated.ts.
Run npm run help:check. It fails if a topic breaks a rule or a generated file is out of date.
Commit the markdown, any pictures and the two generated files together.

Example: head office renames a button on the policy editor. The writer changes the button name in policy-editor.md, sets updated to today and checked to the current commit, runs npm run help:gen, then npm run help:check.

Finding what is out of date

Run npm run help:stale. It lists topics whose sources changed in git since their checked commit, topics never checked, code no topic covers, and page routes no topic lists. Add -- --quiet to print nothing when everything is current. The deploy script runs the quiet form and only warns; it never stops a deploy.

Every option

Command	What it does
`npm run help:gen`	Builds the two generated files from `content/help/*.md`.
`npm run help:check`	Writes nothing. Fails on a broken topic or a stale generated file.
`npm run help:stale`	Reports topics and routes that may be out of date.
`npm run check:help-lib`	Tests search, route matching and front-matter checks.
`npm run help:studio`	Starts the private demo copy of the Hub used for pictures.
`npm run help:shots`	Takes the pictures listed in the recipe files.

Questions

Where do the pictures come from?

Only from the screenshot studio, which uses made-up people and centres. Never from the live site.

Can a topic show a real family or staff member?

No. Use the demo people from docs/help-format.md. The check fails on any email address that does not end in @example.com.

What happens if the check fails during a deploy?

The deploy carries on and prints a warning. Fix the guide in the next change.