Documentation Errata

Documentation Errata

This is a read-only audit of documentation in the sw-mlpl source repository as inspected on 2026-08-01. No source documentation was changed. Entries identify contradictions or likely stale material and point to stronger current evidence.

How to use this page

flowchart LR
    Claim[Documentation claim] --> Current{Matches current source and history?}
    Current -->|Yes| Use[Use as reference]
    Current -->|No| Errata[Check this errata]
    Errata --> Evidence[Prefer source, tests, CHANGES, completed saga]
    Evidence --> Scope[Separate shipped slice from future scope]

Loading

Severity meanings:

• High: likely to cause a failed build, wrong platform decision, or materially false capability claim.
• Medium: wrong paths, versions, status, or counts that confuse navigation and onboarding.
• Low: historical wording or internal inconsistency with limited operational impact.

Summary

Area	Severity	Stale or inconsistent claim	Current evidence
CUDA guide	High	CUDA is planned and not shipped	CUDA foundation and demo-parity sagas, crates, tests, and demos are present
GPU training scope	High	Broad wording can imply arbitrary MLX/CUDA training	General GPU-training design says only recognized shapes are accelerated today
Root build instructions	High	Run cargo build at repository root	Current repository has cellular component workspaces and no root Cargo.toml
Configuration guide	High	CLI server and connected web remain planned	Server, SSE, cancel, persistence, reattach, visualization storage, and web connect mode shipped
Architecture guide	High	CUDA in-process is planned/deferred	CUDA-enabled evaluator/server vertical slice is implemented
MLX guide	Medium	LoRA is planned; CUDA is the future second backend	LoRA and a CUDA vertical slice have shipped; persistent MLX tensor work is active
Paths throughout docs	Medium	apps/mlpl-web, root crates/mlpl-*, and services/mlpl-mlx-serve	Current code lives primarily under components/*/crates/*
Status scoreboard	High	Stops at v0.20-era roadmap and lists Engram only as generic planned Saga 18	Engram E1-E3 completed, E4 is active, later Engram phases remain planned
Engram status	Medium	Older docs say Engram has no concrete API	engram, apply_engram, engram_stats, hashes/gathers, tape path, and demos exist, while the overall track remains in progress
mHC status	Medium	Research documents discuss mHC without a current status landing page	mHC is planned soon, not shipped
Playground counts	Low	README says both 382 glossary entries and 377 alphabetical entries	Counts contradict within the same file and generated content changes frequently

Detailed findings

E-001: docs/using-cuda.md predates the CUDA implementation

Severity: High. The CUDA guide says “planned,” “not yet shipped,” and describes Saga 17 as future work. The current repository contains components/cuda-rt, components/cuda-model, and components/cuda-eval, plus demos/lora_finetune_cuda.mlpl, published CUDA literate pages, and real-GPU parity tests.

Use CUDA foundation and CUDA demo parity for current implemented scope. Preserve an important qualification: a separate generalized CUDA service/distributed layer and arbitrary-model GPU autograd are not complete.

E-002: broad accelerator wording overstates general training

Severity: High. The README and older MLX/status prose can be read as saying autograd, optimizers, and train work generally on MLX. The actual backend design uses special accelerated paths for recognized LoRA and MLP shapes; an unsupported model can fall through to the CPU tape. The same issue applies to CUDA.

The authoritative limitation is documented in future general GPU training. The active persistent-tensor work is addressing this foundation. Documentation should eventually distinguish “same language remains correct,” “forward op dispatched,” and “entire training graph GPU-resident.”

E-003: root quick-start commands no longer match the cellular monorepo

Severity: High. The README shows root-level commands such as cargo build, cargo run -p mlpl-repl, and cargo bench -p mlpl-bench. The repository root currently has no Cargo.toml. Binaries and tools live in component workspaces such as components/cli, components/serve, and components/dev-tools.

Users must change into the owning component workspace or pass --manifest-path. Demo file paths must then be adjusted relative to that workspace.

E-004: docs/configurations.md contains mutually inconsistent eras

Severity: High. The header says it is current through v0.18.0 and early sections acknowledge shipped server/MLX-service slices. Later sections still title the CLI server “planned” and list mlpl-serve, mlpl-repl --connect, and web origin routing as planned. Those later claims are superseded by Saga 21 and 21.5 implementation.

The same file refers to old install paths such as apps/mlpl-repl. Use the CLI server guide for the shipped REST/SSE, cancellation, persistence, reattach, visualization, and connected-browser surface, while also applying path erratum E-007.

E-005: docs/architecture.md is a pre-CUDA topology snapshot

Severity: High. The architecture guide labels in-process CUDA planned/deferred and presents R2/R3 as the only CUDA future. The current code has an in-process CUDA feature and a CUDA-enabled mlpl-serve vertical slice on Linux/NVIDIA.

The future separate CUDA peer service, multi-GPU/distributed operations, and discovery are still not shipped. A future documentation update should show both the current in-process CUDA server and the planned symmetric peer topology.

E-006: docs/using-mlx.md mixes a v0.11 retrospective with obsolete future claims

Severity: Medium. The MLX guide correctly documents early MLX behavior and poor eager round-trip performance, but still calls LoRA planned and CUDA a future backend. Both have since gained shipped slices. Its old crates/mlpl-mlx and crates/mlpl-eval paths also predate component decomposition.

The performance caveat remains valuable. It should now be paired with the active persistent-tensor/Metal work and with a precise distinction between supported fast paths and general training.

E-007: many code paths point to the former monolithic layout

Severity: Medium. Examples include:

• apps/mlpl-web in the README, REPL guide, server guide, and configuration guide.
• crates/mlpl-eval, crates/mlpl-serve, crates/mlpl-cli, and crates/mlpl-bench in multiple guides.
• services/mlpl-mlx-serve in status/architecture-era prose.

Current equivalents generally live under a component workspace, for example components/web/crates/mlpl-web, components/eval/crates/mlpl-eval, components/serve/crates/mlpl-serve, and components/dev-tools/crates/mlpl-bench. Exact crate ownership should be resolved from current component manifests because decomposition continues.

E-008: docs/status.md is no longer a complete current scoreboard

Severity: High. The status page ends its completed table around v0.20 and presents CUDA-as-a-service as wholly planned. It does not capture the later CUDA foundation/demo parity work or the active Engram E1-E4 sequence recorded in CHANGES.md, docs/saga.md, and .agentrail/plan.md.

It remains useful as historical release context but should not be used alone to answer “what exists today?”

E-009: Engram documentation spans obsolete “planned” and current implemented states

Severity: Medium. Older files such as docs/status.md, docs/plan.md, docs/missing-demos.md, docs/gaps-to-be-addressed.md, and docs/are-we-driven-yet.md describe Engram generically as future research or lacking an API. Current source and references contain:

• ngram_hash and gather_rows primitives.
• engram(...), apply_engram(...), and engram_stats(...).
• Differentiation and training through the Engram path.
• Engram Hash, Learnable Phrase Memory, and Tiny LM + Engram demos.
• Completed E1-E3 records.

The correction is not “Engram is finished.” The Engram saga plan is a multi-stage E1-E10 effort. E4 persistent GPU tensors is active, with MLX, import/retrofit, large-model, checkpoint/scaling, and CUDA phases still ahead.

E-010: mHC needs an explicit planned-soon status

Severity: Medium. Research and paper-driven documents discuss mHC, and are-we-driven-yet correctly identifies only partial prerequisites such as ModelSpec; constrained projections and the mHC architecture graph do not exist as completed capability.

At this snapshot, mHC is planned soon. It should be clearly listed in a current roadmap/status document before readers can reliably distinguish it from implemented paper-driven features.

E-011: README playground counts conflict internally

Severity: Low. The README introduction says the playground has 63 demos, 58 lessons, and a 382-entry glossary. Its glossary section later says 377 alphabetical entries. At least the glossary counts cannot both describe the same snapshot. Demos, lessons, and glossary data are generated/evolving, so hard-coded counts should be generated during the page build or labeled with a build date.

E-012: README backend-roadmap section is stale

Severity: Medium. The README groups using-mlx.md and using-cuda.md under “forward-looking, not yet shipped,” despite MLX having shipped long ago and the current CUDA vertical slice being implemented. using-ollama.md is similarly framed by an older Saga-19 status even though llm_call and :ask work exist in native paths.

Recommended future source-doc maintenance order

This wiki does not perform these changes. If the repository documentation is later refreshed, the highest-value order is:

1. Fix root build/install commands for component workspaces.
2. Replace docs/using-cuda.md with a current shipped-scope guide.
3. Rewrite the configuration and architecture matrices around current local/server/peer modes.
4. Add explicit GPU-residency and fallback language to every accelerator claim.
5. Refresh docs/status.md with CUDA, post-v0.20 work, Engram E1-E4, and mHC planned-soon status.
6. Mechanically update former apps, crates, and services paths.
7. Generate playground content counts from the registry at build time.

Audit boundary

This audit focuses on high-visibility user, deployment, backend, architecture, status, Engram, and mHC documentation. It is not a line-by-line verification of every historical plan or research transcript. Planning files are expected to preserve historical ideas; the issue is when they are linked or labeled as current reference without a supersession notice.