docs: retire internal research artifacts and consolidate docs (#3935)

* docs: retire internal research artifacts and consolidate docs (#3926)

* docs: address cleanup review findings (#3926)

Author: louistrue

.github/workflows/moonshot.yml

@@ -40,7 +40,7 @@
 # COST. Deliberately cheap and non-blocking; it MUST NOT become a required
 # check:
 #   - weekly `schedule` + on-demand `workflow_dispatch`, the same profile as
-#     determinism.yml / wide-arithmetic.yml / moonshot.yml;
+#     determinism.yml / wide-arithmetic.yml;
 #   - `push`/`pull_request` ONLY on the paths that can invalidate the result:
 #     the diff engine, the geometry kernel and the wasm bundle it is measured
 #     through, the CLI adapter that builds the fingerprints, and the harness

.github/workflows/xmatch-fixture.yml

@@ -8,6 +8,24 @@ of published `@ifc-lite/*` packages plus a CLI, MCP server, and HTTP server.
 conventions ("house rules"). Read it before a non-trivial change. This file is
 the short version for getting set up and opening a PR.
 
+## Documentation
+
+Keep committed documentation durable and owned by the code it describes:
+
+- `docs/guide` and `docs/tutorials` explain current user workflows.
+- `docs/architecture` records current system boundaries and design constraints.
+- `docs/contributing` contains active contributor and release procedures.
+- A versioned compatibility contract belongs beside its owning package as
+  `SPEC.md`.
+- Planned work belongs in an issue or project, not a checked-in task tracker.
+- Generated benchmark output and investigation transcripts belong in CI
+  artifacts or the originating issue. Git history is the archive; do not add
+  an `archive`, `research-notes`, or completed-plan directory.
+
+Every page under `docs/` must appear in `mkdocs.yml`. Run `pnpm docs:build`,
+`pnpm docs:check-samples`, and `pnpm docs:check-generated` for documentation
+changes.
+
 ## Setup
 
 ```bash

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 /**
  * "Export to BCF" dialog for clash results.
  *
- * The headline requirement (see docs/architecture/clash-detection-plan.md §6) is
+ * The headline requirement (see docs/architecture/clash-detection.md §6) is
  * a *manageable* BCF: 1,000 clashes must never become 1,000 topics. This dialog
  * puts that control in the user's hands — choose how clashes collapse into
  * topics, filter by severity, cap the count, pick the initial status, and

ORCHESTRATION.md

@@ -8,7 +8,7 @@
  * Owns the live `CollabSession`, the local ephemeral identity, the resolved
  * access role, and the presence roster. This is the viewer-side counterpart
  * to `@ifc-lite/collab`; see `docs/guide/collaboration.md` for the feature and
- * `docs/architecture/collab-plan.md` for the design.
+ * `docs/architecture/collaboration.md` for the design.
  *
  * What this scaffolding wires up today:
  *   - identity bootstrap (accountless, persisted handle + color),

apps/viewer/src/components/viewer/ClashBcfExportDialog.tsx

@@ -10,7 +10,7 @@
  * cut distance, click commits via `MutationSlice.splitWallAtDistance`.
  *
  * Bigger surface (slab cut-line, multi-element plane split, beam /
- * column / member) is in `docs/design/element-splitting.md` and
+ * column / member) is in `docs/architecture/element-splitting.md` and
  * arrives in subsequent phases. The slice is shaped to grow without
  * a breaking rename — `splitMode` covers the future modes;
  * `splitHoverPoint` and `splitTargetExpressId` will be reused.