golem-kit 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.2
+
+- An app pins the model its terminal agents run on: `chat: { provider: 'tmux', agent, model }` for normal-mode chat and `agents.builderModel` for the builder. The pin rides the launch args (`-m` for Codex, `--model` for Claude Code) and is replayed on resume.
+
+## 0.2.1
+
+- `./golem` runs on a fresh `pnpm install`: the installed entry resolves `tsx` from golem-kit's own tree instead of the app's `node_modules/.bin`.
+- `init` leaves a typecheckable app: a `tsconfig.json`, `src/globals.d.ts`, `dev`/`build`/`lint`/`typecheck` scripts, and the `typescript`, `@types/node`, `@types/react` devDependencies they need.
+- `./golem build` sees the app's own `src/*.d.ts`, so an app can `import './app.css'` without `@ts-ignore`.
+- The new-app scaffold uses only classes golem-ui's packaged stylesheet ships; an app styles the rest with its own CSS.
+
 ## 0.2.0
 
 - `golem-kit/server` export and an `exports` map, so an app imports the backend by name instead of by path.

package/docs/agents.md

@@ -18,6 +18,7 @@ export default {
   title: 'Field Notes',
   agents: {
     builder: 'claude', // or 'codex': the agent build mode starts with
+    builderModel: 'claude-opus-5-5', // pins that CLI's model
     ordinary: {
       backend: 'anthropic',
       operations: ['records.list', 'records.get', 'records.update', 'notes.archive'],
@@ -29,6 +30,7 @@ export default {
 ```
 
 - `builder` is the default choice in build mode. A person's own pick in the browser still wins and is remembered.
+- `builderModel` pins the builder CLI's model, in that CLI's own spelling (`--model` for Claude Code, `-m` for Codex). A terminal chat pins its own the same way: `chat: { provider: 'tmux', agent: 'codex', model: 'gpt-6-luna' }`. Both survive a resume. Left out, each CLI picks its default.
 - `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.

package/docs/app-backend.md

@@ -13,6 +13,8 @@ Business rules stay in the app; this package supplies storage, the operation bou
 | `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`) |
 
+App styling is the app's own: golem-ui ships a packaged stylesheet holding only the classes its components use, so anything beyond those is CSS written in `src/` and imported from UI code.
+
 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
@@ -92,7 +94,9 @@ type Model = { extract<S extends z.ZodType>(request: { schema: S; text: string;
 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
+The app names the shape it wants and never which model answered. Which runtime does is the app's
+`model: { runtime, name }` — `{ runtime: 'codex', name: 'gpt-6-luna' }` is the cheap everyday pick
+for extraction and scheduled jobs. Absent, it 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

package/docs/builder.md

@@ -6,7 +6,7 @@ Read `docs/domain.md`, the app's DNA, first, and update it in the same change as
 
 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.
+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. Only the utility classes golem-ui's own components use exist in its packaged stylesheet, so any styling beyond those is CSS this app writes and imports from `src/`. 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.
 

package/docs/local-cli.md

@@ -55,9 +55,12 @@ and rebuilds the shared `dist/` directory; requires port 3000).
 
 ## Generated projects
 
-`golem-kit init` creates `package.json`, `golem.config.ts`, `eslint.config.mjs`, `src/app.tsx`,
-`docs/domain.md` (the app's DNA template), small `AGENTS.md` and `CLAUDE.md` pointers to the
-installed framework guide, and an executable `./golem`. Normal initialization writes the
+`golem-kit init` creates `package.json`, `golem.config.ts`, `tsconfig.json`, `eslint.config.mjs`,
+`src/app.tsx`, `src/globals.d.ts`, `docs/domain.md` (the app's DNA template), small `AGENTS.md` and
+`CLAUDE.md` pointers to the installed framework guide, and an executable `./golem`. The generated
+`package.json` carries the scripts `dev`, `build`, `lint` (each one the matching `./golem` command)
+and `typecheck` (`tsc --noEmit` over `tsconfig.json`), plus the `typescript`, `@types/node` and
+`@types/react` devDependencies those scripts need at the versions golem-kit itself uses. Normal initialization writes the
 pinned npm dependency `golem-kit@<framework version>` and installs it with pnpm, along with
 the exact `golem-ui` version golem-kit uses so app code can import its components directly.
 For local packed-tarball acceptance only, set `GOLEM_KIT_TARBALL=/path/to/golem-kit.tgz`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golem-kit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Starter kit and local CLI for Golem applications.",
   "type": "module",
   "exports": {

package/src/browser-build.ts

@@ -39,12 +39,17 @@ export async function buildBrowser(): Promise<void> {
       noEmit: true, jsx: 'react-jsx', module: 'ESNext', moduleResolution: 'Bundler',
       skipLibCheck: true, allowImportingTsExtensions: true,
       types: ['node', 'react', 'react-dom'], typeRoots: [typeRoots],
-      paths: sourcePaths(),
+      // The same two aliases vite.config.ts resolves, because `include` now sweeps in any shell
+      // file a checkout used as its own app keeps beside the app's.
+      paths: {
+        ...sourcePaths(),
+        '@golem/app': [resolve(process.cwd(), 'src/app.tsx')],
+        '@golem/config': [resolve(process.cwd(), 'golem.config.ts')],
+      },
     },
-    files: [
-      resolve(process.cwd(), 'src/app.tsx'), resolve(process.cwd(), 'golem.config.ts'),
-      ...[resolve(process.cwd(), 'src/server/index.ts')].filter(existsSync),
-    ],
+    // `include`, not a `files` list: the app's own ambient declarations (`src/*.d.ts`, so that
+    // `import './app.css'` resolves) only enter the program when the whole of `src/` does.
+    include: [resolve(process.cwd(), 'src/**/*'), resolve(process.cwd(), 'golem.config.ts')],
   }));
   execFileSync(tsc, ['-p', appTsconfig], { cwd: process.cwd(), stdio: 'inherit' });
   await build({ configFile: resolve(frameworkRoot, 'vite.config.ts') });

package/src/cli.ts

@@ -116,7 +116,7 @@ See node_modules/golem-kit/docs/architecture.md to add eslint.config.mjs.`);
 
 function initProject(): void {
   const root = resolve(process.cwd());
-  const files = ['golem.config.ts', 'eslint.config.mjs', 'src/app.tsx', 'docs/domain.md', 'AGENTS.md', 'CLAUDE.md', 'golem', 'brain/index.md', 'brain/log.md'];
+  const files = ['golem.config.ts', 'tsconfig.json', 'eslint.config.mjs', 'src/app.tsx', 'src/globals.d.ts', 'docs/domain.md', 'AGENTS.md', 'CLAUDE.md', 'golem', 'brain/index.md', 'brain/log.md'];
   const existing = files.filter((file) => existsSync(resolve(root, file)));
   if (existing.length) throw new Error(`refusing to overwrite existing files: ${existing.join(', ')}`);
   const packagePath = resolve(root, 'package.json');
@@ -134,10 +134,27 @@ function initProject(): void {
     writeFileSync(packagePath, JSON.stringify({
       name: 'golem-app', private: true, type: 'module', packageManager: 'pnpm@10.28.2',
       engines: { node: '>=22.18.0', pnpm: '10.28.2' },
+      scripts: { dev: './golem dev', build: './golem build', lint: './golem lint', typecheck: 'tsc --noEmit' },
       ...(process.env.GOLEM_KIT_TARBALL ? {} : { dependencies: { 'golem-kit': framework.version } }),
+      // The app's own tsconfig needs a compiler and the React/Node types in the app's tree;
+      // golem-kit has them for its own program, and pnpm does not share them with the app.
+      devDependencies: Object.fromEntries(['typescript', '@types/node', '@types/react']
+        .map((name) => [name, framework.dependencies[name]])),
     }, null, 2) + '\n');
   }
   writeFileSync(resolve(root, 'golem.config.ts'), "export default { title: 'Golem', brain: true }\n");
+  writeFileSync(resolve(root, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: {
+      target: 'ES2023', module: 'ESNext', moduleResolution: 'Bundler',
+      strict: true, noEmit: true, allowImportingTsExtensions: true,
+      jsx: 'react-jsx', skipLibCheck: true, types: ['node'],
+    },
+    include: ['src/**/*', 'golem.config.ts'],
+  }, null, 2) + '\n');
+  writeFileSync(resolve(root, 'src/globals.d.ts'), `// golem-ui ships its own compiled stylesheet; any class beyond the ones its components use is
+// CSS this app writes and imports itself.
+declare module '*.css'
+`);
   writeFileSync(resolve(root, 'brain/index.md'), `---
 okf_version: "0.2"
 ---
@@ -148,7 +165,7 @@ This folder is an Open Knowledge Format bundle: one concept per markdown file wi
   writeFileSync(resolve(root, 'brain/log.md'), '# Log\n');
   writeFileSync(resolve(root, 'src/app.tsx'), `export default function App() {
   return (
-    <section className="flex h-full min-h-64 items-center justify-center bg-neutral-50 p-6 text-center">
+    <section className="flex h-full items-center justify-center bg-neutral-50 p-6 text-center">
       <div>
         <h1 className="text-lg font-semibold">Welcome to Golem</h1>
         <p className="mt-2 text-sm text-neutral-500">Edit src/app.tsx to build your app.</p>

package/src/config.ts

@@ -12,14 +12,14 @@ export type ModelConfig = { runtime: 'claude' | 'codex'; name?: string }
  * terminal agent in the `chat` window of the app's tmux session, briefed from `docs/chat.md`.
  * `roles` restricts chat to those account roles; absent, anyone signed in may chat.
  */
-export type ChatConfig = ({ provider: 'anthropic' } | { provider: 'tmux'; agent?: 'codex' | 'claude' }) & { roles?: string[] }
+export type ChatConfig = ({ provider: 'anthropic' } | { provider: 'tmux'; agent?: 'codex' | 'claude'; model?: string }) & { roles?: string[] }
 /** `brain: true` serves the app's `brain/` folder read-only and mounts the Brain reader beside the app. */
 
 /**
  * `builder` is the agent build mode starts with. `ordinary` turns on everyday chat: an API agent
  * whose only tools are the listed app operations, run as the person chatting.
  */
-export type AgentsConfig = { builder?: 'codex' | 'claude'; ordinary?: OrdinaryAgentConfig }
+export type AgentsConfig = { builder?: 'codex' | 'claude'; builderModel?: string; ordinary?: OrdinaryAgentConfig }
 export type OrdinaryAgentConfig = { backend: 'anthropic'; model: string; operations: string[]; collections?: string[]; roots?: string[]; instructions?: string }
 
 /** golem-ui's Auth role shape: `manages` roles run accounts and may build; `builder` may build. */
@@ -70,10 +70,11 @@ export async function loadAppConfig(root = process.cwd()): Promise<AppConfig> {
       config.agents = { ...config.agents, ordinary: ordinaryAgent({ backend: 'anthropic', ...rest }) }
       config.chat = { provider, ...chatRoles }
     } else if (provider === 'tmux') {
-      const { agent, ...unknown } = rest
+      const { agent, model, ...unknown } = rest
       if (Object.keys(unknown).length) throw new Error(`golem.config.ts chat has unknown fields: ${Object.keys(unknown).join(', ')}`)
       if (agent !== undefined && agent !== 'codex' && agent !== 'claude') throw new Error("golem.config.ts chat.agent must be 'codex' or 'claude'")
-      config.chat = { provider, ...(agent ? { agent } : {}), ...chatRoles }
+      if (model !== undefined && (typeof model !== 'string' || !model)) throw new Error('golem.config.ts chat.model must be a nonempty string')
+      config.chat = { provider, ...(agent ? { agent } : {}), ...(model ? { model: model as string } : {}), ...chatRoles }
     } else throw new Error("golem.config.ts chat.provider must be 'anthropic' or 'tmux'")
   } else if (config.agents?.ordinary) config.chat = { provider: 'anthropic' }
   return config
@@ -117,10 +118,11 @@ function chatRolesOf(value: unknown, accounts: AccountsConfig | undefined): stri
 
 function agents(value: unknown): AgentsConfig {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('golem.config.ts agents must be an object')
-  const { builder, ordinary, ...unknown } = value as Record<string, unknown>
+  const { builder, builderModel, ordinary, ...unknown } = value as Record<string, unknown>
   if (Object.keys(unknown).length) throw new Error(`golem.config.ts agents has unknown fields: ${Object.keys(unknown).join(', ')}`)
   if (builder !== undefined && builder !== 'codex' && builder !== 'claude') throw new Error("golem.config.ts agents.builder must be 'codex' or 'claude'")
-  return { ...(builder ? { builder } : {}), ...(ordinary === undefined ? {} : { ordinary: ordinaryAgent(ordinary) }) }
+  if (builderModel !== undefined && (typeof builderModel !== 'string' || !builderModel)) throw new Error('golem.config.ts agents.builderModel must be a nonempty string')
+  return { ...(builder ? { builder } : {}), ...(builderModel ? { builderModel: builderModel as string } : {}), ...(ordinary === undefined ? {} : { ordinary: ordinaryAgent(ordinary) }) }
 }
 
 // Operations whose input or output is raw bytes, which a chat tool cannot carry.

package/src/dev-server.ts

@@ -45,7 +45,8 @@ export async function startDevServer(
   // A new session needs a runnable CLI; a restored one keeps its ref and resumes on its next message.
   createBackend ??= async (backend, ref, buildMode = true) => {
     if (!ref && !(await discoverAgents()).some((found) => found.agent === backend && found.runnable)) throw new Error(`${backend} is not runnable here`);
-    return new TmuxBackend(appRoot, backend, ref, { stateDir: join(stateDirectory, 'harness'), api: serverUrl(host, port), window: buildMode ? 'builder' : 'chat', ...(buildMode ? {} : { instructions: chatInstructions(appRoot), permissions: 'readonly' }) });
+    const model = buildMode ? app.config.agents?.builderModel : app.config.chat?.provider === 'tmux' ? app.config.chat.model : undefined;
+    return new TmuxBackend(appRoot, backend, ref, { stateDir: join(stateDirectory, 'harness'), api: serverUrl(host, port), window: buildMode ? 'builder' : 'chat', ...(model ? { model } : {}), ...(buildMode ? {} : { instructions: chatInstructions(appRoot), permissions: 'readonly' }) });
   };
   const builder = await builderFlag(stateDirectory);
   const state = new ConversationState(stateDirectory);

package/src/entry.mjs

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -8,11 +9,14 @@ const source = process.env.GOLEM_SOURCE && resolve(process.env.GOLEM_SOURCE)
 const cli = source ? resolve(source, 'src/cli.ts') : resolve(frameworkRoot, 'src/cli.ts')
 if (!existsSync(cli)) throw new Error(`GOLEM_SOURCE must point to a Golem checkout containing src/cli.ts: ${source}`)
 
+// Node does not strip types from files under node_modules, so the installed CLI needs tsx. Resolve
+// it from this file — golem-kit's own dependency tree — because pnpm does not link a transitive
+// dependency's bin into the app's node_modules/.bin, so the app's PATH may not have tsx at all.
 const installed = !source && frameworkRoot.includes('/node_modules/')
-const command = installed ? resolve(process.cwd(), 'node_modules/.bin/golem-kit') : process.execPath
-const args = installed ? process.argv.slice(2) : [cli, ...process.argv.slice(2)]
-const env = installed ? { ...process.env, PATH: `${resolve(process.cwd(), 'node_modules/.bin')}:${process.env.PATH ?? ''}` } : process.env
-const child = spawn(command, args, { cwd: process.cwd(), env, stdio: 'inherit' })
+const args = installed
+  ? [createRequire(import.meta.url).resolve('tsx/cli'), cli, ...process.argv.slice(2)]
+  : [cli, ...process.argv.slice(2)]
+const child = spawn(process.execPath, args, { cwd: process.cwd(), stdio: 'inherit' })
 for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => child.kill(signal))
 const result = await new Promise((resolve, reject) => child.once('error', reject).once('exit', (code, signal) => resolve({ code, signal })))
 if (result.signal) process.kill(process.pid, result.signal)

package/src/runtime/tmux.ts

@@ -53,9 +53,10 @@ export const brainInstructions = 'This app has a brain: `brain/` is an Open Know
 /**
  * `window` names this agent's window in the app's session (`builder`, `chat`); `instructions` its launch prompt;
  * `permissions` its launch profile: `bypass` (default) may do anything, `readonly` can read the app and run
- * `./golem say`, nothing else, and refuses rather than prompts.
+ * `./golem say`, nothing else, and refuses rather than prompts. `model` pins the agent's model, in that
+ * CLI's own spelling (`gpt-6-luna` for codex, `claude-opus-5-5` for claude).
  */
-export type TmuxOptions = { harness?: Harness; stateDir?: string; api?: string; window?: string; instructions?: string; permissions?: 'bypass' | 'readonly' }
+export type TmuxOptions = { harness?: Harness; stateDir?: string; api?: string; window?: string; instructions?: string; permissions?: 'bypass' | 'readonly'; model?: string }
 
 /** The one tmux session of an app's build mode: `tmux attach -t golem-<app dir>` is always the place to look. */
 export const tmuxSessionName = (cwd: string): string => `golem-${basename(cwd).replace(/[^A-Za-z0-9_-]/g, '-')}`
@@ -96,7 +97,10 @@ export class TmuxBackend implements SessionBackend {
       // codex 0.155: the update prompt at launch would take the typed brief as its answer, the
       // paste-burst fold swallows the first Enter of a long line, and the rate-limit "keep current
       // model" nudge after the first turn eats the first message. All off; replayed on resume.
-      extraArgs: this.agent === 'codex' ? ['-c', 'check_for_update_on_startup=false', '-c', 'disable_paste_burst=true', '-c', 'notice.hide_rate_limit_model_nudge=true'] : [],
+      extraArgs: [
+        ...(this.agent === 'codex' ? ['-c', 'check_for_update_on_startup=false', '-c', 'disable_paste_burst=true', '-c', 'notice.hide_rate_limit_model_nudge=true'] : []),
+        ...(this.opts.model ? [this.agent === 'codex' ? '-m' : '--model', this.opts.model] : []),
+      ],
     }
     try {
       // A ref saved under an older naming (`golem-<uuid>`) comes back in the app's fixed session: only