docs: add index README and YAML frontmatter to every doc

docs/README.md

@@ -0,0 +1,84 @@
+---
+created: 2026-05-11
+last_modified: 2026-05-11
+revisions: 0
+doc_type: [REFERENCE]
+---
+
+# m-stdlib — Documentation Index
+
+> First-pass index generated 2026-05-11. Labels follow the shared vocabulary below; the same vocabulary is used across all m-dev-tools repos.
+
+## Vocabulary
+
+Each doc is labeled `[TYPE · type? · connection · connection?]`.
+
+**Types** — `HISTORY` · `ARCHITECTURE` · `DESIGN` · `ADR` · `SPEC` · `REFERENCE` · `GUIDE` · `TUTORIAL` · `ROADMAP` · `PLAN` · `RESEARCH` · `SURVEY` · `GAP-ANALYSIS` · `STATUS` · `EXPLAINER` · `NOTES` · `WORKED-EXAMPLE` · `SETUP` · `INTEGRATION` · `PROPOSAL` · `BUILD-LOG` · `CHANGELOG` · `POSTMORTEM`
+
+**Repo connections** — `history` · `function` · `design` · `architecture` · `planning` · `implementation`
+
+## `guides/` — User and contributor how-to docs
+
+- **`guides/m-doc-grammar.md`** — `[SPEC · function]` Normative grammar for the structured `; doc:` tags that drive the manifest, per-module markdown, and downstream tooling.
+- **`guides/m-tdd-guide.md`** — `[GUIDE · function]` Operational TDD guide covering the m-stdlib primitives, the `m test` runner, and the inner-loop / release-gate commands.
+- **`guides/users-guide.md`** — `[GUIDE · function]` Deep user reference for m-stdlib — purpose, non-goals, acceptance gate, and per-module usage notes.
+
+## `modules/` — Per-module reference docs
+
+- **`modules/index.md`** — `[REFERENCE · architecture · function]` Canonical released-module catalogue, organised by phase, with cross-module runtime dependencies and conformance corpora.
+- **`modules/stdargs.md`** — `[REFERENCE · function]` Reference for the STDARGS module — argparse with long/short/grouped flags, positionals, sub-commands, and `--` terminator.
+- **`modules/stdassert.md`** — `[REFERENCE · function]` Reference for the STDASSERT module — assertion library with nine extrinsics and `^TESTRUN`-compatible output protocol.
+- **`modules/stdb64.md`** — `[REFERENCE · function]` Reference for the STDB64 module — RFC-4648 Base64 with standard and URL-safe alphabets.
+- **`modules/stdcache.md`** — `[REFERENCE · function]` Reference for the STDCACHE module — LRU + TTL cache over a caller-owned array.
+- **`modules/stdcoll.md`** — `[REFERENCE · function]` Reference for the STDCOLL module — Set / Map / Stack / Queue / Deque / Heap / OrderedDict collections.
+- **`modules/stdcompress.md`** — `[REFERENCE · function]` Reference for the STDCOMPRESS module — gzip / deflate / zstd compress and decompress via libz + libzstd callouts.
+- **`modules/stdcrypto.md`** — `[REFERENCE · function]` Reference for the STDCRYPTO module — SHA-256/384/512 and HMAC-SHA-256/384/512 via libcrypto callouts.
+- **`modules/stdcsprng.md`** — `[REFERENCE · function]` Reference for the STDCSPRNG module — crypto random bytes / hex / base64 / token / int / uuid4 over the kernel CSPRNG.
+- **`modules/stdcsv.md`** — `[REFERENCE · function]` Reference for the STDCSV module — RFC-4180 CSV parser and writer with optional file I/O.
+- **`modules/stddate.md`** — `[REFERENCE · function]` Reference for the STDDATE module — ISO-8601 datetime and duration arithmetic over the proleptic Gregorian calendar.
+- **`modules/stdenv.md`** — `[REFERENCE · function]` Reference for the STDENV module — `.env` loader plus typed accessors (`getInt` / `getBool` / `getFloat`).
+- **`modules/stdfix.md`** — `[REFERENCE · function]` Reference for the STDFIX module — fixture lifecycle with `with` / `invoke` one-shot transactional scopes.
+- **`modules/stdfmt.md`** — `[REFERENCE · function]` Reference for the STDFMT module — printf-style formatter, subset of Python `str.format` syntax.
+- **`modules/stdfs.md`** — `[REFERENCE · function]` Reference for the STDFS module — file-system primitives plus byte-faithful I/O via libc callouts.
+- **`modules/stdhex.md`** — `[REFERENCE · function]` Reference for the STDHEX module — RFC-4648 §8 hex encoding with lowercase default and case-insensitive decode.
+- **`modules/stdhttp.md`** — `[REFERENCE · function]` Reference for the STDHTTP module — HTTP/1.1 client with pure-M wire-format helpers and libcurl-backed verbs.
+- **`modules/stdjson.md`** — `[REFERENCE · function]` Reference for the STDJSON module — RFC 8259 JSON parser and serialiser with one M-tree node per JSON value.
+- **`modules/stdlog.md`** — `[REFERENCE · function]` Reference for the STDLOG module — structured `key=value` logger with five levels and four sinks.
+- **`modules/stdmath.md`** — `[REFERENCE · function]` Reference for the STDMATH module — numeric helpers (clamp / min / max / sum / count / mean) over caller-owned arrays.
+- **`modules/stdmock.md`** — `[REFERENCE · function]` Reference for the STDMOCK module — test-time call interception with `register` / `invoke` / `resolve` / `called` / `args`.
+- **`modules/stdos.md`** — `[REFERENCE · function]` Reference for the STDOS module — process / env / cmdline helpers (env / pid / cmdline / argv / cwd / user / hostname).
+- **`modules/stdprof.md`** — `[REFERENCE · function]` Reference for the STDPROF module — wall-clock profiler with `$ZHOROLOG`-microsecond resolution.
+- **`modules/stdregex.md`** — `[REFERENCE · function]` Reference for the STDREGEX module — Thompson-NFA regex engine with literals, classes, groups, alternation, and greedy quantifiers.
+- **`modules/stdseed.md`** — `[REFERENCE · function]` Reference for the STDSEED module — declarative TSV / JSON manifest loader for FileMan record fixtures.
+- **`modules/stdsemver.md`** — `[REFERENCE · function]` Reference for the STDSEMVER module — SemVer 2.0.0 validate / parse / compare / match with range syntax.
+- **`modules/stdsnap.md`** — `[REFERENCE · function]` Reference for the STDSNAP module — snapshot testing with canonical line-per-leaf dump via `$QUERY` walk.
+- **`modules/stdstr.md`** — `[REFERENCE · function]` Reference for the STDSTR module — ASCII string helpers (pad / trim / replaceAll / split / startsWith / endsWith).
+- **`modules/stdtoml.md`** — `[REFERENCE · function]` Reference for the STDTOML module — TOML 1.0 subset with top-level pairs, `[section]` tables, and scalar values.
+- **`modules/stdurl.md`** — `[REFERENCE · function]` Reference for the STDURL module — RFC 3986 URI parse / build / encode / decode / valid / normalize / resolve.
+- **`modules/stduuid.md`** — `[REFERENCE · function]` Reference for the STDUUID module — RFC-4122 v4 and RFC-9562 v7 UUID generation.
+- **`modules/stdxfrm.md`** — `[REFERENCE · function]` Reference for the STDXFRM module — higher-order array transforms (map / filter / reduce) via XECUTE-evaluated lambdas.
+- **`modules/stdxml.md`** — `[REFERENCE · function]` Reference for the STDXML module — XML 1.0 parser plus XPath 1.0 subset with namespaces, predicates, and functions.
+
+## `plans/` — Implementation and roadmap plans
+
+- **`plans/discoverability-and-tooling-plan.md`** — `[PLAN · planning]` Phased plan to turn m-stdlib into a first-class discoverable surface across the source, CLI, VS Code, and AI consumption channels.
+- **`plans/future-modules-plan.md`** — `[PROPOSAL · planning]` Parking lot for module candidates that haven't crossed TDD-red yet, with priority and promotion process.
+- **`plans/m-libraries-remediation.md`** — `[ROADMAP · planning · design]` Background remediation strategy and prioritised roadmap derived from the M libraries survey — decisions locked.
+- **`plans/m-stdlib-implementation-plan.md`** — `[PLAN · planning · implementation]` Live per-module work plan with phase status, non-negotiables, and per-module specs for v0.0.1 through v0.4.0.
+- **`plans/tdd-orchestration-plan.md`** — `[PLAN · planning · architecture]` Cross-project coordination plan sequencing m-stdlib TDD primitives against the matching m-cli capability work.
+
+## `testing/` — Validation results across real-world corpora
+
+- **`testing/modern-m-corpus-test-results.md`** — `[RESEARCH · GAP-ANALYSIS · function]` Findings from running m-stdlib against five active non-VistA OSS M projects, focused on library-fit substitution opportunities.
+- **`testing/realcode-validation.md`** — `[RESEARCH · function]` Toolchain-side validation of m-stdlib against the m-modern-corpus snapshot — collision sweep and lint-pass matrix.
+- **`testing/vista-corpus-lint-results.md`** — `[RESEARCH · function]` Lint-pass results from running m-cli's rule profiles against the 39,375-routine VistA corpus.
+
+## `tracking/` — Live trackers for in-flight work
+
+- **`tracking/README.md`** — `[REFERENCE · architecture · planning]` Existing index for the tracking/ subdir — defines the four-bucket doc model (planning / implementation / discoveries / tracking).
+- **`tracking/changelog.md`** — `[CHANGELOG · history]` Keep-a-Changelog release history; one entry per tag with thin pointers into trackers and per-module History sections.
+- **`tracking/discoverability-tracker.md`** — `[STATUS · implementation · planning]` Wave A–D implementation tracker for the discoverability and tooling plan, with tabular summary and per-task narrative.
+- **`tracking/discoveries.md`** — `[NOTES · history · implementation]` Discoveries register — every issue not anticipated in a locked plan but addressed during implementation, internal and external.
+- **`tracking/module-tracker.md`** — `[STATUS · implementation]` Master per-module tracker — Summary table, closed-tickets archaeology (T1–T30), and Must-know section.
+- **`tracking/parallel-tracks.md`** — `[STATUS · architecture · implementation]` Dispatch view across L1–L27 / H1–H3 / m-cli companion C-tracks with the cross-module dependency map.
+- **`tracking/TODO.md`** — `[STATUS · implementation]` Resume-here pointer — thin index over the trackers with current release status and live work board.

