mindforge-cc 11.8.2 → 11.9.0

package/.mindforge/skills/arxiv/scripts/search_arxiv.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Search arXiv and display results in a clean format.
+
+Usage:
+    python search_arxiv.py "GRPO reinforcement learning"
+    python search_arxiv.py "GRPO reinforcement learning" --max 10
+    python search_arxiv.py "GRPO reinforcement learning" --sort date
+    python search_arxiv.py --author "Yann LeCun" --max 5
+    python search_arxiv.py --category cs.AI --sort date --max 10
+    python search_arxiv.py --id 2402.03300
+    python search_arxiv.py --id 2402.03300,2401.12345
+"""
+import sys
+import urllib.request
+import urllib.parse
+import xml.etree.ElementTree as ET
+
+NS = {'a': 'http://www.w3.org/2005/Atom'}
+
+def search(query=None, author=None, category=None, ids=None, max_results=5, sort="relevance"):
+    params = {}
+    
+    if ids:
+        params['id_list'] = ids
+    else:
+        parts = []
+        if query:
+            parts.append(f'all:{urllib.parse.quote(query)}')
+        if author:
+            parts.append(f'au:{urllib.parse.quote(author)}')
+        if category:
+            parts.append(f'cat:{category}')
+        if not parts:
+            print("Error: provide a query, --author, --category, or --id")
+            sys.exit(1)
+        params['search_query'] = '+AND+'.join(parts)
+    
+    params['max_results'] = str(max_results)
+    
+    sort_map = {"relevance": "relevance", "date": "submittedDate", "updated": "lastUpdatedDate"}
+    params['sortBy'] = sort_map.get(sort, sort)
+    params['sortOrder'] = 'descending'
+    
+    url = "https://export.arxiv.org/api/query?" + "&".join(f"{k}={v}" for k, v in params.items())
+    
+    req = urllib.request.Request(url, headers={'User-Agent': 'HermesAgent/1.0'})
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        data = resp.read()
+    
+    root = ET.fromstring(data)
+    entries = root.findall('a:entry', NS)
+    
+    if not entries:
+        print("No results found.")
+        return
+    
+    total = root.find('{http://a9.com/-/spec/opensearch/1.1/}totalResults')
+    if total is not None:
+        print(f"Found {total.text} results (showing {len(entries)})\n")
+    
+    for i, entry in enumerate(entries):
+        title = entry.find('a:title', NS).text.strip().replace('\n', ' ')
+        raw_id = entry.find('a:id', NS).text.strip()
+        full_id = raw_id.split('/abs/')[-1] if '/abs/' in raw_id else raw_id
+        arxiv_id = full_id.split('v')[0]  # base ID for links
+        published = entry.find('a:published', NS).text[:10]
+        updated = entry.find('a:updated', NS).text[:10]
+        authors = ', '.join(a.find('a:name', NS).text for a in entry.findall('a:author', NS))
+        summary = entry.find('a:summary', NS).text.strip().replace('\n', ' ')
+        cats = ', '.join(c.get('term') for c in entry.findall('a:category', NS))
+        
+        version = full_id[len(arxiv_id):] if full_id != arxiv_id else ""
+        print(f"{i+1}. {title}")
+        print(f"   ID: {arxiv_id}{version} | Published: {published} | Updated: {updated}")
+        print(f"   Authors: {authors}")
+        print(f"   Categories: {cats}")
+        print(f"   Abstract: {summary[:300]}{'...' if len(summary) > 300 else ''}")
+        print(f"   Links: https://arxiv.org/abs/{arxiv_id} | https://arxiv.org/pdf/{arxiv_id}")
+        print()
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    if not args or args[0] in {"-h", "--help"}:
+        print(__doc__)
+        sys.exit(0)
+    
+    query = None
+    author = None
+    category = None
+    ids = None
+    max_results = 5
+    sort = "relevance"
+    
+    i = 0
+    positional = []
+    while i < len(args):
+        if args[i] == "--max" and i + 1 < len(args):
+            max_results = int(args[i + 1]); i += 2
+        elif args[i] == "--sort" and i + 1 < len(args):
+            sort = args[i + 1]; i += 2
+        elif args[i] == "--author" and i + 1 < len(args):
+            author = args[i + 1]; i += 2
+        elif args[i] == "--category" and i + 1 < len(args):
+            category = args[i + 1]; i += 2
+        elif args[i] == "--id" and i + 1 < len(args):
+            ids = args[i + 1]; i += 2
+        else:
+            positional.append(args[i]); i += 1
+    
+    if positional:
+        query = " ".join(positional)
+    
+    search(query=query, author=author, category=category, ids=ids, max_results=max_results, sort=sort)

package/.mindforge/skills/code-tour/SKILL.md

@@ -55,7 +55,7 @@ stop, building understanding progressively.
 
 **Stop format (mandatory for each stop):**
 
-```markdown
+````markdown
 ## Stop N: [Descriptive Title]
 
 **File:** `src/path/to/file.ts` (lines 42-87)
@@ -81,7 +81,7 @@ function handleRequest(ctx: Context) {
 **Checkpoint:** After this stop, you should understand:
 - [Concrete understanding goal 1]
 - [Concrete understanding goal 2]
-```
+````
 
 **Progressive complexity rules:**
 - Stop 1-3: Configuration, entry points, "what runs when the app starts"

package/.mindforge/skills/code-wiki/SKILL.md

@@ -9,7 +9,7 @@ triggers: code wiki, document codebase, knowledge wiki, explain codebase, codeba
 
 # Code Wiki Skill
 
-Generate a comprehensive wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only existing available tools (`terminal`, `read_file`, `search_files`, `write_file`); no Docker, no external services, no extra dependencies.
+Generate a comprehensive wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only existing available tools (`Bash`, `Read`, `Grep`, `Write`); no Docker, no external services, no extra dependencies.
 
 This skill produces **reference documentation** (what/how). It does not produce strategic narrative (why — that's a different skill).
 
@@ -22,7 +22,7 @@ This skill produces **reference documentation** (what/how). It does not produce
 
 Do NOT use this for:
 - Single-file or single-function documentation — just answer directly
-- API reference for one specific endpoint — use `read_file` and answer inline
+- API reference for one specific endpoint — use `Read` and answer inline
 - Strategic "why does this exist" narrative — different skill, different purpose
 - Codebases the user is actively developing in this session — just answer questions as they come
 
@@ -34,7 +34,7 @@ Do NOT use this for:
 
 ## How to Run
 
-Invoke through the `terminal` tool from the target repo's root, then use `read_file` / `search_files` / `write_file` to produce the wiki. Default output location is `~/.agent/wikis/<repo-name>/`. Only write into the repo (`docs/wiki/`) when the user explicitly requests it.
+Invoke through the `Bash` tool from the target repo's root, then use `Read` / `Grep` / `Write` to produce the wiki. Default output location is `~/.agent/wikis/<repo-name>/`. Only write into the repo (`docs/wiki/`) when the user explicitly requests it.
 
 ## Quick Reference
 
@@ -78,13 +78,13 @@ REPO_NAME=$(basename "$PWD")
 Then set the output dir:
 
 ```bash
-OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
+OUTPUT_DIR="$HOME/.mindforge/wikis/$REPO_NAME"
 mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"
 ```
 
 ### 2. Scan repo structure
 
-Use the `terminal` tool for the shell work, `read_file` for manifests:
+Use the `Bash` tool for the shell work, `Read` for manifests:
 
 ```bash
 # Shallow tree first
@@ -107,7 +107,7 @@ pygount --format=summary \
   . 2>/dev/null || true
 ```
 
-Then `read_file` the relevant manifests (`package.json`, `pyproject.toml`, `setup.py`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`) and the project README. Use `search_files target='files'` to find them rather than guessing names.
+Then `Read` the relevant manifests (`package.json`, `pyproject.toml`, `setup.py`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`) and the project README. Use `search_files target='files'` to find them rather than guessing names.
 
 ### 3. Pick modules to document
 
@@ -128,7 +128,7 @@ State the module list to the user before generating per-module docs on big repos
 
 ### 4. Write `README.md`
 
-`read_file` the actual project README plus the top 2–3 entry-point files. Then `write_file`:
+`Read` the actual project README plus the top 2–3 entry-point files. Then `Write`:
 
 ````markdown
 # <Project Name>
@@ -208,7 +208,7 @@ Cap at ~20 nodes per diagram. Split into sub-diagrams if larger.
 
 ### 6. Write per-module docs in `modules/`
 
-For each selected module, inspect its layout with `ls`, identify 3–5 most important files (by size, by being named `core.py` / `main.py` / `__init__.py`, by being imported a lot), then `read_file` those files (use `offset` / `limit` to read only what you need; prefer `search_files` for specific symbols).
+For each selected module, inspect its layout with `ls`, identify 3–5 most important files (by size, by being named `core.py` / `main.py` / `__init__.py`, by being imported a lot), then `Read` those files (use `offset` / `limit` to read only what you need; prefer `Grep` for specific symbols).
 
 ````markdown
 # Module: `<module>`
@@ -245,7 +245,7 @@ signatures, not full implementations.>
 
 ### 7. Write `diagrams/class-diagram.md`
 
-Pick the 5–10 most important classes/types. `read_file` them, then write:
+Pick the 5–10 most important classes/types. `Read` them, then write:
 
 ````markdown
 # Class Diagram
@@ -392,7 +392,7 @@ Generating a full wiki for a 500K-LOC monorepo is wildly token-expensive. Defaul
 
 - Initial scan: max depth 3 directories
 - Per-module docs: cap at 10 modules unless user expands scope
-- Per-file reads: prefer `search_files` for symbols + `read_file` with `offset`/`limit` over full reads
+- Per-file reads: prefer `Grep` for symbols + `Read` with `offset`/`limit` over full reads
 - Skip vendored code (`vendor/`, `third_party/`, generated code, `_pb2.py`, `.min.js`)
 
 If the user says "do the whole thing exhaustively", believe them — but ballpark the cost first: "this repo has ~340 source files, comprehensive coverage will be expensive — confirm?"
@@ -409,7 +409,7 @@ Full incremental-regeneration is a future enhancement — for now, regenerating
 
 ## Pitfalls
 
-- **Fabricating components.** Every diagram node and claimed function call must be in the source. `read_file` before writing. The single biggest failure mode for auto-generated docs is plausible-sounding fabrication.
+- **Fabricating components.** Every diagram node and claimed function call must be in the source. `Read` before writing. The single biggest failure mode for auto-generated docs is plausible-sounding fabrication.
 - **Generic AI prose.** "This module is responsible for..." is content-free. Say what the module actually does in domain-specific terms.
 - **Restating code as prose.** A module doc that says "the `process` function processes things by calling `process_item` on each item" is worse than just linking to the function.
 - **Mermaid > 50 nodes.** They don't render legibly. Split them.

package/.mindforge/skills/code-wiki/templates/README.md

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}}
+
+{{ONE_PARAGRAPH_DESCRIPTION}}
+
+## Key Concepts
+
+- **{{CONCEPT_1}}** — {{ONE_LINE}}
+- **{{CONCEPT_2}}** — {{ONE_LINE}}
+- **{{CONCEPT_3}}** — {{ONE_LINE}}
+
+## Entry Points
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## High-Level Architecture
+
+{{TWO_TO_THREE_SENTENCES}}
+
+See [architecture.md](architecture.md) for the full picture.
+
+## Module Map
+
+| Module | Purpose |
+|---|---|
+| [`{{MODULE_1}}`](modules/{{MODULE_1}}.md) | {{ONE_LINE_PURPOSE}} |
+| [`{{MODULE_2}}`](modules/{{MODULE_2}}.md) | {{ONE_LINE_PURPOSE}} |
+
+## Getting Started
+
+See [getting-started.md](getting-started.md).

package/.mindforge/skills/code-wiki/templates/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+{{TWO_TO_THREE_PARAGRAPHS_SHAPE_OF_SYSTEM}}
+
+## Components
+
+- **{{COMPONENT_1}}** — {{ONE_TO_TWO_SENTENCES}} See [`modules/{{MODULE}}.md`](modules/{{MODULE}}.md).
+- **{{COMPONENT_2}}** — {{ONE_TO_TWO_SENTENCES}}
+
+## System Diagram
+
+```mermaid
+flowchart TD
+    User([User]) --> Entry[Entry Point]
+    Entry --> Core[Core Engine]
+    Core --> StorageA[(Database)]
+    Core --> ExternalAPI{{External API}}
+```
+
+## Data Flow
+
+1. **{{STEP_1}}** — [`{{FILE}}`]({{LINK}})
+2. **{{STEP_2}}** — [`{{FILE}}`]({{LINK}})
+3. **{{STEP_3}}** — [`{{FILE}}`]({{LINK}})
+
+## Key Design Decisions
+
+- {{DECISION_1}}
+- {{DECISION_2}}
+- {{DECISION_3}}

package/.mindforge/skills/code-wiki/templates/getting-started.md

@@ -0,0 +1,47 @@
+# Getting Started
+
+## Prerequisites
+
+- {{LANGUAGE_RUNTIME_VERSION}}
+- {{DEPENDENCY}}
+
+## Installation
+
+```bash
+{{INSTALL_COMMANDS}}
+```
+
+## First Run
+
+```bash
+{{FIRST_RUN_COMMAND}}
+```
+
+You should see {{EXPECTED_OUTPUT}}.
+
+## Common Workflows
+
+### {{WORKFLOW_1}}
+
+```bash
+{{COMMANDS}}
+```
+
+### {{WORKFLOW_2}}
+
+```bash
+{{COMMANDS}}
+```
+
+## Configuration
+
+Key config files and settings:
+
+- `{{CONFIG_FILE}}` — {{WHAT_IT_CONTROLS}}
+- Env var `{{VAR}}` — {{WHAT_IT_CONTROLS}}
+
+## Where to Go Next
+
+- Architecture overview: [architecture.md](architecture.md)
+- Module reference: [README.md#module-map](README.md#module-map)
+- Diagrams: [diagrams/](diagrams/)

package/.mindforge/skills/code-wiki/templates/module.md

@@ -0,0 +1,38 @@
+# Module: `{{MODULE_NAME}}`
+
+{{ONE_TO_TWO_SENTENCE_PURPOSE}}
+
+## Responsibilities
+
+- {{BULLET_1}}
+- {{BULLET_2}}
+- {{BULLET_3}}
+
+## Key Files
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## Public API
+
+### `{{FUNCTION_NAME}}({{SIGNATURE}})`
+
+{{ONE_LINE_DESCRIPTION}}
+
+**Parameters:**
+- `{{PARAM}}` ({{TYPE}}) — {{DESCRIPTION}}
+
+**Returns:** {{TYPE}} — {{DESCRIPTION}}
+
+## Internal Structure
+
+{{HOW_THE_MODULE_IS_ORGANIZED}}
+
+## Dependencies
+
+- **Used by:** {{OTHER_MODULES}}
+- **Uses:** {{OTHER_MODULES_AND_LIBS}}
+
+## Notable Patterns / Gotchas
+
+- {{ANYTHING_NON_OBVIOUS}}

package/.mindforge/skills/concept-diagrams/SKILL.md

@@ -40,9 +40,9 @@ If a more specialized skill is available for the subject, prefer that. If none f
 
 Optional: if the user wants a browsable gallery of multiple diagrams, see "Local Preview Server" at the bottom.
 
-Load the HTML template:
+Load the HTML template with `Read` (path relative to this skill's own directory):
 ```
-skill_view(name="concept-diagrams", file_path="templates/template.html")
+Read(".mindforge/skills/concept-diagrams/templates/template.html")
 ```
 
 The template embeds the full CSS design system (`c-*` color classes, text classes, light/dark variables, arrow marker styles). The SVG you generate relies on these classes being present on the hosting page.
@@ -254,7 +254,7 @@ Write a single `.html` file the user can open directly. No server, no dependenci
 
 ```python
 # 1. Load the template
-template = skill_view("concept-diagrams", "templates/template.html")
+template = Read(".mindforge/skills/concept-diagrams/templates/template.html")
 
 # 2. Fill in title, subtitle, and paste your SVG
 html = template.replace(
@@ -266,7 +266,7 @@ html = template.replace(
 )
 
 # 3. Write to a user-chosen path (or ./ by default)
-write_file("./sn2-mechanism.html", html)
+Write("./sn2-mechanism.html", html)
 ```
 
 Tell the user how to open it:
@@ -329,9 +329,9 @@ The `examples/` directory ships 15 complete, tested diagrams. Browse them for wo
 | `electricity-grid-flow.md` | Multi-stage flow | Voltage hierarchy, flow markers |
 | `ml-benchmark-grouped-bar-chart.md` | Chart | Grouped bars, dual axis |
 
-Load any example with:
+Load any example with `Read`:
 ```
-skill_view(name="concept-diagrams", file_path="examples/<filename>")
+Read(".mindforge/skills/concept-diagrams/examples/<filename>")
 ```
 
 ---

package/.mindforge/skills/concept-diagrams/examples/apartment-floor-plan-conversion.md

@@ -0,0 +1,244 @@
+# Apartment Floor Plan: 3 BHK to 4 BHK Conversion
+
+An architectural floor plan showing a 1,500 sq ft apartment with proposed modifications to convert from 3 BHK to 4 BHK. Demonstrates architectural drawing conventions, room layouts, proposed changes with dotted lines, and area comparison tables.
+
+## Key Patterns Used
+
+- **Architectural floor plan**: Top-down view with walls, doors, windows
+- **Proposed modifications**: Dotted red lines for new walls
+- **Room color coding**: Light fills to distinguish room types
+- **Circulation paths**: Arrows showing new access routes
+- **Data table**: Before/after area comparison with highlighting
+- **Architectural symbols**: North arrow, scale bar, door swings
+
+## Diagram Type
+
+This is an **architectural floor plan** with:
+- **Plan view**: Top-down orthographic projection
+- **Overlay technique**: Existing structure + proposed changes
+- **Quantitative data**: Area measurements and comparison table
+
+## Architectural Drawing Elements
+
+### Wall Styles
+
+```xml
+<!-- Outer walls (thick) -->
+<line class="wall" x1="0" y1="0" x2="560" y2="0"/>
+
+<!-- Internal walls (thinner) -->
+<line class="wall-thin" x1="180" y1="0" x2="180" y2="140"/>
+
+<!-- Proposed new walls (dotted red) -->
+<line class="proposed-wall" x1="125" y1="170" x2="125" y2="330"/>
+```
+
+```css
+.wall { stroke: var(--text-primary); stroke-width: 6; fill: none; stroke-linecap: square; }
+.wall-thin { stroke: var(--text-primary); stroke-width: 3; fill: none; }
+.proposed-wall { stroke: #A32D2D; stroke-width: 4; fill: none; stroke-dasharray: 8 4; }
+```
+
+### Door Symbols
+
+```xml
+<!-- Door opening with swing arc -->
+<rect x="150" y="137" width="25" height="6" fill="var(--bg-primary)"/>
+<path class="door" d="M150,140 L150,165"/>
+<path class="door-swing" d="M150,140 A25,25 0 0,0 175,140"/>
+
+<!-- Sliding door (balcony) -->
+<rect x="60" y="327" width="60" height="6" fill="var(--bg-primary)" stroke="var(--text-secondary)" stroke-width="1"/>
+<line x1="60" y1="330" x2="90" y2="330" stroke="var(--text-secondary)" stroke-width="2"/>
+<line x1="90" y1="330" x2="120" y2="330" stroke="var(--text-secondary)" stroke-width="2" stroke-dasharray="3 3"/>
+
+<!-- Proposed door (dotted) -->
+<rect x="143" y="292" width="22" height="6" fill="var(--bg-primary)" stroke="#A32D2D" stroke-width="1" stroke-dasharray="3 2"/>
+<path d="M165,295 A22,22 0 0,0 165,273" stroke="#A32D2D" stroke-width="1" stroke-dasharray="3 2" fill="none"/>
+```
+
+```css
+.door { stroke: var(--text-secondary); stroke-width: 1.5; fill: none; }
+.door-swing { stroke: var(--text-tertiary); stroke-width: 1; fill: none; stroke-dasharray: 3 2; }
+```
+
+### Window Symbols
+
+```xml
+<!-- Window with glass indication -->
+<rect class="window" x="-3" y="30" width="6" height="50"/>
+<line class="window-glass" x1="0" y1="35" x2="0" y2="75"/>
+
+<!-- Horizontal window (top wall) -->
+<rect class="window" x="220" y="-3" width="60" height="6"/>
+<line class="window-glass" x1="225" y1="0" x2="275" y2="0"/>
+```
+
+```css
+.window { stroke: var(--text-primary); stroke-width: 1; fill: var(--bg-primary); }
+.window-glass { stroke: #378ADD; stroke-width: 2; fill: none; }
+```
+
+### Room Fills
+
+```xml
+<!-- Different colors for room types -->
+<rect class="room-master" x="3" y="3" width="174" height="134" rx="2"/>
+<rect class="room-bed2" x="183" y="3" width="134" height="104" rx="2"/>
+<rect class="room-living" x="3" y="173" width="554" height="154" rx="2"/>
+<rect class="room-kitchen" x="443" y="3" width="114" height="104" rx="2"/>
+<rect class="room-bath" x="183" y="113" width="54" height="54" rx="2"/>
+
+<!-- Proposed new room (highlighted) -->
+<rect class="room-new" x="3" y="223" width="120" height="104"/>
+```
+
+```css
+.room-master { fill: rgba(206, 203, 246, 0.3); }  /* purple tint */
+.room-bed2 { fill: rgba(159, 225, 203, 0.3); }    /* teal tint */
+.room-bed3 { fill: rgba(250, 199, 117, 0.3); }    /* amber tint */
+.room-living { fill: rgba(245, 196, 179, 0.3); }  /* coral tint */
+.room-kitchen { fill: rgba(237, 147, 177, 0.3); } /* pink tint */
+.room-bath { fill: rgba(133, 183, 235, 0.3); }    /* blue tint */
+.room-new { fill: rgba(163, 45, 45, 0.15); }      /* red tint for proposed */
+```
+
+### Support Fixtures
+
+```xml
+<!-- Kitchen counter hint -->
+<rect x="450" y="15" width="50" height="25" fill="none" stroke="var(--text-tertiary)" stroke-width="0.5" rx="2"/>
+<text class="tx" x="475" y="30" text-anchor="middle">Counter</text>
+
+<!-- Balcony (dashed outline) -->
+<rect class="balcony-fill" x="3" y="333" width="200" height="50"/>
+```
+
+```css
+.balcony { fill: none; stroke: var(--text-secondary); stroke-width: 2; stroke-dasharray: 6 3; }
+.balcony-fill { fill: rgba(93, 202, 165, 0.1); }
+```
+
+### Room Labels
+
+```xml
+<!-- Room name and area -->
+<text class="room-label" x="90" y="65" text-anchor="middle">MASTER</text>
+<text class="room-label" x="90" y="78" text-anchor="middle">BEDROOM</text>
+<text class="area-label" x="90" y="95" text-anchor="middle">195 sq ft</text>
+
+<!-- Proposed room (in red) -->
+<text class="room-label" x="63" y="268" text-anchor="middle" fill="#A32D2D">BEDROOM 4</text>
+<text class="tx" x="63" y="282" text-anchor="middle" fill="#A32D2D">(NEW)</text>
+```
+
+```css
+.room-label { font-family: system-ui; font-size: 11px; fill: var(--text-primary); font-weight: 500; }
+.area-label { font-family: system-ui; font-size: 9px; fill: var(--text-tertiary); }
+```
+
+### Circulation Arrow
+
+```xml
+<defs>
+  <marker id="circ-arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto">
+    <path d="M0,0 L10,5 L0,10 Z" class="circulation-fill"/>
+  </marker>
+</defs>
+
+<path class="circulation" d="M300,250 L200,250 L145,250 L145,280" marker-end="url(#circ-arrow)"/>
+<text class="tx" x="250" y="242" fill="#3B6D11" font-weight="500">New corridor access</text>
+```
+
+```css
+.circulation { stroke: #3B6D11; stroke-width: 2; fill: none; }
+.circulation-fill { fill: #3B6D11; }
+```
+
+### North Arrow and Scale Bar
+
+```xml
+<!-- North arrow -->
+<g transform="translate(520, 260)">
+  <circle cx="0" cy="0" r="20" fill="none" stroke="var(--text-tertiary)" stroke-width="0.5"/>
+  <polygon points="0,-18 -5,5 0,0 5,5" fill="var(--text-primary)"/>
+  <text class="tx" x="0" y="-22" text-anchor="middle">N</text>
+</g>
+
+<!-- Scale bar -->
+<g transform="translate(420, 300)">
+  <line x1="0" y1="0" x2="100" y2="0" stroke="var(--text-primary)" stroke-width="2"/>
+  <line x1="0" y1="-5" x2="0" y2="5" stroke="var(--text-primary)" stroke-width="1"/>
+  <line x1="50" y1="-3" x2="50" y2="3" stroke="var(--text-primary)" stroke-width="1"/>
+  <line x1="100" y1="-5" x2="100" y2="5" stroke="var(--text-primary)" stroke-width="1"/>
+  <text class="tx" x="0" y="15" text-anchor="middle">0</text>
+  <text class="tx" x="50" y="15" text-anchor="middle">5'</text>
+  <text class="tx" x="100" y="15" text-anchor="middle">10'</text>
+</g>
+```
+
+## Area Comparison Table
+
+### Table Structure
+
+```xml
+<!-- Header row -->
+<rect class="table-header" x="0" y="0" width="180" height="28" rx="4 4 0 0"/>
+<text class="ts" x="90" y="18" text-anchor="middle" font-weight="500">Room</text>
+
+<!-- Normal row -->
+<rect class="table-row" x="0" y="28" width="180" height="24"/>
+<text class="tx" x="10" y="44">Master Bedroom</text>
+<text class="tx" x="230" y="44" text-anchor="middle">195</text>
+
+<!-- Alternating row -->
+<rect class="table-row-alt" x="0" y="52" width="180" height="24"/>
+
+<!-- Highlighted row (for changes) -->
+<rect class="table-highlight" x="0" y="100" width="180" height="24"/>
+<text class="tx" x="10" y="116" fill="#A32D2D" font-weight="500">Bedroom 4 (NEW)</text>
+<text class="tx" x="430" y="116" text-anchor="middle" fill="#3B6D11">+100</text>
+
+<!-- Total row -->
+<rect x="0" y="268" width="180" height="28" fill="var(--bg-secondary)" stroke="var(--border)" stroke-width="1"/>
+<text class="ts" x="10" y="286" font-weight="500">TOTAL CARPET AREA</text>
+```
+
+```css
+.table-header { fill: var(--bg-secondary); }
+.table-row { fill: var(--bg-primary); stroke: var(--border); stroke-width: 0.5; }
+.table-row-alt { fill: var(--bg-tertiary); stroke: var(--border); stroke-width: 0.5; }
+.table-highlight { fill: rgba(163, 45, 45, 0.1); stroke: #A32D2D; stroke-width: 0.5; }
+```
+
+## Layout Notes
+
+- **ViewBox**: 800×780 (portrait for floor plan + table)
+- **Scale**: 10px = 1 foot (apartment ~50ft × 33ft)
+- **Floor plan origin**: Offset at (50, 60) for margins
+- **Wall thickness**: 6px outer, 3px inner (represents ~6" walls)
+- **Room labels**: Centered in each room with area below
+- **Table placement**: Below floor plan with full width
+
+## Color Coding
+
+| Element | Color | Usage |
+|---------|-------|-------|
+| Proposed walls | Red (#A32D2D) dotted | New construction |
+| New room fill | Red 15% opacity | Bedroom 4 area |
+| Circulation | Green (#3B6D11) | New access path |
+| Window glass | Blue (#378ADD) | Glass indication |
+| Bedrooms | Purple/Teal/Amber tints | Room differentiation |
+| Wet areas | Blue tint | Bathrooms |
+| Living | Coral tint | Common areas |
+
+## When to Use This Pattern
+
+Use this diagram style for:
+- Apartment/house floor plans
+- Office layout planning
+- Renovation proposals showing before/after
+- Space planning with area calculations
+- Real estate marketing materials
+- Interior design presentations
+- Building permit documentation