From 5f83cd67ea599fab3357cab0c65d31da9dc70a4f Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Tue, 16 Jun 2026 14:47:44 -0400
Subject: [PATCH] feat(sideshow-term): add clear command

---
 CHANGELOG.md                                |  2 ++
 sideshow-term/README.md                     |  1 +
 sideshow-term/bin/sideshow-term.js          | 33 +++++++++++++++++++++
 sideshow-term/guide/AGENT_SETUP.md          |  4 +++
 sideshow-term/skills/sideshow-term/SKILL.md |  4 +++
 5 files changed, 44 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 97346ad..5b32e73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ All notable user-visible changes to this project are documented in this file.
   and bare `sideshow-term` opens the watcher. Terminal servers default to port
   4243, with `--port` for choosing another local port. The watcher supports
   mouse input for clicking sidebar snippets and wheel-scrolling content.
+  Agents can run `sideshow-term clear` to remove stale visualizations from the
+  current session, or `sideshow-term clear --all` to clear the whole surface.
   `sideshow-term serve` remains for explicit server-only use.
 - Snippets are now "surfaces" throughout the API: `/api/surfaces`, `surface-*`
   SSE events, and comments keyed by `surfaceId`. The old snippet endpoints and
diff --git a/sideshow-term/README.md b/sideshow-term/README.md
index 41c68a1..2227b61 100644
--- a/sideshow-term/README.md
+++ b/sideshow-term/README.md
@@ -67,6 +67,7 @@ sideshow-term render <file|-> [--width N]   preview STML to plain text (Bun)
 sideshow-term publish <file|-> [--title …]  publish an STML snippet
 sideshow-term update <id> <file|->          revise a snippet (new version)
 sideshow-term list / sessions               inspect what's published
+sideshow-term clear [--session id|--all]    clear existing visualizations
 sideshow-term demo                          seed an example session
 sideshow-term guide / setup                 print the agent contract
 ```
diff --git a/sideshow-term/bin/sideshow-term.js b/sideshow-term/bin/sideshow-term.js
index ccf5fec..cab0615 100644
--- a/sideshow-term/bin/sideshow-term.js
+++ b/sideshow-term/bin/sideshow-term.js
@@ -43,6 +43,8 @@ usage:
   sideshow-term update <id> <file|->      revise a snippet (new version)
       --title <t>            replace title
   sideshow-term list [--session <id>|--all]   list snippets
+  sideshow-term clear [--session <id>|--all] [--sessions]
+                                      clear existing visualizations
   sideshow-term sessions                  list sessions
   sideshow-term comment <text> [opts]     post a comment
       --snippet <id> | --session <id>
@@ -375,6 +377,37 @@ const commands = {
     out(await api(`/api/sessions/${session}/snippets`));
   },
 
+  async clear() {
+    const { values: flags } = parse({
+      options: {
+        session: { type: "string" },
+        all: { type: "boolean" },
+        sessions: { type: "boolean" },
+      },
+    });
+    if (flags.all && flags.session) fail("pass either --session or --all, not both");
+    const sessionIds = flags.all
+      ? (await api("/api/sessions")).map((session) => session.id)
+      : [flags.session ?? (await resolveSession(flags))].filter(Boolean);
+    if (sessionIds.length === 0) fail("no active session — pass --session or --all");
+
+    let visualizations = 0;
+    let deletedSessions = 0;
+    for (const session of sessionIds) {
+      const snippets = await api(`/api/sessions/${session}/snippets`);
+      for (const snippet of snippets) {
+        await api(`/api/snippets/${snippet.id}`, { method: "DELETE" });
+        visualizations += 1;
+      }
+      if (flags.sessions) {
+        await api(`/api/sessions/${session}`, { method: "DELETE" });
+        deletedSessions += 1;
+      }
+    }
+
+    out({ ok: true, sessions: sessionIds.length, visualizations, deletedSessions });
+  },
+
   async sessions() {
     parse();
     out(await api("/api/sessions"));
diff --git a/sideshow-term/guide/AGENT_SETUP.md b/sideshow-term/guide/AGENT_SETUP.md
index 5fa3336..ab3e8b6 100644
--- a/sideshow-term/guide/AGENT_SETUP.md
+++ b/sideshow-term/guide/AGENT_SETUP.md
@@ -17,6 +17,10 @@ sideshow-term update <id> revised.stml
 
 # Preview in your own shell, no viewer needed:
 sideshow-term render sketch.stml
+
+# Clear stale visuals before replacing a board:
+sideshow-term clear           # current session
+sideshow-term clear --all     # every session on this surface
 ```
 
 If `sideshow-term` is not on PATH but you are in this repo, use
diff --git a/sideshow-term/skills/sideshow-term/SKILL.md b/sideshow-term/skills/sideshow-term/SKILL.md
index 36cd187..1e15fd4 100644
--- a/sideshow-term/skills/sideshow-term/SKILL.md
+++ b/sideshow-term/skills/sideshow-term/SKILL.md
@@ -38,6 +38,10 @@ Save the returned `sessionId` and snippet `id`. Iterate with
 publishing near-duplicates — versions are kept. Preview without the viewer:
 `sideshow-term render sketch.stml`.
 
+To remove stale visuals before replacing a board, run `sideshow-term clear` for
+the current session or `sideshow-term clear --all` for every session on the
+surface.
+
 Rules of thumb:
 
 - On your first publish, set a session title that names the task ("Auth