Documentation Map

Where everything lives in docs/, and where a new doc belongs. The rulebook itself is docs/README.md — read it before adding anything.

Two kinds of docs, two organising principles

	Reference / knowledge	Delivery / work
Answers	"What's true about Forge"	"What we're doing to Forge"
Organised by	type — a stable folder	status — a pipeline
Lifespan	Lives forever, cross-linked	Transient; archived when done

Reference layers are organised by type because a doc rarely changes type. Delivery work is organised by status because status is exactly what changes — and moving a folder between stages with git mv is a clean, visible signal in history.

Reference layers

Folder	Holds	Rule of thumb
domain/	Vendor-neutral industry knowledge — how the manufacturing and quote-to-cash world works	"True even if Forge didn't exist"
product/	How Forge works, mapped to the domain — per-feature reference, UI flows, the workflow narrative model	"How a user accomplishes X in Forge"
technical	How Forge is built — architecture, API, schema, coding standards, integrations, UI patterns, CI/CD, testing	"How an engineer changes it"
business	Cross-cutting rules, decisions, invariants, correctness and definition-of-done specs	"The why behind the behaviour"
training/	Learning material feeding the in-app LMS	"Material to teach someone"

The two big generated sets — functional-reference/ and ui-flows/ — are indexed here as Feature Reference and UI Flows.

Delivery pipeline

delivery/
  pending/       "going to"  — planned, not started
  in-progress/   "are"       — actively being worked
  complete/      "have been" — shipped AND verified (archive of the effort)
  abandoned/     dropped, with a one-line why + superseded-by

• An effort is a folder, not a file: delivery/in-progress/<effort-slug>/, bundling spec, definition of done, notes and evidence.
• A transition is one atomic git mv, preserving history. Update the effort's status: frontmatter to match its new folder in the same commit.
• complete/ is an archive of the work, not the source of truth. When an effort finishes, its durable facts graduate into the reference layers — rules to business, feature behaviour to product. Current truth always lives in reference; complete/ is the historical record of how it got there.

Browse: pending · in-progress · complete · abandoned

Frontmatter

Every doc carries frontmatter — title, type, status, id, updated. Tooling enforces placement and shape; see §6 Enforcement in the docs README.

A standing warning about drift

Documentation in a fast-moving beta goes stale, and a stale doc is worse than a missing one because it is believed. Two habits keep it honest here:

1. Verify a claim against the code before relying on it — particularly version numbers, counts, and whether a feature is wired up. Where a doc and the code disagree, the code is right and the doc is a bug.
2. Fix the doc, don't work around it. Some facts asserted in CLAUDE.md files are covered by tests that fail when the doc drifts from the code; the intended fix is to correct the prose.

This wiki holds to the same rule: it links to canonical docs rather than copying them, and where it does summarise, it prefers a durable statement over a number that will rot.