From ad12bbe7adf585f7d5931021b968bd4d438e381d Mon Sep 17 00:00:00 2001
From: Mihai Ionescu <129006005+andududu@users.noreply.github.com>
Date: Mon, 21 Sep 2026 20:20:29 +0100
Subject: [PATCH 1/2] Jeview calls itself a visualizer, and says it is not
 affiliated with TypeSafe AI

- "A local middleman" said how Jeview works, not what it is for. It is a
  visualizer: the README, llms.txt, the viewer's own explanation and the
  package now say so, and go on to explain that it sits between your code
  and TypeSafe, which is still how you use it.
- The README and AGENTS.md say in so many words that Jeview is not
  affiliated with TypeSafe AI.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 AGENTS.md     | 3 ++-
 README.md     | 4 ++--
 jeview.ts     | 2 +-
 llms.txt      | 2 +-
 package.json  | 2 +-
 src/jeview.ts | 4 ++--
 ui/index.html | 2 +-
 7 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b599384..bbd1456 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,7 @@
 # Working on Jeview
 
-Jeview is a local gateway for Jev (TypeSafe System One) with a live viewer. To *use* a running Jeview, read
+Jeview is a local visualizer for Jev (TypeSafe System One): a gateway your code sends its calls through, with a live
+viewer. It is unofficial, and not affiliated with TypeSafe AI. To *use* a running Jeview, read
 [llms.txt](llms.txt), or `/llms.txt` on the Jeview itself. This file is for changing the code.
 
 ## The lie of the land
diff --git a/README.md b/README.md
index b83e152..5e15103 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,8 @@
 
 > Agents: [llms.txt](llms.txt) says how to use a running Jeview, and [AGENTS.md](AGENTS.md) how to work on this repository.
 
