PR Review: docs: render palace and architecture diagrams as Mermaid

Executive Summary

Affected Areas: Root README, package README (mempalace/), benchmarks docs, hooks docs

Business Impact: Improved developer experience — diagrams render as interactive SVGs on GitHub instead of monospaced ASCII

Flow Changes: None — no code paths affected

Ratings

PR Health

• Has clear description
• References ticket/issue (if applicable) — N/A, standalone docs improvement
• Appropriate size (5 files, +65/−72 lines)
• Has relevant tests — N/A, documentation only

Guidelines Compliance

No project guidelines loaded.

Medium Priority Issues

(Should fix, not blocking)

[Bug] #1: Curly braces {} in Mermaid node labels may break rendering

Location: hooks/README.md (Save Hook diagram, nodes F and K) | Confidence: MED

The nodes F["echo '{}' — let AI stop"] and K["Hook sees flag — echo '{}' — let it through"] contain literal {} inside double-quoted Mermaid labels. In Mermaid, {} is the diamond/rhombus shape syntax. While modern renderers (10.x+) handle this inside "...", older viewers (GitLab, some VS Code extensions, Obsidian) can choke on it.

-  E -->|less than 15| F["echo '{}' — let AI stop"]
+  E -->|less than 15| F["echo '#123;#125;' — let AI stop"]

-  J --> K["Hook sees flag — echo '{}' — let it through"]
+  J --> K["Hook sees flag — echo '#123;#125;' — let it through"]

[Code Quality] #2: Quote style changed from double to single quotes

Location: hooks/README.md (Save Hook diagram, nodes F and K) | Confidence: MED

The original ASCII diagram shows echo "{}" (double quotes). The Mermaid version changes this to echo '{}' (single quotes). The hook outputs valid JSON ({} is an empty JSON object), so double quotes are the semantically correct representation. Readers may use the diagram as a reference for the hook's actual behavior.

-  E -->|less than 15| F["echo '{}' — let AI stop"]
+  E -->|less than 15| F['echo "#123;#125;" — let AI stop']

Note: Combining this fix with #1 resolves both issues simultaneously.

[Semantic] #3: Tunnel uses directional arrow instead of bidirectional link

Location: README.md (palace layout diagram, tunnel connection) | Confidence: MED

The prose states: "tunnels, which connect rooms from different wings to one another" — describing a bidirectional connection. The Mermaid uses PA -.->|tunnel| PrA which renders as a one-way dotted arrow from Person wing to Project wing, introducing directionality that doesn't exist in the original.

-  PA -.->|tunnel| PrA
+  PA <-.->|tunnel| PrA

Low Priority Issues

(Nice to have)

[Code Quality] #4: Minor label text simplifications

Location: benchmarks/BENCHMARKS.md, benchmarks/HYBRID_MODE.md | Confidence: LOW

Small wording changes in node labels drop qualifiers present in the original ASCII:

• BENCHMARKS.md: HALL (concept: travel, ...) became HALL — travel, ... — drops the "concept:" prefix
• HYBRID_MODE.md: "the primary index" → "primary index"; "extracted from user expressions" → "from user expressions"

These don't meaningfully change understanding but represent minor semantic drift from the originals.

Positive Observations

• mempalace/README.md: The Mermaid diagram is better than the original ASCII — it adds explicit dotted-line connections (Search -.-> C and KQ -.-> K) that make implicit data flows visible. The prose confirms these relationships ("The MCP server exposes both to any AI tool"), so these additions are accurate.
• Database shapes: Uses [(...)] cylinder notation for ChromaDB and SQLite — a nice semantic touch.
• Decision diamond: hooks/README.md correctly uses {...} diamond shape for the message-count branch, improving clarity over the original ASCII's ┌───/└─── notation.
• Subgraph usage: README.md uses subgraph blocks for wings, providing clear visual grouping.
• All 5 diagrams are syntactically valid flowchart TB declarations with unique node IDs.

Flow Impact Analysis

No code flow impact — all changes are documentation only.

Created by Octocode MCP https://octocode.ai

Thanks for the review — addressed the feedback in the latest push:

Tunnel (README palace diagram)

• Switched to a bidirectional dotted link: PA <-.->|tunnel| PrA so it matches “connect rooms from different wings to one another.”

Hooks Save-hook diagram ({} + echo semantics)

• Removed literal {} from Mermaid node labels (avoids parsers that treat {} as rhombus syntax).
• Documented the real behavior in prose right under the diagram: the hook prints echo "{}" (empty JSON) when allowing a stop.
• Node text now describes “empty JSON on stdout” without embedding curly braces in the chart.

Benchmark copy drift

• Restored the original phrasing in benchmarks/BENCHMARKS.md (HALL concept: …) and benchmarks/HYBRID_MODE.md (primary index, “opened on demand…”, “extracted from user expressions”).

Happy to tweak further if anything still looks off.