From a4f300aa30df2b5a7adb6c196c3a0da098a2aef1 Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 20:33:45 -0400 Subject: [PATCH] docs(AGENTS): add Layout conventions section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Specializes the org-level layout rule for m-standard's top-level layout. States the cross-repo rule (docs/ is prose-only) and maps each top-level dir to its purpose: integrated/ for reconciled output, per-source/ for provenance, schemas/ for validation, sources/ for upstream replicas, mappings/ for cross-source name maps, dist/ for the Phase 0 contract. Links back to .github/CONTRIBUTING.md § Layout conventions for the org-level rule. --- AGENTS.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index c97a3f3..e7883e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,3 +164,23 @@ still match what the pipeline produces. - **No live network at pipeline run time.** `make sources` is the only stage that touches the network; all downstream stages read disk. - **Determinism.** Reconcile output must be byte-stable across runs. + +## Layout conventions + +`docs/` holds **only** human-readable prose. Technical artifacts live +elsewhere — m-standard's top-level layout: + +| Path | Contents | +|---|---| +| `docs/` | Spec, ADRs, user guides, build logs, m-libraries surveys | +| `integrated/` | Reconciled cross-source layer — machine-readable M-language reference (TSV + JSON) | +| `per-source/` | Per-source extracted TSVs (anno / ydb / iris) — provenance layer | +| `schemas/` | JSON Schemas validating `integrated/*.json` | +| `sources/` | Offline replicas of upstream sources | +| `mappings/` | Hand-maintained cross-source name mappings | +| `dist/` | Phase 0 `repo.meta.json` (org-level contract) | +| `src/m_standard/` | Library + pipeline tools | +| `tools/` | Non-Python helpers (`clone-ydb.sh`, `check-repo-meta.py`) | + +Enforced by `make check-docs-prose` (CI gate). Org-level rule: +[`.github/CONTRIBUTING.md` § Layout conventions](https://github.com/m-dev-tools/.github/blob/main/CONTRIBUTING.md#layout-conventions).