Workspace-root Docs Conventions

Files under docs/** at the workspace root use a two-letter prefix scheme on every new file name. This rule is the authoritative workspace-root convention and is intentionally self-contained.

Prefixes and directories

Prefix	Layer	Folder
ul-	Universe lore	docs/lore/universe/
gl-	Game-local lore	docs/lore/games/{game}/
lh-	Lore hooks / cross-reference	docs/lore/games/{game}/hooks/
gd-	Game design	docs/design/games/{game}/
ud-	Universe design	docs/design/universe/
ad-	ADRs	docs/adr/
sp-	Specs	docs/specs/
rn-	Runtime / engine	docs/runtime/
pr-	Project / process / meta	docs/project/

The table is closed. Introducing a new prefix requires an ADR.

Rules for new files

• Every new file under docs/** must carry a valid prefix from the table above.
• Prefix and folder must agree. A ul-* file may not live in docs/design/; a gd-* file may not live in docs/lore/.
• Post-prefix names must be globally unique within the workspace-root docs/ tree. Lowercase-hyphenated; no spaces; no underscores.
• New files declare layer in YAML frontmatter: prefix:, layer:, status:, date: are required. ad-* adds id: and title:.
• Cross-layer reference rules apply: ul-* and ud-* may reference only ul-* / ud-*; gl-* may reference same-game gl-* plus ul-* / ud-*; gd-* routes lore links through lh-* rows; lh-* is the only mediation layer. A ul-* or ud-* file referencing a gl-* file is a layering FAIL.

Rule for existing files (no silent migration)

Existing un-prefixed files under docs/decisions/, docs/design/, docs/research/, and the top-level docs/*.md files keep their names. This convention does not retroactively rename anything. Migration is the explicit scope of a future Project-File-Migration-Prompt.md task — it does not happen as a side effect of an unrelated wave.

No silent renames. No redirect stubs. Mixing prefixed and un-prefixed files in the same tree is expected during the transition window.

Deviations summary

• docs/decisions/ADR-NNNN-*.md (uppercase, legacy) and docs/adr/ad-NNNN-*.md (lowercase, new) are two separate workspace-root ADR namespaces. Cite the full path or name the subject; a bare ADR-0002 reference is ambiguous.
• docs/design/ retains its existing numbered specs (00-overview.md through 10-host-secs-execution-boundary.md) under their current un-prefixed names. NEW spec content goes into docs/specs/ with the sp- prefix.
• docs/research/ continues as the un-prefixed scratch tier; docs/project/pr-* is committed governance. Research notes do not graduate to governance by simple rename.

When editing existing files in this scope

If the file already carries a prefix, read its YAML frontmatter first; prefix: and layer: tell you which layer's cross-reference rules apply. If the file is un-prefixed (an existing pre-scheme doc), the cross-layer rules above do not retroactively apply — edit in place without renaming.