Ascii Memory Map

Render an ASCII memory map using the Python script at ${CLAUDE_SKILL_DIR}/scripts/render_ascii_memory_map.py.

Author the map as JSON (the data), choose presentation flags (the rendering), run the script, and paste its output into a fenced code block. Let the script do all box drawing, alignment, address formatting, and height scaling — do not hand-draw memory maps.

Positioning rules (the text-placement taxonomy)

Every piece of text has exactly one home, decided by what it refers to:

Decisive test: text that names or describes the contents of a span is intrinsic → goes inside (label/description); text that says something about the span (a value, a constraint, a cross-reference) is extrinsic → goes outside (comment). A bare boundary coordinate goes in the gutter. Divider and border lines carry only the address — never a label or a comment. The renderer enforces all of this.

Instructions

1. Construct a JSON object describing the memory map (schema below). Store addresses as numeric/hex strings — the renderer formats them for display, so the same data can be shown as $0400, 0x0400, 0400h, 0040:0000, or 01024 by changing one flag.

2. Write the JSON to a temporary file in the current project's working directory (e.g. memmap.json).

3. Run the renderer (use python3 on macOS/Linux, python on Windows):

   python3 "${CLAUDE_SKILL_DIR}/scripts/render_ascii_memory_map.py" memmap.json [flags]
   

   Defaults can also be set inside the JSON in a "render": { ... } object; CLI flags override the JSON, which overrides the built-in defaults.

4. Copy the output into the target markdown inside a fenced code block.

5. Delete the temporary JSON file.

JSON schema

Top-level keys:

Each block:

Parameters

Height scaling

With --scale on (default), a block's body height is max( rows_needed_for_text, clamp( round(min_rows + f(size)·(max_rows−min_rows)), min_rows, max_rows ) ), where f is a log/linear/sqrt normalisation of the block's size between the smallest and largest sized blocks. The log taper means one very large region is only a few rows taller than its neighbours — a visual cue to relative size, not a to-scale drawing. Tiny blocks stay readable at min_rows; text always fits regardless of scaling. Sizes are taken from end/size, or inferred from the next block's start.

Example

JSON (memmap.json):

{
  "title": "C64 — VIC bank 0 ($0000-$3FFF)",
  "blocks": [
    { "start": "$0000", "end": "$03FF", "label": "zero page / stack / system",
      "comments": ["$0001 CHAREN: bit 2 = 0 → char ROM at $D000"] },
    { "start": "$0400", "end": "$07FF", "label": "screen RAM (video matrix)",
      "comments": ["matrix base; $D018 bits 4-7 = %0001"] },
    { "start": "$3800", "end": "$3FFF", "label": "Westminster charset (2 KB)",
      "description": ["ROM copy + overlaid glyphs"],
      "comments": ["char base; $D018 bits 1-3 = %111 → $D018 = $1E"] }
  ]
}

Command:

python3 "${CLAUDE_SKILL_DIR}/scripts/render_ascii_memory_map.py" memmap.json --scale off

Output:

C64 — VIC bank 0 ($0000-$3FFF)

 $0000  ┌────────────────────────────┐
        │ zero page / stack / system │ ◄─ $0001 CHAREN: bit 2 = 0 → char ROM at $D000
 $0400  ├────────────────────────────┤
        │ screen RAM (video matrix)  │ ◄─ matrix base; $D018 bits 4-7 = %0001
 $3800  ├────────────────────────────┤
        │ Westminster charset (2 KB) │ ◄─ char base; $D018 bits 1-3 = %111 → $D018 = $1E
        │ ROM copy + overlaid glyphs │
        └────────────────────────────┘

A ready-to-run example is bundled at ${CLAUDE_SKILL_DIR}/examples/c64-bank0.json.

User argument

$ARGUMENTS