Service documentation

A service's documentation is not written by hand. The service's end-to-end journey captures it while it runs, so the documentation always describes the software as it is. A service is not done until its test passes and its regenerated documentation is published to the central documentation share.

What a run produces

For each documented service, npm run docs:services in the e2e kit writes one folder:

e2e/docs/services/<mda-code>/<service-key>/
  screenshots/          numbered step images
  <service-key>.md      the process in plain English, with the screenshots
  <service-key>.docx    the same, from the standard Word template
  capture.json          what the run recorded; the input of both documents

For example, docs/services/WARMA/water-permit/ holds water-permit.md, water-permit.docx, capture.json and images such as 01-find-the-service-and-read-its-page-desktop.png, 01-find-the-service-and-read-its-page-mobile.png and doc-01-...-sealed-pdf.png.

Screenshot names

Pattern	What it shows
`NN-<step>-desktop.png`	Step NN at desktop width (every step)
`NN-<step>-mobile.png`	Step NN at 375 px (citizen steps)
`doc-NN-<output>.png`	The first page of an issued document

All data on the screenshots is synthetic: the seeded @example.test accounts, invented names and NRCs, and the provider test doubles, on a local test installation. The capture refuses to run unless the stack is the local e2e stack with the kit's seeded test accounts.

capture.json

capture.json holds what the journey recorded:

Key	Content
`service`	Name, key, owner, description, who can apply, fees, processing time, validity, legal references, documents, outputs, process, capabilities, published version, legacy mapping (read from the public service API)
`context`	Topology and seed profile of the run
`versions`	Commits of the backend, portal, back office and kit
`steps`	Each step: number, actor, title, description, section, view (portal or back office), desktop and mobile images, spec
`outputs`	Each issued document: title, description, fields, seal, verification, image
`payment`	Payment facts of the run (fee, invoice, receipt)
`notifications`	Notices the run produced (in-app, SMS, e-mail), recipients masked
`tests`	Each test of the journey and its result
`generatedAt`, `docVersion`	When it was generated; "service v<n>, platform <commit>"

The service summary comes from the service's own configuration. If the summary is wrong or empty, fix the service in the back office, not the test.

The Word document and its required sections

<service-key>.docx is filled from the standard template in e2e/docs/services/_template/ (service-template.docx, with service-template.md for the Markdown). The generator only writes content into marked places; the template decides the look and the order. The template has a cover page (Republic of Zambia, the service name, owner, service key, version, date, and a note that the data is synthetic), a contents list, and these sections:

Service summary: owner MDA, purpose, eligibility, fees, turnaround, required documents.
Application process, step by step: the configured process and every step with its screenshots, for the citizen
and each officer role.
Payment.
Output documents: an image of each issued document, its fields, its seal and how it is verified.
Notifications sent.
Legacy mapping, when the service replaces a legacy service (otherwise a sentence saying there is none).
Version and date: version, date, platform snapshot, journeys and their results.

Change the template, not the generated documents. Change it in Word, or in code with npm run docs:template, then regenerate.

Generating and checking

npm run docs:services                           # every documented service, a fresh stack per topology
npm run docs:services -- --only <service-key>   # one service
npm run docs:services -- --use-running          # on the stack you started with npm run stack
npm run docs:check                              # no run: published docs complete, journeys passed

A service's folder is published into docs/services/ only when all its journeys passed and its documentation is complete: every step image, a 375 px image for each citizen step, and a readable .docx with every placeholder filled. A failed journey makes the command exit with code 1 and leaves the old folder as it was, so a broken service never gets fresh-looking documentation.

Register a new service in docs/services/services.json (MDA code, service key, title, topology, seed profile and its spec files). Services of the imported catalogue are documented by the data-driven catalogue journey, per owner (--mda <owner>) or per list (--zigs <ids>). Where it stops at a missing platform feature, the gap is recorded in docs/services/catalogue-gaps.json.

The service status list

e2e/SERVICE-STATUS.md lists every service of the catalogue with five checks:

Check	Done when
Form	The correct and full application form: every legacy field converted, or verified by a passing journey
Workflow	The correct process: the legacy process converted step for step, or verified by a passing journey
Outputs	The correct output documents, every printed field filled, or issued and verified by a journey
E2E	An e2e journey exists and all its tests passed on the last run
Docs	The documentation folder is complete (`.md`, `.docx`, numbered screenshots), as `docs:check` sees it

The first three columns also have a partial state (for example a lookup still unresolved); E2E and Docs are passed or not. A service is done when all five are green and its documentation is on the share.

SERVICE-STATUS.md is generated by npm run status:services from the catalogue snapshot, the import audit and docs/services/. Never edit it by hand: fix the service, then regenerate. npm run e2e and npm run docs:services regenerate it too. Every change that touches a service (form, process, fees, documents, templates, module, journey or seed) regenerates it, and the change report says which columns changed and why. When a column got worse, fix it, or record the reason and the safe default in the open-questions file.

Done means published

The central documentation share holds the single current copy of the kit and every service's documentation. Every person who works on a service runs the kit and puts the regenerated documentation back.

Account. Use your own personal SFTP account with an SSH key. Never share an account. Never write a password into
a repository, a ticket, a chat or the kit's settings.
Automatic upload. npm run share:sync uploads every file that is new or newer locally. It never deletes anything
on the share, never overwrites a file that is newer there (a colleague's), and never sends node_modules/, .stack/, test-results/, playwright-report/, .worktrees/, .git/, keys or .env. It runs by itself after a passing npm run e2e or npm run docs:services and after npm run status:services, once your local, git-ignored settings file names your account and the path to your key. A failed run is not published.
Server check. The share's host key is pinned. If it ever changes, the upload stops: tell the administrator and
never switch the check off.
Fresh copy first. Take a fresh copy (npm run share:sync -- --pull) before starting the next piece of work.

Rules for publishing (people and AI agents)

Publish only after the service's journey passes on both seed profiles and npm run docs:check is green.
Upload only the service folder you regenerated and the kit files you changed. Never delete, rename or overwrite
another service's folder.
Use an SSH key held in your key agent. Never read, print, copy or commit a private key or its passphrase.
If authentication or the host key check fails, stop and report it. Do not retry with another account, a password or
weaker options.
Never upload credentials, .env files, dependencies, test output or real personal data.
Say in your report which folders you published, and the status of each service you touched.

Where the evidence shows

The hub's service catalogue shows this evidence. The list can be searched and filtered by MDA and shows each service's five checks. A service's own page shows its e2e result (for example "3/3 passed, mihud, combined"), a summary of its documentation (steps and images), its generated documentation and a link to download the DOCX.

The hub builds this index from SERVICE-STATUS.md joined with the backend's catalogue snapshot, synchronised into its content/synced/ folder by npm run sync:sources in the hub. Regenerate and publish promptly, so what developers and MDAs see is current.