The service status list and publishing

A service is done only when its test passes, its documentation is generated, and that documentation is on the central documentation share for everyone to use. This lesson covers the service status list, how to publish, and the rules that keep the share safe and current.

The service status list

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

Check	Green when	Partial when	Red when
Form	The exact legacy form, every field converted, or verified by a passing journey	Fields the legacy looked up elsewhere are missing, or a lookup is unresolved	A placeholder form, an empty form, or import problems
Workflow	The legacy process converted step for step, or verified by a passing journey	A standard workflow stands in for a missing one, or a document step has no template	It needs a capability that is not available
Outputs	The legacy certificate converted with every printed field filled, or issued and verified by a journey	Printed fields nothing fills, or not yet checked against the legacy system	A legacy certificate exists but was not converted
E2E	A journey exists and all its tests passed on the last run		No journey
Docs	The documentation folder is complete (`.md`, `.docx`, numbered screenshots), as `docs:check` sees it		Not generated

A service is done when all five are green and its documentation is on the share. The status list cannot see the share, so publishing is your responsibility.

Services without a journey of their own are run by the kit's data-driven catalogue journey, which drives any imported service from its own data. Where it stops because the platform lacks a feature, the gap is named in the status list's notes and counted in docs/services/catalogue-gaps.json, which becomes a list of features to build next.

Never edit it by hand

SERVICE-STATUS.md is generated by npm run status:services from the catalogue snapshot, the import audit and the documentation folders. npm run e2e and npm run docs:services regenerate it too. If a row is wrong, fix the service (or its journey), then regenerate.

Every change that touches a service (its form, process, fees, documents, templates, module, journey or seed) must regenerate the list. In your change report, say which columns changed for the services you touched and why. If a column got worse, fix it, or write down the reason and the safe default you assumed in the project's open-questions file.

The kit and every service's documentation live on one central SFTP share. It is the single current copy: everyone who works on a service runs the kit and puts the regenerated documentation back, so all services stay documented.

Your account

Use your own personal SFTP account with an SSH key. Ask the administrator for an account; never share one.
Create a key pair for this purpose, protect it with a passphrase and load it into your SSH agent. Send only the public
key to the administrator, who registers it. Nobody can add a key to their own account.
Never write a password or passphrase into a repository, a ticket, a chat or the kit's settings. The kit's local
settings file (git-ignored, never uploaded) names only your account, the path to your key and the folder.

share:sync

npm run share:sync keeps the share current:

npm run share:sync                 # upload what is new or newer here
npm run share:sync -- --dry-run    # only list what would be uploaded
npm run share:sync -- --pull       # take a fresh copy: download what is newer on the share

It is designed to be safe:

it uploads only files that are new or newer locally;
it never deletes anything on the share;
it never overwrites a file that is newer on the share (a colleague's);
it never sends node_modules/, .stack/, test-results/, playwright-report/, .worktrees/, .git/, the
local settings file, .env files, keys or other credential files;
the share server's host key is pinned: if it changes, the upload stops. Tell the administrator; never switch the
check off.

It also runs by itself, in the background, after a passing npm run e2e, after npm run docs:services when every journey passed, and after npm run status:services. A failed run is not published.

Rules for publishing

These rules apply to people and to AI agents working on their behalf:

Publish only after the service's journey passes on both seed profiles (and federated, when the service can live
on a node) and npm run docs:check is green.
Upload only the service folder you regenerated (docs/services/<mda-code>/<service-key>/) and the kit files you
changed (tests, seed, scripts).
Never delete, rename or overwrite another service's folder. Remove a file only when your own regeneration dropped
it.
Take a fresh copy of the kit (share:sync -- --pull) before starting the next piece of work.
Use the SSH key only through the agent. Never read, print, copy, move 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 real personal data. Screenshots show synthetic data only.
In your report, say which folders you published and the status row of each service you touched.

Where people see the evidence

The Pamodzi Developer Hub's service catalogue (/services) shows, for each service, its five checks from the status list and a link to its generated documentation. Developers, vendors and MDAs use it to see which services are complete and how each one works, so publishing promptly matters.

Putting it together

For the "Example Vendor Permit", the full sequence is:

npm run share:sync -- --pull                                    # fresh copy
npm run e2e -- tests/48-example-permit.spec.js                  # mihud
E2E_SEED_PROFILE=neutral npm run e2e -- tests/48-example-permit.spec.js
npm run docs:services -- --only example-vendor-permit
npm run docs:check
npm run status:services                                         # check the row: five checks green
npm run share:sync -- --dry-run                                 # see what will go
npm run share:sync

Then report: the folder published, and the service's five checks.

Check your understanding

What are the five checks of the service status list?
Why must you never edit SERVICE-STATUS.md by hand, and what do you do instead?
What does share:sync never do to files on the share?
When does share:sync run by itself, and when does it not publish?
What do you do if the share's host key check fails?
Where can developers and MDAs see a service's checks and documentation?

The service status list and publishing