ToastMachine Markdown documentation audit

ToastMachine Markdown documentation audit

Audit date: 2026-10-19 (Europe/London). Evidence: local source and working-tree inspection. No application tests, provider calls or deployments were performed.

1. Executive summary

The classification totals describe the intake population. This report is an additional KEEP output, listed separately in section 3. No existing file was removed. No uncertain document is presented as disposable.

Documentation health is useful but partial. Substantial Worker references, accepted contracts and source-backed test catalogues coexist with unfinished security/reliability/operations sections. Twenty-seven topic pages were empty scope placeholders; they now provide bounded implementation baselines and evidence links, while remaining partial. The README incorrectly described every topic as a skeleton. Tag discovery had moved beyond the documented pagination-only interface. Historical reviews contained phase-specific schema, publication and archive statements that could mislead readers about current behavior.

The historical catalogue accounts for 542 named declarations in 69 files. Current static AST inspection finds 557 declarations in 70 files: Corpus +11, Resources +2, MCP +2. Additive specification supplements preserve stable historical IDs/assertions; they do not claim executions. No runtime-discovered count, pass count or coverage percentage is inferred.

All 239 distinct revision-pinned local GitHub source paths resolved in local Git objects, and their numeric line references were in range. Hosted access was not tested. Some pinned source bytes differ from the working tree; section 7 lists those files.

2. Audit scope and methodology

Repository boundaries and intake state

The workspace root is /home/johnny/projects, containing independent sibling projects. The root .git is not a usable project checkout. The requested report is therefore placed at toastmachine-docs/docs/audits/markdown-documentation-audit.md, following the existing audit directory. The target path did not exist; the pre-existing performance/caching audit was retained.

Paths in the inventory include the project directory so similarly named files remain unambiguous. They are relative to this multi-repository workspace; strip the first component for an individual repository-relative path. Cross-project relative links target the actual sibling checkout layout. They require those checkouts; hosted wiki publication would need a separate link-location review.

Six Worker implementations were found through actual wrangler.jsonc:main and entrypoint exports, not documentation assumptions:

