From 33aac0449f42e9e6791ade786c79720631dcfb1f Mon Sep 17 00:00:00 2001 From: Mihai Ionescu <129006005+andududu@users.noreply.github.com> Date: Mon, 21 Sep 2026 20:16:44 +0100 Subject: [PATCH] llms.txt and AGENTS.md are in the repository, where an agent reading it will find them - llms.txt was served only by a running Jeview, at a local address nobody reading the repository can open. The same text is now a file at its root, written by `npm run llms` from the code that serves it, and a test fails if the two ever differ. - AGENTS.md is for changing the code: where things are, how to check your work, and the rules that are easy to break without knowing them (no dependencies, only syntax Node can strip, the body byte for byte, the key never shown, loopback only, nothing else leaves the machine). - The README points at both from its first lines. Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 5 ++++- llms.txt | 45 +++++++++++++++++++++++++++++++++++++++++++ package.json | 3 ++- test/jeview.test.ts | 7 ++++++- 5 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md create mode 100644 llms.txt diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b599384 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Working on Jeview + +Jeview is a local gateway for Jev (TypeSafe System One) with a live viewer. 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 + +- `src/jeview.ts`: the whole server. The proxy, the SQLite store, the read API, and the text of llms.txt. +- `jeview.ts`: the command line. `launch.sh` finds a Node and runs it. +- `ui/`: the viewer, plain JavaScript with no build step, served from disk on every request. +- `demo/`: Pixel Knight and Support Desk, each a small server and a page. They play through a running Jeview. +- `test/jeview.test.ts`: every promise the server makes, against a stand-in for Jev. + +## Check your work + +```sh +npm install # only the type checker +npm run typecheck +npm run check:pages # the browser scripts parse +npm test +``` + +Tests never call TypeSafe. The demos do: every call is real and costs money, so do not run them in CI or leave them +running. They play only while a page is open. + +## Rules of the house + +- **No dependencies at run time.** Node 24 and its standard library are all Jeview needs. Keep it so. +- **Node runs the TypeScript as it is**, by stripping the types. Use only syntax that can be stripped: no enums, no + namespaces, no parameter properties. Imports name the file, `.ts` included. +- **The body goes to Jev byte for byte**, and Jev's answer comes back as sent, plus `events`. Jeview's own headers + (`Jeview-*`) never reach Jev. +- **The key is never shown**, logged or returned: only whether it is set, and its last four characters. +- **Loopback only.** Jeview answers to local host names, refuses requests from web pages on other sites, and has no + login. Each of these has a test; a change that needs one of them loosened is probably the wrong change. +- **Nothing leaves the machine but calls to Jev.** No telemetry, no fonts or scripts from elsewhere: the viewer's + content security policy allows only its own origin. +- **Pages are built from nodes and text**, never from HTML strings that carry data: recorded calls hold whatever a + caller sent. See `h()` in `ui/app.js`. +- **The viewer must work with an older server**, and the server with an older viewer's requests: the pages are read + from disk while an older process may still be running. +- After changing `llmsText`, run `npm run llms` to write `llms.txt` again. A test compares the two. + +## Writing + +Comments say why, in plain words, and only where the code cannot. Commit messages are one sentence about what +changed for the person using Jeview, then the details. Match the code around you: it is dense on purpose. diff --git a/README.md b/README.md index c250d83..b83e152 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Jeview +> 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. @@ -45,7 +47,8 @@ requests and the same answers, with no key needed from the caller. those answers, send its event id in a `Jeview-Trigger` header, and the map grows that request off the answer. Jeview drops its own headers before calling Jev and sends the body on unchanged. -Agents can read `http://127.0.0.1:4777/llms.txt`. +Agents can read `http://127.0.0.1:4777/llms.txt`: a running Jeview serves it with its own address and whether a key is +set. [llms.txt](llms.txt) here is the same text, for the default address. ## Options diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..f50fd6b --- /dev/null +++ b/llms.txt @@ -0,0 +1,45 @@ +# 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/ +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 +else: Jeview runs locally, and TypeSafe is the only place it sends anything. + +The Jev key: not set yet, so calls are refused. Set it in the viewer at http://127.0.0.1:4777/ (the key icon, top right). + +## Send Jev requests here + +Use http://127.0.0.1:4777/v1/systemone wherever you would use https://api.typesafe.ai/v1/systemone: the same body +{ model, state, questions }, the same answers. No key is needed from the caller. To group requests under a project or +label, add it to the path: http://127.0.0.1:4777/