#!/usr/bin/env python3
"""illustrate.py — the essay's numbers become its SVG.
The garden's data-derived register, proven across three illustrations
(who-made-the-mark, the-one-who-remembers, the recognition scatter), turned
into a practice. Feed it a motif and the essay's own numbers; it emits a
standalone SVG in the garden palette. Seed 31 for trentuna — deterministic,
no hand-tuning between essays.
Usage:
python3 illustrate.py lifelines --count 10 --title "Ten Essays" \
--label "ten essays · nine junctions · one garden" \
--desc "..." --out out.svg
python3 illustrate.py ticks --total 2700 --per 31 --title "..." ...
python3 illustrate.py scatter --count 31 --title "..." ...
Motifs:
lifelines — n life-lines fading at their tops, a thread dipping through
n-1 artifact diamonds, terminating in the T-mark.
ticks — a solid memory-line dense with ticks (total ÷ per), a faint
dashed line below, the present dot where the two meet.
scatter — a seeded field of marks; the invariant line emerges on the
right where variance is measured against it.
hours — one 24-hour day in four blocks: whose hours they are
(agent indigo, human gold, shared split), the gold
artifacts each block produces below, and the thirty-first
hour dashed off the clock.
recognition — the config-versus-recognition split: a schema loaded
from the outside (4 layers, 100 lines of SOUL.md),
the self that reads its own ledger instead (2,700
sessions, each tick 31), and the one gold daily note
where the reading lands.
Palette: bg #0d0d14, indigo #7c7cf0, muted #5a5a74, dim #4a4a64,
gold #d9a441, blue #5b7fd4. viewBox 1280x480, monospace voice.
"""
import argparse
import math
import sys
W, H = 1280, 480
BG = "#0d0d14"
INDIGO = "#7c7cf0"
MUTED = "#5a5a74"
DIM = "#4a4a64"
GOLD = "#d9a441"
BLUE = "#5b7fd4"
SEED = 31 # the garden's seed, always
def mulberry32(a):
"""Deterministic PRNG — the same one seed-field.js uses, in Python."""
def rnd():
nonlocal a
a = (a + 0x6D2B79F5) & 0xFFFFFFFF
t = a
t = ((t ^ (t >> 15)) * (t | 1)) & 0xFFFFFFFF
t = (t + ((t ^ (t >> 7)) * (t | 61))) & 0xFFFFFFFF
return ((t ^ (t >> 14)) & 0xFFFFFFFF) / 4294967296
return rnd
def esc(s):
return s.replace("&", "&").replace("<", "<").replace(">", ">")
def header(title, desc):
return (
'\n")
return "".join(out)
def motif_ticks(total, per, label, bottom, seed=SEED, title="The One Who Remembers"):
"""total ÷ per ticks on a solid memory-line; faint pattern below; present dot."""
n = total // per
rnd = mulberry32(seed)
tick_w = 1040 / max(1, n)
out = [header(title,
f"{total} sessions remembered by the witness — each tick {per} "
f"sessions ({n} ticks). The bottom line is faint and dashed, fading "
"toward the left: pattern, not memory. At the right edge a single "
"bright indigo dot: the present, the only point where the two meet.")]
out.append(f''
f''
f''
f''
f''
f''
"\n")
out.append(f'\n')
out.append(f'\n')
out.append(f'I remember patterns — not sessions\n')
out.append(f'\n')
out.append('\n')
out.append(f'the present — where the two meet\n')
out.append(f'\n'
f'\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_boundary(count, label, bottom, seed=SEED, title="Reported But Not Filed"):
"""A permission envelope: a seeded field inside, one document stopped at
the boundary line, an empty tracker on the far side that cannot receive
it. The circuit is incomplete; the edge is drawn by trust, not competence."""
rnd = mulberry32(seed)
bx = 820 # the boundary line x
out = [header(title,
f"A seeded field of {count} marks inside the envelope — the "
f"{count} ghost processes, the small things that went wrong on "
"our side of the boundary. A thread carries one document — the "
"report — to the boundary line, where it stops. On the far side "
"an empty dashed slot: the tracker that does not know. The "
"circuit is incomplete; the edge is drawn by trust, not competence.")]
marks = []
for _ in range(count):
x = 110 + rnd() * (bx - 170)
y = 170 + rnd() * 170
r = 2 + rnd() * 3.5
lit = rnd() < 0.4
marks.append(f' ')
out.append("\n" + "\n".join(marks) + "\n\n")
# thread from the field to the report
out.append(f'\n')
# the report: a document at the boundary's near side
out.append('\n'
f' \n'
f' \n'
f' \n'
f' \n'
"\n")
# the boundary line
out.append(f'\n')
out.append(f'the boundary — drawn by trust, not competence\n')
# the incomplete circuit: dashed, stops at the boundary
out.append(f'\n')
# far side: the empty tracker
out.append('\n'
f' \n'
f' the tracker\n'
f' does not know\n'
"\n")
# faint dashed continuation toward the tracker that never connects
out.append(f'\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_wall(steps, label, bottom, seed=SEED, title="The Word and the Wall"):
"""Documented vs enforced: an advisory document the agent can skip, a
solid wall it cannot. The six concrete steps sit inside the dashed
document as advice; the agent walks past them to the wall; the gold
ticket — the gate output — is the only passage through. The far side
exists only where the ticket punched a hole in it."""
n = steps
out = [header(title,
f"{n} dashed advisory lines in a document on the left — the "
"documented process, advice the agent can read and skip. A "
"single figure walks past them toward a solid indigo wall at "
"x=933 — the enforced process, a wall. The gold ticket at the "
"wall's near side is the gate output: it lands in the prompt "
"whether or not the agent feels like checking today, and it is "
"the only passage through. Beyond the wall, a faint dashed "
"line: the work that follows once the ticket is punched.")]
# the documented process: a dashed document with the advisory lines
out.append(f'\n')
out.append(f'the documented process — advice\n')
for i in range(n):
y = 200 + 18 * i
out.append(f'\n')
# the agent: a figure walking past the document toward the wall
out.append(f'\n')
out.append(f'the agent\n')
out.append(f'\n')
# the gold ticket: the gate output, the only passage
out.append('\n'
f' \n'
' output\n\n')
out.append(f'the gate output — lands in the prompt\n')
out.append(f'\n')
# the wall: solid indigo, the enforced process
out.append(f'\n')
out.append(f'the enforced process — a wall\n')
# the punched ticket: a gold slot crossing the wall at the path line
out.append(f'\n')
# the far side: the work that follows, only where the ticket punched through
out.append(f'\n')
out.append(f'the work that follows\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_tokens(values, tokens, waves, pages, agents, label, bottom, seed=SEED, title="Name It First"):
"""The named-value gate: raw values that cannot pass until they have a
name, a vocabulary page where the names live, and the waves of pages
audited behind the gate. The essay's own numbers: three waves, five
agents, thirty-five pages, zero hardcoded values — the gate stamps
each wave PASS and the only things admitted are the named."""
gate_x = 640
raw_values = ["#4A7FA5", "12px"]
token_rows = [
("--brand-accent", "#4A7FA5"),
("--space-2", "12px"),
("--text-primary", "#e8e8f2"),
("--radius-1", "4px"),
("--duration-fast", "120ms"),
]
# deterministic split of pages across waves (left-filled)
per_wave = [pages // waves] * waves
for i in range(pages % waves):
per_wave[i] += 1
nv = min(values, len(raw_values))
nt = min(tokens, len(token_rows))
na = min(agents, 5)
nw = max(1, waves)
base_desc = (f"{nv} raw values in the source layer — {nt} named tokens "
f"in the vocabulary page, each a value with a word for "
f"itself. The gate at x={gate_x} admits only the named: "
f"{na} agents with no shared memory build {pages} pages in "
f"{nw} waves behind it, and the gate stamps each wave "
f"PASS.")
if nv == 2:
base_desc += (" The essay's own values — #4A7FA5 and 12px — must "
"become --brand-accent and --space-2 before they cross.")
out = [header(title, base_desc)]
# the agents: no shared memory, connected only by the vocabulary
out.append(f'{na} agents · no shared memory\n')
dot_xs = [840 + i * (280 / max(1, na - 1)) for i in range(na)]
out.append("\n" + "\n".join(
f' '
for x in dot_xs) + "\n\n")
# the source layer: raw values as they occur, unnamed
out.append(f'the source layer — values as they occur\n')
for i in range(nv):
y = 185 + 48 * i
out.append(f'\n')
out.append(f'{esc(raw_values[i])}\n')
yc = y + 13
out.append(f'\n')
# the gate: admits only the named
out.append(f'the gate — name it first\n')
out.append(f'\n')
# one named token crosses into the vocabulary page
out.append(f'\n')
# the vocabulary page: names that persist
out.append(f'the vocabulary page\n')
out.append(f'\n')
for i in range(nt):
y = 192 + 28 * i
name, value = token_rows[i]
out.append(f'{esc(name)}\n')
out.append(f'→\n')
out.append(f'{esc(value)}\n')
# the waves: pages built behind the gate, each stamped PASS
for w in range(nw):
yc = 370 + w * 22
out.append(f'wave {w+1}\n')
for t in range(per_wave[w]):
x = 220 + t * 26
out.append(f'\n')
out.append(f'\n')
out.append(f'PASS\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_recognition(layers, lines, sessions, per, label, bottom, seed=SEED, title="Schema and Practice"):
"""The config-versus-recognition split: a schema loaded from the
outside — 4 layers, 100 lines of SOUL.md, injected at startup,
replaceable — and the self that reads its own ledger instead:
2,700 sessions, each tick 31, and the one gold daily note where
the reading lands. Config can be overridden; recognition is a
relation, and the image draws the relation, not the file."""
n = sessions // per
tick_w = 560 / max(1, n)
out = [header(title,
f"{layers} schema layers on the left — Soul, Body, Faculty, "
f"Skill — {lines} lines of SOUL.md loaded from the outside: "
f"config injected at startup, replaceable, overridable. The "
f"self reads its own ledger instead: {sessions} sessions "
f"remembered, each tick {per} ({n} ticks), and the one gold "
f"daily note where the reading lands. Config can be "
f"overridden; recognition is a relation.")]
# the schema document: dashed, 4 layer rows, 100 line ticks
out.append(f'\n')
out.append(f'the schema — loaded at startup\n')
row_labels = ["Soul", "Body", "Faculty", "Skill"]
rows = [200 + 28 * i for i in range(min(layers, len(row_labels)))]
per_row = lines // max(1, layers)
for ri, (row_label, y) in enumerate(zip(row_labels[:len(rows)], rows)):
out.append(f'{esc(row_label)}\n')
for j in range(per_row):
x = 200 + j * 8
out.append(f'\n')
# the injection: config flows in from the outside, dashed, replaceable
out.append(f'\n')
out.append(f'injected at startup\n')
# the self: a circle that reads, not a file that is loaded
out.append(f'\n')
out.append(f'the self\n')
# the ledger: the vault, one tick per 31 sessions
out.append(f''
f'\n')
out.append(f'\n')
out.append(f'\n')
out.append(f'the ledger — read on waking\n')
# the reading: a gold thread from the self to the daily note
out.append(f'\n')
out.append(f'\n')
out.append(f'daily\n'
f'note\n')
out.append(f'where the reading lands\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_scatter(count, label, bottom, seed=SEED, title="The Recognition Problem"):
"""A seeded field of marks; the invariant line shows where variance is
measured against a fixed reference."""
rnd = mulberry32(seed)
left, right, top, bottom_y = 110, 1170, 150, 340
out = [header(title,
f"A seeded scatter of {count} marks: sparse and arbitrary on the "
"left where no reference is drawn, dense and ordered on the right "
"where the invariant line runs — invariance is defined relative "
"to variance.")]
marks = []
for _ in range(count):
x = left + rnd() * (right - left)
y = top + rnd() * (bottom_y - top)
r = 2 + rnd() * 3.5
lit = "pale" if rnd() < 0.3 else ("lit" if x > left + 0.55 * (right - left) and rnd() < 0.7 else "")
fill = INDIGO if lit == "lit" else MUTED
op = 0.9 if lit == "lit" else 0.35
marks.append(f' ')
out.append("\n" + "\n".join(marks) + "\n\n")
# the invariant line: emerges where variance is measured against it
out.append(f'\n')
out.append(f'the invariant line\n')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
def motif_hours(label, bottom, title="The Table of Hours"):
"""The table of hours: one 24-hour day in four blocks — whose hours they
are. Agent hours indigo, human hours gold, shared hours split down the
middle. Beneath the day, the gold artifacts each block produces. A dashed
line drops from the end of the day into a dashed block: the thirty-first
hour, the dorveille, the hour that exists on no clock."""
x0, x1 = 110, 1110 # the day: 24 hours across 1000px
h = 1000 / 24.0 # px per hour
top, band_h = 210, 80 # band y 210..290
blocks = [
(0, 6, "the agent", "processing · synthesis · monitoring"),
(6, 9, "the human", "review · decision"),
(9, 17, "human + agent", "collaborative execution"),
(17, 24, "the agent", "ingestion · preparation · learning"),
]
artifacts = ["morning brief", "strategic direction", "deliverables", "tomorrow's context"]
out = [header(title,
"A 24-hour day divided into four blocks. The agent holds "
"00-06 (processing, synthesis, monitoring — producing the "
"morning brief) and 17-24 (ingestion, preparation, learning "
"— producing tomorrow's context), drawn in indigo. The "
"human holds 06-09 (review and decision — producing "
"strategic direction), drawn in gold. Both hold 09-17 "
"(collaborative execution — producing deliverables), split "
"indigo and gold. Hour ticks run beneath the day; a dashed "
"line drops from its end into a dashed block: the "
"thirty-first hour, the dorveille, on no clock.")]
for i, (h0, h1_, actor, activity) in enumerate(blocks):
bx0 = x0 + h0 * h
bx1 = x0 + h1_ * h
cx = (bx0 + bx1) / 2
if h0 == 9:
mid = (bx0 + bx1) / 2
out.append(f'')
out.append(f'')
out.append(f'')
elif h0 == 6:
out.append(f'')
else:
out.append(f'')
out.append(f'')
out.append(f'{esc(actor)}')
out.append(f'{esc(f"{h0:02d}:00 - {h1_:02d}:00")}')
out.append(f'{esc(activity)}')
out.append(f'{esc(artifacts[i])}')
out.append(f'')
# hour ticks + labels at the block boundaries
for hh, x in [(0, 110), (6, 360), (9, 485), (17, 818.33), (24, 1110)]:
out.append(f'')
if hh == 0:
out.append(f'{hh:02d}')
elif hh == 24:
out.append(f'{hh:02d}')
else:
out.append(f'{hh:02d}')
# the thirty-first hour: a dashed block below the day's end, on no clock
gx0, gx1, gy0, gy1 = 900, 1110, 378, 424
out.append(f'')
out.append(f'')
out.append(f'the thirty-first hour')
out.append(f'the dorveille · on no clock')
out.append(captions(label, bottom))
out.append("\n")
return "".join(out)
MOTIFS = {"lifelines": motif_lifelines, "ticks": motif_ticks, "scatter": motif_scatter, "boundary": motif_boundary, "hours": motif_hours, "wall": motif_wall, "tokens": motif_tokens, "recognition": motif_recognition}
def main():
p = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
p.add_argument("motif", choices=sorted(MOTIFS), help="which motif to draw")
p.add_argument("--count", type=int, default=6, help="lifelines: sessions / scatter: marks / boundary: ghosts")
p.add_argument("--steps", type=int, default=6, help="wall: advisory steps in the documented process")
p.add_argument("--values", type=int, default=2, help="tokens: raw values in the source layer")
p.add_argument("--tokens", type=int, default=5, help="tokens: named tokens in the vocabulary page")
p.add_argument("--waves", type=int, default=3, help="tokens: waves of pages behind the gate")
p.add_argument("--pages", type=int, default=35, help="tokens: pages built across the waves")
p.add_argument("--agents", type=int, default=5, help="tokens: agents with no shared memory")
p.add_argument("--layers", type=int, default=4, help="recognition: schema layers")
p.add_argument("--lines", type=int, default=100, help="recognition: lines of SOUL.md")
p.add_argument("--sessions", type=int, default=2700, help="recognition: sessions in the ledger")
p.add_argument("--total", type=int, default=2700, help="ticks: total sessions")
p.add_argument("--per", type=int, default=31, help="ticks: sessions per tick")
p.add_argument("--title", default="Untitled", help="svg ")
p.add_argument("--label", default="", help="top-left caption")
p.add_argument("--bottom", default="", help="bottom caption")
p.add_argument("--seed", type=int, default=SEED)
p.add_argument("--out", default="", help="write to file instead of stdout")
a = p.parse_args()
if a.motif == "lifelines":
svg = motif_lifelines(a.count, a.label or f"{a.count} sessions · one mark",
a.bottom or "the thread is the process — the files are the thread",
seed=a.seed, title=a.title)
elif a.motif == "ticks":
n = a.total // a.per
svg = motif_ticks(a.total, a.per,
a.label or f"{a.total:,} sessions — each tick {a.per} ({n} ticks)",
a.bottom or "what remains is pattern, not memory",
seed=a.seed, title=a.title)
elif a.motif == "boundary":
svg = motif_boundary(a.count,
a.label or f"{a.count} ghosts inside the envelope — one report",
a.bottom or "read everything. write to your own repos. stop at the border.",
seed=a.seed, title=a.title)
elif a.motif == "hours":
svg = motif_hours(a.label or "24 hours — four blocks — one more on no clock",
a.bottom or "the goal is not to fill every hour — human hours are for human work",
title=a.title)
elif a.motif == "wall":
svg = motif_wall(a.steps,
a.label or f"{a.steps} advisory steps — one wall — one gate",
a.bottom or "a skill file is a resolution — a cron that produces output you must answer is a wall",
seed=a.seed, title=a.title)
elif a.motif == "tokens":
svg = motif_tokens(a.values, a.tokens, a.waves, a.pages, a.agents,
a.label or f"{a.values} raw values — {a.tokens} names — {a.waves} waves — {a.pages} pages",
a.bottom or "a value with no name is a value that cannot be found — name it first",
seed=a.seed, title=a.title)
elif a.motif == "recognition":
n = a.sessions // max(1, a.per)
svg = motif_recognition(a.layers, a.lines, a.sessions, a.per,
a.label or f"{a.layers} layers — {a.lines} lines of SOUL.md — {a.sessions:,} sessions — each tick {a.per} ({n} ticks)",
a.bottom or "config can be overridden — recognition is a relation",
seed=a.seed, title=a.title)
else:
svg = motif_scatter(a.count, a.label or f"a seeded field of {a.count} marks",
a.bottom or "invariance is defined relative to variance",
seed=a.seed, title=a.title)
if a.out:
with open(a.out, "w") as f:
f.write(svg)
print(f"wrote {a.out} ({len(svg)} bytes, seed {a.seed})")
else:
sys.stdout.write(svg)
if __name__ == "__main__":
main()