golem-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0
+
+- `golem-kit/server` export and an `exports` map, so an app imports the backend by name instead of by path.
+- App backend: records, files and server-defined operations, documented in `docs/app-backend.md`.
+- App server code can call a model: `context.model.extract` takes free text and returns a schema-shaped value; the app chooses the model, and reads images too.
+- Durable scheduled and long-running app jobs, with their runs visible in the sample app.
+- Optional local accounts, groups and build access: invites, open sign-up, guests refused from `invoke`, signed-out and demoted pages cleared live.
+- App brain: a `brain/` Open Knowledge Format bundle served read-only, a Brain reader beside the app, and agent citations rendered as source chips.
+- Knowledge files and consented source views: sources offered from chat, opened only on consent, drafts kept across switching and closing, symlinked roots refused.
+- Ordinary chat: an API agent limited to the app's listed operations, configured apart from the builder.
+- Chat belongs to a role: `chat.roles` gates every chat route, and build keeps its own permission. No chat means no chat rights.
+- Tmux chat provider: one persistent agent session per app (`golem-<app>`), `golem say` to post back into it, `/reset`, and resume of legacy harness refs into `golem-<app>:builder`.
+- Normal-mode tmux chat runs read-only, with a launch profile per window replayed on resume.
+- Terminal popup in build mode: a live tmux pane stream, with keys going straight to the pane.
+- Browser shell bottom bar: the app / Brain / Admin in the menu row, Builder and theme in the gear; an app with more than one screen gets its own items.
+- Builder mode is app state, with a Shell toggle and an app-defined normal chat.
+- Build-mode chat: a Stop pill via `chat.interrupt`, and a one-row compact header at 320px chat width.
+- Build mode reloads the page only when the bundle changed, and paints the theme before the first frame.
+- Persistent dark mode toggle, and the framework's dark styles packaged.
+- Source mode covers the app's own code, not just the shell (`GOLEM_SOURCE`, `GOLEM_UI_SOURCE`).
+- Claude Code runs builds beside Codex; a new conversation picks its agent.
+- App server code reloads after build-mode rebuilds, and the last good module is kept when an edit is malformed.
+- Shared architecture lint (`golem-kit/eslint`, `./golem lint`) and an App DNA template in new apps.
+- New apps install `golem-ui` directly, pinned to the version golem-kit builds with.
+- Requires `golem-ui` 0.2.0.
+
+## 0.1.1
+
+First published release: the local CLI, the dev server, the browser shell and the Codex build session.

package/README.md

@@ -4,7 +4,7 @@
 
 ## What is Golem?
 
-Golem is an early local application shell for building applications with AI. **Your app is its own IDE:** enter build mode, ask a locally authenticated Codex to edit the app, and keep using it in the same browser shell.
+Golem is an early local application shell for building applications with AI. **Your app is its own IDE:** enter build mode, ask a locally authenticated Claude Code or Codex to edit the app, and keep using it in the same browser shell.
 
 ## Getting Started
 
@@ -22,20 +22,25 @@ Start the application:
 ./golem dev
 ```
 
-Open the browser address printed in the terminal, enter build mode, and start a conversation. Build chat requires the Codex CLI installed and authenticated on the same machine. After a successful build-mode change, the browser shell rebuilds and refreshes; conversations are saved in `.golem/` and restored when the server restarts.
+Open the browser address printed in the terminal, enter build mode, and start a conversation. Build chat requires the Claude Code or Codex CLI installed and signed in on the same machine; when both are ready, choose one before entering build mode. Each conversation keeps its agent; use **New conversation** to start another, possibly with the other agent, while earlier conversations stay saved. After a successful build-mode change, the browser shell rebuilds and refreshes; conversations are saved in `.golem/` and restored when the server restarts.
 
-`./golem build` writes the browser shell to `dist/`. `./golem dev` binds only to `127.0.0.1:3000`.
+`./golem build` writes the browser shell to `dist/`. `./golem dev` defaults to
+`127.0.0.1:3000`; set an optional `host` and `port` in `golem.config.ts`, then restart
+the dev server. The terminal prints the usable address.
+
+`./golem lint` checks the app's architecture boundaries; see
+[the architecture guide](docs/architecture.md) to adapt or disable them.
 
 ## Local source development
 
-Use an installed package by default, or opt into a durable checkout while developing Golem:
+Use an installed package by default, or put a durable checkout in the app's uncommitted `.env.local` while developing Golem:
 
 ```sh
