Writing documentation

Adding a pageCopy Anchor Link

1. Create apps/docs/content/docs/<section>/<slug>.mdx. The file name is the URL slug: lowercase, hyphenated.
2. Add the slug to the section's meta.json pages list. A page that is not listed is appended automatically by Fumadocs, but listing it makes the order explicit and is required by the validator.
3. Run npm run validate --workspace tobin-docs, then npm run build --workspace tobin-docs.

FrontmatterCopy Anchor Link

Every page needs a title and a one-sentence description. Both are used for search and for the page header.

---
title: Install and run
description: Clone the repository, install dependencies, and start the apps.
---

There is no draft flag: every .mdx file under content/docs is published, searchable and in the sidebar. Do not commit unfinished pages or placeholders. Keep work in progress on a branch or in a draft pull request, and merge a page only when it is accurate. If a page is accurate but incomplete, say so in the page itself.

HeadingsCopy Anchor Link

• Do not repeat the title as a level 1 heading; the page header renders it.
• Start body headings at level 2. Do not skip levels.
• Write headings in sentence case.

LinksCopy Anchor Link

• Link to other pages by their absolute docs path: [Testing](/docs/development/testing).
• Link to a repository file with its GitHub URL on main, for example https://github.com/tobin-protocol/tobin/blob/main/CONTRIBUTING.md. The target must be a tracked file; the validator checks this.
• Link to canonical records instead of copying them.
• Never link to evidence that is unpublished, or to a local path.

CodeCopy Anchor Link

• Fence code blocks with a language: bash, ts, json, text.
• Use bash for commands. Mention PowerShell where the command differs on Windows.
• Every command must be one you ran or checked against package.json, Cargo or CI. Do not invent flags.
• Never include a secret, a seed phrase, a real key, a local path, or a full production contract id.

Callouts, tabs and stepsCopy Anchor Link

<Callout type="warn" title="Testnet only">Text.</Callout>

Callout types are info (default), warn and error. Use <Steps> and <Step> for ordered procedures and <Tabs> only for genuine alternatives such as operating systems. Prefer plain prose and tables.

ImagesCopy Anchor Link

Put images under apps/docs/public/ and reference them with an absolute path such as /img/example.png. Give every image meaningful alt text. The validator reports missing files. Do not add third-party logos or invented screenshots.

MDX pitfallsCopy Anchor Link

Curly braces and a bare < start JSX. Put them in code spans, or escape them.

Style and accuracyCopy Anchor Link

• Be direct and specific. State limitations rather than hiding them.
• Use the project's terms (see the glossary). The code says Organization for an institution.
• Keep the provenance and transaction-state distinctions exact. Do not write "settled" for a prepared or submitted batch.
• Do not claim production readiness, Mainnet support, an audit, wallet compatibility beyond what was shown, or conformance.
• Do not invent partners, customers, statistics, benchmarks, slogans, social links or contact addresses.

Where a new page belongsCopy Anchor Link

A decision, acceptance record, audit, evidence file or security review is not a page here. It belongs in the root docs/ directory as a canonical record, and pages link to it. See Documentation governance.

Hand-written and generated referenceCopy Anchor Link

Write by hand: architecture, tutorials, concepts, security principles, operational procedures, design decisions, troubleshooting and contribution instructions.

Consider generating, only from an authoritative source, and only when the generator is worth maintaining: the public TypeScript API, SDK exports and types, error-code tables, command lists, contract interfaces and ABI, and API schemas (none exists for the institutional API today). Do not generate from incomplete or misleading metadata, and do not add a generator dependency without a clear maintenance benefit. Generated pages must say what they were generated from, and a check must fail when the source and the page drift apart.

Quality standardsCopy Anchor Link

• Technically accurate. Check each statement against the code, tests or a canonical record.
• Consistent terminology, taken from the glossary and domain model.
• No invented API endpoints, environment variables, flags, error codes or configuration.
• No unsupported product claims and no fabricated benchmark numbers. Say when something was not measured.
• Mark Testnet-only capabilities as Testnet-only.
• Keep application state and on-chain state separate; do not call a prepared or submitted batch "settled".
• Link to the authoritative architecture record instead of restating it.
• Examples must work against the actual codebase. Run them.
• Write for two readers: an experienced engineer who wants precision and someone joining the project who needs the terms defined on first use.

Preview and validateCopy Anchor Link

From the repository root:

npm ci                                           # first time; CI uses npm ci --ignore-scripts
npm run dev       --workspace tobin-docs         # preview at http://localhost:3000
npm run typecheck --workspace tobin-docs
npm run validate  --workspace tobin-docs         # frontmatter, navigation, links, images, forbidden strings
npm run build     --workspace tobin-docs         # compiles every page; catches malformed MDX
node scripts/ci/check-links.mjs                  # only if you edited a tracked .md file

Submitting a documentation pull requestCopy Anchor Link

1. Work in your own fork (see Contribution workflow). Update your fork's main from upstream (git fetch upstream, git merge --ff-only upstream/main), then git switch -c docs/<short-description>.
2. Edit only the pages in your assigned scope. Do not edit accepted records under the root docs/ directory, contracts, deployment manifests or evidence.
3. Preview, validate and build as above.
4. Commit with a Conventional Commit message such as docs(reference): document the SDK client. Do not add AI attribution or co-author trailers.
5. Open a pull request against main using the template, say which commands you ran, and disclose anything you did not verify.
6. Obtain review and merge only after approval. Reviewers check technical accuracy first.

Review checklistCopy Anchor Link

• Facts checked against the code, tests or a canonical record.
• Commands run or verified.
• Links resolve (npm run validate --workspace tobin-docs).
• Limitations stated; no unsupported claims.
• Listed in meta.json.
• Builds locally.