Docs contribution guide

Ship doc changes that are accurate, linkable, and easy to review — even when the implementation is moving underneath you.

Quick reference

Resource	Route	Source
Alpha support boundary	/product/support-boundary	apps/loom-docs/product/
CLI reference	/reference/cli/overview	apps/loom-docs/reference/cli/
Diagnostics ladder	/docs/troubleshooting/diagnostics-ladder	apps/loom-docs/docs/troubleshooting/
Workflow schema v1	/reference/workflow/schema-v1	apps/loom-docs/reference/workflow/
Hello Loom quickstart	/docs/getting-started/hello-loom	apps/loom-docs/docs/getting-started/

Fast checklist

Run through this for every docs PR before requesting review.

• CLI surface changed? Update the relevant pages under apps/loom-docs/reference/cli/ and verify they match loom <command> --help output.
• Making a behavioral claim? Use a state from the Alpha support boundary, name its scope, and link concrete evidence.
• Mentioning future behavior? Label it Planned, link its tracking issue or specification, and keep it separate from current behavior.
• Troubleshooting content? Keep it pointer-first — link the diagnostics ladder, tell the reader what to check next, avoid pasting log walls.
• New page? Place it in the right area and wire it into the correct sidebar file (see Adding a new page below).
• Ran verification? Serve or build the docs locally before requesting review.

1) Where your content belongs

Choose the section that matches the reader's task.

Area	Route	Purpose	Example
Docs	/docs/…	Tutorials, conceptual explanations, guided how-tos. Focus on "why" and "how it fits together".	/docs/getting-started/hello-loom
Reference	/reference/…	Precise, stable facts — CLI commands, schemas, contracts. Optimize for lookup and exactness.	/reference/workflow/schema-v1
Knowledge Base	/kb/…	Patterns, FAQs, playbooks, deeper operational guidance.	apps/loom-docs/kb/faqs/index.md

Default: put learning paths in Docs, anything that must match machine output in Reference.

2) When the CLI changes

If a change affects any of the following, treat it as a required doc update:

• A command is added, removed, or renamed
• A flag is added, removed, or renamed
• Flag defaults change in a user-visible way
• An environment variable is introduced, removed, renamed, or changes behavior
• Output or examples in docs no longer match real --help text

Where to update

Start with the CLI overview: /reference/cli/overview. Most CLI pages live under apps/loom-docs/reference/cli/.

Minimum content per command page

• Command purpose — one sentence
• Copy-pastable example for the common path
• Flags and environment variables that a typical user touches
• "Changed in …" note if the PR updates behavior

3) Use the canonical claim states

Use the Alpha support boundary for every statement about product behavior:

• Supported is present in the current release, bounded to documented constraints, and backed by executable or reference evidence.
• Experimental is present for evaluation but may change or be removed during Alpha.
• Planned is directional and not part of the current executable contract.
• Unsupported is absent, rejected, or outside the documented contract.

Every new present-tense guarantee must name the release, platform, provider, input, or lifecycle limits that matter and link a concrete evidence location. Good evidence includes executable help, a focused test, a schema or contract source, or a release/CI verification result.

If that evidence does not exist, do not write the behavior as Supported. Choose the state the facts justify or remove the claim until it can be verified.

Planned claims need a tracking issue or specification and must not imply a date or final design. Unsupported behavior may be documented to set a boundary, but a workaround does not make it supported.

For example, a schema claim should link the workflow schema v1 reference. A CLI claim should link the relevant generated or help-verified CLI reference.

4) Troubleshooting docs — pointer-first

When writing troubleshooting guidance:

1. Link the Diagnostics ladder early.
2. Prefer "check these artifacts next" over "scroll through this output".
3. Use the ladder's manifest/event terminology consistently.

If your doc introduces a new troubleshooting concept, it should either fit into the existing ladder or include a "Where this fits in the ladder" note linking back to it.

5) Adding a new page

File placement

Area	Directory
Docs	apps/loom-docs/docs/
Reference	apps/loom-docs/reference/
Knowledge Base	apps/loom-docs/kb/

Naming conventions

• Use kebab-case filenames: my-new-page.md
• Keep titles task- or concept-shaped (what someone would search for)
• Avoid duplicating words implied by the section path

Wire the sidebar

Adding a page without navigation makes it invisible. Update the correct sidebar file:

Area	Sidebar file
Docs	apps/loom-docs/sidebars.ts
Reference	apps/loom-docs/sidebars.reference.ts
Knowledge Base	apps/loom-docs/sidebars.kb.ts

Mirror existing patterns in the file (category structure, ordering). If unsure, search for a nearby page and follow that structure.

6) Verify your change

A) Serve locally (fast feedback)

pnpm nx run loom-docs:serve

Once running, verify:

• The new/edited page renders without broken Markdown
• Sidebar navigation includes the page (if you added one)
• Internal links resolve (no 404s)

B) Build the docs (catches more issues)

pnpm nx run loom-docs:build

Use this when you changed sidebars, reference pages with many links, or anything that could break static generation.

C) Verify CLI docs against --help

Run the CLI and compare the output to the doc page you touched:

loom --help
loom <command> --help

If the docs contain an example command, run it (or a safe variant) and confirm the output and flags match.

7) Review expectations

When you open a docs PR:

• What changed — 1–3 bullets, especially if it tracks an implementation PR
• How you verified — "Served docs locally" / "Built docs" / "Compared --help output"
• Reviewer — if the repo has a CODEOWNERS file, follow it

If docs cannot ship in the same PR as the code change, create a follow-up task and link it from the PR description.

Common edge cases

Situation	What to do
Change touches multiple areas (CLI + runtime logs + schema)	Update all impacted pages and add cross-links. Prefer linking the canonical reference for schemas: /reference/workflow/schema-v1.
Examples include environment-variable output	Keep examples stable and minimal. If output is inherently variable, say so ("output will differ based on …") instead of pasting a brittle transcript.
Describing behavior not yet supported	Use Planned with a tracking source, or Unsupported when the current executable rejects it. Link the support boundary.

PR description template

Copy this into your merge request description:

## Summary

- What changed:
- Why:

## Verification

- [ ] `pnpm nx run loom-docs:serve`
- [ ] `pnpm nx run loom-docs:build`
- [ ] CLI docs checked vs `--help` output (if applicable)

## Links

- Related code change:
- Tracking issue/spec (for Planned sections):