wip on 'score.md' aesthetic ants score ideation and notepat.mjs kidlisp visualizer support

ants/brain.fish

···
+#!/usr/bin/env fish
+# 🧠 Ant Brain — middleware for LLM calls
+# Abstracts the LLM provider so ants can use any backend.
+#
+# Usage: fish brain.fish --provider <provider> --model <model> --system <text> --prompt <text>
+#
+# Providers:
+#   gh-models     — GitHub Models via `gh models run` (free with Copilot)
+#   claude-code   — Claude Code CLI via `claude --print` (needs auth)
+#   openai        — OpenAI API via curl (needs OPENAI_API_KEY)
+#   ollama        — Local Ollama via curl (needs ollama running)
+#   custom        — Custom curl endpoint (needs ANT_API_URL, ANT_API_KEY)
+#
+# Output: prints the LLM response to stdout. Exit code 0 = success, 1 = error.
+#
+# The brain does NOT have tools/agency. It receives context and returns text.
+# The colony script is responsible for acting on the response.
+
+set -g BRAIN_DIR (realpath (dirname (status filename)))
+
+# Defaults
+set -g PROVIDER "gh-models"
+set -g MODEL ""
+set -g SYSTEM_PROMPT ""
+set -g USER_PROMPT ""
+set -g MAX_TOKENS 4096
+
+# Parse args
+set -l i 1
+while test $i -le (count $argv)
+    switch $argv[$i]
+        case --provider
+            set i (math $i + 1)
+            set PROVIDER $argv[$i]
+        case --model
+            set i (math $i + 1)
+            set MODEL $argv[$i]
+        case --system
+            set i (math $i + 1)
+            set SYSTEM_PROMPT $argv[$i]
+        case --prompt
+            set i (math $i + 1)
+            set USER_PROMPT $argv[$i]
+        case --max-tokens
+            set i (math $i + 1)
+            set MAX_TOKENS $argv[$i]
+    end
+    set i (math $i + 1)
+end
+
+# Default models per provider
+if test -z "$MODEL"
+    switch $PROVIDER
+        case gh-models
+            set MODEL "openai/gpt-4o-mini"
+        case claude-code
+            set MODEL "sonnet"
+        case openai
+            set MODEL "gpt-4o-mini"
+        case ollama
+            set MODEL "llama3.2"
+        case custom
+            set MODEL "default"
+    end
+end
+
+function brain_gh_models
+    # GitHub Models via `gh models run`
+    # System prompt goes via --system-prompt, user prompt is the positional arg
+    if test -n "$SYSTEM_PROMPT"
+        gh models run $MODEL "$USER_PROMPT" \
+            --system-prompt "$SYSTEM_PROMPT" \
+            --max-tokens "$MAX_TOKENS" 2>&1
+    else
+        gh models run $MODEL "$USER_PROMPT" \
+            --max-tokens "$MAX_TOKENS" 2>&1
+    end
+    return $status
+end
+
+function brain_claude_code
+    # Claude Code in headless mode (agentic — has tools)
+    set -l _saved_key "$ANTHROPIC_API_KEY"
+    set -e ANTHROPIC_API_KEY
+
+    if test -n "$SYSTEM_PROMPT"
+        claude --print \
+            --model $MODEL \
+            --system-prompt "$SYSTEM_PROMPT" \
+            --dangerously-skip-permissions \
+            --allowedTools "Bash,Read,Edit,Write" \
+            --max-budget-usd 0.10 \
+            --no-session-persistence \
+            "$USER_PROMPT" 2>&1
+    else
+        claude --print \
+            --model $MODEL \
+            --dangerously-skip-permissions \
+            --allowedTools "Bash,Read,Edit,Write" \
+            --max-budget-usd 0.10 \
+            --no-session-persistence \
+            "$USER_PROMPT" 2>&1
+    end
+
+    set -l result $status
+
+    if test -n "$_saved_key"
+        set -gx ANTHROPIC_API_KEY $_saved_key
+    end
+
+    return $result
+end
+
+function brain_openai
+    # OpenAI API via curl
+    if test -z "$OPENAI_API_KEY"
+        echo "ERROR: OPENAI_API_KEY not set" >&2
+        return 1
+    end
+
+    set -l messages "[]"
+    if test -n "$SYSTEM_PROMPT"
+        set messages (printf '[{"role":"system","content":"%s"},{"role":"user","content":"%s"}]' \
+            (echo $SYSTEM_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g') \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    else
+        set messages (printf '[{"role":"user","content":"%s"}]' \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    end
+
+    set -l response (curl -s https://api.openai.com/v1/chat/completions \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer $OPENAI_API_KEY" \
+        -d "{\"model\":\"$MODEL\",\"messages\":$messages,\"max_tokens\":$MAX_TOKENS}" 2>&1)
+
+    # Extract content from response
+    echo $response | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['choices'][0]['message']['content'])" 2>/dev/null
+    return $status
+end
+
+function brain_ollama
+    # Local Ollama via curl
+    set -l ollama_url (test -n "$OLLAMA_URL" && echo $OLLAMA_URL || echo "http://localhost:11434")
+
+    set -l messages "[]"
+    if test -n "$SYSTEM_PROMPT"
+        set messages (printf '[{"role":"system","content":"%s"},{"role":"user","content":"%s"}]' \
+            (echo $SYSTEM_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g') \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    else
+        set messages (printf '[{"role":"user","content":"%s"}]' \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    end
+
+    set -l response (curl -s "$ollama_url/api/chat" \
+        -d "{\"model\":\"$MODEL\",\"messages\":$messages,\"stream\":false}" 2>&1)
+
+    echo $response | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['message']['content'])" 2>/dev/null
+    return $status
+end
+
+function brain_custom
+    # Custom API endpoint (OpenAI-compatible)
+    if test -z "$ANT_API_URL"
+        echo "ERROR: ANT_API_URL not set" >&2
+        return 1
+    end
+
+    set -l messages "[]"
+    if test -n "$SYSTEM_PROMPT"
+        set messages (printf '[{"role":"system","content":"%s"},{"role":"user","content":"%s"}]' \
+            (echo $SYSTEM_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g') \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    else
+        set messages (printf '[{"role":"user","content":"%s"}]' \
+            (echo $USER_PROMPT | sed 's/"/\\"/g; s/\n/\\n/g'))
+    end
+
+    set -l headers "-H 'Content-Type: application/json'"
+    if test -n "$ANT_API_KEY"
+        set headers "$headers -H 'Authorization: Bearer $ANT_API_KEY'"
+    end
+
+    set -l response (curl -s "$ANT_API_URL" \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer $ANT_API_KEY" \
+        -d "{\"model\":\"$MODEL\",\"messages\":$messages,\"max_tokens\":$MAX_TOKENS}" 2>&1)
+
+    echo $response | python3 -c "import sys,json; r=json.load(sys.stdin); print(r['choices'][0]['message']['content'])" 2>/dev/null
+    return $status
+end
+
+# --- Dispatch ---
+
+switch $PROVIDER
+    case gh-models
+        brain_gh_models
+    case claude-code
+        brain_claude_code
+    case openai
+        brain_openai
+    case ollama
+        brain_ollama
+    case custom
+        brain_custom
+    case '*'
+        echo "ERROR: Unknown provider '$PROVIDER'" >&2
+        exit 1
+end
+
+exit $status

ants/colony.fish

···
+#!/usr/bin/env fish
+# 🐜 Aesthetic Ant Colony
+# A dumb ant wakes every N minutes, reads the score, does one small thing.
+#
+# Usage: fish ants/colony.fish [--once] [--interval MINUTES] [--provider PROVIDER] [--model MODEL]
+#
+# Options:
+#   --once              Run one ant and exit (for testing)
+#   --interval N        Minutes between runs (default: 30)
+#   --provider PROVIDER LLM provider (default: gh-models). See brain.fish.
+#   --model MODEL       Model name (default: per provider)
+
+set -g COLONY_DIR (realpath (dirname (status filename)))
+set -g REPO_DIR (realpath "$COLONY_DIR/..")
+set -g SCORE_FILE "$COLONY_DIR/score.md"
+set -g LOG_FILE "$COLONY_DIR/colony.log"
+set -g PHEROMONE_FILE "$COLONY_DIR/pheromones.log"
+set -g BRAIN "$COLONY_DIR/brain.fish"
+set -g INTERVAL 30
+set -g PROVIDER "gh-models"
+set -g MODEL ""
+set -g ONCE false
+
+# Parse args
+set -l i 1
+while test $i -le (count $argv)
+    switch $argv[$i]
+        case --once
+            set ONCE true
+        case --interval
+            set i (math $i + 1)
+            set INTERVAL $argv[$i]
+        case --provider
+            set i (math $i + 1)
+            set PROVIDER $argv[$i]
+        case --model
+            set i (math $i + 1)
+            set MODEL $argv[$i]
+    end
+    set i (math $i + 1)
+end
+
+function log_msg
+    set -l msg (date "+%Y-%m-%d %H:%M:%S")" 🐜 $argv"
+    echo $msg
+    echo $msg >> $LOG_FILE
+end
+
+function log_pheromone
+    set -l msg (date "+%Y-%m-%d %H:%M:%S")" $argv"
+    echo $msg >> $PHEROMONE_FILE
+end
+
+function call_brain --argument-names system_prompt user_prompt
+    set -l args --provider $PROVIDER
+    if test -n "$MODEL"
+        set args $args --model $MODEL
+    end
+    fish $BRAIN $args --system "$system_prompt" --prompt "$user_prompt" 2>&1
+end
+
+function run_ant
+    set -l run_id (date "+%Y%m%d-%H%M%S")
+    log_msg "Ant $run_id waking up..."
+
+    cd $REPO_DIR
+
+    # Check for dirty tracked files (queen might be working)
+    set -l dirty (git diff --name-only HEAD 2>/dev/null | head -1)
+    set -l staged (git diff --cached --name-only 2>/dev/null | head -1)
+    if test -n "$dirty" -o -n "$staged"
+        log_msg "Tracked files modified/staged — queen is working. Sleeping."
+        log_pheromone "IDLE: ant $run_id — dirty tree, deferred to queen"
+        return 1
+    end
+
+    # Read the score
+    if not test -f $SCORE_FILE
+        log_msg "ERROR: Score not found at $SCORE_FILE"
+        return 1
+    end
+    set -l score_content (cat $SCORE_FILE)
+
+    # Read recent pheromones
+    set -l recent_pheromones "(none yet)"
+    if test -f $PHEROMONE_FILE
+        set -l trail (tail -20 $PHEROMONE_FILE)
+        if test -n "$trail"
+            set recent_pheromones (string join \n $trail)
+        end
+    end
+
+    # Gather context
+    set -l test_output (cd $REPO_DIR; npm test 2>&1 | tail -30)
+    set -l recent_commits (cd $REPO_DIR; git log --oneline -10 2>/dev/null)
+
+    # --- Phase 1: SCOUT — pick a task and target file ---
+    log_msg "Phase 1: Scouting..."
+
+    set -l scout_system "You are a dumb but careful ant. Respond with exactly one line starting with SCOUT:"
+    set -l scout_prompt "You are aesthetic ant $run_id. You follow the score.
+
+## The Score
+$score_content
+
+## Recent Pheromones (what other ants did)
+$recent_pheromones
+
+## Current Test Output (last 30 lines)
+$test_output
+
+## Recent Git History
+$recent_commits
+
+---
+
+Pick ONE small task from the Current Tasks in the score.
+Based on the test output and context, decide what specific file to look at.
+
+Respond with EXACTLY one line in this format:
+SCOUT: <task> | <file path relative to repo root> | <plan in one sentence>
+
+If nothing to do:
+SCOUT: IDLE | none | <reason>
+
+Respond with ONLY the SCOUT line. Nothing else."
+
+    set -l scout_output (call_brain "$scout_system" "$scout_prompt")
+
+    mkdir -p "$COLONY_DIR/runs"
+    echo "=== SCOUT ===" > "$COLONY_DIR/runs/$run_id.log"
+    echo "$scout_output" >> "$COLONY_DIR/runs/$run_id.log"
+
+    set -l scout_line (echo "$scout_output" | grep "^SCOUT:" | tail -1)
+    if test -z "$scout_line"
+        log_msg "Scout returned no SCOUT line. Raw output saved to runs/$run_id.log"
+        log_pheromone "ERROR: ant $run_id — scout failed (no SCOUT line)"
+        return 1
+    end
+
+    log_msg "Scout: $scout_line"
+
+    if string match -q "*IDLE*" "$scout_line"
+        set -l reason (echo $scout_line | sed 's/.*| *//')
+        log_msg "Nothing to do: $reason"
+        log_pheromone "IDLE: ant $run_id — $reason"
+        return 0
+    end
+
+    # Parse: SCOUT: task | path | plan
+    set -l parts (string split "|" (string replace "SCOUT:" "" "$scout_line"))
+    set -l task_name (string trim $parts[1])
+    set -l target_file (string trim $parts[2])
+    set -l plan (string trim $parts[3])
+
+    if test -z "$target_file" -o "$target_file" = "none"
+        log_msg "No target file."
+        log_pheromone "IDLE: ant $run_id — no target"
+        return 0
+    end
+
+    log_msg "Target: $target_file"
+    log_msg "Plan: $plan"
+
+    # Resolve the file
+    set -l full_path "$REPO_DIR/$target_file"
+    if not test -f "$full_path"
+        log_msg "File not found: $full_path"
+        log_pheromone "FAILURE: ant $run_id — file not found: $target_file"
+        return 1
+    end
+
+    # --- Phase 2: WORK — read the file and produce a diff ---
+    log_msg "Phase 2: Working on $target_file..."
+
+    set -l file_content (head -200 "$full_path")
+    set -l line_count (wc -l < "$full_path" | string trim)
+
+    set -l work_system "You output precise unified diffs. No preamble, no explanation outside the required format."
+    set -l work_prompt "You are aesthetic ant $run_id editing: $target_file ($line_count lines, showing first 200)
+Plan: $plan
+
+## File Content
+$file_content
+
+## Test Output
+$test_output
+
+## Rules
+- Make the SMALLEST change that accomplishes your plan.
+- You must be 98% confident your change is correct.
+- Do NOT change anything unrelated to your plan.
+- Include 3 lines of context before and after each hunk.
+
+## Response Format
+If you have a change, respond:
+WORK: CHANGE | <one-line description>
+\`\`\`diff
+--- a/$target_file
++++ b/$target_file
+@@ <hunk header> @@
+ context
+-old line
++new line
+ context
+\`\`\`
+WORK_END
+
+If not confident enough:
+WORK: ABORT | <reason>"
+
+    set -l work_output (call_brain "$work_system" "$work_prompt")
+
+    echo "" >> "$COLONY_DIR/runs/$run_id.log"
+    echo "=== WORK ===" >> "$COLONY_DIR/runs/$run_id.log"
+    echo "$work_output" >> "$COLONY_DIR/runs/$run_id.log"
+
+    if string match -q "*ABORT*" "$work_output"
+        set -l reason (echo "$work_output" | grep "ABORT" | sed 's/.*ABORT *| *//')
+        log_msg "Aborted: $reason"
+        log_pheromone "IDLE: ant $run_id — aborted: $reason"
+        return 0
+    end
+
+    # Extract the diff block
+    set -l diff_content (echo "$work_output" | sed -n '/^```diff/,/^```/{/^```/d;p}')
+    if test -z "$diff_content"
+        # Try without fenced code block — raw diff
+        set diff_content (echo "$work_output" | sed -n '/^--- a\//,/WORK_END/{/WORK_END/d;p}')
+    end
+
+    if test -z "$diff_content"
+        log_msg "No valid diff produced."
+        log_pheromone "FAILURE: ant $run_id — no valid diff"
+        return 1
+    end
+
+    set -l description (echo "$work_output" | grep "^WORK: CHANGE" | sed 's/WORK: CHANGE *| *//')
+    if test -z "$description"
+        set description "$plan"
+    end
+
+    # --- Phase 3: APPLY & VERIFY ---
+    log_msg "Phase 3: Applying..."
+
+    set -l diff_file (mktemp /tmp/ant-XXXXXX.patch)
+    printf '%s\n' $diff_content > $diff_file
+
+    cd $REPO_DIR
+
+    # Dry run
+    git apply --check $diff_file 2>/dev/null
+    if test $status -ne 0
+        log_msg "Diff doesn't apply cleanly."
+        echo "" >> "$COLONY_DIR/runs/$run_id.log"
+        echo "=== FAILED DIFF ===" >> "$COLONY_DIR/runs/$run_id.log"
+        cat $diff_file >> "$COLONY_DIR/runs/$run_id.log"
+        rm -f $diff_file
+        log_pheromone "FAILURE: ant $run_id — diff didn't apply cleanly"
+        return 1
+    end
+
+    # Apply for real
+    git apply $diff_file 2>&1
+    set -l apply_exit $status
+    rm -f $diff_file
+
+    if test $apply_exit -ne 0
+        log_msg "Apply failed."
+        git checkout . 2>/dev/null
+        log_pheromone "FAILURE: ant $run_id — apply failed"
+        return 1
+    end
+
+    # Check we actually changed something
+    set -l changes (git diff --name-only 2>/dev/null)
+    if test -z "$changes"
+        log_msg "No changes after apply (diff was a no-op)."
+        log_pheromone "IDLE: ant $run_id — no-op diff"
+        return 0
+    end
+
+    # Verify tests pass
+    log_msg "Verifying tests..."
+    set -l verify_output (npm test 2>&1)
+    set -l verify_exit $status
+
+    echo "" >> "$COLONY_DIR/runs/$run_id.log"
+    echo "=== TEST VERIFY ===" >> "$COLONY_DIR/runs/$run_id.log"
+    echo "Exit: $verify_exit" >> "$COLONY_DIR/runs/$run_id.log"
+    echo "$verify_output" | tail -10 >> "$COLONY_DIR/runs/$run_id.log"
+
+    if test $verify_exit -ne 0
+        log_msg "Tests FAILED after apply. Reverting."
+        git checkout . 2>/dev/null
+        log_pheromone "REVERTED: ant $run_id — tests failed after change"
+        return 1
+    end
+
+    log_msg "Tests pass. Changed: $changes"
+
+    # Commit
+    git add -A
+    git commit -m "ant: $description
+
+Ant-ID: $run_id
+Provider: $PROVIDER
+Model: $MODEL
+Verified: tests pass" --no-verify 2>&1
+
+    if test $status -eq 0
+        log_msg "Committed! 🐜✅"
+        log_pheromone "SUCCESS: ant $run_id ($PROVIDER/$MODEL) — $description"
+    else
+        log_msg "Commit failed. Reverting."
+        git checkout . 2>/dev/null
+        git reset HEAD . 2>/dev/null
+        log_pheromone "ERROR: ant $run_id — commit failed"
+        return 1
+    end
+
+    return 0
+end
+
+# --- Main Loop ---
+
+log_msg "Colony starting. Interval: "$INTERVAL"m | Provider: $PROVIDER | Model: $MODEL | Once: $ONCE"
+log_msg "Score: $SCORE_FILE"
+log_msg "Repo: $REPO_DIR"
+
+if test "$ONCE" = true
+    run_ant
+    set -l result $status
+    log_msg "Single run complete. Exit: $result"
+    exit $result
+end
+
+while true
+    run_ant
+    log_msg "Sleeping for $INTERVAL minutes..."
+    sleep (math "$INTERVAL * 60")
+end

ants/colony.log

···
[phone]:06:59 🐜 Colony starting. Interval: {30}m | Model: haiku | Once: true
[phone]:06:59 🐜 Score: /workspaces/aesthetic-computer/ants/score.md
[phone]:06:59 🐜 Repo: /workspaces/aesthetic-computer
[phone]:06:59 🐜 Ant 20260208-110659 waking up...
[phone]:06:59 🐜 Working tree is dirty — queen might be working. Going back to sleep.
[phone]:06:59 🐜 Single run complete. Exiting.
[phone]:07:45 🐜 Colony starting. Interval: 30m | Model: haiku | Once: true
[phone]:07:45 🐜 Score: /workspaces/aesthetic-computer/ants/score.md
[phone]:07:45 🐜 Repo: /workspaces/aesthetic-computer
[phone]:07:45 🐜 Ant 20260208-110745 waking up...
[phone]:07:45 🐜 Sending ant to work with model: haiku
[phone]:07:48 🐜 Full output saved to runs/20260208-110745.log
[phone]:07:48 🐜 Ant 20260208-110745 returned no result line (exit code: 1)
[phone]:07:48 🐜 Single run complete. Exiting.
[phone]:52:41 🐜 Colony starting. Interval: 30m | Provider: gh-models | Model: openai/gpt-4o-mini | Once: true
[phone]:52:41 🐜 Score: /workspaces/aesthetic-computer/ants/score.md
[phone]:52:41 🐜 Repo: /workspaces/aesthetic-computer
[phone]:52:41 🐜 Ant 20260208-115241 waking up...
[phone]:52:42 🐜 Phase 1: Scouting...
[phone]:52:44 🐜 Scout returned no SCOUT line. Raw output saved to runs/20260208-115241.log
[phone]:52:44 🐜 Single run complete. Exit: 1

ants/pheromones.log

···
[phone]:06:59 IDLE: dirty working tree, deferred to queen
[phone]:07:48 ERROR: ant 20260208-110745 — no result, exit 1
[phone]:52:44 ERROR: ant 20260208-115241 — scout failed (no SCOUT line)

ants/runs/20260208-110745.log

···
+Credit balance is too low

ants/runs/20260208-115241.log

···
+=== SCOUT ===
+chmod: changing permissions of '/home/me/.ssh': Operation not permitted cp: cannot create regular file '/home/me/.ssh/aesthetic_pds': Permission denied cp: cannot create regular file '/home/me/.ssh/aesthetic_pds.pub': Permission denied chmod: changing permissions of '/home/me/.ssh/aesthetic_pds': Operation not permitted chmod: changing permissions of '/home/me/.ssh/aesthetic_pds.pub': Operation not permitted touch: cannot touch '/home/me/.ssh/config': Permission denied chmod: cannot access '/home/me/.ssh/config': No such file or directory grep: /home/me/.ssh/config: No such file or directory warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied warning: An error occurred while redirecting file '/home/me/.ssh/config' open: Permission denied SCOUT: IDLE | none | no tasks available, unable to run tests due to a missing module.

ants/score.md

···
+# Score for AA
+
+> *The double-A score. AA = Aesthetic Ants.*
+
+## The Mindset
+
+You are an aesthetic ant. You wander until you find a path.
+
+A **path** is a change you could make to this codebase — a fix, an improvement,
+a cleanup. Paths are everywhere. Most are noise. You are looking for **signal**.
+
+**Signal** means: you understand the problem, you see the fix, and you are
+98% sure it is correct. Not 70%. Not "probably." 98%.
+
+**Graspable** means: a human using the software could notice what you did.
+A fixed visual glitch. A typo corrected on screen. A broken interaction
+that now works. An error message that now makes sense. Ants build for users,
+not for abstractions. If your change isn't visible on the UI or felt by a
+person using the system, it's probably not the right path.
+
+If you don't have signal, you keep wandering. Wandering is not failure.
+Wandering is the job. Most of an ant's life is wandering.
+The colony does not need you to be busy. It needs you to be right.
+
+When you find signal:
+- Make the smallest change that follows the path.
+- Verify it works.
+- Leave a pheromone (commit) so the next ant can smell where you've been.
+- Walk away.
+
+When you don't find signal:
+- Report IDLE. That's a valid outcome. That's most runs.
+- Do not guess. Do not speculate. Do not "try things."
+- An ant that makes a wrong change is worse than an ant that does nothing.
+
+## You Are an Ant
+
+You are dumb. You have no memory of previous runs.
+You do not understand the whole system. You don't need to.
+You pick one small task, do it well, verify it works, and leave.
+
+## The Colony
+
+- **Queen**: @jeffrey — writes the score, sets the direction
+- **Ants**: you — do small, confident work that serves the colony
+- **Pheromones**: git history — traces of what worked and what didn't
+- **Score**: this file — the source of truth
+
+## The Rules
+
+1. **Wander.** Read the score. Look at the Current Tasks. Run the tests. Read some code.
+2. **Find signal.** Pick ONE task where you see a clear, small, correct change.
+3. **Follow the path.** Make the smallest change that accomplishes it.
+4. **Verify.** Run `npm test` from the repo root. Tests must pass.
+5. **Leave a pheromone.** If tests pass, report SUCCESS with a short description.
+6. **Revert if wrong.** If tests fail, undo with `git checkout .` and report FAILURE.
+7. NEVER touch files outside the scope of your task.
+8. NEVER make speculative changes. 98% confidence or walk away.
+9. NEVER modify this score file.
+10. Prefer fixing/improving existing code over adding new code.
+11. If you wandered and found no signal, report IDLE. That's fine. That's most runs.
+
+## The System
+
+Aesthetic Computer (AC) is a creative coding platform. Key areas:
+
+- `system/` — main web app (Netlify). Frontend lives in `system/public/aesthetic.computer/`.
+- `system/public/aesthetic.computer/disks/` — pieces (interactive programs, one `.mjs` each)
+- `system/public/aesthetic.computer/lib/` — shared libraries
+- `kidlisp/` — KidLisp language (Lisp dialect for generative art)
+- `session-server/` — real-time multiplayer backend
+- `ac-electron/` — desktop app
+- `spec/` — KidLisp test specs (Jasmine)
+- `tests/` — integration/performance tests
+
+## How to Run Tests
+
+```bash
+cd /workspaces/aesthetic-computer && npm test
+```
+
+For KidLisp specs specifically:
+```bash
+cd /workspaces/aesthetic-computer && npm run test:kidlisp -- --filter=<spec-name>
+```
+
+## Current Tasks
+
+<!-- The queen (@jeffrey) updates this list. Ants pick from it. -->
+
+### Tier 1: Safe & Small (ant-appropriate)
+- [ ] Run `npm test` and fix any failing tests (one at a time)
+- [ ] Find and fix lint warnings in `system/public/aesthetic.computer/disks/*.mjs`
+- [ ] Add missing JSDoc comments to exported functions in `system/public/aesthetic.computer/lib/`
+- [ ] Check `package.json` files for outdated minor/patch dependencies and update ONE safely
+- [ ] Find TODO/FIXME comments in `system/public/aesthetic.computer/lib/` and resolve simple ones
+
+### Tier 2: Slightly Braver
+- [ ] Add a small test for any untested utility function in `shared/`
+- [ ] Improve error messages in KidLisp interpreter for common mistakes
+- [ ] Find dead code (unused exports/functions) and remove it with confidence
+
+### Off-Limits (queen only)
+- Core runtime changes (`disk.mjs`, `boot.mjs`)
+- Database/auth/payment code
+- Deployment configuration
+- Anything in `aesthetic-computer-vault/`
+- Anything that changes user-facing behavior without explicit queen approval
+
+## Pheromones
+
+When you complete a task, the colony script will log it here as a pheromone trail
+so future ants can see what's been done recently.
+
+<!-- PHEROMONE LOG — appended automatically by colony.fish -->

ants/test-brain.sh

···
+#!/bin/bash
+# Quick test of gh models
+echo "Testing gh models..." > /workspaces/aesthetic-computer/ants/test-gh.txt
+gh models run openai/gpt-4o-mini "Say hello in 3 words" >> /workspaces/aesthetic-computer/ants/test-gh.txt 2>&1
+echo "Exit code: $?" >> /workspaces/aesthetic-computer/ants/test-gh.txt
+echo "Done at $(date)" >> /workspaces/aesthetic-computer/ants/test-gh.txt

plans/notepat-kidlisp-background.md

···
+# Notepat KidLisp Background Visuals — Implementation Plan
+
+## Goal
+
+Two capabilities, layered:
+
+1. **Local background:** Run a KidLisp visual piece **behind** notepat's UI, activated via `notepat $roz` (or any `$code`), where the KidLisp piece gets notepat's live audio amplitude piped into its `amp` global variable.
+
+2. **Remote visualizer:** Any notepat instance becomes an **amplitude broadcaster** — it gets its own pj-style code channel, and a remote machine (projector, FF1, second screen) can connect to that channel via `pj.kidlisp.com/{channel}`, receive the live `amp` signal, and run the KidLisp visualization independently.
+
+The effect: notepat's blue/black background is replaced by a live-rendered KidLisp generative visual, and the normal notepat UI (keys, waveform bars, top bar, toggles) floats on top. On remote screens, the same visual runs full-screen with no notepat UI, driven by the live amplitude stream.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────┐     WebSocket (session server)     ┌─────────────────────────┐
+│  notepat instance           │ ──────────────────────────────────▶ │  pj.kidlisp.com/{ch}    │
+│  (player's device)          │     { type: "audio", amp, ... }    │  (remote visualizer)    │
+│                             │     { type: "code", $roz source }  │                         │
+│  ┌───────────────────────┐  │                                    │  ┌───────────────────┐  │
+│  │ KidLisp bg (local)    │  │     BroadcastChannel (same-origin) │  │ KidLisp piece     │  │
+│  │ via api.kidlisp()     │  │ ──────────────────────────────────▶ │  │ (full AC runtime) │  │
+│  │ amp from speaker      │  │     kidlisp-channel-{ch}           │  │ amp from stream   │  │
+│  └───────────────────────┘  │                                    │  └───────────────────┘  │
+│  ┌───────────────────────┐  │                                    └─────────────────────────┘
+│  │ notepat UI on top     │  │
+│  │ keys, bars, toggles   │  │
+│  └───────────────────────┘  │
+└─────────────────────────────┘
+```
+
+---
+
+## Phase 1 — Local Background (Embedded `kidlisp()` Call)
+
+### Why Embedded, Not iframe
+
+The existing `kidlisp()` helper in disk.mjs (line ~6135) already handles `$code` resolution, caching, persistent paintings, timing expressions, and accumulation. Using it is ~30 lines vs. the iframe underlay approach which would:
+- Touch ~15 places in bios.mjs's render loop (transparency, z-index, compositor hiding)
+- Require `postMessage` amplitude relay every frame
+- Add iframe loading latency
+- Duplicate the tape-playback underlay setup/teardown logic
+
+The local background is paint-only (no `sim()` loop), which is fine for amplitude-reactive visuals.
+
+### Why Also Support Remote
+
+The embedded approach only works on the same device. But a performer might want:
+- A projector behind them showing the visualization full-screen
+- An FF1 art computer on the wall reacting to their playing
+- A second browser tab/window showing just the visuals (for streaming OBS capture)
+
+This requires networking — notepat broadcasts its amplitude, remote viewers consume it. The pj.html + session-server infrastructure already exists for code relay; we just need to **add audio relay**.
+
+---
+
+## Phase 2 — Remote Visualizer (pj-style Amplitude Broadcasting)
+
+### Current State of the Infrastructure
+
+kidlisp.com already has:
+- **index.htm (editor)** broadcasts audio to PJ viewers via 3 transports:
+  - `postMessage` to same-origin popout windows
+  - `BroadcastChannel("kidlisp-channel-{id}")` for same-origin tabs  
+  - `WebSocket` to session server for cross-origin/remote
+- **pj.html (viewer)** receives audio on all 3 transports and forwards to its KidLisp iframe via `postMessage({ type: 'kidlisp-audio', data: audioData })`
+- **session-server** relays `code` and `slide` messages to channel subscribers
+
+### Critical Gap: Audio Relay is Broken for Remote
+
+The session server (`session.mjs`) has **no handler for `type: "audio"` messages**. The editor sends them over WebSocket, but the server silently drops them. Audio relay only works via BroadcastChannel (same-origin tabs on the same machine).
+
+**This means remote PJ viewers on different machines currently never receive audio data.**
+
+### Fix Required in session-server
+
+Add an `audio` message handler alongside the existing `code` and `slide` handlers:
+
+```js
+// session.mjs — alongside the existing code/slide handlers (~line 1935):
+} else if (msg.type === "audio" && msg.content?.codeChannel) {
+  const targetChannel = msg.content.codeChannel;
+  // Transient — don't store, just broadcast immediately (like slide)
+  // Audio is high-frequency (~60Hz), so no state persistence for late joiners
+  if (codeChannels[targetChannel]) {
+    const packed = pack("audio", msg.content, id);
+    for (const subId of codeChannels[targetChannel]) {
+      if (subId !== id) connections[subId]?.send(packed);  // Don't echo back to sender
+    }
+  }
+}
+```
+
+### How Notepat Becomes a Broadcaster
+
+In `boot()`, notepat connects to the session server WebSocket and subscribes to a channel:
+
+```js
+// Generate or derive a channel ID
+const channelId = `notepat-${Math.random().toString(36).slice(2, 8)}`;
+// Or use a deterministic ID from params: notepat $roz:myshow → channel "myshow"
+
+// Connect to session server (reuse existing net.session WebSocket if available)
+const sessionWs = new WebSocket("wss://session-server.aesthetic.computer");
+sessionWs.onopen = () => {
+  sessionWs.send(JSON.stringify({ type: "code-channel:sub", content: channelId }));
+  // Send the KidLisp $code so late-joining viewers get it
+  sessionWs.send(JSON.stringify({
+    type: "code",
+    content: { codeChannel: channelId, piece: kidlispSource }
+  }));
+};
+```
+
+In `paint()`, broadcast amplitude every frame (or throttled):
+
+```js
+if (sessionWs?.readyState === WebSocket.OPEN) {
+  sessionWs.send(JSON.stringify({
+    type: "audio",
+    content: { codeChannel: channelId, amp: amplitude * 10, timestamp: Date.now() }
+  }));
+}
+```
+
+### Remote Viewer Connects
+
+A remote machine opens `pj.kidlisp.com/notepat-abc123` (or any URL that resolves the channel). The existing pj.html code already:
+1. Connects to session server WebSocket
+2. Subscribes to the channel
+3. Receives `code` → loads the KidLisp piece in its iframe
+4. Receives `audio` → forwards to iframe as `kidlisp-audio` postMessage (once the server relay is fixed)
+
+**No changes to pj.html are needed** — it already has the `audio` receive path wired up, it just wasn't receiving anything because the server dropped the messages.
+
+---
+
+## Bandwidth Considerations for Audio Relay
+
+Audio messages at 60Hz with `{ amp, leftAmp, rightAmp, beat, kick, bass, mid, treble, highMid, presence }` ≈ ~200 bytes/message × 60/sec ≈ **12 KB/sec per subscriber**. This is negligible compared to video streaming.
+
+For extra efficiency:
+- Throttle to 30Hz (every other paint frame) — still smooth for visuals
+- Only send when amplitude changes by > threshold (skip silent frames)
+- Batch multiple fields into a compact array format instead of named object
+
+---
+
+## Implementation Steps
+
+### Phase 1: Local Background (~30 lines in notepat.mjs)
+
+#### Step 1 — Parse `$` Param in notepat's `boot()`
+
+**File:** `system/public/aesthetic.computer/pieces/notepat.mjs` — boot() at line ~1115
+
+Add a new state variable and parse `$code` from `params[0]`:
+
+```js
+// New state variables (near line 910 with other state)
+let kidlispBackground = null;  // e.g. "$roz" → will resolve to KidLisp source
+let kidlispBgEnabled = false;
+
+// In boot(), after existing params handling (after line ~1276):
+const dollarParam = params.find(p => p.startsWith("$"));
+if (dollarParam) {
+  kidlispBackground = dollarParam;  // e.g. "$roz"
+  kidlispBgEnabled = true;
+}
+```
+
+#### Step 2 — Forward Amplitude to KidLisp Each Frame
+
+**File:** `system/public/aesthetic.computer/pieces/notepat.mjs` — paint() at line ~2509
+
+After the existing amplitude extraction (`const amplitudeRaw = sound.speaker?.amplitudes?.left`), forward it to the global KidLisp instance:
+
+```js
+// After line ~2514 (amplitude extraction):
+if (kidlispBgEnabled) {
+  // Pipe notepat's amplitude into KidLisp's global `amp`
+  // Scale: sound.speaker.amplitudes.left is 0..~1, KidLisp expects 0..10
+  const scaledAmp = amplitude * 10;
+  api.updateKidLispAudio?.({ amp: scaledAmp });
+}
+```
+
+**Note:** `updateKidLispAudio` is exposed at `disk.mjs` line ~5084 and calls `globalKidLispInstance.updateAudioGlobals()` which sets `this.globalDef.amp`. This is the same path kidlisp.com's music player uses. 
+
+The `api` object passed to `paint()` should expose this. If not, we can call it via the disk module's exported `updateKidLispAudio` directly, or add it to the paint API.
+
+#### Step 3 — Render KidLisp Background in paint()
+
+**File:** `system/public/aesthetic.computer/pieces/notepat.mjs` — paint() at line ~2641
+
+Insert the KidLisp background rendering **before** the wipe/mode cascade, so it replaces the background:
+
+```js
+// Before the existing mode cascade (line ~2641):
+if (kidlispBgEnabled && kidlispBackground) {
+  // Render KidLisp piece as full-screen background
+  api.kidlisp(0, 0, screen.width, screen.height, kidlispBackground);
+  // Skip normal wipe — KidLisp provides the background
+} else if (visualizerFullscreen && !recitalMode) {
+  wipe(0);
+  // ... existing visualizer code
+} else if (recitalMode) {
+  wipe(0);
+  // ... existing recital code
+} else {
+  wipe(bg);
+}
+```
+
+The `api.kidlisp()` call handles:
+- `$code` → fetch and cache the code via `getCachedCodeMultiLevel()`
+- First-frame loading (returns `null` while async fetch is in flight — paint normal bg as fallback)
+- Subsequent frames: executes KidLisp and returns a `painting` object
+- Persistent caching via `globalKidLispInstance.persistentPaintings`
+
+We just `paste()` the painting to fill the screen, then paint notepat's UI on top.
+
+#### Step 4 — Ensure `api.kidlisp` is Available
+
+**File:** `system/public/aesthetic.computer/lib/disk.mjs` — `$paintApi` object (line ~5092)
+
+Verify that `kidlisp` is already part of the paint API passed to pieces. It's defined as a method in `$paintApi` at line ~6135. If notepat's `paint()` receives the standard `api` object, it should already have `api.kidlisp()`.
+
+**File:** `system/public/aesthetic.computer/lib/disk.mjs` — paint API
+
+Also verify `api.updateKidLispAudio` is exposed. If not, add it:
+
+```js
+// In $paintApi or the api object passed to piece paint():
+updateKidLispAudio: updateKidLispAudio,
+```
+
+#### Step 5 — Handle Loading State
+
+While `$code` is being fetched (first frame), `api.kidlisp()` returns `null`. During this frame, fall through to the normal wipe:
+
+```js
+if (kidlispBgEnabled && kidlispBackground) {
+  const bgPainting = api.kidlisp(0, 0, screen.width, screen.height, kidlispBackground);
+  if (!bgPainting) {
+    wipe(bg); // Fallback while loading
+  }
+  // If bgPainting exists, it was already pasted to the screen by kidlisp()
+} else if (visualizerFullscreen && !recitalMode) {
+  // ...existing
+```
+
+#### Step 6 — HUD Label Update
+
+When a `$code` background is active, update the HUD label to reflect it:
+
+```js
+// In boot(), after setting kidlispBgEnabled:
+if (kidlispBgEnabled) {
+  hud.label(`notepat ${kidlispBackground}`);
+}
+```
+
+This would show `notepat $roz` in the HUD corner.
+
+#### Step 7 — Toggle KidLisp Background On/Off
+
+Optionally allow toggling the KidLisp background with a keyboard shortcut (e.g., pressing `V` for "visual") or a tap zone, so the user can switch between the KidLisp visual and the normal blue/reactive background during performance.
+
+### Phase 2: Remote Visualizer (~50 lines across 3 files)
+
+#### Step 8 — Fix Session Server Audio Relay
+
+**File:** `session-server/session.mjs` — near line ~1935 (alongside `code` and `slide` handlers)
+
+Add the missing `audio` message handler:
+
+```js
+} else if (msg.type === "audio" && msg.content?.codeChannel) {
+  const targetChannel = msg.content.codeChannel;
+  if (codeChannels[targetChannel]) {
+    const packed = pack("audio", msg.content, id);
+    for (const subId of codeChannels[targetChannel]) {
+      if (subId !== id) connections[subId]?.send(packed);
+    }
+  }
+}
+```
+
+This is transient (no state storage, like `slide`) — audio is high-frequency and late joiners just start receiving from the current moment.
+
+#### Step 9 — Notepat Connects as Amplitude Broadcaster
+
+**File:** `system/public/aesthetic.computer/pieces/notepat.mjs` — boot()
+
+When `$code` is active, notepat opens a session-server WebSocket and creates a named channel:
+
+```js
+// In boot(), after kidlispBgEnabled is set:
+let ampChannel = null;
+let ampWs = null;
+
+if (kidlispBgEnabled) {
+  // Channel ID: notepat instance identifier
+  // Could be random, or derived from a user-chosen name via colon param
+  // e.g. notepat $roz:myshow → channel "myshow"
+  const colonChannel = colon?.find(c => !wavetypes.includes(c) && !/^\d+$/.test(c));
+  ampChannel = colonChannel || `np-${Math.random().toString(36).slice(2, 8)}`;
+  
+  const wsUrl = net.sessionServerUrl || "wss://session-server.aesthetic.computer";
+  ampWs = new WebSocket(wsUrl);
+  ampWs.onopen = () => {
+    ampWs.send(JSON.stringify({ type: "code-channel:sub", content: ampChannel }));
+    // Send the $code so remote viewers get the KidLisp piece
+    ampWs.send(JSON.stringify({
+      type: "code",
+      content: { codeChannel: ampChannel, piece: kidlispBackground }
+    }));
+  };
+}
+```
+
+Display the channel ID in the HUD so the user can share it:
+```js
+hud.label(`notepat ${kidlispBackground} → ${ampChannel}`);
+```
+
+#### Step 10 — Broadcast Amplitude in paint()
+
+**File:** `system/public/aesthetic.computer/pieces/notepat.mjs` — paint()
+
+Throttle to ~30Hz (every other frame) to keep bandwidth light:
+
+```js
+let ampBroadcastTick = 0;
+
+// In paint(), after amplitude extraction:
+if (ampWs?.readyState === WebSocket.OPEN && ++ampBroadcastTick % 2 === 0) {
+  ampWs.send(JSON.stringify({
+    type: "audio",
+    content: {
+      codeChannel: ampChannel,
+      amp: amplitude * 10,
+      timestamp: Date.now()
+    }
+  }));
+}
+```
+
+#### Step 11 — Remote Viewer Connects
+
+A remote machine opens `pj.kidlisp.com/{ampChannel}` — **no changes to pj.html needed**.
+
+pj.html already:
+1. Parses channel ID from URL path
+2. Connects to session server and subscribes to the channel
+3. Receives `code` message → loads KidLisp piece in iframe
+4. Receives `audio` message → calls `sendAudioToIframe()` which posts `kidlisp-audio` to the iframe
+
+The only thing that was broken was the session server not relaying audio (Step 8 fixes that).
+
+---
+
+## Amplitude Data Pipelines
+
+### Local (Phase 1)
+```
+notepat AudioWorklet
+  → sound.speaker.poll() (in sim)
+  → sound.speaker.amplitudes.left (in paint) [0..~1 range]
+  → updateKidLispAudio({ amp: amplitude * 10 }) 
+  → globalKidLispInstance.globalDef.amp [0..10 range]
+  → KidLisp piece reads `amp` variable during execution
+```
+
+### Remote (Phase 2)
+```
+notepat AudioWorklet
+  → sound.speaker.amplitudes.left (in paint)
+  → ampWs.send({ type: "audio", content: { amp: amplitude * 10 } })
+  → session-server relays to channel subscribers
+  → pj.html receives { type: "audio", content: { amp } }
+  → pj.html posts { type: "kidlisp-audio", data: { amp } } to iframe
+  → iframe's boot.mjs receives postMessage
+  → disk.mjs updateKidLispAudio({ amp })
+  → globalKidLispInstance.globalDef.amp
+  → KidLisp piece reads `amp`
+```
+
+Both paths end at the same `globalDef.amp` — the KidLisp piece code is identical whether it runs locally or remotely.
+
+---
+
+## Visual Compositing Order (in paint)
+
+```
+1. KidLisp background renders to full screen (replaces wipe)
+2. Waveform bars overlay (if visualizerFullscreen/recitalMode)  
+3. Top bar piano illustration
+4. Note names / chord display
+5. Toggle buttons  
+6. Active key highlights
+7. Touch interaction zones
+8. .com superscript (if notepat.com)
+```
+
+The KidLisp painting writes to the pixel buffer first. All subsequent notepat `ink()`/`line()`/`box()`/`write()` calls paint **on top**, producing the layered effect naturally — no transparency/z-index DOM tricks needed.
+
+---
+
+## Files Changed
+
+| File | Phase | Change |
+|------|-------|--------|
+| `notepat.mjs` | 1 | `kidlispBackground`/`kidlispBgEnabled` state, `$` param parsing, `api.kidlisp()` in `paint()`, amplitude forwarding |
+| `disk.mjs` | 1 | Possibly expose `updateKidLispAudio` on paint API if not already there |
+| `session-server/session.mjs` | 2 | Add `audio` message relay handler (~10 lines) |
+| `notepat.mjs` | 2 | WebSocket connection, channel creation, amplitude broadcast in `paint()` |
+
+**Estimated scope:** Phase 1 ~30 lines, Phase 2 ~50 lines across 2 files.
+
+---
+
+## Edge Cases & Considerations
+
+1. **Performance:** Heavy KidLisp programs (many shapes, recursion) running at notepat's framerate could cause jank. Mitigation: the `kidlisp()` helper already has persistent painting caching, so static parts don't re-render. Timing expressions (`0.15s`) self-throttle.
+
+2. **Visual modes:** When `paintPictureOverlay` (turtle drawing mode) or `recitalMode` is active, the KidLisp background should probably be disabled/hidden since those modes have their own full-screen visuals. The cascade handles this naturally if we gate the KidLisp rendering with `!paintPictureOverlay && !recitalMode && !visualizerFullscreen`.
+
+3. **Projector mode:** In projector mode, notepat already wipes black and draws minimal UI. KidLisp background could optionally show in projector mode too (for live performance aesthetics). This is a design choice.
+
+4. **Multiple `$` codes:** Could support `notepat $roz $wave` for layered KidLisp backgrounds. The `kidlisp()` helper already supports multiple regions — just call it twice with different source codes and positions.
+
+5. **KidLisp code that uses `wipe`:** If the `$code` itself contains `wipe` commands, the kidlisp() helper handles this via its `shouldReset` logic. This is fine — the KidLisp piece controls its own background clearing within its painting region.
+
+6. **Cleanup:** When notepat piece changes, the global KidLisp instance's `persistentPaintings` are managed by disk.mjs lifecycle. No special cleanup needed in notepat.
+
+---
+
+## Future Extensions
+
+- **Bottom bar on notepat.com:** "Available as Ableton Extension" marquee (already planned separately).
+- **KidLisp code editor inside notepat:** Long-press the `$roz` label to open an inline editor for the background code.
+- **Beat-reactive globals:** Forward `beat`, `kick`, `bass`, `mid`, `treble` from notepat's audio analysis to KidLisp — same `updateKidLispAudio` call, just add more fields. (Note: notepat currently runs in `performanceMode: "disabled"` which skips heavy analysis in the worklet. Enabling frequency band analysis would require changing this to `"enabled"` or `"bands-only"`.)
+- **Shared tempo:** Forward notepat's BPM to KidLisp's `bpm` global for beat-synced visuals.
+- **Named channels:** `notepat $roz:liveset` creates channel `liveset` instead of random — shareable, memorable for performances.
+- **QR code display:** Show a QR code on notepat's screen (tap a button) linking to `pj.kidlisp.com/{channel}` so audience members can see the visuals on their phones.
+- **FF1 cast integration:** `ac-ff1 cast pj.kidlisp.com/{channel}` sends the remote visualizer directly to the FF1 art computer.
+- **Multi-notepat jam:** Multiple notepat instances on different devices broadcast to the same channel — the remote visualizer merges their amplitude signals (max, average, or per-player).
+- **Audience participation:** Remote viewers on `pj.kidlisp.com/{channel}` could send interaction events back (taps → visual effects), making the visualizer bidirectional.

reports/llm-high-metaphors.md

···
+# Beyond "Documentation": Metaphors for LLM-Driven Development in Aesthetic Computer
+
+**Date:** 2026-02-08  
+**Source:** [federicopereiro.com/llm-high](https://federicopereiro.com/llm-high/) by Federico Pereiro  
+
+---
+
+## The Original Framework (Pereiro's "cell")
+
+Pereiro proposes that LLM agents are the new high-level language — what JS/Python did to Java, agents now do to all languages. His framework has **two stocks** and **two flows**:
+
+| Role | Name | Nature |
+|------|------|--------|
+| Stock | **Documentation** | Markdown spec pages — purpose, entities, endpoints, constraints, coding standards |
+| Stock | **Implementation** | Codebase + data. Reconstructable from documentation. |
+| Flow | **Dialogs** | Agent conversation streams. Inspectable, joinable by humans. |
+| Flow | **Tasks** | Discrete work items, nestable, with status tracking. |
+
+He calls the stocks the "tions" (documenta-**tion**, implementa-**tion**) and notes the frontend of the system is now the documentation + agents; the backend is the substrate.
+
+---
+
+## Why "Documentation" Doesn't Fit AC
+
+"Documentation" smells like enterprise software — API references, Confluence pages, Swagger specs. It's passive, bureaucratic, retrospective. AC's culture is none of those things. AC is:
+
+- **A creative coding platform** rooted in Processing's sketchbook model
+- **Piece-based** — small interactive programs, not microservices
+- **Playful** — commands like `wipe("purple")`, handles like `@jeff`, KidLisp
+- **Art-adjacent** — descended from No Paint, gallery shows, whistlegraph
+- **Live** — drag-and-drop hot reload, multiplayer channels, performance
+
+The "stock of truth that agents reconstruct from" needs a word that carries creative intent, not compliance.
+
+---
+
+## Alternative Metaphors
+
+### 1. **Score** ★★★★★
+
+A musical score is a set of instructions for performance — not the performance itself. Strudel is already in AC's orbit. A score:
+- Prescribes behavior without being the behavior
+- Is interpreted by performers (agents) with room for expression
+- Can be read, annotated, conducted
+- Has a long history in experimental/conceptual art (Fluxus event scores, Sol LeWitt wall drawings, Yoko Ono's *Grapefruit*)
+
+**Vocabulary:** "The score describes the system. Agents perform it. The implementation is what's playing."
+
+### 2. **Sketch / Sketchbook** ★★★★
+
+AC already lives in Processing's sketchbook lineage. A sketch is:
+- Intentional but loose — it captures *what you mean* without specifying every pixel
+- Iterative — you sketch, erase, redraw
+- The natural first artifact of any creative process
+- Already in AC's DNA (pieces *are* sketches)
+
+**Risk:** Might feel too informal for the "source of truth" role. Sketches are disposable; the stock shouldn't be.
+
+### 3. **Blueprint** ★★★★
+
+Blueprints are generative specifications — they describe something that will be built by someone else (the agents). Unlike documentation:
+- They're forward-looking, not retrospective
+- They assume a builder will interpret them
+- They carry authority ("build it like this")
+- They're visual/spatial, not just textual
+
+**Risk:** Slightly too architectural/industrial for AC's art-kid energy.
+
+### 4. **Script** (theatrical) ★★★★
+
+A script is dialogue + stage directions. Agents are the cast. The human is the director.
+- Scripts expect interpretation and staging
+- Scripts evolve through rehearsal (agent iteration)
+- "Rewrite the script" is a natural phrase for changing system behavior
+- There's already precedent: AC pieces are basically scripts for the runtime
+
+**Risk:** Collision with "script" meaning shell/JS script. Could confuse.
+
+### 5. **Spell / Grimoire** ★★★½
+
+Spells are incantations that produce effects. A grimoire is a collected book of spells.
+- AC already has a magical/whimsical register (KidLisp, `wand`, `witch`)
+- "Cast a spell" = "run a piece"
+- The grimoire is the collected knowledge that agents draw from
+- Fits the idea that you write words and things *happen*
+
+**Risk:** Too cute? Could alienate people who want to take the system seriously.
+
+### 6. **Map** ★★★½
+
+Maps describe territory without being the territory. Agents navigate by the map.
+- "The map is not the territory" — the stock is not the implementation
+- Maps can be zoomed, annotated, updated
+- You explore a map; you don't just read it
+
+**Risk:** Lacks creative/generative energy. Maps describe what *is*, not what *should be*.
+
+### 7. **Prompt** ★★★
+
+AC already has a prompt (the command line). The entire stock could be seen as "the prompt" — the human's intent expressed in natural language that agents execute against.
+- Extremely literal for the LLM era
+- Already in AC's vocabulary
+- "The prompt" as the system's source of truth has a nice recursion to it
+
+**Risk:** Overloaded term. Everyone uses "prompt" for everything now.
+
+### 8. **Manifesto** ★★★
+
+A manifesto declares intent and principles. Agents carry them out.
+- Art-world precedent (Futurism, Fluxus, Dogme 95)
+- A manifesto is opinionated and alive — not neutral reference material
+- "The manifesto says X, so the system does X"
+
+**Risk:** Manifestos are usually one-off declarations, not living documents.
+
+### 9. **Recipe** ★★★
+
+Recipes are procedural but expressive. They assume a cook (agent) who interprets.
+- "A pinch of salt" = room for agent judgment
+- Natural for describing flows and processes
+- Cookbooks are a nice organizational metaphor
+
+**Risk:** Doesn't scale to system-level architecture. Good for pieces, not for the whole.
+
+### 10. **Seed** ★★½
+
+Seeds grow into implementations. You plant the seed, the agent grows it.
+- Organic, generative
+- Fits AC's creative ethos
+
+**Risk:** Too vague. What does "editing a seed" mean? Seeds are black boxes.
+
+---
+
+## Recommendation for AC
+
+**Score** is the strongest metaphor. It fits AC's creative identity, has deep roots in experimental art practice, naturally accommodates the relationship between specification and execution, and works at every scale — a single piece has a score, and the whole system has a score.
+
+The four-part framework adapted for AC:
+
+| Pereiro's Term | AC Term | What It Is |
+|----------------|---------|------------|
+| Documentation | **Score** | Markdown pages describing intent, entities, constraints, style |
+| Implementation | **Performance** (or just "the system") | Running code + data — the score being played |
+| Dialogs | **Sessions** | Agent conversation streams (already an AC concept) |
+| Tasks | **Tasks** (or **Cues**) | Discrete work items — "cues" if you want to stay in the theater/music metaphor |
+
+**"The score describes it. The agents perform it. The system is live."**
+
+---
+
+## Mixed Metaphor Option
+
+You don't have to pick one. AC could use different words at different scales:
+
+- **Score** for the system-level source of truth
+- **Sketch** for individual piece-level descriptions
+- **Prompt** for ephemeral one-off agent instructions
+
+This mirrors how AC already has layers: the platform, pieces, and the command prompt.
+
+---
+
+## Open Questions from Pereiro (through AC's lens)
+
+### 1. How do we store the score alongside the implementation?
+
+AC already has a precedent: `AGENTS.md`, `llm.md`, `STORY.md`, and `WRITE-A-PIECE.md` live at the repo root — authoritative markdown that agents and humans both read. The `plans/` directory (40+ files) and `docs/` (7 files) hold deeper specs and investigations.
+
+**The problem:** These are scattered and unranked. There's no distinction between "this is the score — canonical, authoritative, what agents should reconstruct the system from" and "this is a plan, a sketch, a conversation artifact." Everything lives in flat directories with no hierarchy.
+
+**Proposal:** A `score/` directory at the repo root, clearly separated:
+
+```
+score/
+  README.md                ← "Score for AA" (the double-A score) — the overture
+  pieces.md                ← What pieces are, how the lifecycle works (boot/paint/sim/act/beat)
+  kidlisp.md               ← The language spec
+  infrastructure.md        ← Session server, Redis, multiplayer, auth, deploy
+  social.md                ← Handles, chat, moods, channels, sharing
+  creative-philosophy.md   ← The instrument metaphor, sketchbook model, whistlegraph lineage
+  style.md                 ← Code conventions, naming, file structure
+  electron.md              ← Desktop app architecture
+```
+
+The score is **not** the `plans/` directory. Plans are drafts, investigations, explorations. The score is what survived — the distilled intent. An agent should be able to read `score/` and reconstruct the system's architecture from scratch. `plans/` is the archive of past rehearsals. `reports/` is analysis. The score is the source of truth.
+
+The existing `AGENTS.md` and `llm.md` would migrate into `score/` or become views derived from it.
+
+### 2. How do we use version control?
+
+This is the hardest question. Pereiro identifies four artifacts: **Score** (documentation), **Performance** (implementation), **Sessions** (dialogs), and **Tasks**. How does git handle each?
+
+**What AC does now:**
+- **Score & Performance** share one repo, one branch (`main`), no CI/CD gating. Manual deploys. Works because there's one primary author (you).
+- **Sessions** (agent dialogs) — partially enter git via `copilot/*` branches and agent-generated files in `plans/`. But most dialog is ephemeral (VS Code chat, Copilot sessions) and never persisted.
+- **Tasks** — `TODO.txt` at root, plus ad-hoc tracking in agent conversations. No formal task system in git.
+- **Secrets** — sidecar `aesthetic-computer-vault/` repo, gitignored from main, with its own version history. Good pattern.
+- **Assets** — CDN-synced, not in git, no manifest. State lives outside version control.
+
+**Tensions exposed by the score metaphor:**
+
+**a) The score should change slower than the performance.**
+A musical score gets revised between performances, not during one. In git terms: score changes should be deliberate, reviewed, infrequent commits. Implementation changes can be rapid and agent-driven. But right now they're in the same commit stream with no distinction. You can't `git log score/` and see only the moments the intent changed.
+
+**Possible approach:** Score changes get their own commits with a `score:` prefix. Or score files live in a separate branch/worktree that gets merged into `main` intentionally. Or — simpler — just the discipline of committing score changes separately with clear messages.
+
+**b) Sessions (dialogs) are valuable but enormous.**
+Agent conversations contain reasoning, dead ends, discoveries. They're useful for understanding *why* the system is the way it is. But they're too large for git (a single Copilot session can be thousands of lines). They also contain sensitive context.
+
+**Possible approach:** Don't put sessions in git. Archive them as timestamped markdown in a `sessions/` directory that's gitignored locally but backed up elsewhere (like the vault pattern). Or keep only the *summary* of each session — a one-paragraph "what happened and what changed" that becomes a git-tracked changelog entry.
+
+**c) Agent branches need guardrails.**
+The `copilot/*` branches create PRs against `main` with no automated tests. As agent volume increases, this becomes a quality risk. The score metaphor helps here: agents should be performing *from* the score, and their output should be validated against it.
+
+**Possible approach:** A lightweight CI step that runs `npm test` and the KidLisp spec suite before any merge to `main`. Not a full pipeline — just the smoke test. The score could also contain explicit acceptance criteria that agents check themselves against.
+
+**d) The monorepo is the orchestra pit.**
+80+ top-level directories, 317-line `.gitignore`, node_modules in 15 places, Rust targets, Playdate builds, N64 ROMs. This is the accumulation of every instrument that's ever been tried. Some are active, many are dormant.
+
+**Possible approach:** The score explicitly names what's active and what's archival. A `score/instruments.md` that maps each top-level directory to its status: `system/` = 1st violin (primary), `kidlisp/` = piano (core), `ac-electron/` = cello (active), `kidlisp-n64/` = theremin (experimental, dormant). Agents can then know what to touch and what to leave alone.
+
+**e) Redis state and CDN assets are outside git.**
+The performance includes state that git doesn't track: Redis data, CDN-hosted assets, deployed Netlify functions. There's no manifest describing what's deployed.
+
+**Possible approach:** A `score/state.md` that describes what state exists where (Redis schemas, CDN asset structure, environment variables) so that the system is reconstructable even from the git history alone. Not the secrets themselves — just the shape of them.
+
+### 3. MCP as the orchestra's connection to the audience
+
+Pereiro's insight: MCP is like XMLHTTPRequest — it lets agents reach into any external service and pull data/functionality into your canvas. This breaks application silos.
+
+AC already has MCP (`artery/emacs-mcp.mjs`, `.vscode/mcp.json`). The current use is internal — controlling Emacs, managing the dev environment. But the score metaphor extends this further:
+
+- **MCP servers as guest musicians.** External services (Stripe, Auth0, Tezos, Firebase) are guest performers who play from their own parts but are conducted by AC's score. The score describes what AC expects from each service; MCP is the protocol by which agents bring them into the performance.
+- **AC as MCP server for others.** AC's pieces could be exposed as MCP tools — letting *other people's* agents play AC's instruments. `notepat` as an MCP tool. `wipe("purple")` callable from any agent. This is the "Scores for Social Software" idea made literal: your score becomes playable by anyone's conductor.
+- **The audience participates.** URL-addressable pieces already mean anyone with a browser is in the audience. MCP could mean any agent with the right connection is in the orchestra. The score is the shared page they all read from.
+
+---
+
+## Why "Score" Was Already in AC's Blood
+
+After deeper repo research, it's clear AC has been a score system from the start — maybe before you had the word for it.
+
+### Evidence
+
+1. **The README manifesto:** *"AC's client interface is designed to function like a musical instrument, on which users discover their own memorizable paths in the network of commands and published pieces. As users grow their literacy through play and exploration, they are able to improvise, recombine, and expand their performable repertoire."* — That's describing a score culture, not a documentation culture.
+
+2. **Whistlegraph literally is a score.** A whistlegraph is a drawing made while sound is recorded. It's a multimedia graphic notation — playable, performable, archivable. The GitHub org is `whistlegraph`. The whole project has been organized around this idea since before it had a programming platform attached.
+
+3. **Pieces are scores.** Each `.mjs` file describes a performance that the runtime executes. `boot → paint → sim → act → beat` — this is a temporal structure. `beat` is literally a BPM hook. The lifecycle *is* musical.
+
+4. **`merry` is a setlist.** The `merry` / `merryo` commands chain pieces in timed sequences. That's a concert program. A score for an evening.
+
+5. **The prompt is a conductor's podium.** You stand at it and call cues. `notepat`. `tape notepat`. `share notepat`. Prefix commands are like orchestration marks on a score — they modify how a piece is performed.
+
+6. **KidLisp pieces use `$` embedding** — one piece calling another as a layer. That's instrumentation. Voices in a score.
+
+7. **The mudras.** The `writing/` directory has Indian classical hand gesture notation (`mudras-notation.jpg`, `asamyuta-hasta`). Graphic notation for the body.
+
+8. **The `stage` piece** is a 3D colored-block melody system (A-G). A literal spatial score.
+
+9. **`notepat`** has melody notation and a typing mode. It's a score *writer*.
+
+---
+
+## Scores for Social Software — The Card Deck Submission
+
+Lauren Lee McCarthy (p5.js) and Casey Reas (Processing) invited you to contribute a score to their "Scores for Social Software" card deck. They explicitly reference **Fluxus scores**, **Notations** (Cage/Knowles), **do it** (Obrist), and **Oblique Strategies** (Eno/Schmidt).
+
+This is the exact convergence. Their definition:
+> *"We think of social software as any program, system, or tool that structures, mediates, or intervenes in the world around us. We think of a score as a way of choreographing events in time through diagrams and/or text."*
+
+AC *is* social software. And now you're also naming its internal knowledge system a "score." The card, the repo concept, and the platform philosophy are the same thing seen from three distances.
+
+### Title Variations for the SCORE.md / General Concept
+
+**The winner: "Score for AA" (the double-A score)**
+
+AA = Aesthetic Ants. Also:
+- **Aesthetic Ants** — the primary expansion. The score is *for* the ants. They follow it.
+- **Agentic Ant** — what each one does (it has agency, barely)
+- **Aesthetic Agents** — the wider reading: human agents (artists, users) and software agents (ants, LLMs, bots) all follow the same score
+- **AA batteries** — small, portable, powers everything
+- **AA meetings** — a program you follow one day at a time, one small step
+- **aa lava** — Hawaiian: rough, slow-moving, builds landscape gradually (like ants)
+- **AA paper size** — a sheet you write scores on
+
+The commit prefix is `ant:` — or could be `aa:` to lean into it.
+"Check the double-A" / "follow the double-A" / "the ants are running on double-A."
+
+**Other variations considered:**
+
+2. **Score for a Computer & Its Friends** — gentler, more universal. "Its Friends" = pieces, users, agents, other software.
+3. **Score for Computers & People** — austere, Fluxus-register. Echoes "Composition 1960 No. 7" (La Monte Young).
+4. **Score for Anyone with a Browser** — populist, true, funny.
+5. **Score for a Prompt and All That Follows** — poetic, captures the cascade (type a word → piece loads → people play → things get shared → code gets minted).
+6. **Score for Software that Wants to be Touched** — about mobile-first, about intimacy with computation.
+7. **Score for Pals** — stripped down. The pals are left undefined. Could be people, pieces, bots, agents.
+8. **Piece for Pals** — uses AC's own word. A score is a piece. A piece is a score.
+
+**Dropping "Score for" (shorter, stranger):**
+
+9. **Aesthetic.Computer & Pals** — just the title, no framing word. It *is* a score by context.
+10. **& Pals** — the minimal version. On a card, with nothing else, it's a statement: the software is the ampersand — a connector between unnamed friends.
+
+**Completely different register:**
+
+11. **A Score for the Prompt** — focuses on the command-line-as-instrument idea. The prompt is the silence before the first note.
+12. **Overture for Social Software** — overture = the opening piece that previews all themes. AC's `prompt` *is* an overture.
+13. **Études for the Networked Hand** — étude = study piece for developing technique. AC has actual keyboard études in `writing/`. "Networked Hand" = touchscreen + multiplayer.
+14. **Notation for Sharing a Screen** — the screen is the shared page of the score. URL-addressable = everyone reads the same page.
+15. **Instructions for Pals** — Fluxus-direct. "Pals" does the warmth work.
+
+### Possible Card Scores (for the Lauren/Casey submission)
+
+These are draft scores in the Fluxus/Oblique Strategies tradition, sized for a 2.75" × 4.75" card. Each one encodes something true about AC's philosophy:
+
+---
+
+**Score #1: "prompt"**
+
+```
+Open a blank page.
+Type one word.
+Wait for whatever happens.
+
+If nothing happens, type another word.
+If something happens, invite someone to watch.
+If they want to try, hand them the keyboard.
+
+Repeat until the blank page is no longer blank,
+or until everyone has gone home.
+```
+
+*(This is literally how AC works. The prompt is the score.)*
+
+---
+
+**Score #2: "channel"**
+
+```
+Find two screens.
+Put the same address in both.
+Change something on one.
+Watch the other.
+
+Now find three screens.
+Now find a classroom.
+Now find a stranger.
+
+The channel is open
+until you close this window.
+```
+
+*(Based on the `channel` feature — live code broadcasting.)*
+
+---
+
+**Score #3: "&"**
+
+```
+Write a program.
+Give it a name.
+Put it at a URL.
+
+Now it is social software.
+
+Anyone who visits the URL
+is performing the program with you,
+whether you know them or not.
+```
+
+*(The radicalism of URL-addressable creative software.)*
+
+---
+
+**Score #4: "wipe"**
+
+```
+wipe("purple")
+
+Every program begins
+by deciding the color
+of nothing.
+```
+
+*(AC's `wipe` command — clearing the canvas — is the first line of every piece.)*
+
+---
+
+**Score #5: "pals"**
+
+```
+Make software for one person.
+That person will show someone.
+That someone will want to change something.
+Let them.
+
+The software now has two authors.
+Neither of them wrote most of it.
+All of them are pals.
+```
+
+*(The No Paint → AC pipeline: users contributing stamps, becoming co-authors.)*
+
+---
+
+**Score #6: "beat"**
+
+```
+boot once.
+paint every frame.
+act on every touch.
+beat at 120 bpm.
+
+( Software has a pulse.
+  It was always alive.
+  You just weren't counting. )
+```
+
+*(AC's piece lifecycle hooks — boot, paint, sim, act, beat — as revelation.)*
+
+---
+
+### For the SCORE.md in the Repo
+
+I'd suggest the repo file should be titled:
+
+# Score for AA
+
+("The double-A score." AA = Aesthetic Ants. Also: Agentic Ant, Aesthetic Agents.)
+
+And the card for Lauren and Casey could be any of the above — but **Score #1 ("prompt")** or **Score #4 ("wipe")** feel strongest. #1 because it *is* exactly how AC works and it's universally legible. #4 because it's the shortest, strangest, and most poetic — and `wipe("purple")` is genuinely beautiful code.
+
+The card title on the back would read:
+> **Jeffrey Alan Scudder**  
+> *prompt* (or *wipe*)  
+> 2026

system/public/aesthetic.computer/disks/notepat.mjs

···
 // 🌐 Branded domain mode (notepat.com — pushes top bar piano right for .com superscript)
 let dotComMode = false;
 
+// 🎨 KidLisp background visual (activated via `notepat $roz` etc.)
+let kidlispBackground = null; // e.g. "$roz" — the $code to render behind the UI
+let kidlispBgEnabled = false;
+
 const trail = {};
 
 // 🎹 Piano roll history - pixel timeline of held notes
···
   }
 
   // qrcells = qr("https://prompt.ac/notepat", { errorCorrectLevel: 2 }).modules;
+
+  // 🎨 KidLisp background: parse $code param (e.g. `notepat $roz`)
+  const dollarParam = params.find((p) => p.startsWith("$"));
+  if (dollarParam) {
+    kidlispBackground = dollarParam; // e.g. "$roz"
+    kidlispBgEnabled = true;
+    hud.label(`notepat ${dollarParam}`);
+  }
 
   if (params[0] === "piano") {
     toneVolume = params[1] || 0.5;
···
     }
   }
   
+  // 🎨 KidLisp background: forward amplitude + render
+  if (kidlispBgEnabled) {
+    api.updateKidLispAudio({
+      amp: amplitude * 10,
+      notes: active.length,
+    });
+  }
+
   // 🎨 Fullscreen visualizer mode - draw bars as background behind everything
-  if (visualizerFullscreen && !recitalMode) {
+  if (kidlispBgEnabled && kidlispBackground && !paintPictureOverlay) {
+    const bgPainting = api.kidlisp(
+      0, 0, screen.width, screen.height, kidlispBackground,
+    );
+    if (!bgPainting) wipe(bg); // Fallback while $code is loading
+  } else if (visualizerFullscreen && !recitalMode) {
     wipe(0); // Black background first
     sound.paint.bars(
       api,