notes

A personal linked-notes vault — markdown, [[wikilinks]], backlinks, tags, graph.

This is an app: the forge runs it. Production follows the default branch; every open pull gets a preview at its own address with its own copy of the data. Everything the app keeps lives under FORGE_APP_DATA, which is what makes "production data" and "preview data" two different things.

PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts   # run it here
bun test                                                # what `forge.json`'s app.test runs on every push
FORGE_APP_DATA=./data bun run src/tty.ts                # the terminal
FORGE_APP_DATA=./data bun run src/db.ts --check         # schema version, integrity
bun run lint:design                                     # no colour but the tokens'
bun run contract:emit                                   # rewrite contract/openapi.json from the routes

app.test in forge.json runs beside app.run in every deploy, not before it: the preview comes up the moment the app answers, and says live, or serving · tests failed the moment the suite disagrees.

The shape

One implementation, many doors. src/actions.ts is every operation as a plain function — (db, who, input) in, data or a named failure out — and the page, the JSON API, the MCP server and the terminal all call it and decide nothing themselves. AGENTS.md says how to add to it.

file	what it is
`src/actions.ts`	list, add, delete; the audit trail, read
`contract.json`	who may do what: roles, and the least role each verb needs
`src/contract.ts`, `src/can.ts`	the table, read at boot; the forge's evaluator, verbatim
`src/security.ts`	the door: rationing, same origin, the table before the body
`src/audit.ts`	every change and every refused one, as a row
`src/who.ts`	who is asking, from the forge's signed headers
`src/db.ts`	SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations
`src/live.ts`	the in-process bus and `GET /events`
`src/mcp.ts`	the actions as MCP tools at `POST /mcp`
`src/routes.ts`	every path, in one table, each API route described beside it
`src/openapi.ts`	the routes as OpenAPI; committed at `contract/openapi.json`
`src/page.ts`	the HTML, rendered on the server, with its share metadata
`design/tokens.json`, `src/tokens.ts`	the look as data, light and dark; compiled to `/tokens.css`
`src/http.ts`	the floor: headers, body cap, files
`src/server.ts`	boot: open the database, serve
`src/tty.ts`	the terminal, over the same actions
`src/env.ts`	what the forge told this process
`static/app.css`, `static/live.js`	the look in the tokens' words, and the list that stays current

What every app stands on

The door. Before a route sees a request, src/security.ts rations

writes (and a stranger's API calls), refuses a write from another site, and turns away — before the body is read — anyone the table lets through a resource's door for no row at all: 401 for a stranger, 403 for anyone else. The action still decides about the real row.

The audit trail. Every change, and every change refused, is a row:

who, which resource and verb, which row, when, and whether they were let. Admins read it at GET /api/audit. A row that cannot be written is a log line, never a failed request.

The API, described. GET /openapi.json is contract/openapi.json,

written from the routes by bun run contract:emit; each operation names its cell of the table (x-contract). bun test fails while it is stale.

Up, or not. GET /healthz answers { ok, version, uptime }; the

forge waits on it before it sends anyone to a deploy.

The look. design/tokens.json holds every colour, space and size,

light and dark; nothing else spells out a colour (bun run lint:design), and every pair a person reads meets 4.5:1 in both themes.

The open web. A shared link unfurls (description, Open Graph, a

card); /robots.txt keeps crawlers to the page, and out of previews entirely; /.well-known/security.txt sends a reporter to the forge that runs the app.

Who you are

The forge says who is asking on every request it proxies, and the app verifies the signature (src/who.ts); nothing else is trusted. Three tiers:

anon — anyone. Reads.
user — signed in to the forge and able to see this app. Adds notes, as

themselves, and removes their own.

admin — able to write this repository. Removes any note.

"Sign in" is /__forge/signin?to=<path> and "Sign out" is /__forge/signout; the forge answers both on the app's own host.

Any interface

The same actions, the same rules, at every door. A script is the person whose forge grant it carries; a bare script is anonymous.

curl https://<app>/api/notes
curl -X POST https://<app>/api/notes -H 'content-type: application/json' -d '{"body":"hi"}'
curl -X DELETE https://<app>/api/notes/1

As an MCP server, for Claude Code or Claude Desktop — list_notes, add_note, delete_note:

claude mcp add --transport http __TITLE__ https://<app>/mcp

{
  "mcpServers": { "__TITLE__": { "type": "http", "url": "https://<app>/mcp" } }
}

The page stays current over /events: a note someone else adds or removes appears without a reload. Without JavaScript it is the same page, one reload behind.

The terminal opens with the exact command in FORGE_APP_SSH when the app runs (ssh -p 2222 <name>@<forge> — the app is the login name, the forge the host; <name>--<pull>@<forge> for a preview's). It is src/tty.ts on a real pty over the same data, as the account at the keyboard.

The forge sets PORT, FORGE_APP_DATA, FORGE_APP_ENV (production or preview), FORGE_APP_URL, FORGE_APP_COMMIT, FORGE_APP_SSH and FORGE_APP_IDENTITY_KEY when it starts the app. forge.json says how.

benjivers/notes Public Public: anyone can read this; nobody can change it.

notes

The shape

What every app stands on

Who you are

Any interface

Keyboard shortcuts