Additional implementation evidence: Corpus toastmachine-corpus-worker/schema.sql, src/d1/*, src/relationship-store.ts, src/protocol.ts, src/cache.ts, src/lineage.ts, src/materializer.ts, src/public-archive.ts and recovery modules; Resources cache/contract builders/operation IDs; each Worker’s package scripts, test paths, test configuration and deployment workflow. The SDK’s client/transport/validation/sync/archive/SQLite modules and backup export/snapshot/manifest/upload pipeline were inspected where documentation depends on them.

Worker-specific documentation is in toastmachine-docs/workers/*.md; specifications are in workers/test-cases/*.md. Architecture/protocol/data/integrations/development/operations/testing, templates and README navigation live in the same repository. Corpus retains payload contracts/reports and a lineage runbook. Resources retains contract reviews/design notes. Backup and SDK have their own READMEs, runbooks and historical/maintainer reports. The architecture decisions directory contains only .gitkeep. No project Markdown changelog or additional project AGENTS.md was found; dependency/vendor guidance was outside scope.

Pre-existing changes, captured before editing and preserved:

toastmachine-corpus-worker:

 M src/d1-store.ts
 M src/d1/tags.ts
 M src/routes/tags.ts
 M src/store.ts
 M tests/tags.test.ts

toastmachine-docs:

?? docs/audits/performance-and-caching-audit.md

toastmachine-mcp-worker:

 M src/client.ts
 M src/tools.ts
 M tests/routing.test.ts
 M tests/tools.test.ts

toastmachine-resources-worker:

 M src/index.ts
 M src/operation-ids.ts
 M src/resources/openapi.ts
 M test/contract-gaps.test.mjs
 M test/worker.test.mjs
?? test/tags-openapi.test.mjs

Backup, Events, Ingress and Registration began clean. SDK has no Git status baseline; file hashes were captured. The untracked performance/caching audit was included in the intake inventory but left byte-for-byte unchanged.

Assessment and validation

1. Enumerated all project .md files, including hidden/untracked project Markdown, excluding dependency trees and Git internals. Read file contents for purpose/status/reference assessment; classified each independently.
2. Traced entrypoints/imports, routing, storage contracts, authentication, cache wrappers, config declarations, tests and workflow commands. Source code is evidence, not a permitted edit target.
3. Compared dated/pinned documentation with current files. Used local git show revision:path to verify every distinct pinned source target and line range. Preserved historical revision links rather than silently repointing them.
4. Parsed current test sources with the installed TypeScript AST API without importing tests. Compared named declarations with cited revisions. One each/for declaration counts once, irrespective of runtime matrix expansion.
5. Scanned relative inline Markdown links and heading fragments, excluding fenced/inline code. This avoided treating the literal test string ${next} as a documentation link. Follow-up searches found no additional reference-link definitions or HTML link navigation requiring a separate resolver.
6. Checked SDK pin bytes: 557,076 bytes, SHA-256 cfe35c7fe53c5a648ed6d295b01128af98d48f9fe8c2e20d3b1beea376614113, matching local openapi-source.json; 78 operation rows/IDs agree. This is local consistency, not a fresh public fetch.
7. Compared file hashes, Git state and diffs; ran read-only whitespace checks. Only apply_patch edits to existing Markdown and this new report were authorized/executed.

Limits of assurance

Every intake Markdown file received a classification. This is a file-level maintenance and static-reference audit, not exhaustive re-proof of every implementation or copied test assertion. Large generated catalogues were assessed with full-content reference/source-drift checks and focused semantic inspection; shared helper assertions, all parameter expansions and all failure schedules were not rederived. Their existing warnings/proposed gaps remain relevant.

No application suite, build, generator, package installation, format-write command, local server, recovery script, provider API, production probe or deployment was run. Such commands can create non-Markdown state and were unnecessary for these edits. Historic pass counts remain historical and are not this audit’s results. External URLs (4,064 distinct Markdown HTTP(S) targets at intake) are unverified, not assumed broken. Local Git evidence does not establish public hosting/auth availability.

Excluded: node_modules/vendor documentation, .git internals, generated caches/build output, and non-project files outside the sibling project directories. Non-Markdown implementation/configuration/tests were read as evidence only. Deployed config, actual provider limits/support, live retention/credentials, registry publication and browser/Node 24 behavior were not established.

3. Complete Markdown inventory

UPDATE means corrected in place during this audit; it does not imply every section is now complete. KEEP preserves a useful current contract/reference/template with its stated limitations. REVIEW preserves distinct historical/uncertain material pending owner judgment.

New output, excluded from the 73-file intake totals:

4. Files updated

All 49 intake UPDATE files were edited in place. Each new topic baseline is explicitly partial/Code-confirmed; scope and related-navigation structure were preserved. Existing historical results, source IDs and rationale were retained.

5. Removal candidates — recommendations only

None recommended. No pair in the intake inventory has identical complete bytes. Overlapping purposes are not sufficient evidence of dispensability:

• Worker references describe component behavior; protocol/data/operations pages provide cross-component contracts and operator context.
• Test inventories/specifications overlap but have distinct navigation, curated risk analysis, stable source IDs and assertions.
• Templates remain reusable rather than duplicate filled documents.
• Earlier SDK/Resources reviews contain unique compatibility decisions, fixture caveats and validation history even when their old current-status statements are superseded.
• Backup source audits/options/validation records have distinct consistency, FTS and recovery rationale.
• The pre-existing performance/caching audit contains measurement plans and findings beyond the scope of Worker pages.

No candidate met the threshold for removal, so no replacement/dependency-migration or confidence claim is fabricated. Preserve all unique rationale and source provenance if a future owner proposes consolidation. No incoming-link absence, date or filename was treated as removal evidence.

6. Files requiring human review

Additional human decisions, separate from removal:

• Adopt/validate operational ownership, complete security/reliability/observability/deployment sections, and decide which application suites should gate releases.
• Review deployed access controls for MCP Event Hub test routes and Corpus/internal route families. Source establishes branching, not external exposure.
• Confirm backup extraction capability against the deployed FTS database, provider authorization/lock semantics and a complete isolated restore. Existing blockers were not cleared by this audit.
• Decide maintenance of source-extracted test catalogues: additive supplements are current, but historical body excerpts should not silently become working-tree excerpts. The three changed specifications require semantic re-review before claiming current complete assertion coverage.
• Decide whether cross-repository links are consumed in sibling checkouts or a hosted wiki; review hosted navigation before publication.
• Preserve records of original executions outside temporary directories if historical results are intended as independently reviewable evidence.

7. Broken links and consistency issues

Broken links identified and corrected

All six occurred in toastmachine-corpus-worker/STRUCTURED_PAYLOAD_IMPLEMENTATION_REPORT.md, originally line 51. Each pointed to an absent absolute temporary file. They were changed to labeled historical path text; no placeholder log, fabricated result or substitute evidence was created.

No missing intake Markdown target or heading fragment was found after excluding code literals. Missing navigation was addressed by linking the existing audits and connecting the formerly empty topic pages to source/current guidance. Final validation includes the new links.

Factual, status and navigation issues

Pinned source drift (not broken links)

All referenced objects exist locally. The following 16 source paths differ from the corresponding cited historical bytes. This is expected for preserved historical snapshots and cannot justify deleting their documentation.

External links remain unverified. Do not interpret local existence of a pinned Git object as a successful hosted HTTP/link check.

8. Documentation gaps

1. Worker sections remain unfinished. Detailed threat models, authorization matrices, failure/retry/timeout tables, concurrency assumptions, observability, rollback, resource limits and source-reference tables still contain prompts in six Worker pages. Basic security/command additions do not fill them all.
2. Current test bodies need deeper review. Static supplements cover declaration additions, but altered existing assertions, indirect helpers, conditional branches and matrix cases need current semantic review and actual execution. The six proposed and four partially covered curated cases were not implemented or relabeled as passing.
3. Local development runbook is partial. Configured ports/bindings are documented, but a reproducible six-service startup, schema/lineage seed, secret setup and teardown sequence was not exercised.
4. Recovery acceptance remains open. A real retained backup and isolated cloud restore, full data/schema/FTS validation and provider permission/retention evidence are absent from this audit. Public archive coverage alone cannot replace private recovery requirements.
5. Release coordination lacks observed execution. Source runbooks specify fencing, lineage rotation, migrations, contract publication and SDK pin refresh, but operator adoption and actual environment state require evidence.
6. Performance/observability are unmeasured. Cache TTLs/keys and query paths are documented; traffic, cost, hit rate, load limits, dashboards, alerts and escalation ownership require observation. The retained performance audit is a separate plan, not a measured production result.
7. Scope/exposure review is incomplete. Binding declarations and internal path names do not attest network isolation. MCP test routes and low-level maintenance exposure need an environment-specific decision.
8. Documentation navigation needs a publication model. Local sibling links now expose authoritative source/runbooks; standalone hosted docs cannot be assumed to resolve those paths.
9. Historical evidence retention is weak. Six temporary-log links are now explicitly unavailable. A durable evidence location, exact revisions/environment and immutable run artifacts would make earlier results reviewable.

These are gaps in explaining or validating existing behavior. Moderation/redaction remains an open design issue; no implemented endpoint, cleanup capability, exactly-once delivery or automatic arbitrary-restore detection was invented to fill a gap.

9. Recommended next actions

1. Before release/readiness claims: validate deployment identity/bindings, intended test/internal-route exposure, backup extraction and isolated restore; preserve independent lineage and evidence records.
2. Next documentation pass: finish security, failure and operations sections with responsible owners; replace remaining prompts only when supported. Use current topic pages as entrypoints, not complete runbooks.
3. Current tests: semantically reconcile changed historical excerpts, execute the established suites in a separately authorized environment, and assess proposed/partial curated cases. Decide suite CI gates explicitly.
4. Contract maintenance: compare hosted bytes/behavior with source and SDK provenance during the normal release workflow. Do not regenerate non-Markdown assets as part of this audit.
5. Historical retention/navigation: retain all REVIEW files pending ownership review; choose stable evidence storage and hosted-link conventions. Consider consolidation only after preserving unique rationale and checking incoming references.
6. Measurement: follow the pre-existing performance/caching audit’s bounded experiments before changing cache/storage architecture. No such implementation was authorized here.

10. Safety and change summary

Verified results:

• 74 Markdown files scanned, including this report; 801 internal link occurrences, with 0 missing targets or heading anchors. Code literals were excluded. External targets were not fetched.
• All 239 distinct historical source targets resolved in local Git objects; checked numeric line anchors were in range. Sixteen source paths differ from current bytes and are disclosed in section 7.
• Read-only TypeScript AST counts: 557 named declarations / 70 test files. No test module was imported or executed.
• Local SDK pin checksum and all 78 operation-reference rows agree. No generation was run.
• git diff --check exited 0 in all eight Git repositories. SDK has no Git metadata; its content was checked through the file baseline.
• Compared the 418-file project baseline (source/docs/supporting files, excluding dependencies/Git/cache/build directories) by SHA-256: 49 existing files changed, all .md; one file added, this .md report; zero baseline files missing; zero non-Markdown content changes; zero unexpected changed paths; all eight repository HEADs unchanged.
• The pre-existing untracked performance/caching audit remained byte-for-byte unchanged. All intake non-Markdown user edits and the untracked Resources tag test remained byte-for-byte unchanged.

Safety confirmations:

• No files were deleted.
• No files were moved or renamed.
• No non-Markdown files were modified.
• No application, infrastructure, configuration, dependency, database or production changes were made.
• No commits, pushes, publications or deployments were performed.
• Modifications were limited to existing Markdown files and this new audit report.

Only read-only inspection/validation tools and Markdown-only apply_patch mutations were used. Historical pass counts and deployment/publication records are not represented as audit executions.

All intentional edits are limited to 49 existing Markdown files and this new report. Earlier non-Markdown changes are user work and are not audit modifications.