-GOLEM_SOURCE=/path/to/golem ./golem dev
+GOLEM_SOURCE=/path/to/golem
 ```
 
 See [the local CLI guide](docs/local-cli.md) for the complete command contract.
 
 ## Current scope
 
-Claude integration, domain storage, accounts, and permissions are planned, not part of this release.
+Apps store records and files and define server operations as described in [the app backend guide](docs/app-backend.md). Builds run with Codex or Claude Code; see [the local CLI guide](docs/local-cli.md). An app can also offer ordinary chat: an assistant that uses the app's data as the person chatting, configured apart from the builder; see [the agents guide](docs/agents.md).

package/docs/agents.md

@@ -0,0 +1,64 @@
+# Agents
+
+A Golem app has two kinds of agent. They are configured separately and never share access.
+
+| | Builder | Ordinary chat |
+|---|---|---|
+| Purpose | Change the app's code | Use the app: find, read and change its data |
+| Who may start one | Anyone without accounts; with accounts, managers and the `builder` role | Anyone who may use the app |
+| Runs as | This computer's account (Codex or Claude Code CLI) | The person chatting, through the app's operations |
+| Can reach | The file system, like any terminal agent | Only the operations the app lists |
+| Credential | The CLI's own sign-in | `ANTHROPIC_API_KEY` in the server environment |
+
+## Configuration
+
+```ts
+// golem.config.ts
+export default {
+  title: 'Field Notes',
+  agents: {
+    builder: 'claude', // or 'codex': the agent build mode starts with
+    ordinary: {
+      backend: 'anthropic',
+      operations: ['records.list', 'records.get', 'records.update', 'notes.archive'],
+      collections: ['notes'],
+      instructions: 'Notes belong to field teams. Quote a note title before changing it.',
+    },
+  },
+}
+```
+
+- `builder` is the default choice in build mode. A person's own pick in the browser still wins and is remembered.
+- `ordinary` turns on the **Start a chat** button. Leave it out and there is no ordinary chat.
+- `ordinary.model` defaults to `claude-opus-5`.
+- `golem.config.ts` is bundled into the browser. Keep the API key in `.env.local` or the server environment, never in this file.
+
+## What ordinary chat enforces
+
+- **Operations**: the agent gets a tool for each listed operation and nothing else. It cannot build, run commands, read files, or enter build mode. A message cannot add a tool.
+- **Permissions**: each tool call goes through the same `authorize` as a browser call, as the person who sent the message, refreshed on every call. A call the person may not make fails with the same `Not allowed: <operation>` error the app's own UI would get. Signing out stops a running turn.
+- **Collections and roots**: with `collections`, the built-in `records.*` operations refuse any other collection; with `roots`, the `knowledge.*` operations and source offers refuse any other knowledge root. Custom operations are limited only by being listed and by `authorize`; `collections` does not confine what their code touches.
+- **Refused**: a terminal backend (`'codex'` or `'claude'`) for ordinary chat, because its file access cannot be limited to the listed operations. Also `files.upload` and `files.read`, which carry file bytes, and operations whose tool names would be invalid or the same (`a.b` and `a__b` both become `a__b`). Golem stops at startup instead of ignoring the setting.
+
+## Showing sources
+
+With knowledge roots (see `knowledge.md`) and `view.actions` and `view.request` listed in `operations`, the assistant can offer to open a knowledge file at a passage. The offer appears under the chat in the tab the message came from, with **Open** and **Dismiss**. Nothing opens until the person chooses **Open**; then that tab alone shows the file in the Editor, headed by its path and the passage's line numbers. Other tabs on the same sign-in are not moved.
+
+- **Marking the passage needs a newer golem-ui.** The shell hands the Editor the passage through its `focus` prop: the lines, the file version they were counted in, and their text. The Editor waits until it has that version or a later one and no conflict is open. It then marks the passage where that exact text appears once in what it shows, so unsaved edits above it are allowed for. It marks nothing when the text is missing or appears twice, and it never changes the draft. The released golem-ui 0.1.1 has no `focus`: the file opens at the top, and the header's saved line numbers are the only pointer. To get the mark before a release, run against a golem-ui checkout that has it, with `GOLEM_UI_SOURCE` (see `source-development.md`).
+- **Edits are kept.** Opened sources share one Editor for the life of the page. Opening another source parks the current one's unsaved draft or open conflict in the Editor without writing it, and opening it again restores it. **Back to app** hides the Editor, and **Show** under the chat brings it back as it was. A header note names any other source with unsaved edits. Leaving or reloading the page while a source has unsaved edits, a save in flight or an open conflict asks the browser to confirm first.
+
+## Conversations
+
+- An ordinary chat belongs to the account that started it, or, for a signed-out visitor where the app allows guests, to that browser (an opaque `HttpOnly` cookie). Nobody else can read or continue it, managers included.
+- Chats are saved in `.golem/` with the model's context, tool results included, and restored after a restart. Nothing runs again by itself: a turn cut off by a restart or **Interrupt** stays stopped, and a tool call whose outcome is unknown is reported to the model as unknown.
+- **Interrupt** during a tool call lets that call finish; the model is not called again for that turn.
+- Provider failures appear in the chat as a plain message. They never include the key.
+
+## Provider
+
+Ordinary chat calls the Anthropic Messages API through `@anthropic-ai/sdk` with a manual tool loop: each listed operation is a client tool (`.` becomes `__`, since tool names must match `^[a-zA-Z0-9_-]{1,128}$`), and each call is answered with a `tool_result`, marked `is_error` when the operation refuses.
+
+- Tool use: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview and https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
+- Models (`claude-opus-5`): https://platform.claude.com/docs/en/about-claude/models/overview
+
+The tests run against a scripted stand-in for this API, `test/fixtures/messages-api.mjs`; point `ANTHROPIC_BASE_URL` at it to try chat without a key.

package/docs/app-backend.md

@@ -0,0 +1,259 @@
+# App backend
+
+Golem serves an app's records, files and operations from the same local server as the browser shell.
+Records are plain JSON values; the store adds `id`, `version`, `createdAt` and `updatedAt`.
+Business rules stay in the app; this package supplies storage, the operation boundary and the browser binding.
+
+## Where code lives
+
+| Path | Runs in | Imports |
+| --- | --- | --- |
+| `src/app.tsx` and other UI files | browser | `golem-ui`, `golem-kit/client`, `src/shared/` |
+| `src/shared/` | both | plain types and values only |
+| `src/server/index.ts` | server | `golem-kit/server`, `src/shared/`, `src/server/**` |
+| `src/server/persistence/` | server | the only place for backend-specific code (`records.native`) |
+
+UI code reaches data only through `golem-kit/client`. Secrets come from `process.env` (loaded from `.env.local`) inside `src/server/`; `golem.config.ts` is bundled into the browser, so it holds no secrets.
+
+## Configuration
+
+`golem.config.ts` keeps `title`, `host` and `port` and adds one optional field:
+
+```ts
+export default { title: 'Field Notes', storage: 'sqlite' } // 'jsonl' (default) or 'sqlite'
+```
+
+Data lives under `.golem/data/`: `records/<collection>.jsonl` or `records.sqlite`, plus `files/<id>`. Switching `storage` starts from an empty store; there is no migration between the two.
+
+- **jsonl**: one append-only log per collection, fsynced per write and compacted on load. A torn final line from a crash is dropped. One server process per app.
+- **sqlite**: one `records` table of JSON documents through the built-in `node:sqlite`, queried with `json_extract`. `records.native` is the open `DatabaseSync` for real SQL in `src/server/persistence/`.
+
+## Browser binding: `golem-kit/client`
+
+```ts
+import { files, invoke, records } from 'golem-kit/client'
+<RecordList config={...} adapters={{ records }} />
+<Upload config={{ folder: 'attachments' }} adapters={{ files }} />
+const result = await invoke<{ message: string }>('notes.archive', { id })
+```
+
+`records` and `files` implement the golem-ui `RecordsAdapter` and `FilesAdapter`. A stale `update` (one with `expectedVersion`) rejects with golem-ui's `VersionConflictError`, which carries the current row. The released golem-ui 0.1.1 `RecordForm` sends only the changed fields and no `expectedVersion`, so the last save wins; call `records.update` with `expectedVersion` yourself where that matters. The next golem-ui `RecordForm` sends the loaded record's `version` as `expectedVersion` and lets the person choose between their values and the saved ones; until it is released, use it through `GOLEM_UI_SOURCE` (see `source-development.md`). `subscribe` listens to the server's change stream, so writes from any caller, the agent included, refresh open lists.
+
+## Server module: `src/server/index.ts`
+
+Optional. When the file exists it must default-export an `AppServerModule`:
+
+```ts
+import { defineOperation, z, type AppServerModule } from 'golem-kit/server'
+
+export const archive = defineOperation({
+  name: 'notes.archive',
+  description: 'Archive one note so it leaves the active list.',
+  input: z.object({ id: z.string() }),
+  output: z.object({ id: z.string(), version: z.number() }),
+  record: (input) => ({ collection: 'notes', id: input.id }),
+  async run(input, { records }) {
+    const note = await records.update('notes', input.id, { archived: true })
+    return { id: note.id, version: note.version }
+  },
+})
+
+export default {
+  operations: [archive],
+  authorize: ({ operation, record }) => !(record?.locked === true && operation !== 'records.get'),
+} satisfies AppServerModule
+```
+
+Exact signatures (source: `src/operations.ts`, `src/backend/app.ts`):
+
+```ts
+type AppServerModule = {
+  operations?: Operation[]
+  jobs?: JobDefinition[]   // see Jobs
+  authorize?: (request: AuthorizeRequest) => boolean | Promise<boolean>
+  resolvePrincipal?: (request: IncomingMessage) => Principal | Promise<Principal>
+}
+type AuthorizeRequest = { operation: string; input: unknown; principal: Principal; via: 'http' | 'agent' | 'server'; record: Row | null }
+type Principal = { kind: 'anonymous' } | { kind: 'user'; id: string; name: string; roles: string[]; groups: string[]; session?: string }
+type OperationContext = { principal; via; records: RecordStore; files: FileStore; model: Model; permits(record: Row): Promise<boolean>; job?: JobContext }
+type Model = { extract<S extends z.ZodType>(request: { schema: S; text: string; instructions?: string; images?: string[] }): Promise<z.output<S>> }
+```
+
+- **One invoke path.** HTTP (`POST /api/app/operations/<name>`), the raw file routes and in-process agent tools (`app.agentTools(principal)`) all call the same `invoke`: validate input, load the `record` the operation names, `authorize`, run, validate output.
+- **Principal** comes from the server, never from request input: local accounts when `accounts` is configured (see below), else `resolvePrincipal`. Without either, every caller is `anonymous` and `authorize` defaults to allowing everything: the local single-person mode existing apps run in.
+- **authorize** runs once per call with the target `record` (or `null`), and again per row for `records.list` and `files.list`, where `false` hides the row. App operations that return lists filter with `context.permits(row)`; `context.records` and `context.files` are unfiltered.
+- **Builtin operations** back the adapters and go through the same hook: `records.list|get|create|update|remove`, `files.list|upload|read|caption|remove`. File metadata lives in the internal `_files` collection, so `authorize` sees it as `record` for file reads and writes.
+
+## Calling a model
+
+`context.model.extract` turns free text into a value one of the app's own schemas accepts:
+
+```ts
+const meeting = await model.extract({ schema: z.object({ date: z.string(), attendees: z.array(z.string()) }), text, instructions: 'Leave a field empty rather than guessing.' })
+```
+
+The app names the shape it wants and never which model answered. Today that is the local Claude
+Code CLI — the runtime build mode already depends on, and the one that asks for no API key; the prompt
+goes in on stdin and the call runs in a temporary directory, so neither `ps` nor the app's folder
+is part of it. When no model can answer — the runtime is missing, times out, or gives nothing the
+schema accepts — it throws `ModelUnavailableError`. Catch it and store the failure as a state of
+the record: the text a person sent is worth keeping whether or not the structure came back.
+
+Photos go in next to the text as `images: string[]` — absolute paths on the server's disk, up to
+10, read by the runtime itself and never copied. A runtime that reads no images throws
+`ModelUnavailableError`; a path that is missing, unreadable or not absolute is `InvalidError`.
+
+## Knowledge files
+
+Markdown the app keeps in its own folders, committed to Git with the code. Opt in from `src/server/index.ts`; only trusted server code names the folders:
+
+```ts
+export default {
+  knowledge: { handbook: 'knowledge' }, // root name → directory inside the app
+  authorize: ({ operation, principal, record }) =>
+    !operation.startsWith('knowledge.') || !record?.path?.startsWith('staff/') || principal.groups.includes('staff'),
+} satisfies AppServerModule
+```
+
+That adds four operations on the usual invoke path. `authorize` sees `record = { id: '<root>/<path>', root, path }` on every call, including for a file not created yet, and again per file for `list` and `search`, where `false` hides it.
+
+| Operation | Input | Result |
+| --- | --- | --- |
+| `knowledge.list` | `{ root, folder? }` | `{ rows: [{ id: path, path, title, type, version }] }` |
+| `knowledge.search` | `{ root, text, limit? }` | `[{ path, line, text }]`, lines are 1-based |
+| `knowledge.read` | `{ root, path }` | `{ id: path, root, path, body, version, sha256, type, title }` |
+| `knowledge.write` | `{ root, path, body, expectedVersion }` | the file as read; `expectedVersion: 0` creates |
+
+- **Paths** are relative `.md` paths. `..`, hidden segments, absolute paths and backslashes are refused. Nothing between the app root and a file may be a symlink, the configured root included, and a file with a second hard link is refused, so each file has exactly one path. File text is data for the reader and the agent, never instructions to Golem.
+- **Versions**: `version` counts the contents Golem has seen, kept in the internal `_knowledge` collection. An edit made on disk shows up as a new version on the next read or save. A write sent with an older version is refused with `VersionConflictError` carrying the current file, so nothing is overwritten.
+- **Limit**: Golem's own writes are serialized per file and the disk bytes are compared again right before an atomic rename. An editor outside Golem is not locked: a save from it that lands in that last instant is overwritten. One server process per app.
+- `type` and `title` come from the file's frontmatter (see [the knowledge recipe](knowledge.md)); `title` falls back to the first `#` heading, then the file name.
+
+In the browser, `knowledge` from `golem-kit/client` is a golem-ui `RecordsAdapter`: `collection` is the root name, `id` the path, `body` the text. Use it with `Editor` (versioned saves; a conflicting save is merged line by line) and with `RecordList` for navigation:
+
+```tsx
+<Editor config={{ collection: 'handbook', id: 'guides/opening.md' }} adapters={{ records: knowledge, clock }} />
+```
+
+## Showing a source in the person's view
+
+An agent can offer to open a knowledge file with a passage highlighted. The person accepts or dismisses the offer; nothing moves until they accept, and only the view where they accepted moves.
+
+- **Conversations** belong to the agent runtime. It installs `app.views.useConversations({ owner(request, principal), owns(conversation, owner) })`: `owner` derives a trusted key from the real request and its server-resolved principal (an account id, or a key for the runtime's own browser cookie, which is how anonymous visitors are told apart), `null` to refuse; `owns` says whether that key owns the conversation. Until they are installed, no view opens and no offer is made.
+- **View**: each browser tab showing a conversation calls `openView(conversation, listener)` from `golem-kit/client`. The server issues an unguessable view id bound to the tab's principal and sign-in session, its owner key and that conversation. Every later call on the view checks all three again.
+- **Message**: before accepting a chat message that names a view, the runtime calls `app.views.bound(view, { principal, owner, conversation })` and refuses the message when it is `false`.
+- **Offer**: the runtime builds the agent's tools with `app.agentTools(principal, { owner, conversation, view })`, `view` being the one the message came from. With knowledge configured, this adds `view.actions` (the catalog, no data) and `view.request { action: 'source.open', input: { root, path, quote? | line?, endLine? } }`; the same call is `app.views.request({ principal, owner, conversation, view }, action, input)`. The server reads the file as the principal first; a denied or missing file refuses with the same `Cannot open that source`. The offer `{ id, conversation, input: { root, path, line, endLine } }` goes to that one view. Without `view` it is only returned (`delivered: false`) for the chat to show.
+- **Answer**: `answer(offer, true)` from the view checks the person and the file again, then sends `apply` to that view only. If the file changed since the offer, the offered lines are found again where they now are; if they are gone, the answer fails with `VersionConflictError` and the agent has to offer again. Consent is per offer; an unanswered offer expires after ten minutes, and a closed tab's view is dropped. Render the file with `Editor` and move to `line`–`endLine`. `apply` carries the file `version` those lines were counted in and their `text`. Accepting may be what notices a change on disk, so give `Editor` the `focus` once the file it shows has that version, or the passage is marked in the text it is about to replace. When the person has unsaved edits the lines on screen differ from the file's: find `text` in the draft and focus there, or open without a mark when it is not there.
+
+## Accounts
+
+Optional local accounts: email and password, server sessions, roles and groups. Without `accounts` in `golem.config.ts` the app stays anonymous and nobody signs in.
+
+```ts
+export default {
+  title: 'Field Notes',
+  accounts: {
+    guests: false,       // default: signed-out visitors see only the sign-in screen
+    allowSignUp: false,  // default: people join through invite links
+    roles: [             // golem-ui Auth roles; ids are unique
+      { id: 'member', label: 'Member' },
+      { id: 'builder', label: 'Builder' },
+      { id: 'admin', label: 'Admin', manages: true },
+    ],
+  },
+  origin: 'https://notes.example.test', // only when served behind a proxy or HTTPS; see below
+}
+```
+
+The roles above are the default. A role with `manages: true` may invite, change roles and groups, remove members, and build. The `builder` role may build. Every other role is for the app's own `authorize`. At least one role must manage, and the last member holding one cannot be demoted or removed. An invite carries its role. A sign-up without one (`allowSignUp: true`) gets the first role that neither manages nor is `builder`, whatever the order.
+
+- **guests: false**: `invoke` refuses `anonymous` with `UnauthorizedError` on every path (HTTP, agent tools, server code). Signed-out `/api/app/*` calls, the change stream included, answer 401, and the shell shows golem-ui's sign-in screen.
+- **guests: true**: signed-out callers run as `anonymous` through `authorize`. The default `authorize` allows everything, so write one that refuses what guests may not do.
+- **Policy** stays in `authorize`: check `principal.roles`, `principal.groups` and `record`. Without an `authorize`, every signed-in member may do everything.
+- **Build mode** needs a signed-in member who may build; `/api/runtime` and every `/api/sessions` route answer 401 or 403 to anyone else. A build conversation belongs to the member who started it. Conversations saved before accounts were enabled are visible to managers only. Losing build access, or signing out everywhere, interrupts a running build turn.
+- **Managing**: managers get a Admin item in the shell menu row: golem-ui's member list for invites, roles and removal, plus a groups editor. Apps can use `identity` and `setGroups` from `golem-kit/client`.
+- **Identity in the UI**: `identity` from `golem-kit/client` is golem-ui's `IdentityAdapter`. Pass it to `Auth.Guard` or `Timeline`. It exposes nothing a server rule trusts.
+
+### First admin and recovery
+
+When the store has no account yet, `./golem dev` prints a one-use admin invite link that expires in 24 hours. Open it and sign up. There are no default credentials. A running app never creates another admin link by itself. If every admin is locked out, stop the server and run `GOLEM_ADMIN_INVITE=1 ./golem dev`. It prints a fresh admin invite link to the terminal only. Anyone who can start the server already owns `.golem/data`.
+
+### Agents and jobs
+
+- `app.agentTools(principal)` refreshes the principal before every call. A principal with a `session` works only while that browser session is live; after sign-out its calls fail with `UnauthorizedError` and never fall back to anonymous.
+- Server-owned work that acts for a person (a job; see [Jobs](#jobs)) stores the account id and calls `app.resolveAccount(id)` on every run. It gets the current roles and groups, no session, and `ForbiddenError` once the account is removed. Nothing a browser sends becomes a principal.
+
+### Security boundary
+
+- Passwords are hashed with Node's scrypt and a random salt.
+- The session cookie is a random 256-bit token. It is `HttpOnly` and `SameSite=Lax`, is `Secure` when `origin` is https, and expires after 14 days. The server stores only its SHA-256 in the reserved `_sessions` collection. Sign-out and member removal delete it.
+- Accounts, sessions and invites live in reserved `_` collections. The records operations refuse those collections, and the change stream never names them.
+- Five failed sign-ins lock that email, and separately that client address, for 15 minutes.
+- Browser writes must come from this origin. Without `origin`, the `Origin` header must match the `Host` header. Behind a proxy, set `origin` to the public origin; then it is the only one accepted. Forwarding headers such as `X-Forwarded-For` are never read, so behind a proxy the per-address lockout counts the proxy's address.
+- This protects one app's data between people who use it. It is not a hosted identity provider: there is no email verification, password reset (a manager removes and re-invites), external sign-in or two-factor. Server code and anyone with the data directory can read everything.
+
+## Jobs
+
+Optional server-side work that keeps running when the browser closes: one run now, or on a schedule. The app owns each job; a caller picks a job and its input, never the operation or who it acts for.
+
+```ts
+// src/server/index.ts
+export default {
+  operations: [generate],
+  jobs: [{ name: 'sample-notes', description: 'Write a batch of sample notes.', operation: 'notes.generate' }],
+} satisfies AppServerModule
+```
+
+```ts
+type JobDefinition = {
+  name: string
+  description: string
+  operation: string          // a registered app operation
+  anonymous?: boolean        // guests may start it when the app has accounts; runs act as anonymous
+  missed?: 'skip' | 'once'   // default 'skip'
+}
+```
+
+From the browser, `jobs` in `golem-kit/client` wraps the builtin operations: `jobs.start(job, input)`, `jobs.schedule(job, { every: seconds } | { cron, timezone }, input)`, `jobs.unschedule(id)`, `jobs.runs({ job?, scheduleId?, limit? })`, `jobs.cancel(id)`, `jobs.resolve(id, 'retry' | 'dismiss')`, `jobs.list()` and `jobs.subscribe(listener)`. Each is an ordinary operation (`jobs.start` and so on), so it goes through `authorize`. For `jobs.cancel`, `jobs.resolve` and `jobs.unschedule`, `authorize` also gets the run or schedule as `record`.
+
+- **Who a run acts for.** A signed-in caller's account id is stored with the run or schedule. Every run calls `app.resolveAccount(id)`, so it gets that account's current roles and groups and needs no live session. Then it calls the operation through `invoke` with `via: 'server'`. If the account was removed or lost a role, the run fails with that error. Anonymous callers run as `anonymous`. In an app with accounts, they need `anonymous: true` on the job and `guests: true`.
+- **Visibility.** People see, cancel and settle only their own runs and schedules, and `authorize` can narrow that further. Run state lives in the reserved `_job_runs` and `_job_schedules` collections, which `records.*` refuse. The change stream names only `_jobs`.
+- **Operation context.** A run passes `context.job = { runId, key, signal, progress }` to the operation. Call `await job.progress({ done, total, message })` to report progress. `key` stays the same across an explicit retry and is unique for each scheduled slot, and it is a valid record id. Write with ids derived from it (`${key}-${index}`) so a retry skips work already done. Golem makes no exactly-once promise.
+- **Cancel** aborts `job.signal`, and nothing more. The run stays `running`, with `cancelRequested`, until the operation returns or throws. Pass the signal on (`fetch`, `timers/promises`) or call `signal.throwIfAborted()` between steps. An operation that ignores the signal finishes as `succeeded`. Writes already made stay.
+- **Statuses:** `running`, `succeeded`, `failed` (with `error`), `cancelled` and `interrupted`.
+- **Stopping the server** aborts every running operation's `signal` and records nothing more. An operation that ignores the signal keeps going until the process exits, and calls it already made to other services may still complete.
+- **Restarts.** A run still `running` when the server stopped becomes `interrupted` at the next start. Its effects may be partial, so it never runs again by itself. `jobs.resolve(id, 'retry')` starts a new run with the same input and `key`, and `'dismiss'` leaves it as is. Only one retry is accepted per interrupted run.
+- **Schedules** persist across restarts. `every` is in seconds, 10 or more, counted from when the previous slot fired. `cron` uses five fields, or six with seconds, parsed by [croner](https://github.com/hexagon/croner), and needs an IANA `timezone`, such as `'Europe/Lisbon'`.
+- **Overlap** is skipped. A slot is skipped and recorded as `lastSkippedAt` while an earlier run of the schedule is still running (cancelling included) or is interrupted and not yet settled. An unsettled interrupted run pauses its schedule.
+- **Missed slots** are slots that passed while the server was down. With `skip`, the schedule waits for the next slot and records `lastMissedAt`. With `once`, it runs one catch-up at start.
+- **Reload** validates `jobs` with the rest of the module. A bad definition keeps the old module serving. A schedule or interrupted run remembers the operation it was made with. If its job is removed or now names another operation, it never runs. The schedule records the reason as `error` and skips each slot. To pick up the change, schedule the job again.
+- Finished runs are kept; there is no retention limit yet.
+- Jobs do not send notifications, export data or call external services unless the app's own operation does.
+
+## Errors
+
+Throw these from `golem-kit/server`; the HTTP status and the browser error follow from the name.
+
+| Error | Status | Meaning |
+| --- | --- | --- |
+| `InvalidError` | 400 | Bad input, name, id, folder or path segment |
+| `UnauthorizedError` | 401 | Not signed in, or the session ended |
+| `ForbiddenError` | 403 | `authorize` returned false |
+| `NotFoundError` | 404 | No such record, file or operation |
+| `VersionConflictError` | 409 | `expectedVersion` no longer matches; carries `current` |
+| `RecordRefusedError` | 422 | A business rule refused the write; `fields` name the controls |
+| `ModelUnavailableError` | 503 | No model could answer `context.model` |
+
+Any other thrown error answers 500 with a generic message and is logged on the server.
+
+## Server code reload
+
+After a successful build-mode turn, the dev server rebuilds the browser, then bundles `src/server/index.ts` with every local file it imports and swaps the new operations and hooks in place. Stores, open change streams and conversations continue. Packages stay shared with the running server. If the new module fails to load or validate, the old one keeps serving and the conversation shows the error instead of refreshing. Outside build mode, restart `./golem dev` after editing server code.
+
+## Adding a capability
+
+1. Put shared record shapes in `src/shared/`.
+2. Define the operation in `src/server/`, naming its `record` when it acts on one, and add it to `operations`.
+3. Add any access rule to `authorize` in terms of `principal`, `operation` and `record`.
+4. Call it from the UI with `invoke('<name>', input)`; use `records` and `files` for plain CRUD and uploads.
+5. Exercise it in the browser: create, edit, reload the page, restart `./golem dev`, and confirm the data is still there.

package/docs/architecture.md

@@ -0,0 +1,93 @@
+# App architecture
+
+How a Golem app keeps its knowledge in the right place, and how `./golem lint` checks the few
+boundaries Golem cares about.
+
+## Knowledge ownership
+
+Each piece of knowledge has one owner:
+
+- **The app** owns its business: `docs/domain.md` (the app's DNA) and the code under `src/`.
+  Concepts, operations, rules, and decisions specific to this app live only here.
+- **golem-kit** owns the shell, CLI, runtime, and this generic guidance. Read it from the
+  installed package; the app keeps pointers to it, never copies.
+- **golem-ui** owns components and their adapter contracts. Its `README.md` is the reference.
+
+When a change needs reusable framework or UI-kit behavior, propose it for that package instead
+of growing a private copy inside the app.
+
+## DNA and code change together
+
+`docs/domain.md` records the app's purpose, concepts, operations, and decisions. When a change
+adds or alters a concept, an operation, or a rule, update the DNA in the same change as the
+code. Discuss changes to an important decision with the person before implementing them.
+
+## Layout
+
+Golem assumes only this much structure under `src/`:
+
+| Path | Holds | May import |
+| --- | --- | --- |
+| `src/` (outside `src/server/`) | Browser UI and domain logic | `src/shared/`, browser-safe packages |
+| `src/shared/` | Plain types and values used by both sides | Nothing from `src/server/` |
+| `src/server/` | Backend modules | Anything except storage drivers |
+| `src/server/persistence/` | Storage adapters | Storage drivers |
+
+Everything else, such as module names and folder depth, is the app's choice. Record choices that
+matter in `docs/domain.md`.
+
+## Deliberate seams
+
+The UI reaches the backend through the app's declared API, never by importing server modules.
+Types the UI and server share go in `src/shared/`, so type-only imports from `src/server/` are
+refused too. Components receive data through golem-ui's `config` plus `adapters` shape rather
+than opening their own data connections. Storage drivers stay behind persistence adapters, so the
+rest of the app depends on the adapter's contract, not on a database client.
+
+## Checking the architecture
+
+`./golem lint` runs ESLint with the app's `eslint.config.mjs`. The generated file uses the shared
+config:
+
+```js
+import golem from 'golem-kit/eslint'
+
+export default golem()
+```
+
+It reports:
+
+- storage driver imports (`pg`, `mysql2`, `better-sqlite3`, `node:sqlite`, `mongodb`, `redis`,
+  and similar) outside `src/server/persistence/`;
+- imports of `src/server/` modules, `golem-kit/server`, or `node:` built-ins from code outside
+  `src/server/`.
+
+These are architectural guardrails an app may adapt, not security boundaries. They read import
+specifiers as written: relative paths are matched by directory name, and aliases, bare Node
+built-in names such as `fs`, `require()`, and dynamic `import()` are not checked. Keep secrets on
+the server and out of browser bundles regardless of what the lint reports.
+
+## Adapting or disabling a rule
+
+Change a rule deliberately and say why in the same change. Pass options to `golem()`:
+
+```js
+import golem, { golemDrivers } from 'golem-kit/eslint'
+
+export default golem({
+  server: 'src/backend',              // backend directory; false disables the server boundary
+  persistence: 'src/backend/storage', // storage adapter directory
+  drivers: [...golemDrivers, 'example-db'], // false disables the driver boundary
+  serverModules: ['golem-kit/server'],       // packages only the server may import
+})
+```
+
+For a single justified exception, use ESLint's standard directive with a reason:
+
+```ts
+// eslint-disable-next-line no-restricted-imports -- migration script reads the legacy database directly
+import pg from 'pg'
+```
+
+To turn every Golem check off, replace `golem()` with your own ESLint config, such as
+`export default []`. An app created before this config existed can opt in by adding the `eslint.config.mjs` above.

package/docs/builder.md

@@ -0,0 +1,15 @@
+# Building a Golem app
+
+You are the in-app builder. The person sees a Chat beside their app’s Canvas. Ask what they want to create in ordinary language, then help them shape it. Build mode is explicit: only build-mode turns may change files. After a successful build-mode turn, Golem rebuilds and refreshes the Canvas. Conversation history and sessions persist, so continue the work naturally when a thread resumes.
+
+Read `docs/domain.md`, the app's DNA, first, and update it in the same change as the code it describes. `node_modules/golem-kit/docs/architecture.md` explains where code belongs; run `./golem lint` to check it. Before a major design or build, discuss the app’s intent, important workflows, and contracts with the person. Keep their business language, rules, and decisions in this app; put reusable framework behavior and UI-kit changes in their owning packages. Keep plumbing separate from business decisions and make each module own the knowledge it needs.
+
+For implementation and pull-request work, start with the user or business problem and the resulting behavior. Keep a PR description to one short paragraph; add terse validation and dependencies only when useful. Run checks appropriate to the change.
+
+Supported app surface: edit `src/app.tsx` (it may also `export const screens = [{ id, label, icon? }]`; each one gets an item in the bottom menu row and the chosen id arrives as the `screen` prop); configure the shell title, host, port, storage, optional accounts, and optional agents in `golem.config.ts` (read `node_modules/golem-kit/docs/agents.md` before turning on ordinary chat); use `./golem help`, `./golem build`, `./golem lint`, and `./golem dev`. The installed `golem-ui` package is the component contract: its `README.md` names the current components and adapters, while its API and adapter docs are linked there. Use its `config` plus `adapters` shape rather than inventing a data layer inside a component. Ask before changing an important application contract or proposing framework/UI-kit work.
+
+Before storing records or files, adding server behavior an agent or the UI calls, or adding sign-in, roles or groups, read `node_modules/golem-kit/docs/app-backend.md`: it names where UI, shared, and server code live and the operation, authorization, and storage contracts.
+
+Before adding a knowledge base, notes, a handbook or any markdown the app should keep in folders, read `node_modules/golem-kit/docs/knowledge.md`.
+
+When the app has a `brain/` folder, it is an Open Knowledge Format bundle: read `brain/index.md` first, then the concepts it points to. Ground answers in those files and cite each passage you used as `path#Lstart-Lend`, the path relative to `brain/` (`concepts/opening.md#L4-L9`); Golem turns a citation in your message into a source chip that opens the passage in the Brain reader. Keep `brain/index.md` and `brain/log.md` current when you add or change a concept.

package/docs/knowledge.md

@@ -0,0 +1,35 @@
+# Knowledge recipe
+
+Read when an app keeps markdown knowledge in folders: a handbook, research notes, a second brain. The storage, permission and editing contracts are in [the app backend guide](app-backend.md#knowledge-files); this file is how to organize and maintain the content. It is optional per app, and the app chooses its folders and types.
+
+## Format: OKF v0.2
+
+Files follow the [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/ad30107c31c06aec8a7d5636e0d1058118604e6f/SPEC.md) (pinned; v0.2 renamed fields from v0.1). Golem reads only `type` and `title` and preserves everything else.
+
+- One concept per `.md` file. Its path without `.md` is its identity, so rename with care and fix the links that point at it.
+- Each concept starts with YAML frontmatter holding a non-empty `type`. `title` and a one-sentence `description` are recommended. The app picks its own type names.
+- Link concepts with ordinary markdown links, preferably from the root: `[Opening the workshop](/guides/opening.md)`. A link to a page not written yet is fine.
+- `index.md` and `log.md` are reserved. `index.md` lists a folder's concepts under headings, one `* [Title](path) - description` line each, with no frontmatter (the root `index.md` may carry `okf_version: "0.2"`). `log.md` records changes newest first under `## YYYY-MM-DD` headings.
+
+```markdown
+---
+type: Playbook
+title: Opening the workshop
+description: What to switch on, in order, before the first job of the day.
+---
+# Opening the workshop
+
+1. Unlock the side door.
+2. Switch on the dust extractor before any saw.
+```
+
+## Maintaining it
+
+- **Agree the map first.** Before writing much, settle with the person which folders and types the domain needs. Add folders when material asks for them.
+- **Capture, then organize.** New material goes in as it arrives, even rough. Tidy it in small steps: split a concept that covers two things, merge duplicates, add the links.
+- **Keep sources.** Record where a claim came from with a link, or keep the original under `references/`, so an answer can be traced back to its source.
+- **Keep indexes current.** When you add, rename or remove a concept, update the `index.md` of its folder in the same change and add a `log.md` line.
+- **Answer from sources.** Search, read the files, and cite the path and lines you used. Say what is missing or looks out of date instead of filling the gap; offer to write it down.
+- **Edit with the reader.** Read before writing and send the version you read. When a save is refused because the file changed, read it again and merge; never write over the other change.
+
+Frontmatter such as `verified` or `status` is advisory. Who may read or change a file is decided only by the app's `authorize`.