Contribution Guide

Who writes what

The hub is organised around the flow (six-stage value loop) plus cross-cutting platform docs and a reference layer.

If you own a subsystem in the codebase, you own its doc in flow/ (if it’s a loop stage) or platform/ (if it’s cross-cutting).

How to add a new doc

1. Pick the right home: if it’s part of one of the six flow stages, drop it into flow/<NN-stage-name>/. If cross-cutting, into platform/. If it’s a definition or shared term, reference/.
2. Copy frontmatter from a sibling file (any verified doc has the right shape). Fill in every required field.
3. Start with status: draft and accuracy: unverified unless you can genuinely defend otherwise.
4. Write in clear, sectioned markdown. H2 (##) for top-level sections, H3 (###) for sub-sections. These become RAG chunk boundaries later.
5. Link to related docs with relative paths: [see Collections & Prompts](../flow/01-collections-and-prompts).
6. Commit with a clear message: docs(knowledge): add flow/<your-doc>.

How to update a doc

1. If substantive: update updated: to today’s date and reset accuracy: to unverified until re-verified.
2. If typo/cosmetic: bump updated: only. Accuracy unchanged.
3. Link to the superseding PR or commit in the text when behaviour changes.

How to promote status

• draft → review: Content is complete. Ping in Slack #docs (or similar) asking for a review.
• review → canonical: Another team member has read it and challenged anything suspect. Accuracy is verified.
• canonical → outdated: Behaviour changed. Downgrade immediately; fix soon.

Accuracy verification — what counts

To mark a doc accuracy: verified:

1. Open the referenced code path(s).
2. Confirm that the claims in the doc match the code.
3. Set verified_against_code: to the commit SHA (e.g. abc1234) or ISO date.

Do NOT mark verified based on “I remember this from 3 weeks ago.” Memory drifts. Code is truth.

Tone guidelines

• Internal/engineering docs: concise, code-linked, present tense (“the extraction pipeline persists…”).
• Sales-facing docs: confident, customer-benefit framed, avoid internal jargon.
• Customer guides: action-oriented (“Click Settings → Integrations…”). Use screenshots or short videos.
• GEO education: authority voice, cite sources, avoid marketing fluff.

What not to do

• Don’t write one doc that tries to serve all audiences.
• Don’t mark canonical if accuracy: unverified. These are independent axes; both must be high before external use.
• Don’t leave broken links. Check before committing.
• Don’t duplicate content across docs. Link instead.
• Don’t write content without a frontmatter. CI will eventually reject this.

Flagging problems

Something inaccurate and you can’t fix it? Add it to accuracy-gaps.md with: doc path, what’s wrong, what the truth probably is, who might know.

How content reaches readers

Markdown in this repo is the source of truth. The team-facing rendered hub is a Nextra app deployed to Vercel at learn.internal.nudg3.ai, password-protected. When you promote a doc from draft → verified:

1. Update frontmatter (status, accuracy, verified_against_code).
2. Commit + push.
3. The Nextra site picks it up on next deploy (auto via submodule, or trigger manually).
4. Drop a one-line note in the team Slack channel.

Full architecture and rationale: publishing.md.

Writing for RAG (future)

Cue will eventually query these docs via pgvector. To make that work well:

• Keep H2/H3 hierarchy clean — chunks will split on these boundaries.
• Opening paragraph of each section should be self-contained (a chunk should make sense in isolation).
• Use links, not inline copy, when referring to other docs.
• Tag every doc precisely — semantic search uses tags: as prefilter.