docs/guides/m-doc-grammar.md

@@ -9,6 +9,10 @@ plan: docs/plans/discoverability-and-tooling-plan.md (the design rationale —
   this guide is the normative spec implementing § 3.1)
 tracker: docs/tracking/discoverability-tracker.md (WA1 closes when this guide
   is reviewed; WA2 is the backfill that brings src/ into compliance)
+created: 2026-05-08
+last_modified: 2026-05-08
+revisions: 1
+doc_type: [SPEC]
 ---
 
 # m-stdlib — M-doc tag grammar

docs/guides/m-tdd-guide.md

@@ -2,6 +2,10 @@
 title: M Test Driven Development Guide
 audience: M developers building or maintaining test suites on top of m-stdlib's TDD primitives.
 companion: users-guide.md (general m-stdlib usage). modules/index.md (per-module reference).
+created: 2026-05-08
+last_modified: 2026-05-10
+revisions: 4
+doc_type: [GUIDE]
 ---
 
 # M Test Driven Development Guide

docs/guides/users-guide.md

@@ -3,6 +3,10 @@ title: m-stdlib — user's guide
 status: live
 audience: M developers (VistA, FIS-GT.M heritage projects, IRIS sites) who want a runtime-library substrate so they don't have to re-invent assertions, JSON, regex, datetime, logging, CSV, URL parsing, file I/O, HTTP, crypto digests, and the rest at every site.
 companion: modules/index.md (canonical inventory); module-tracker.md (live work board); m-stdlib-implementation-plan.md (per-module specs); m-tdd-guide.md (operational TDD guide for projects building tests on top of m-stdlib's TDD primitives).
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 17
+doc_type: [GUIDE]
 ---
 
 # m-stdlib — user's guide

docs/modules/index.md

@@ -1,3 +1,10 @@
+---
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 6
+doc_type: [REFERENCE]
+---
+
 # m-stdlib modules
 
 Regenerated at the **v0.4.0** release (2026-05-08). One row per

docs/modules/stdargs.md

@@ -9,6 +9,10 @@ labels: ['addflag', 'addpos', 'addsub', 'free', 'help', 'new', 'parse']
 errors: ['U-STDARGS-MISSING-POSITIONAL', 'U-STDARGS-MISSING-VALUE', 'U-STDARGS-UNKNOWN-ACTION', 'U-STDARGS-UNKNOWN-FLAG', 'U-STDARGS-UNKNOWN-SUBCOMMAND']
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDARGS` — argparse

docs/modules/stdassert.md

@@ -9,6 +9,10 @@ labels: ['contains', 'eq', 'false', 'len', 'ne', 'near', 'raises', 'report', 'st
 errors: []
 conformance: []
 see_also: ['STDSNAP']
+created: 2026-04-30
+last_modified: 2026-05-08
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDASSERT` — assertion library

docs/modules/stdb64.md

@@ -9,6 +9,10 @@ labels: ['decode', 'encode', 'urldecode', 'urlencode', 'valid']
 errors: []
 conformance: ['tests/conformance/b64/']
 see_also: ['STDCSPRNG']
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDB64` — RFC-4648 Base64

docs/modules/stdcache.md

@@ -9,6 +9,10 @@ labels: ['capacity', 'clear', 'get', 'has', 'new', 'put', 'remove', 'size']
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 4
+doc_type: [REFERENCE]
 ---
 
 # `STDCACHE` — LRU + TTL cache

docs/modules/stdcoll.md

@@ -9,6 +9,10 @@ labels: ['dequeClear', 'dequePeekBack', 'dequePeekFront', 'dequePopBack', 'deque
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDCOLL` — collections

docs/modules/stdcompress.md

@@ -9,6 +9,10 @@ labels: ['available', 'deflate', 'gunzip', 'gzip', 'inflate', 'zstdCompress', 'z
 errors: ['U-STDCOMPRESS-BAD-LEVEL', 'U-STDCOMPRESS-CALLOUT-MISSING', 'U-STDCOMPRESS-LIBZ-FAIL', 'U-STDCOMPRESS-LIBZSTD-FAIL']
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 7
+doc_type: [REFERENCE]
 ---
 
 # `STDCOMPRESS` — gzip / deflate / zstd compression

docs/modules/stdcrypto.md

@@ -9,6 +9,10 @@ labels: ['available', 'hmacSha256', 'hmacSha256Bytes', 'hmacSha384', 'hmacSha384
 errors: ['U-STDCRYPTO-CALLOUT-MISSING', 'U-STDCRYPTO-DIGEST-FAIL', 'U-STDCRYPTO-HMAC-FAIL']
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 7
+doc_type: [REFERENCE]
 ---
 
 # `STDCRYPTO` — Cryptographic digests + HMAC

docs/modules/stdcsprng.md

@@ -9,6 +9,10 @@ labels: ['available', 'base64', 'bytes', 'hex', 'int', 'token', 'useCallout', 'u
 errors: ['U-STDCSPRNG-BAD-COUNT', 'U-STDCSPRNG-BAD-RANGE', 'U-STDCSPRNG-OPEN-FAIL']
 conformance: []
 see_also: ['STDB64', 'STDHEX', 'STDUUID']
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 6
+doc_type: [REFERENCE]
 ---
 
 # `STDCSPRNG` — Cryptographic random

docs/modules/stdcsv.md

@@ -9,6 +9,10 @@ labels: ['parse', 'parseFile', 'write', 'writeFile']
 errors: ['U-STDCSV-OPEN-FAIL']
 conformance: ['tests/conformance/csv/']
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDCSV` — RFC-4180 CSV

docs/modules/stddate.md

@@ -9,6 +9,10 @@ labels: ['add', 'diff', 'fromh', 'now', 'strftime', 'strptime', 'toh']
 errors: ['U-STDDATE-BAD-DUR', 'U-STDDATE-BAD-HOROLOG', 'U-STDDATE-BAD-ISO']
 conformance: []
 see_also: ['STDLOG']
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 6
+doc_type: [REFERENCE]
 ---
 
 # `STDDATE` — ISO-8601 datetime + duration arithmetic

docs/modules/stdenv.md

@@ -9,6 +9,10 @@ labels: ['get', 'getBool', 'getFloat', 'getInt', 'has', 'parse', 'parseFile', 'v
 errors: ['U-STDFS-OPEN-FAIL']
 conformance: []
 see_also: ['STDFS']
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 4
+doc_type: [REFERENCE]
 ---
 
 # `STDENV` — `.env` loader + typed accessors

docs/modules/stdfix.md

@@ -9,6 +9,10 @@ labels: ['active', 'cleanup', 'invoke', 'register', 'with']
 errors: ['U-STDFIX-EMPTY-TAG', 'U-STDFIX-UNREGISTERED-TAG']
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 7
+doc_type: [REFERENCE]
 ---
 
 # `STDFIX` — fixture lifecycle and per-test isolation

docs/modules/stdfmt.md

@@ -9,6 +9,10 @@ labels: ['f', 'fn']
 errors: ['U-STDFMT-MISSING-ARG', 'U-STDFMT-UNCLOSED-BRACE', 'U-STDFMT-UNESCAPED-RBRACE', 'U-STDFMT-UNKNOWN-TYPE']
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDFMT` — printf-style formatter

docs/modules/stdfs.md

@@ -9,6 +9,10 @@ labels: ['append', 'appendBytes', 'available', 'basename', 'dirname', 'exists',
 errors: ['U-STDFS-NOT-WIRED', 'U-STDFS-OPEN-FAIL', 'U-STDFS-READ-TRUNCATED', 'U-STDFS-REMOVE-FAIL']
 conformance: []
 see_also: ['STDENV', 'STDSNAP']
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 7
+doc_type: [REFERENCE]
 ---
 
 # `STDFS` — File-system primitives

docs/modules/stdhex.md

@@ -9,6 +9,10 @@ labels: ['decode', 'encode', 'encodeu', 'valid']
 errors: []
 conformance: []
 see_also: ['STDCSPRNG']
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDHEX` — RFC-4648 §8 hex encoding

docs/modules/stdhttp.md

@@ -9,6 +9,10 @@ labels: ['available', 'buildRequest', 'formatHeaders', 'get', 'parseHeader', 'pa
 errors: []
 conformance: []
 see_also: ['STDURL']
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 6
+doc_type: [REFERENCE]
 ---
 
 # `STDHTTP` — HTTP/1.1 client (libcurl callout)

docs/modules/stdlog.md

@@ -9,6 +9,10 @@ labels: ['DEBUG', 'ERROR', 'FATAL', 'FORMAT', 'INFO', 'LEVEL', 'SINK', 'WARN']
 errors: ['U-STDLOG-INVALID-FORMAT', 'U-STDLOG-INVALID-LEVEL', 'U-STDLOG-INVALID-SINK']
 conformance: []
 see_also: ['STDDATE', 'STDJSON']
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 4
+doc_type: [REFERENCE]
 ---
 
 # `STDLOG` — structured key=value logger

docs/modules/stdmath.md

@@ -9,6 +9,10 @@ labels: ['clamp', 'count', 'max', 'mean', 'min', 'sum']
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-08
+revisions: 2
+doc_type: [REFERENCE]
 ---
 
 # `STDMATH` — Numeric helpers

docs/modules/stdmock.md

@@ -9,6 +9,10 @@ labels: ['args', 'called', 'clear', 'invoke', 'register', 'resolve', 'unregister
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-08
+revisions: 3
+doc_type: [REFERENCE]
 ---
 
 # `STDMOCK` — opt-in test-time call interception

docs/modules/stdos.md

@@ -9,6 +9,10 @@ labels: ['arg', 'argc', 'argv', 'cmdline', 'cwd', 'env', 'exit', 'hostname', 'pi
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDOS` — Process / env / cmdline helpers

docs/modules/stdprof.md

@@ -9,6 +9,10 @@ labels: ['clear', 'count', 'max', 'mean', 'min', 'new', 'percentile', 'start', '
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDPROF` — Wall-clock profiler

docs/modules/stdregex.md

@@ -9,6 +9,10 @@ labels: ['compile', 'find', 'findall', 'free', 'groups', 'match', 'replace', 'se
 errors: ['U-STDREGEX-BAD-PATTERN', 'U-STDREGEX-NO-MATCH', 'U-STDREGEX-UNSUPPORTED']
 conformance: []
 see_also: []
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDREGEX` — regular expressions

docs/modules/stdseed.md

@@ -9,6 +9,10 @@ labels: ['clear', 'load', 'loadJson', 'loaded', 'validate']
 errors: ['U-STDSEED-FILE-NOT-FOUND', 'U-STDSEED-FILER-ERROR', 'U-STDSEED-INVALID-JSON', 'U-STDSEED-INVALID-MANIFEST', 'U-STDSEED-MISSING-FIELD', 'U-STDSEED-MISSING-FILE']
 conformance: []
 see_also: ['STDJSON']
+created: 2026-05-05
+last_modified: 2026-05-10
+revisions: 6
+doc_type: [REFERENCE]
 ---
 
 # `STDSEED` — declarative test data

docs/modules/stdsemver.md

@@ -9,6 +9,10 @@ labels: ['build', 'compare', 'major', 'matches', 'minor', 'parse', 'patch', 'pre
 errors: []
 conformance: []
 see_also: []
+created: 2026-05-07
+last_modified: 2026-05-10
+revisions: 5
+doc_type: [REFERENCE]
 ---
 
 # `STDSEMVER` — SemVer 2.0.0