From a733c18e52f0e964b71712e27397293c3c60cdbd Mon Sep 17 00:00:00 2001 From: Rafael Richards Date: Sun, 10 May 2026 20:34:57 -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-stdlib's top-level layout. States the cross-repo rule (docs/ is prose-only) and maps each top-level dir to its purpose: docs/ for tracking + per-module reference + plans + guides + testing writeups, dist/ for Phase 0 contract + generated artifacts (manifest / errors / skill), examples/ for demo M source, templates/ for project scaffolds, scripts/ for shell helpers, src/ for M source, tests/ for hand-written + generated test suites, tools/ for Python generator scripts. Links back to .github/CONTRIBUTING.md § Layout conventions for the org-level rule. --- AGENTS.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 25d8dee..0f19ced 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -180,3 +180,22 @@ make check-manifest # drift gate: dist/ matches src/ AND repo.meta.json is co module's source, tests, or per-module doc must update the relevant row in `docs/tracking/module-tracker.md` (see "Tracking conventions" above). + +## Layout conventions + +`docs/` holds **only** human-readable prose. Technical artifacts live +elsewhere — m-stdlib's top-level layout: + +| Path | Contents | +|---|---| +| `docs/` | Tracking (changelog, module tracker, discoveries, parallel tracks), per-module API reference (`modules/`), plans, guides, testing writeups | +| `dist/` | Phase 0 `repo.meta.json` + `stdlib-manifest.json` / `errors.json` / `skill/` (drift gates) | +| `examples/` | Demo M source (e.g. `stdargs-demo.m`) | +| `templates/` | Project scaffolds (e.g. `m-vista-test-suite/`) | +| `scripts/` | Shell helpers | +| `src/` | M (`.m`) source | +| `tests/` | Test suites — hand-written `STD*TST.m` + generated `STD*DOCTST.m` | +| `tools/` | Python generator scripts (gen-manifest, gen-skill, gen-doctests, write-module-frontmatter) | + +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).