Plain-language glossary and writing guide

Technical words in plain English

Action digest

A fingerprint of the exact action a person reviewed. If the action changes, the fingerprint no longer matches.

Advisory lock

A database rule that makes one job wait while another job is changing the same conversation, order, or payout.

Available balance

Money recorded for an owner that is no longer waiting for a hold or review.

Certification

Proof that one exact connection to an outside company passed its production checks.

Conversation goal

The job a person is trying to finish in a chat, including where they stopped.

Held balance

Money recorded for an owner that cannot be paid out yet.

Inbox event

An update from an outside company that Neo saves before working on it.

Outbox command

A saved instruction that Neo still needs to send to an outside company.

Reconciliation

Checking Neo's records against an outside company's records and fixing a mismatch safely.

Sandbox

A test setup where no real money moves and no real-world job is completed.

How to update this guide

1. Check the current code, test, and product journey before changing a claim.
2. Write the user's journey first: what they do, what Neo does next, and what result they see.
3. Add technical detail only after the simple explanation.
4. Say clearly whether a feature is built, live, switched on, test only, or unfinished.
5. Never publish secrets, private customer details, or instructions that make an attack easier.
6. Run the documentation checks and open the changed pages on desktop and mobile.
7. Update the deeper project records when a product rule, safety rule, or release process changed.

The plain-language rule

Assume the reader knows nothing about Neo and has not studied software engineering.

1. Start with what the feature helps a person do.
2. Tell the story in the order it happens.
3. Use everyday words before technical words.
4. When a technical word is necessary, explain it the first time.
5. Keep paragraphs short and remove details that do not help the current step.
6. Put file names, internal controls, and proof after the simple explanation.
7. Label future or test-only work clearly.

Diagrams should use the words a reader already learned on the page. Public claims must still follow docs/NEO_OUTCOME_MESSAGING.md.

Documentation verification

npm run docs:check
npm run typecheck
npm test
git diff --check

Local and deployed browser QA checks navigation, search, tables of contents, Mermaid rendering, internal links, keyboard behavior, 404 pages, responsive layout, and the public/app/API/docs host boundary.

• src/documentation.ts
• scripts/check-documentation.ts
• test/documentation.test.ts
• docs/audits/documentation-traceability.md