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
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.
• Mentioning future behavior? Separate it into a Planned section, distinct from Supported today.
• 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

Use these rules so readers know what kind of truth they are getting.

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) Supported today vs. Planned

Prevent readers from confusing roadmap items with working features.

Supported today — only describe behavior you can point to in the current codebase.

Supported today: Loom supports workflow schema v1. See /reference/workflow/schema-v1 for the full field reference.

Planned: schema v2 to support [DESCRIBE CAPABILITY]. This section is intentionally future-looking and may change. Link the tracking issue.

Avoid

Loom will support schema v2 soon and you can rely on it for production.

If you must mention future work, add a link to the tracking issue. If you don't have one, leave a placeholder: [NEEDS SOURCE: link to tracking issue/spec].

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	Put it under Planned with a tracking link or [NEEDS SOURCE: …] placeholder.

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):