README.md

VistA Cloud Dev — documentation

The design corpus behind modernizing VistA-M development on InterSystems IRIS: a git-first dev bridge, a cross-engine m CLI / Go toolchain, and the VA modernization strategy that frames them.

Where to start

• Doing the work? → m-cli-go-toolchain-implementation-plan.md. This is the one live document — the authoritative build-and-tracking plan. It's the only doc that changes regularly; it's what you open day-to-day.
• Understanding why it's shaped this way? → start with the dependency map, then dig into background/.

Everything outside the active cluster below is foundation: the specs, decisions, investigations, and research that led to the plan. It's living reference (consult it), not historical/ (it isn't superseded) — just not the daily driver.

Active cluster (root) — what you use now

Doc	Type	What it is
m-cli-go-toolchain-implementation-plan.md	plan	The live tracker. The authoritative build sequence and status for the Go m-cli toolchain — bump this as work progresses.
m-cli-go-toolchain-spec.md	spec · canonical	The what/how the plan implements: the cross-engine m CLI command surface, the source/runtime seams, the module layout.
iris-tooling-dependency-map.md	map · canonical	The whole toolchain dependency graph and the ordered build sequence the plan follows.

Background — the foundation

Strategy

• background/vaec-vista-dev-modernization.md — plan — the top-level "why": modern M tooling (version control, M-aware IDE, unit testing) for VA's IRIS-hosted VistA.

Dev bridge — the round-trip product reasoning

• background/dev-bridge/vista-iris-dev-bridge-spec.md — spec · canonical — the core contract: git-first, instance-seeded, test-driven dev of VistA-M on IRIS (.m is canonical).
• background/dev-bridge/vista-iris-dev-bridge-spec-public.md — spec — the public-environment profile of the core.
• background/dev-bridge/vista-iris-dev-bridge-spec-va.md — spec — the VA-environment profile of the core.
• background/dev-bridge/vscode-plugin-design.md — spec — the VS Code editor surface (the parity anchor every developer touches).
• background/dev-bridge/kids-package-round-trip.md — spec — the KIDS release-engineering outer loop (build round-trip into GitHub and back).
• background/dev-bridge/server-side-tooling-split.md — investigation — where the inner loop bisects (server-side run/verify vs container-side edit); adopted by the m-cli spec §9.
• background/dev-bridge/iris-native-source-control-investigation.md — investigation — probed the IRIS-native (%Studio.SourceControl / git-source-control) route; recommended it, but the project chose .m-canonical instead — kept for the reasoning, not adopted.

Toolchain — the m-cli / Go reasoning

• background/toolchain/host-side-go-toolchain-adr.md — adr — the decision to make Go the host-side toolchain language (the three-tier boundary).
• background/toolchain/liberation-binary-design.md — adr — irissync (the Liberation binary): language decision + design as the sole owner of the IRIS source boundary.
• background/toolchain/iris-source-materialization.md — plan — making m-cli usable against the IRIS routine store (the SourceProvider seam + sync engine).
• background/toolchain/iris-ydb-portability.md — research — IRIS ↔ YottaDB CLI comparison and the portability plan for m-cli.
• background/toolchain/go-cli-frameworks.md — research — comparison of Go CLI toolkits (feeds the m-cli framework choice).

How this stays current

• Every doc carries doc-framework frontmatter (type, status, tags). Importance reads off status: canonical (the two core specs + the map) are the sources of truth; proposed specs/plans are in-flight; accepted ADRs and investigations are the settled "why"; nothing here is superseded.
• Validate before pushing: python3 ../doc-framework/tools/validate_docs.py .
• Convention: the active cluster lives at root; background/ is foundation (living reference); a future obsolete doc would move to historical/ with a supersession banner.