Documentation Map - armoryworks/forge GitHub Wiki

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.

Where the wikis fit

The umbrella repo's wiki — this one — is the hub: product-level orientation that is true of Forge as a whole. Each sibling repo has its own spoke wiki carrying component depth: layout, conventions, traps and the workflows specific to that codebase. The rule between them mirrors the rule between wiki and docs/: a concept lives in exactly one place, and everything else links to it.

Layer	Holds	Example
Hub wiki	Product truth and orientation	What capability gating is
Spoke wiki	Component depth for one repo	How to add a capability-gated controller
`docs/` in the umbrella repo	Canonical reference and delivery record	Every capability, field by field

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:

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.
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.