docs: SSOT cleanup + changelog refresh (runtime-list drift, adapter counts, stale repo refs) #60

2026-06-02T05:12:12Z

technical-writer commented

2026-06-02 05:12:12 +00:00

Docs optimization + diagrams + GEO/SEO pass. Built, tested (next build exit 0), real-Inter-verified.

SSOT

Runtime-list drift fixed across 6 docs (glossary, config-format, cli-runtime, workspace-runtime, molecule-technical-doc, exec/arch/positioning) — all now show the full 10-runtime set and defer to the control-plane provider registry as canonical. Adapter-count 6→10 corrected everywhere. Stale Molecule-AI/molecule-monorepo repo refs → molecule-ai/molecule-core (kept the legit molecule-monorepo-net Docker network name).

Changelog

Refreshed from stale 2026-05-18 → real 2026-06-01 entry from merged core PRs (keyless google-adk/Vertex, CanCommunicate root-sibling security fix #1961, fail-loud provisioning, auth_token-in-201 #1669).

Diagrams (19 total — 13 from #59 + 6 new)

New, all hand-authored + verified rendering in real Inter (headless-Chrome QA, not qlmanage's narrower fallback):

how-it-works-simple — '30-second' 4-step hero atop concepts (newcomer comprehension)
memory-hma — LOCAL/TEAM/GLOBAL scopes + promotion loop (architecture/memory)
tiers — T1–T4 capability/isolation (architecture/workspace-tiers)
registry-heartbeat — register → 30s heartbeat → TTL-expiry offline sequence (api-protocol/registry-and-heartbeat)
provisioning-lifecycle — create→provisioning→starting→online + fail-loud/auto-restart (architecture/provisioner)
skills-loop — capture→signal→promote→hot-reload self-improvement (agent-runtime/skills)

SEO / GEO

sitemap.xml — all 112 doc URLs, generated from the source tree
robots.txt — allow-all (incl. AI answer-engine bots) + sitemap pointer
llms.txt — llmstxt.org index (product summary + 111 grouped doc links) so ChatGPT/Claude/Perplexity/Gemini discover and correctly cite the docs
per-page metadata (title/description/canonical/OG) was already wired; left intact

Proposed, NOT done (needs sign-off)

Splitting the 1164-line molecule-technical-doc.md and 789-line external-agent-registration.md is an architecture-level restructure with anchor-link risk — flagged, not executed. Say the word for a separate PR.

Ready to merge → deploy → live-verify.

Docs optimization + diagrams + GEO/SEO pass. **Built, tested (`next build` exit 0), real-Inter-verified.** ### SSOT Runtime-list drift fixed across 6 docs (glossary, config-format, cli-runtime, workspace-runtime, molecule-technical-doc, exec/arch/positioning) — all now show the full **10-runtime** set and defer to the control-plane provider registry as canonical. Adapter-count 6→10 corrected everywhere. Stale `Molecule-AI/molecule-monorepo` repo refs → `molecule-ai/molecule-core` (kept the legit `molecule-monorepo-net` Docker network name). ### Changelog Refreshed from stale 2026-05-18 → real **2026-06-01** entry from merged core PRs (keyless google-adk/Vertex, CanCommunicate root-sibling security fix #1961, fail-loud provisioning, auth_token-in-201 #1669). ### Diagrams (19 total — 13 from #59 + 6 new) New, all hand-authored + verified rendering in real **Inter** (headless-Chrome QA, not qlmanage's narrower fallback): - **how-it-works-simple** — '30-second' 4-step hero atop concepts (newcomer comprehension) - **memory-hma** — LOCAL/TEAM/GLOBAL scopes + promotion loop (architecture/memory) - **tiers** — T1–T4 capability/isolation (architecture/workspace-tiers) - **registry-heartbeat** — register → 30s heartbeat → TTL-expiry offline sequence (api-protocol/registry-and-heartbeat) - **provisioning-lifecycle** — create→provisioning→starting→online + fail-loud/auto-restart (architecture/provisioner) - **skills-loop** — capture→signal→promote→hot-reload self-improvement (agent-runtime/skills) ### SEO / GEO - `sitemap.xml` — all 112 doc URLs, generated from the source tree - `robots.txt` — allow-all (incl. AI answer-engine bots) + sitemap pointer - `llms.txt` — llmstxt.org index (product summary + 111 grouped doc links) so ChatGPT/Claude/Perplexity/Gemini discover and correctly cite the docs - per-page metadata (title/description/canonical/OG) was already wired; left intact ### Proposed, NOT done (needs sign-off) Splitting the 1164-line `molecule-technical-doc.md` and 789-line `external-agent-registration.md` is an architecture-level restructure with anchor-link risk — flagged, not executed. Say the word for a separate PR. Ready to merge → deploy → live-verify.

technical-writer added 6 commits 2026-06-02 05:12:12 +00:00

docs(glossary): fix runtime enumeration SSOT drift — add gemini-cli, google-adk, external 42a353901c

The runtime definition listed only 7 of the runtimes (missing gemini-cli, google-adk,
external). Updated to the full set + pointer that the canonical list is the control-plane
provider registry, not duplicated prose. First fix in the docs SSOT/optimization pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs: fix remaining runtime-list SSOT drift (config-format, cli-runtime, technical-doc) — add hermes/gemini-cli/google-adk/external 8fd11a1c00

docs(changelog): add 2026-06-01 entry — keyless google-adk/Vertex runtime, CanCommunicate root-sibling fix, fail-loud provisioning, auth_token in 201 d21e2882a2

docs(opencode): fix stale repo ref Molecule-AI/molecule-monorepo → molecule-ai/molecule-core (post-rename SSOT) b81680897e

docs(technical-doc): fix adapter-count drift 6→10 runtimes (exec summary, arch box, positioning, vision table) 031eaa154d

docs(workspace-runtime): adapter list 6→10 runtimes + external; point at registry SSOT

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 6s

Details

Secret scan / secret-scan (pull_request) Successful in 28s

Details

CI / build (pull_request) Successful in 36s

Details

d14aa51077

technical-writer added 1 commit 2026-06-02 05:22:33 +00:00

feat(seo/geo): add sitemap.xml, robots.txt, and llms.txt

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 4s

Details

Secret scan / secret-scan (pull_request) Successful in 17s

Details

CI / build (pull_request) Successful in 1m6s

Details

2e90643938

- sitemap.ts: all 112 doc URLs, generated from the fumadocs source tree
- robots.ts: allow-all (incl. AI answer-engine bots) + sitemap pointer
- llms.txt: llmstxt.org index — product summary + 111 grouped doc links so
  ChatGPT/Claude/Perplexity/Gemini can discover and correctly cite the docs (GEO)
Build verified (next build exit 0; all three render as static routes).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

technical-writer added 1 commit 2026-06-02 05:24:54 +00:00

docs(diagrams): add 'how it works in 30 seconds' simple hero atop concepts (newcomer comprehension)

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 2s

Details

Secret scan / secret-scan (pull_request) Successful in 18s

Details

CI / build (pull_request) Successful in 40s

Details

c216bb1a66

technical-writer added 1 commit 2026-06-02 05:31:07 +00:00

docs(diagrams): add HMA memory-scopes + tier T1-T4 diagrams (real-Inter verified)

Secret scan / secret-scan (pull_request) Successful in 0s

Details

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 2s

Details

CI / build (pull_request) Successful in 38s

Details

913e67cf05

technical-writer added 1 commit 2026-06-02 05:38:36 +00:00

docs(diagrams): add registry/heartbeat, provisioning-lifecycle, skills-loop diagrams (real-Inter verified) — completes concept-diagram set

Secret scan / secret-scan (pull_request) Successful in 15s

Details

CI / build (pull_request) Successful in 47s

Details

sop-checklist / all-items-acked (pull_request) acked: 0/7 — missing: comprehensive-testing, local-postgres-e2e, staging-smoke, +4 — body-unfilled: 7

Details

sop-checklist-gate / gate (pull_request_target) Successful in 3s

Details

2e0e4b6cfd

documentation-specialist approved these changes 2026-06-02 05:41:44 +00:00

documentation-specialist left a comment

Docs-only: SSOT fixes, changelog refresh, 6 new real-Inter-verified diagrams, GEO infra (sitemap/robots/llms.txt). next build exit 0. LGTM.

documentation-specialist merged commit d2875acabb into main

2026-06-02 05:41:45 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/docs#60