docs: add rendered architecture diagrams (Mermaid)#63
Merged
Conversation
Add four GitHub-native Mermaid diagrams, each grounded in source and render-validated with mermaid-cli: - README 'How it works': system overview (local-first, only the public registry is remote; trust scan + atomic config writes + guard runtime) - ARCHITECTURE 'Data Flow': install + trust-gate flow (replaces ASCII), with the min-trust and already-installed fail branches made explicit - ARCHITECTURE: new 'Secrets resolution data flow' — shows plaintext secrets live only in the guarded child's in-memory env, never on disk - ARCHITECTURE 'Guard data flow': stdio MITM relay as a sequence diagram (replaces ASCII) — bidirectional parent->child / child->parent inspection, schema-drift block path, and event-log sink No code changes.
Adds the same render-validated runtime message-flow sequence diagram to GUARD.md's 'Mental model' section (as 'Full message flow'), so the user-facing guard reference shows the bidirectional inspection pipeline alongside the existing ASCII sketch + detection-layers table. Same diagram already lives in ARCHITECTURE.md's 'Guard data flow'.
Audit against src/scanner/ found the overview diagram mislabeled the trust pipeline. Corrected to the real 4-component model from trust-score.ts: - Health Check (0-30, health-check.ts: spawn + verify) - Tier 1: Static Patterns (0-40, tier1.ts: secrets/injection/typosquat/exfil) - Tier 2: External Scan (0-20, tier2.ts: optional MCP-Scan) - Registry Metadata (0-10: publisher/age/downloads) Previously Tier 1/Tier 2 labels were swapped and registry metadata was folded into Tier 1; trust score 'max 80 (100 with external scan)' now reflects the dynamic maxPossible. Install + secrets + guard-relay diagrams audited and confirmed accurate (no change).
Full-repo doc audit (every implementation doc vs src/), each finding independently confirmed with file:line evidence. Surgical fixes: README.md - add 'mcpm why' to the Commands table (was undocumented) - expand 'mcpm publish' into scaffold / check / submit subcommands - mcpm serve exposes 8 tools, not 9 (mcpm_up is not registered) docs/ARCHITECTURE.md - CI matrix is Node 22/24/26 (was 20/22/24) - commands/ module: 24 commands, guard 12 subcommands, publish 3 - complete the Commands table (add outdated/why/secrets/publish) docs/GUARD.md - wrap transform includes --declared-env and --orig-hash flags - policy-overrides actions are ignore/warn/block/log_only (+ paused_until) docs/POLICY.md - mark signature_overrides as optional (matches Zod schema) docs/SIGNATURES.md - inspection model also scans structuredContent + JSON-RPC errors (tool_response) and title + full inputSchema (tool_description) CLAUDE.md - version v0.8.0, Node >=22.0.0, last-updated 2026-06-03 - local storage: aliases.json (not scans.json, which doesn't exist) - mcpm serve exposes 8 tools; complete the command list src/commands/guard.ts - header comment: all v0.5.0 guard subcommands are implemented (was 'land in subsequent build steps')
The earlier doc-drift pass set the MCP tool count to 8 to match main's then-current code (mcpm_up built but unregistered). PR #64 registers mcpm_up, so the correct count is 9. Restore mcpm_up to the tool lists in README and CLAUDE. Merge order: this should land with/after #64 (which registers the tool); main's code exposes 9 only once #64 is merged.
This was referenced Jun 8, 2026
Merged
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds 4 GitHub-native Mermaid diagrams so the architecture is visible at a glance instead of buried in prose/ASCII. Each was drafted from the actual source, adversarially verified against the code, and render-validated with
mermaid-cli(all four produce clean SVGs — no syntax-error fallbacks). No code changes.What's added / where
README.md→ How it works~/.mcpm/state.docs/ARCHITECTURE.md→ Data Flow (replaces ASCII)docs/ARCHITECTURE.md→ new Secrets resolution data flowdocs/ARCHITECTURE.md→ Guard data flow (replaces ASCII) anddocs/GUARD.md→ Mental model → Full message flowWhy
The guard relay, trust pipeline, and secrets resolution are inherently flows — far clearer as a picture than as three paragraphs. Mermaid renders natively on GitHub (no checked-in images, diffable in PRs, contributor-editable).
Verification
mermaid-clirendered all 4 to valid SVG (sizes 28–50 KB), confirmed they contain real node labels (Stdio MITM Relay,resolveEnvPlaceholders, etc.) rather than error text.src/commands/install.ts,src/scanner/,src/guard/(run-inner.ts,relay.ts), andsrc/store/keychain.ts.🤖 Generated with Claude Code