-An unofficial local middleman for Jev ([TypeSafe](https://typesafe.ai) System One), with a live view of every call.
-Jeview is an independent project: it is not made or endorsed by TypeSafe.
+An unofficial local visualizer for Jev ([TypeSafe](https://typesafe.ai) System One): a live view of every call your code
+makes. Jeview is an independent project. It is not affiliated with TypeSafe AI, nor made or endorsed by it.
 
 ```
 your code  →  Jeview (127.0.0.1:4777)  →  TypeSafe (api.typesafe.ai)
diff --git a/jeview.ts b/jeview.ts
index 903e298..1453168 100644
--- a/jeview.ts
+++ b/jeview.ts
@@ -1,4 +1,4 @@
-// Jeview: a local middleman for Jev with a live view of every call (README.md).
+// Jeview: a local visualizer for Jev, with a live view of every call (README.md).
 //   node jeview.ts [--port 4777] [--dir ~/.local/share/jeview]
 // Open http://127.0.0.1:4777/, add your Jev key (the key icon), and send Jev requests to http://127.0.0.1:4777/v1/systemone
 // (or /<label>/v1/systemone) instead of https://api.typesafe.ai/v1/systemone. --jev-endpoint points it at a local mock.
diff --git a/llms.txt b/llms.txt
index f50fd6b..44a0ca8 100644
--- a/llms.txt
+++ b/llms.txt
@@ -1,6 +1,6 @@
 # Jeview
 
-A local middleman for Jev (TypeSafe System One) at http://127.0.0.1:4777, with a live view of every call at http://127.0.0.1:4777/
+An unofficial local visualizer for Jev (TypeSafe System One) at http://127.0.0.1:4777, with a live view of every call at http://127.0.0.1:4777/
 It is a gateway, not a model: it sits between a Jev client and TypeSafe and answers nothing itself. Each request it
 receives goes on to Jev with the Jev key set in the viewer, Jev's answer goes back to the caller, and the call is kept
 whole (what was asked, what Jev saw, what it answered) in a SQLite database on this machine. Nothing is stored anywhere
diff --git a/package.json b/package.json
index 9a618df..8ba695c 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
   "name": "jeview",
   "version": "0.1.0",
   "private": true,
-  "description": "An unofficial local middleman for Jev (TypeSafe), with a live view of every call.",
+  "description": "An unofficial local visualizer for Jev (TypeSafe), with a live view of every call.",
   "license": "MIT",
   "repository": { "type": "git", "url": "git+https://github.com/andududu/jeview.git" },
   "type": "module",
diff --git a/src/jeview.ts b/src/jeview.ts
index a6e8c30..6933e17 100644
--- a/src/jeview.ts
+++ b/src/jeview.ts
@@ -1,4 +1,4 @@
-// Jeview: a local middleman for Jev with a live view of every call (README.md). A client sends its Jev requests
+// Jeview: a local visualizer for Jev, with a live view of every call (README.md). A client sends its Jev requests
 // here exactly as it would to TypeSafe (POST /v1/systemone, or /<label>/v1/systemone to group requests); the proxy
 // calls Jev with the key set in the viewer (without a key, calls are refused), answers the client with
 // Jev's answer, and keeps each call whole in a private SQLite database. Loopback only: calls can hold private data.
@@ -201,7 +201,7 @@ function keyChange(req: IncomingMessage, body: Buffer): string | null {
 export function llmsText(origin: string, keyed: boolean): string {
   return `# Jeview
 
-A local middleman for Jev (TypeSafe System One) at ${origin}, with a live view of every call at ${origin}/
+An unofficial local visualizer for Jev (TypeSafe System One) at ${origin}, with a live view of every call at ${origin}/
 It is a gateway, not a model: it sits between a Jev client and TypeSafe and answers nothing itself. Each request it
 receives goes on to Jev with the Jev key set in the viewer, Jev's answer goes back to the caller, and the call is kept
 whole (what was asked, what Jev saw, what it answered) in a SQLite database on this machine. Nothing is stored anywhere
diff --git a/ui/index.html b/ui/index.html
index 8e8afe1..32d9e35 100644
--- a/ui/index.html
+++ b/ui/index.html
@@ -33,7 +33,7 @@
 
 <div id="about-panel" class="popover" hidden>
   <p class="eyebrow">What Jeview is</p>
-  <p class="quiet">A middleman between your code and Jev. Your requests come here instead of going to TypeSafe; Jeview sends each one on with your key, hands Jev's answer back, and keeps a copy to show you. It answers nothing itself.</p>
+  <p class="quiet">A visualizer for Jev that sits between your code and TypeSafe. Your requests come here instead of going to TypeSafe; Jeview sends each one on with your key, hands Jev's answer back, and keeps a copy to show you. It answers nothing itself.</p>
   <p class="eyebrow">Send Jev requests here</p>
   <p class="line"><code id="run-line">http://127.0.0.1:4777/v1/systemone</code><button class="ghost small" data-copy="run-line">Copy</button></p>
   <p class="quiet">The same requests and answers as TypeSafe's address, with no key needed. To group requests under a project or label, add it to the path: <code>/&lt;label&gt;/v1/systemone</code>.</p>

From 35e6f07ddb1799542f5188298ce376b2ae06e1f7 Mon Sep 17 00:00:00 2001
From: Mihai Ionescu <129006005+andududu@users.noreply.github.com>
Date: Mon, 21 Sep 2026 20:23:33 +0100
Subject: [PATCH 2/2] A port that is taken says so in a sentence

Starting Jeview, or either demo, on a port already in use ended in a Node
stack trace. The likeliest cause is one already running, so each now says
that in a sentence, with where to open it and the flag that starts this one
on another port.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 demo/pixel-knight.ts | 1 +
 demo/support-desk.ts | 1 +
 jeview.ts            | 2 ++
 3 files changed, 4 insertions(+)

diff --git a/demo/pixel-knight.ts b/demo/pixel-knight.ts
index 4935ff9..ef1e416 100644
--- a/demo/pixel-knight.ts
+++ b/demo/pixel-knight.ts
@@ -309,6 +309,7 @@ const server = createServer((req, res) => {
   }
   res.writeHead(404).end();
 });
+server.on("error", (error: NodeJS.ErrnoException) => { console.error(error.code === "EADDRINUSE" ? `Port ${port} is already in use. If Pixel Knight is already running, open http://127.0.0.1:${port}/; otherwise start this one on another port: --port ${port + 1}` : `Pixel Knight could not start: ${error.message}`); process.exit(1); });
 server.listen(port, "127.0.0.1", () => console.log(`Pixel Knight: open http://127.0.0.1:${port}/ to watch Jev play (through ${url}). Ctrl-C stops it.`));
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
diff --git a/demo/support-desk.ts b/demo/support-desk.ts
index 0d2259d..a10f675 100644
--- a/demo/support-desk.ts
+++ b/demo/support-desk.ts
@@ -156,6 +156,7 @@ const server = createServer((req, res) => {
   }
   res.writeHead(404).end();
 });
+server.on("error", (error: NodeJS.ErrnoException) => { console.error(error.code === "EADDRINUSE" ? `Port ${port} is already in use. If Support Desk is already running, open http://127.0.0.1:${port}/; otherwise start this one on another port: --port ${port + 1}` : `Support Desk could not start: ${error.message}`); process.exit(1); });
 server.listen(port, "127.0.0.1", () => console.log(`Support Desk: open http://127.0.0.1:${port}/ to watch Jev triage the inbox (through ${url}). Ctrl-C stops it.`));
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
diff --git a/jeview.ts b/jeview.ts
index 1453168..43a2c4e 100644
--- a/jeview.ts
+++ b/jeview.ts
@@ -12,4 +12,6 @@ const port = Number(values.port);
 if (!Number.isInteger(port) || port < 1 || port > 65535) throw Error("Usage: node jeview.ts [--port 4777] [--dir ~/.local/share/jeview] [--jev-endpoint URL]");
 const { server, store } = createJeview({ dir: values.dir, port, ...(values["jev-endpoint"] ? { jevEndpoint: values["jev-endpoint"] } : {}) });
 for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => { server.close(); process.exit(0); });
+// a port that is taken, most often by a Jeview already running, is said in a sentence
+server.on("error", (error: NodeJS.ErrnoException) => { console.error(error.code === "EADDRINUSE" ? `Port ${port} is already in use. If Jeview is already running, open http://127.0.0.1:${port}/; otherwise start this one on another port: --port ${port + 1}` : `Jeview could not start: ${error.message}`); process.exit(1); });
 server.listen(port, "127.0.0.1", () => console.log(JSON.stringify({ viewer: `http://127.0.0.1:${port}/`, send_jev_requests_to: `http://127.0.0.1:${port}/v1/systemone`, jev_key: store.setting("jevKey") ? "set" : "not set: add it in the viewer (the key icon, top right)", database: store.database, recorded: store.count() })));