m-dev-tools · rafael5 · May 11, 2026 · May 11, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,36 @@
+---
+created: 2026-05-11
+last_modified: 2026-05-11
+revisions: 0
+doc_type: [REFERENCE]
+---
+
+# tree-sitter-m — 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`
+
+## Top-level
+
+- **`spec.md`** — `[SPEC · DESIGN · design · architecture]` Full v0.1 specification covering scope, architectural decisions, language structure, build pipeline, and v1.0 success criteria.
+- **`build-log.md`** — `[BUILD-LOG · HISTORY · history · implementation]` Chronological per-milestone progression log capturing deliveries, decisions made mid-build, and drift from spec.
+- **`discoveries.md`** — `[GAP-ANALYSIS · NOTES · implementation · function]` DISC-NNN findings from real-world parser use, covering upstream m-standard gaps and intentional parser-side limitations.
+- **`tree-sitter-notes.md`** — `[REFERENCE · NOTES · implementation · design]` Tree-sitter lexer and parser gotchas with workaround patterns; mandatory reading before adding grammar rules.
+- **`vista-parse-error-categories.md`** — `[GAP-ANALYSIS · PLAN · planning · implementation]` Living triage of remaining VistA-corpus parse errors bucketed into actionable categories.
+
+## `adr/` — Architecture Decision Records for the grammar
+
+- **`adr/README.md`** — `[REFERENCE · architecture]` Existing ADR index — see for full per-ADR detail.
+- **`adr/AD-01-source-grammar-surface.md`** — `[ADR · design · architecture]` Source keyword tables from m-standard's union grammar-surface rather than any single M standard.
+- **`adr/AD-02-hand-code-language-structure.md`** — `[ADR · design · architecture]` Hand-code invariant structural rules in `grammar.js`; data-drive the keyword tables from m-standard.
+- **`adr/AD-03-standard-status-on-nodes.md`** — `[ADR · design · function]` Stamp every recognised keyword node with a `standard_status` tier attribute via sidecar metadata lookup.
+- **`adr/AD-04-pin-mstandard-schema.md`** — `[ADR · architecture · planning]` Pin the consumed `m-standard` schema_version so breaking upstream changes require a deliberate major bump.
+- **`adr/AD-05-real-source-corpus.md`** — `[ADR · design · implementation]` Validate against three test layers including the full 39,330-routine VistA corpus as the reality gate.
+- **`adr/AD-06-tree-sitter-bindings.md`** — `[ADR · architecture · implementation]` Ship Node, Rust, Python, and Go bindings via tree-sitter's standard scaffold with no bespoke binding code.
diff --git a/docs/adr/AD-01-source-grammar-surface.md b/docs/adr/AD-01-source-grammar-surface.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [ADR]
+---
+
 # AD-01: Source the keyword tables from `m-standard`'s grammar-surface, not from any single standard
 
 **Status:** accepted (B0, 2026-04)

diff --git a/docs/adr/AD-02-hand-code-language-structure.md b/docs/adr/AD-02-hand-code-language-structure.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [ADR]
+---
+
 # AD-02: Hand-code the language structure; data-drive the keyword tables
 
 **Status:** accepted (B0, 2026-04)

diff --git a/docs/adr/AD-03-standard-status-on-nodes.md b/docs/adr/AD-03-standard-status-on-nodes.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [ADR]
+---
+
 # AD-03: Stamp `standard_status` as an AST node attribute
 
 **Status:** accepted (B0, 2026-04); partial implementation (B3)

diff --git a/docs/adr/AD-04-pin-mstandard-schema.md b/docs/adr/AD-04-pin-mstandard-schema.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [ADR]
+---
+
 # AD-04: Pin to a specific `m-standard` schema version
 
 **Status:** accepted (B0, 2026-04)

diff --git a/docs/adr/AD-05-real-source-corpus.md b/docs/adr/AD-05-real-source-corpus.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [ADR]
+---
+
 # AD-05: Test against a corpus of real M code from multiple sources
 
 **Status:** accepted (B0, 2026-04); validated end of B5 (99.06% on full

diff --git a/docs/adr/AD-06-tree-sitter-bindings.md b/docs/adr/AD-06-tree-sitter-bindings.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-05-09
+revisions: 2
+doc_type: [ADR]
+---
+
 # AD-06: Provide language bindings via tree-sitter's standard scaffold
 
 **Status:** accepted (B0, 2026-04); scaffolded + locally verified (B6,

diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 1
+doc_type: [REFERENCE]
+---
+
 # Architectural decisions — tree-sitter-m
 
 The six decisions that drive the rest of [`docs/spec.md`](../spec.md).

diff --git a/docs/build-log.md b/docs/build-log.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-25
+last_modified: 2026-05-09
+revisions: 23
+doc_type: [BUILD-LOG, HISTORY]
+---
+
 # Build log — tree-sitter-m
 
 Chronological notes on milestone deliveries, decisions made during

diff --git a/docs/discoveries.md b/docs/discoveries.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-05-09
+revisions: 3
+doc_type: [GAP-ANALYSIS, NOTES]
+---
+
 # tree-sitter-m discoveries log
 
 Findings surfaced by real-world use of the parser — gaps in the

diff --git a/docs/spec.md b/docs/spec.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-25
+last_modified: 2026-05-09
+revisions: 7
+doc_type: [SPEC, DESIGN]
+---
+
 # tree-sitter-m — Specification v0.1
 
 **Status:** draft for review

diff --git a/docs/tree-sitter-notes.md b/docs/tree-sitter-notes.md
@@ -1,3 +1,10 @@
+---
+created: 2026-04-26
+last_modified: 2026-04-26
+revisions: 2
+doc_type: [REFERENCE, NOTES]
+---
+
 # Tree-sitter implementation notes
 
 Things about tree-sitter's lexer/parser that aren't obvious from the

diff --git a/docs/vista-parse-error-categories.md b/docs/vista-parse-error-categories.md
@@ -1,3 +1,10 @@
+---
+created: 2026-05-06
+last_modified: 2026-05-06
+revisions: 1
+doc_type: [GAP-ANALYSIS, PLAN]
+---
+
 # VistA parse-error triage — patterns to close
 
 Living document. Triage of the 376 parse-error files in the