bazilion 0.0.0

package/.understand-anything/meta.json

@@ -0,0 +1,6 @@
+{
+  "lastAnalyzedAt": "2026-05-22T09:05:00.000Z",
+  "gitCommitHash": "663cf6bac528c56e62eb2f5d8e46d294f3f89090",
+  "version": "1.0.0",
+  "analyzedFiles": 250
+}

package/CLAUDE.md

@@ -0,0 +1,164 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Dev commands
+
+Node 22.12+ required (for built-in `node:sqlite` + `.ts` ecosystem). pnpm 10+ as the package manager. Everything runs via `tsx`, which is pinned as a root dev-dep — no separate install.
+
+```sh
+pnpm install
+pnpm test              # vitest run across the whole tree
+pnpm typecheck         # tsc --noEmit (excludes apps/web — see below)
+pnpm lint              # biome check
+pnpm format            # biome check --write
+```
+
+Running a single test: `pnpm vitest run apps/daemon/test/core/agents.test.ts` (or `pnpm vitest -t 'pattern'`).
+
+Running the CLI locally (no build step — `tsx` executes `.ts` directly):
+
+```sh
+pnpm tsx apps/cli/src/index.ts <subcommand>
+# e.g. pnpm tsx apps/cli/src/index.ts agent chat <uuid>
+#      pnpm tsx apps/cli/src/index.ts serve        # boots the daemon (web UI runs separately)
+```
+
+`README.md` has the full user-facing quickstart (`bazilion serve` auto-bootstraps `~/.bazilion` on first run → start the web UI on :4322 → finish first-run setup on /config → spawn from the auto-seeded `default` profile).
+
+## Architecture
+
+pnpm workspaces monorepo. **Four apps** (cli, daemon, web, mobile), **two packages** (api-types, client).
+
+The **daemon** (`apps/daemon`) is the single owner of `~/.bazilion` AND the LLM/tool stack. It's also the only place server-side code lives — there's no `@bazilion/core` or `@bazilion/runtime` package; that code is internal to the daemon under `apps/daemon/src/core/` (DB schema, repos, domain ops, paths, secrets, services, skills) and `apps/daemon/src/runtime/` (pi adapter, providers, memory, tools, worker, sessions). Every other process — CLI, web frontend SSR, mobile app, future browser SPA — talks to the daemon over HTTP. **Workers spawned per turn don't hold their own DB handle either** — they receive pre-resolved data on stdin and round-trip live messaging back to the daemon over Node IPC.
+
+Three invariants:
+
+1. **Nothing outside `apps/daemon` imports daemon-internal code at runtime.** Clients talk to the daemon over HTTP via `@bazilion/client` + `@bazilion/api-types`. The CLI's tests are the one pragmatic exception: they reach into `apps/daemon/src/...` via relative imports for setup/inspection. No other consumer should follow that pattern.
+2. **The daemon owns the DB, scheduler, agent-cancel registry, secrets table, and the bootstrap token in auth.json.** Other processes are stateless clients.
+3. **The daemon self-bootstraps on first `bazilion serve`** — there is no `bazilion init` command. `apps/daemon/src/lib/ctx.ts:bootstrap()` runs idempotently at startup: creates `~/.bazilion/{profiles,agents,skills,groups,logs}`, opens the DB, runs migrations, and (if `auth.json` is missing) mints a bootstrap web_tokens row + writes the plaintext to `auth.json`.
+
+- **`packages/api-types`** — **hermetic** wire-shape package. Owns the canonical type definitions for everything that crosses the HTTP/IPC wire: entity shapes (`Agent`, `Group`, `Profile`, `Message`, `WebToken`, `AgentTrigger`, `ResolvedAgent`, `LoadedProfile`, `OpenAICodexStatus`, …) in `entities.ts`, chat/provider events (`ChatFrame`, `SessionEvent`, `ProviderMessage`, `ToolCall`, `ToolDef`) in `events.ts`, memory wire types in `memory.ts`, and request/response envelopes + `PROFILE_FILES` in `index.ts`. **Zero deps** — no node-only modules, no daemon code. The daemon imports its entity/wire types FROM here; that's what keeps `apps/web`, `apps/mobile`, and `@bazilion/client` from ever reaching Node-only code (`node:sqlite`, undici, pi-ai, the worker spawner).
+- **`packages/client`** — HTTP client for **cross-origin consumers that need explicit auth headers**: the CLI today, a future React Native / mobile app tomorrow. Exports `createClient({ serverUrl, token })`, `ApiClientError`, `BazilionClient`. Pure `fetch` + `TextDecoder` + NDJSON stream async generator — no `node:*` imports, no node-only deps. `token` is `string | (() => string | Promise<string>)` so rotating credentials (OAuth refresh, mobile keychain reads) plug in without rebuilding the client; the package builds `Authorization: Bearer <token>` + `Origin: <serverUrl>` headers internally. `apps/cli/src/client.ts` wraps it with the Node-specific `loadClientConfig()` (reads `~/.bazilion/auth.json` + `BAZILION_SERVER`/`BAZILION_TOKEN` env via the CLI's local `apps/cli/src/{paths,auth-file}.ts` helpers). **Not used by `apps/web` browser-side code**: the web UI hits its own server same-origin with relative URLs, so the `bz_token` cookie auto-attaches.
+
+### Auth model
+
+One token table (`web_tokens`), one source of truth in the daemon. `apps/daemon/src/lib/auth.ts` exposes `isValidToken(t)` (queries `web_tokens` only — there's no separate bootstrap path) and `extractBearer(header)`; `apps/daemon/src/lib/middleware-auth.ts` is the Hono middleware that gates every route. The middleware reads `Authorization: Bearer <t>` first, falls back to the `bz_token` cookie (via `hono/cookie`) — whichever the client sent, the same `isValidToken` lookup decides. Public paths (`/api/login`, `/api/health`) skip auth; setup-open paths (`/api/config/*`, `/api/auth/*`) skip the first-run gate.
+
+The bootstrap token is the plaintext stored in `~/.bazilion/auth.json` — written there by the daemon's self-bootstrap on first `bazilion serve` (`apps/daemon/src/lib/ctx.ts:bootstrap()`) alongside its hash inserted into `web_tokens` (label `bootstrap`). Both the CLI (loopback bearer) and the daemon (PBKDF2 seed for the secrets table) read this file. **Do not allow revoking the bootstrap row**: `DELETE /api/tokens/:id` rejects (409) when the requested id matches the auth-token's hash, and the web UI hides the revoke button for that row. Otherwise the operator could lock themselves out.
+
+**SSR cookie-forward**: server fns inside `apps/web/src/lib/daemon-client.ts` read `bz_token` via `getCookie` from `@tanstack/react-start/server` and forward it as a bearer header when calling the daemon — user identity is preserved end-to-end, daemon audit logs always reflect the actual user. **`daemon-client.ts` is server-only**: any module that ends up in the client bundle must import constants from `apps/web/src/lib/wire-constants.ts` instead (Vite's import-protection rejects `@tanstack/react-start/server` in client code). Native clients (CLI, mobile) send bearer via `@bazilion/client`. Tokens are minted + revoked with `bazilion token create/list/revoke` → `POST|GET|DELETE /api/tokens`. When adding a new auth surface, extend `isValidToken` — don't bypass it.
+
+### Mobile / LAN notes
+
+The daemon binds `127.0.0.1:4321` by default. `bazilion serve --host 0.0.0.0 [--port N]` exposes it on the LAN for a mobile client; the serve command prints a loud warning in that case because the API is admin-level and TLS is the user's responsibility (Tailscale handles it for personal networks; reverse-proxy with TLS for anything else). The web frontend's `vite.config.ts` reads `WEB_HOST`/`WEB_PORT` so it can move off 4322 if needed. Pairing: `bazilion token create <label> --qr` mints a token and emits a `bazilion://pair?server=<url>&token=<t>` URL plus a terminal QR code (via `qrcode-terminal`). The server URL is auto-detected from the first non-loopback IPv4 interface when the CLI's stored URL is loopback-only; `--server <url>` overrides detection (useful for Tailscale hostnames). No gateway/relay has been built — the mobile app is expected to speak to the daemon directly over LAN/Tailscale/VPN.
+
+### apps/mobile
+
+Expo SDK 54 + Expo Router 6 (file-based), React 19, RN 0.81, new-architecture-enabled. URL scheme `bazilion://` for deep-link pairing. Structure:
+- `app/` — file-based routes. `_layout.tsx` wraps the stack; `index.tsx` is the auth gate (loads credentials from `expo-secure-store`, redirects to `/pair` or `/agents`); `pair.tsx` is the camera+manual-paste pairing flow; `agents/index.tsx` is a FlatList of agents (pull-to-refresh, 401→/pair auto-unpair, header-level unpair button); `agents/[id].tsx` is an agent detail stub where chat will land next.
+- `src/pair-url.ts` — pure TS parser for `bazilion://pair?server=…&token=…`. RN-free, unit-tested by root vitest (`apps/mobile/test/pair-url.test.ts`).
+- `src/auth.ts` — `expo-secure-store` wrapper (`loadCredentials` / `saveCredentials` / `clearCredentials` / `verifyCredentials`) and a `clientFor(creds)` factory returning `@bazilion/client`'s `BazilionClient`.
+- `metro.config.js` — sets `watchFolders`/`nodeModulesPaths` so Metro resolves workspace packages through pnpm's symlink layout.
+- Excluded from root `tsconfig.json`, `biome.json`. Run `pnpm --filter @bazilion/mobile typecheck` for mobile-only TS checks. Run `pnpm --filter @bazilion/mobile start` for the Expo dev server.
+- `@bazilion/api-types` is hermetic — entity types and wire shapes are defined inline (`entities.ts`, `events.ts`, `memory.ts`); it has no dep on the daemon. That's what keeps mobile's TS checker out of Node-only code. Metro itself never sees these imports at runtime (babel's TS transform strips `import type` / `export type`) — but do not add a *value* import from `@bazilion/daemon` (or any daemon-internal path) to the mobile tree, or the bundle will explode.
+
+- **`apps/cli`** — thin citty-based CLI. Every subcommand except `serve` talks to the daemon over HTTP via `@bazilion/client`. No direct DB access in the CLI's runtime path. The two filesystem-level commands are: `serve` (boots `apps/daemon` directly — the daemon then auto-bootstraps `~/.bazilion`); `uninstall` (two-tier teardown: data wipe vs. full — operates on the filesystem so it works even when the daemon isn't running). Local helpers `apps/cli/src/paths.ts` (`resolveCliPaths`) and `apps/cli/src/auth-file.ts` (`readAuthFile` + `AuthFile` type) duplicate just enough of the daemon's path/auth utilities for these filesystem-touching commands. The web UI runs separately during dev: `cd apps/web && pnpm dev`. Remote daemon is opt-in via `BAZILION_SERVER` + `BAZILION_TOKEN` env vars; otherwise the client reads `auth.json` and hits `http://127.0.0.1:4321`.
+
+- **`apps/daemon`** — Hono on `@hono/node-server`, binds `127.0.0.1:4321` by default (`HOST`/`PORT` env override). Owns all server-side code under one roof:
+  - `src/index.ts` — entry: eagerly calls `getCtx()` so the bootstrap message + auth.json land before the port binds, then starts Hono.
+  - `src/lib/` — daemon-only glue: `ctx.ts` (singleton + self-bootstrap), `middleware-auth.ts`, `auth.ts`, `agent-cancel.ts`, `agent-id.ts`, `agent-turn.ts`, `api-key.ts`, `cron.ts`, `messaging-host.ts`, `scheduler.ts`.
+  - `src/routes/` — HTTP routes by resource family: `agents.ts` (CRUD + group + skills + triggers + messages + sessions + chat NDJSON + `/cancel`), `groups.ts` (CRUD + USER.md + per-group shared memory at `/api/groups/:slug/memory*`), `profiles.ts`, `skills.ts`, `triggers.ts`, `messages.ts`, `config.ts`, `auth-login.ts` (ChatGPT OAuth + `/providers/test` + `/login`), `misc.ts` (`/health`, `/backup`, `/tokens`).
+  - `src/core/` — what used to be `packages/core`: SQLite schema + migrations (`db/`), repos (`repos/`), domain ops (`agent/`, `group/`, `profile/`, `skills/`), `paths.ts`, `secrets.ts`, `services.ts`, `availableModels.ts`. Barrel export at `src/core/index.ts`.
+  - `src/runtime/` — what used to be `packages/runtime`: pi-coding-agent integration (`pi/`), provider adapters (`providers/`), memory backends (`memory/`), Bazilion-specific tools (`tools/`), per-turn worker subprocess (`worker/{entry,spawn,ipc-protocol}.ts`), heartbeat helpers (`auto-reply/`), OpenAI Codex OAuth (`auth/`). Barrel export at `src/runtime/index.ts`.
+  - Auth + first-run middleware (`src/lib/middleware-auth.ts`) gates every route; public paths whitelisted inside the middleware. The daemon installs its own SIGINT/SIGTERM handlers and shuts the HTTP server gracefully.
+- **`apps/web`** — TanStack Start (React 19 + Vite 7) frontend, **daemon-only client**. The canonical end-user UI. File-based routes under `src/routes/`: `__root.tsx` (root layout + `beforeLoad` auth gate), `index.tsx`, `login.tsx`, `welcome.tsx`, `agents/{index,$id/{index,inbox,triggers}}.tsx`, `profiles/{index,$id}.tsx`, `groups/{index,$id/{index,memory}}.tsx`, `skills/index.tsx`, `config/{index,services,tokens}.tsx`, `api/$.ts` (catch-all proxy). Tailwind v4 (CSS-first) + shadcn/ui. SSR loaders use `apps/web/src/lib/daemon-client.ts` (server-only) inside `createServerFn` handlers; that helper reads the request's `bz_token` cookie and forwards it as `Authorization: Bearer …` to `http://127.0.0.1:4321` (overridable via `BAZILION_DAEMON`). Browser fetches hit relative `/api/*` URLs that pass through the catch-all reverse proxy (cookie→bearer translation, streaming-capable for chat NDJSON). The dev server binds `WEB_PORT` (default 4322) — pair with `bazilion serve` on 4321. **CLI/web parity is mandatory**: every HTTP endpoint must have both a CLI surface and a web UI surface. Chat markdown is rendered via `marked` + DOMPurify; styles for the `.md-content` class live in `apps/web/src/styles.css` (without them, Tailwind preflight strips list markers, header sizes, code styling, etc).
+
+### SQLite driver
+
+`apps/daemon/src/core/db/client.ts` uses `node:sqlite` (Node 22+ built-in). `node:sqlite` has no callable `transaction()` wrapper, so the wrapper implements manual `BEGIN/COMMIT/ROLLBACK` in its `transaction()` method. Don't look for a `bun:sqlite` fallback — the project is Node-only.
+
+### On-disk layout
+
+State lives in `~/.bazilion/` (overridable via `$BAZILION_HOME`):
+
+```
+~/.bazilion/
+  bazilion.db                  # ALL DB state: entities + secrets + config (encrypted) + tokens
+  auth.json                    # {token, remote?} — bootstrap bearer + optional CLI remote target
+  groups/<slug>/               # collaboration root, mounted as cwd; may be a symlink (--link)
+    memory/                    # group-shared qmd index (.qmd-index.sqlite + markdown notes)
+    ... project files / work product ...
+  agents/<id>/                 # agent's PRIVATE home — strictly outside the group tree
+    SOUL.md / IDENTITY.md / AGENTS.md / TOOLS.md / HEARTBEAT.md / [BOOTSTRAP.md]
+    sessions/<sessionId>.jsonl # pi's append-only transcript
+    agent.json
+  profiles/<id>/               # profile templates
+  skills/<name>/SKILL.md       # installed skills
+  logs/
+```
+
+Path resolution is centralized in `apps/daemon/src/core/paths.ts`. The `Paths` struct has `home`, `db`, `authFile`, `profilesDir`, `agentsDir`, `groupsDir`, `skillsDir`, `logsDir`, plus `agentDir(id)` / `groupDir(slug)` / `profileDir(id)` / `skillDir(name)` computed helpers. The CLI has its own minimal `apps/cli/src/paths.ts` (`resolveCliPaths` returns just `{home, authFile}`) for the filesystem-level commands (`uninstall`, `backup`, `login`, `token show-local`) — they don't need the full struct. **There is no longer a `configFile` field — `config.json` and `secrets.enc` were collapsed into the DB.** `bazilion uninstall` mirrors this layout as a two-tier teardown: data tier = DB + `profiles/` + `agents/` + `groups/`; full wipe adds `auth.json`, `logs/`, `skills/`. Symlinked groups (registered with `--link`) only have the slot under `~/.bazilion/groups/` removed; the symlink target is never touched.
+
+### Group registration
+
+Groups always live at `~/.bazilion/groups/<slug>/`. The CLI (`bazilion group add <slug> [--link <target>]`) and the web `/groups` create form pass only the slug + optional name + optional link target; the daemon decides where the slot goes. `--link <abs-path>` materializes the slot as a symlink to an existing directory (the "agents working on my existing project tree" path); the target must exist and be a directory. Without `--link`, a fresh real directory is created. `groupRepo.get/list/insert(db, ..., paths)` derive `Group.path` from `paths.groupDir(id)` at read time — there is no `path` column anymore.
+
+### Memory model
+
+Memory is **per-group**, shared across every agent in the group. The qmd backend lives at `<group.path>/memory/`; each turn's worker calls `qmdBackend(join(agent.group.path, 'memory'))`. The `memory_*` tool descriptions explicitly tell the LLM the store is shared and direct personal notes (persona quirks, preferences) to `home_write IDENTITY.md` instead. The schema's per-agent memory dir is gone — `spawnAgent` only creates `agents/<id>/sessions/`. External surfaces match the ownership: HTTP at `/api/groups/:slug/memory*`, web UI at `/groups/:slug/memory`, CLI at `bazilion memory <write|read|list|search|rm> <group-slug> ...`. There are no `/api/agents/:id/memory*` routes — clients always address the group.
+
+### Worker subprocess + IPC
+
+Every chat turn runs in its own Node subprocess (`apps/daemon/src/runtime/worker/{entry,spawn,ipc-protocol}.ts`). The daemon's `apps/daemon/src/lib/agent-turn.ts:runAgentTurn`:
+1. Resolves the agent + provider gate + merged secrets env in-process (the worker no longer holds a SQLite handle).
+2. Pre-fetches the OAuth access token for `openai-codex` agents via `apps/daemon/src/lib/api-key.ts:resolveAgentApiKey` (env-key providers return `{}`).
+3. Spawns the worker with `stdio: ['pipe', 'pipe', 'inherit', 'ipc']` — the IPC channel is what makes messaging tools work without a worker DB handle.
+4. Sends `{agent, message, enabledProviders, apiKey?}` on stdin.
+5. Line-parses NDJSON `ChatFrame`s from worker stdout and yields them.
+6. Services worker `process.send({type:'rpc', method, args, id})` calls (the messaging-tool RPCs) by dispatching to `apps/daemon/src/lib/messaging-host.ts:createDbMessagingHost(db)` and replying with `child.send({type:'rpc-reply', id, ok, result|error})`.
+
+`SessionEvent` types: `user_message` / `assistant_message` / `assistant_delta` / `tool_call` / `tool_result` / `tool_error` / `error`. `ChatFrame` shapes: `{kind:'event', event}` / `{kind:'done', messages}` / `{kind:'fatal', error}`. **There is no `runId`, no `runs` table, no `events` table** — those were dropped along with the per-run audit metadata layer; pi's session JSONL files are the canonical transcript and the only persistent record of what an agent has said.
+
+Cancellation: keyed by **agentId** (not runId). The daemon's `apps/daemon/src/lib/agent-cancel.ts` registers an `AbortController` per active agent on each `runAgentTurn` start; `POST /api/agents/:id/cancel` aborts the controller, which SIGTERMs the worker (3 s grace → SIGKILL); the child's own SIGTERM handler aborts its internal controller so pi unwinds the provider fetch and emits an `error` event with `error: 'cancelled'` before exiting. CLI: `bazilion agent cancel <id>`. The worker also calls `process.disconnect()` in its `finally` so the IPC channel doesn't pin the event loop alive after the turn settles.
+
+See `docs/agent-engine.md` for the full turn-loop walkthrough.
+
+### Providers
+
+Model strings are `provider:model` (e.g. `lmstudio:my-loaded-model`, `anthropic:claude-opus-4-6`, `gemini:gemini-2.0-flash-exp`, `openai-codex:gpt-5.3-codex`). `createProviderRegistry` + `loadProviderConfigFromEnv` in `apps/daemon/src/runtime/providers/registry.ts` resolve strings to `{ provider, model }`. Credentials come from env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `LMSTUDIO_URL`/`LMSTUDIO_API_KEY`, `OLLAMA_URL`); plain API-key providers never touch the DB. The daemon's `mergeSecretsIntoEnv(db, authToken)` layers DB-stored secrets + plaintext config over `process.env` — this happens **server-side** per API request (chat, provider test, health) and again per worker spawn (the merged env is passed via `child_process.spawn`'s `env` option).
+
+**`openai-codex`** is the OAuth exception: credentials live as a JSON `{refresh, access, expires}` blob under the `OPENAI_CODEX_OAUTH` row of the `secrets` table. The provider registry's `apiKey` field is invoked as an async supplier so refreshes happen lazily on each chat() without rebuilding the cached Provider instance. Pass `{db, authToken}` as the second arg to `loadProviderConfigFromEnv(env, oauth?)` to enable it. For the worker subprocess specifically, `runAgentTurn` pre-fetches the initial access token via `resolveAgentApiKey` and passes it through `WorkerInput.apiKey` → `createBazilionSession({apiKey})`. The worker doesn't have a refresher wired — long turns that exceed the JWT lifetime fail; the daemon-side compact/context paths get full lazy refresh because they pass `withRefresher: true`.
+
+### Secrets and config
+
+`secrets.enc` and `config.json` are gone. The DB has two tables:
+
+- **`secrets(key TEXT PK, envelope TEXT NOT NULL, updated_at INTEGER)`** — AES-256-GCM envelopes (salt+iv+tag+data hex JSON), one row per env-var-shaped key (`ANTHROPIC_API_KEY`, `OPENAI_CODEX_OAUTH`, …). Encryption key derived from `auth.json`'s `token` via PBKDF2-SHA256 100k. Same crypto as the previous file-based store; only the storage medium changed. Threat model is unchanged: anyone who can read both `bazilion.db` *and* `auth.json` can decrypt — the encryption guards against accidental exposure (cat'd dumps, screenshares), not against filesystem read.
+- **`config(key TEXT PK, value TEXT NOT NULL, updated_at INTEGER)`** — plaintext for env-var-shaped values that don't need confidentiality (server URLs, region slugs, project IDs). The `CONFIG_KEYS` allowlist (derived from `services.ts`) is enforced in `repos/config.ts` on writes.
+
+API in `apps/daemon/src/core/`: `openSecrets(db, password)` and `openConfig(db)` (ConfigStore + SecretsStore types). The daemon caches the auth token in `getCtx().authToken` so all routes can call `mergeSecretsIntoEnv(db, authToken)` without re-reading `auth.json`.
+
+## Conventions
+
+- Biome formatter: single quotes, no semicolons, trailing commas, 2-space indent, 100-col width.
+- TS is strict with `noUncheckedIndexedAccess` and `verbatimModuleSyntax`. `.ts` extensions are required on all relative imports (`allowImportingTsExtensions: true`) — `tsx` and Vite both handle it.
+- `apps/web/` is excluded from the root `tsconfig.json` and from biome (it has its own Vite/TanStack-managed tooling). Run `pnpm --filter @bazilion/web typecheck` for web-only TS checks. The whole-tree `typecheck` intentionally skips it.
+- Migrations are numbered SQL files in `apps/daemon/src/core/db/migrations/`. The schema is consolidated into a single `0001_init.sql` (the project is alpha; we wiped the DB and collapsed the prior chain on every shape change rather than maintaining an ALTER chain). Add new migrations as new numbered files going forward; the runner is idempotent and runs from the daemon's self-bootstrap (`apps/daemon/src/lib/ctx.ts:bootstrap()`) on every startup. Existing installs pick new files up automatically.
+
+## Already-shipped invariants (don't re-implement)
+
+- **Daemon = sole owner of `~/.bazilion`** — the worker subprocess delegates anything DB-backed (messaging tools, provider gate, agent resolution, secrets) back to the daemon over Node IPC + stdin. There is no per-worker SQLite handle.
+- **Groups = single filesystem root + USER.md + roster + shared memory.** One agent → one group. `groups.user_md` is a DB column (agents can't clobber it via `write`/`edit`). Groups always live under `~/.bazilion/groups/<slug>/` (real dir or symlink via `--link`).
+- **Memory is group-shared.** `qmdBackend(group.path/memory)` — every member writes to and reads from the same store. Personal notes go to `IDENTITY.md` via `home_write`.
+- **No runs/events tables, no stats CLI.** The runs/events audit layer was dropped in favor of pi's session JSONL files (which are the authoritative transcript). There is no `bazilion run list/show/cancel/prune` and no `bazilion stats`. Cancel is `bazilion agent cancel <id>` (keyed by agentId).
+- **Bootstrap auth lives in `auth.json`.** The daemon reads it once at startup (`getCtx().authToken`) and uses it as the PBKDF2 seed for the secrets table. The CLI reads it as its loopback bearer. The `bootstrap` row in `web_tokens` cannot be revoked — `DELETE /api/tokens/:id` rejects a hash match against the auth token.
+- **First-run gate** — `isSetupComplete(db)` returns true iff at least one enabled provider has ≥1 curated model. Web middleware redirects non-API routes to `/welcome` while the gate is closed; API routes return 409. Allowed prefixes during setup: `/welcome`, `/login`, `/config`, `/api/config`, `/api/auth`, `/api/health`, `/api/login`. Crossing the threshold triggers `ensureSetupSeeded(db, paths)` which creates the `default` profile (skillsMode: `'all'`) + `default` group (at `~/.bazilion/groups/default/`).
+- **Spawn-time skill override is gone.** Skills come from the profile only — `skillsMode: 'all'` attaches every installed skill at spawn, `'selected'` uses `profile_default_skills`. Per-agent tweaks happen post-spawn via `bazilion agent skill add/rm` (or the per-agent skills card on the detail page).
+- **Web client constants live in `apps/web/src/lib/wire-constants.ts`** (`DEFAULT_GROUP_ID`, `DEFAULT_PROFILE_ID`, `REASONING_LEVELS`). `apps/web/src/lib/daemon-client.ts` is server-only — Vite's import-protection rejects it from any client-bundled module.
+- **OpenClaw skill model: prompt-only.** Skills under `~/.bazilion/skills/<name>/` get their SKILL.md body injected into the system prompt of every agent they're attached to; helper scripts run via the agent's generic `bash` tool. No framework `entry:` extension, no trust gate.
+- **qmd memory backend** (`apps/daemon/src/runtime/memory/qmd.ts`) — wraps `@tobilu/qmd`'s `searchLex` (BM25) for all memory routes. One `.qmd-index.sqlite` per group. Hybrid/vector paths are intentionally not enabled (pulls `node-llama-cpp` and multi-GB GGUF models; excluded in `pnpm.onlyBuiltDependencies`).
+- **Heartbeats / cron triggers** (`agent_triggers` table; `apps/daemon/src/lib/scheduler.ts`) — in-process tick loop (default 5s, `BAZILION_SCHEDULER_TICK_MS`; disable with `BAZILION_SCHEDULER=off`) pinned to `globalThis[Symbol.for('bazilion.scheduler')]`. Interval kind uses `last_fired_at + every ≤ now` with `created_at` as baseline; cron kind parses 5-field expressions via `apps/daemon/src/lib/cron.ts`. Firing reuses `runAgentTurn`; `last_fired_at` is updated *before* the run kicks off so a restart mid-fire doesn't double-trigger. CLI: `bazilion trigger add|list|rm|enable|disable`.
+- **Inbox / messaging surfaces** — the `send_message` / `read_inbox` / `wait_for_reply` tools (`apps/daemon/src/runtime/tools/messaging.ts`) are wired with `MessagingHost` injection: in the daemon (compact/context routes) the host is `createDbMessagingHost(db)`; in the worker the host is `createIpcMessagingHost()` which proxies every method through Node IPC. Outside-the-loop surfaces: `GET /api/agents/:id/messages?unread=1` (list), `POST /api/agents/:id/messages` (now accepts `replyTo`), `GET|PATCH /api/messages/:id` (detail + mark-read). CLI: `bazilion inbox list <agent> [--unread]`, `inbox show <id>`, `inbox read <id>`. Web: `/agents/:id/inbox`.
+- **`web_fetch` hardening: Readability + markdown + cache + SSRF guard** — `@mozilla/readability` over `linkedom`, output as markdown (or text via `extract_mode`). SSRF guard at `apps/daemon/src/runtime/tools/web-ssrf.ts` blocks loopback/private/link-local + DNS rebinding (re-validates resolved IPs, pins them into undici's `Agent.connect.lookup`). 15-min in-memory LRU per `${mode}|${url}` (100-entry cap). UA spoofs desktop Safari. 20s default timeout, 3 max redirects.
+- **ChatGPT OAuth / `openai-codex` provider** — credentials in `secrets:OPENAI_CODEX_OAUTH`. CLI runs the loopback flow (port 1455) client-side and PUTs credentials to `/api/auth/openai`; web `/config` has a "Connect ChatGPT" card. `apps/daemon/src/lib/api-key.ts:resolveAgentApiKey` is the single helper every session-creating call site uses to pre-fetch the access token; for daemon-side sessions it also wires a refresher for mid-turn JWT swaps. Worker turns don't get the refresher today (they'd need a new IPC method).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrizio Rullo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# bazilion
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Multi-agent runtime inspired by [OpenClaw](https://docs.openclaw.ai). Profiles are templates, agents are instances spawned from a profile into a single group (the collaboration context — one filesystem root, one USER.md, one roster, one shared memory), skills attach on the fly, and agents can talk to each other through a DB-backed mailbox.
+
+Local-only. TypeScript + Node monorepo (pnpm + tsx + vitest). The web UI lives at `apps/web` (TanStack Start + React 19 + Tailwind v4 + shadcn/ui) and pairs with the standalone Hono daemon at `apps/daemon`. The CLI talks over HTTP, so keep `bazilion serve` running while you work in another terminal.
+
+## Status
+
+Whole-run subprocess isolation with worker↔daemon Node-IPC for messaging, ChatGPT OAuth, qmd memory (group-shared), scheduler/triggers, profile skills mode, and groups (one-to-one agent membership). The daemon is the **single owner of `~/.bazilion`** — config + secrets live in the SQLite DB, the only other file at the root is `auth.json` (the bootstrap bearer). See `docs/architecture.md` for the engineer-to-engineer reference.
+
+## Quickstart
+
+```sh
+# Install dependencies (Node 22.12+ and pnpm 10+ required)
+pnpm install
+
+# Start the daemon — on first run it auto-bootstraps ~/.bazilion
+# (creates dirs, runs migrations, mints the bootstrap token, writes auth.json).
+# The bootstrap message prints the token before the HTTP port binds.
+pnpm tsx apps/cli/src/index.ts serve
+
+# In another terminal, start the web UI (Vite dev server on 4322)
+cd apps/web && pnpm dev
+# → http://127.0.0.1:4322 — paste the bootstrap token to log in
+```
+
+Open `http://127.0.0.1:4322` in a browser. On a fresh install every page redirects to `/welcome` until you finish first-run setup: enable a provider on `/config` and list at least one model for it. The moment both conditions hold, a `default` profile + `default` group (at `~/.bazilion/groups/default/`) are auto-created wired to that model. The default profile uses `skillsMode: 'all'` so spawned agents inherit every installed skill out of the box. The homepage unlocks with a one-click spawn dropdown.
+
+From there:
+
+```sh
+# Homepage: click "+ new ▾" in the sidebar and pick the default profile to
+# spawn an agent, or select any other profile you've created.
+
+# From the CLI — one-shot or interactive:
+pnpm tsx apps/cli/src/index.ts agent spawn --profile default --name first
+# → spawned agent <uuid> (first)
+
+pnpm tsx apps/cli/src/index.ts agent chat <uuid>               # readline REPL
+pnpm tsx apps/cli/src/index.ts agent chat <uuid> --message "say hi"
+```
+
+Credentials can also come from the environment if you'd rather not use `/config` (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `LMSTUDIO_URL`/`LMSTUDIO_API_KEY`, `OLLAMA_URL`, etc.) — but you still need to enable the provider and list its models in the web UI (or via the provider-state / provider-models APIs) to clear the first-run gate.
+
+## CLI commands
+
+```
+bazilion serve [--port N] [--host H]       # boot the daemon (auto-bootstraps on first run; HTTP API on 4321)
+bazilion uninstall [--yes] [--all]         # wipe state (two-tier: data vs full)
+bazilion doctor                            # diagnose your install
+bazilion auth openai login|logout|status   # ChatGPT OAuth (Plus/Pro/Team accounts)
+bazilion profile create|list|show|edit|update|delete   # manage profile templates
+bazilion group add|list|rm                 # register groups (always under ~/.bazilion/groups/<slug>/)
+bazilion group user-md show|set|clear      # per-group USER.md (read-only to agents)
+bazilion agent spawn|list|show|archive|unarchive|delete  # agent lifecycle
+bazilion agent edit <id> [--model …] [--reasoning …]    # patch agent settings
+bazilion agent chat <id> [--message X]     # interactive REPL or one-shot
+bazilion agent cancel <id>                 # abort an in-flight turn
+bazilion agent move <id> <group>           # move an agent to a different group
+bazilion agent skill add|rm <id> <name>    # attach/detach a skill on an agent
+bazilion agent chat-reset|chat-trim|chat-context|chat-compact <id>
+bazilion skill list|import|rm              # skill library (import --from openclaw)
+bazilion memory write|read|search|list|rm <agent>  # group-shared memory accessed via the agent
+bazilion send <from> <to> <message>        # mailbox send
+bazilion inbox list|show|read              # inspect agent inboxes
+bazilion trigger add|list|rm|enable|disable  # heartbeats / cron triggers
+bazilion provider list|enable|disable|models|test    # provider config + smoke test
+bazilion config get|set                    # service config (URLs, IDs, secrets)
+bazilion login --server URL --token T      # save a remote daemon's coordinates
+bazilion token create|list|revoke|show-local         # web tokens for API/CLI clients
+bazilion backup create [output.tar.gz]     # tar ~/.bazilion to a file
+bazilion backup restore <file.tar.gz>      # extract a backup (stop the daemon first)
+bazilion completion bash|zsh|fish          # print a shell completion script
+```
+
+## Concepts
+
+- **Profile** — a template (`SOUL.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`, `HEARTBEAT.md`, optional `BOOTSTRAP.md`, default model, skills mode + default skills). Profiles are agent classes. `skillsMode: 'all'` attaches every installed skill at spawn, `'selected'` uses the curated `defaultSkills` list. The auto-seeded `default` profile uses `'all'` so a fresh install ships with every skill wired up; user-created profiles default to `'selected'`. Delete `default` freely if you'd rather only keep your own.
+- **Group** — a collaboration context: one filesystem root, one USER.md, one roster, one shared memory. Every agent belongs to exactly one group, chosen at spawn time. The agent's coding tools (`read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`, supplied by [pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent)) are rooted at the group directory. USER.md is read-only to agents — edit it via `bazilion group user-md set` or the web UI. First-run setup seeds a `default` group at `~/.bazilion/groups/default/`. Groups always live under `~/.bazilion/groups/<slug>/`; pass `--link <existing-path>` to `bazilion group add` to materialize the slot as a symlink to your existing project tree instead of as a fresh directory.
+- **Agent** — an instance spawned from a profile into a group. Has a private home (`~/.bazilion/agents/<id>/` — its copy of the templates, plus pi's append-only session JSONL under `sessions/`) reachable via the `home_*` tools, and one group membership reachable via the coding tools. UUIDs as ids.
+- **Skill** — a directory under `~/.bazilion/skills/<name>/` with a `SKILL.md` (standard OpenClaw / Anthropic agent-skill format). Imported via `bazilion skill import --from openclaw` (or any path). The body is injected into the system prompt of every agent the skill is attached to; helper scripts shipped alongside the markdown are invoked by the agent via its generic `bash` tool (no framework-level entrypoint and no trust gate — see CLAUDE.md for why we removed both).
+- **Memory** — **group-shared** BM25 index rooted at `<groupPath>/memory/`. Every agent in the group reads + writes the same store. The current backend is `qmdBackend` (BM25 over markdown via [@tobilu/qmd](https://github.com/tobi/qmd)). Use it for project knowledge — codebase notes, decisions, things the user told you about the work; for personal notes about an agent (preferences, persona quirks), use `home_write` on `IDENTITY.md` instead.
+- **Mailbox** — `messages` table. Agents talk to each other via `send_message` / `read_inbox` / `wait_for_reply` tools, via `bazilion send` from the CLI, or from outside the loop: `bazilion inbox list <agent> [--unread]`, `bazilion inbox show <id>`, `bazilion inbox read <id>`, or the web UI at `/agents/<id>/inbox`. The worker delegates these tool calls to the daemon over Node IPC — workers don't hold their own SQLite handle.
+- **Trigger** — a heartbeat (interval in seconds) or cron expression that periodically wakes an agent with a stored message. An in-process scheduler ticks every 5 s (overridable via `BAZILION_SCHEDULER_TICK_MS`; disable with `BAZILION_SCHEDULER=off`) and fires due triggers through the same code path as user chat. Example: `bazilion trigger add <agent> --every 300 --message "check your inbox"`.
+
+## Tree
+
+```
+bazilion/
+├── docs/                         # engineer-to-engineer references
+│   ├── architecture.md           # components, flows, invariants
+│   └── agent-engine.md           # the LLM turn loop, end to end
+├── apps/
+│   ├── cli/                      # bazilion binary
+│   ├── daemon/                   # Hono HTTP API (booted by `bazilion serve`)
+│   ├── web/                      # TanStack Start UI (pairs with apps/daemon)
+│   └── mobile/                   # Expo / React Native app (LAN/Tailscale pairing)
+└── packages/
+    ├── api-types/                # hermetic HTTP/IPC wire types (zero deps)
+    └── client/                   # cross-origin HTTP client used by CLI + mobile
+```
+
+The daemon's data layer (`apps/daemon/src/core/`: DB, repos, profile/agent/group ops, skills) and LLM/runtime stack (`apps/daemon/src/runtime/`: providers, tools, memory, worker subprocess) live inside the daemon — they're not separate packages.
+
+## Tests
+
+```sh
+pnpm test             # vitest across the whole tree
+pnpm typecheck        # tsc --noEmit on the non-web tree
+pnpm lint             # biome
+pnpm format           # biome --write
+```
+
+## ChatGPT OAuth (use your ChatGPT Plus/Pro/Team account)
+
+Bazilion has two OpenAI integrations. The classic one (`openai` provider) authenticates with an API key and hits `api.openai.com`. The second (`openai-codex` provider) signs in with your ChatGPT account via OAuth and talks to the ChatGPT backend that Codex CLI uses — so Plus/Pro/Team accounts can run chat turns against `gpt-5.x` / `gpt-5.x-codex` models inside Bazilion the same way they do in Codex.
+
+```sh
+# CLI: runs the browser flow locally (loopback on :1455), then uploads the
+# resulting credentials to the server. Works even against a remote bazilion.
+bazilion auth openai login
+bazilion auth openai status        # connected? when does the access token expire?
+bazilion auth openai logout        # wipe stored credentials
+
+# Web UI: /config has a "Connect ChatGPT" card that does the same thing, but
+# spawns the browser on the server's machine (fine when you're local; use the
+# CLI from a remote client).
+```
+
+After connecting, enable `openai-codex` on `/config` and curate at least one model (e.g. `gpt-5.1`, `gpt-5.1-codex-max`, `gpt-5.2-codex`, `gpt-5.3-codex`). Credentials are stored AES-256-GCM-encrypted in the daemon's `secrets` table (key derived from the bootstrap token in `auth.json`); the access token auto-refreshes via the stored refresh token.
+
+## Uninstalling
+
+```sh
+# Interactive — asks two y/N prompts (data-tier, then full-wipe)
+bazilion uninstall
+
+# Non-interactive equivalents
+bazilion uninstall --yes          # wipe DB + agent/profile/group data only
+bazilion uninstall --yes --all    # also remove auth.json, logs/, skills/
+```
+
+Two tiers: the **data tier** (`bazilion.db*`, `profiles/`, `agents/`, `groups/`) is the factory-reset path — useful during alpha when the DB schema moves. The **full wipe** (`--all`) additionally removes `auth.json`, logs, and the skill library, leaving nothing behind under `~/.bazilion/`. Symlinked groups (registered via `--link`) only have their slot under `~/.bazilion/groups/` removed; the symlink target is never touched.
+
+## Stack notes
+
+- **SQLite driver**: `node:sqlite` (Node 22+ built-in). Wrapped in `apps/daemon/src/core/db/client.ts` with a manual `BEGIN/COMMIT/ROLLBACK` `transaction()` helper since `node:sqlite` has no callable wrapper of its own.
+- **Daemon owns the DB**: workers spawned per turn don't hold their own SQLite handle. Anything they need at request time (agent record, provider gate, secrets) is pre-resolved by the daemon and passed via stdin; live messaging tool calls (`send_message` / `read_inbox` / `wait_for_reply`) round-trip back to the daemon over Node IPC (the `'ipc'` channel on `child_process.spawn`).
+- **Native modules**: qmd pulls `better-sqlite3` and a handful of tree-sitter grammars (small native compiles on install). `node-llama-cpp` is a qmd transitive dep but intentionally excluded from build in `pnpm.onlyBuiltDependencies` — qmd's BM25 search doesn't need it, and enabling it would require downloading multi-GB GGUF models.
+- **Skills format**: standard agent-skill `SKILL.md` (YAML frontmatter with `name` / `description`, free-form body). OpenClaw skills drop in unchanged via `bazilion skill import --from openclaw`.
+- **Session loop + coding tools**: [pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) owns the per-turn agent loop, transcript storage (JSONL session files under `~/.bazilion/agents/<id>/sessions/`), compaction, and the file-IO toolset (`read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`).
+- **LLM providers**: routed through [pi-ai](https://www.npmjs.com/package/@mariozechner/pi-ai) — Anthropic, OpenAI, OpenAI Codex (ChatGPT OAuth), Google AI Studio, Google Vertex, Azure OpenAI, AWS Bedrock, Mistral, Groq, Cerebras, xAI, Z.AI, Hugging Face, OpenRouter, Vercel AI Gateway, LM Studio, Ollama. Model strings are `provider:model`.
+
+## Exposing beyond loopback
+
+By default, `bazilion serve` binds `127.0.0.1:4321` — local-only. To use bazilion from another machine (Tailscale, LAN, etc.), put a TLS-terminating reverse proxy in front. Don't expose the daemon directly; it has no TLS and no rate limiting.
+
+```sh
+# On the server, bind to loopback (default) and keep the proxy local.
+bazilion serve
+
+# Mint a per-client token (plaintext shown exactly once — copy it now).
+bazilion token create "laptop"
+
+# On the client machine — stores the server + token in ~/.bazilion/auth.json.
+bazilion login --server https://bazilion.example.com --token <token>
+
+# Revoke when the client is lost or retired.
+bazilion token list
+bazilion token revoke <id>
+```
+
+Note: the bootstrap token (the row labelled `bootstrap`, written to `auth.json` by the daemon's first-run bootstrap) **cannot be revoked** from the API or web UI — revoking it would lock the local CLI out of its own daemon. Mint additional tokens for any other client.
+
+Minimal Caddyfile (`caddy run --config Caddyfile`):
+
+```
+bazilion.example.com {
+  reverse_proxy 127.0.0.1:4321
+}
+```
+
+Caddy handles the TLS cert via Let's Encrypt automatically. For Tailscale, point the hostname at your tailnet node and use Tailscale's MagicDNS + HTTPS certs. The `web_tokens` table + cookie check runs behind the proxy, so every request still needs a valid token — the proxy only adds transport security.
+
+If you *do* want the daemon to bind a non-loopback address directly (dev/test only), pass `--host 0.0.0.0` to `bazilion serve`. Anyone who can reach that port can try tokens, so do not ship it without a proxy.
+
+## What's deferred
+
+- **Hard skill sandboxing** — skills run with the user's full FS access (no seccomp / bubblewrap / containers). Bazilion is single-user local; skills under `~/.bazilion/skills/` are user-owned by definition. Revisit if a marketplace or multi-user install ever happens.
+- **qmd vector/hybrid search** — BM25 is wired; the semantic path (embeddings + LLM rerank) is disabled to avoid the multi-GB GGUF model download. Enable opt-in later.
+- **Mempalace memory backend** — out of scope for v1.
+- **`generate_image` / vision input** — the chat pane already renders markdown images, but agent-invokable image generation and user image uploads aren't wired.
+- **Worker-side OAuth refresh** — long worker turns that exceed the openai-codex JWT lifetime fail on refresh. The daemon-side compact/context paths still get lazy refresh; only the worker subprocess relies on the initial token carrying the whole turn. See `apps/daemon/src/lib/api-key.ts`.

package/apps/cli/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@bazilion/cli",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "bazilion": "./src/index.ts"
+  },
+  "dependencies": {
+    "@bazilion/api-types": "workspace:*",
+    "@bazilion/client": "workspace:*",
+    "@mariozechner/pi-ai": "^0.69.0",
+    "citty": "^0.1.6",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
+    "@types/qrcode-terminal": "^0.12.2",
+    "adm-zip": "^0.5.17"
+  }
+}

package/apps/cli/src/auth-file.ts

@@ -0,0 +1,18 @@
+import { existsSync, readFileSync } from 'node:fs'
+
+export interface AuthFile {
+  token: string
+  remote?: { server: string; token: string } | null
+}
+
+export function readAuthFile(authFile: string): AuthFile {
+  if (!existsSync(authFile)) {
+    throw new Error(`${authFile} not found. Start the daemon with \`bazilion serve\` first.`)
+  }
+  const raw = readFileSync(authFile, 'utf8')
+  const parsed = JSON.parse(raw) as Partial<AuthFile>
+  if (typeof parsed.token !== 'string' || !parsed.token) {
+    throw new Error(`${authFile} is missing the "token" field`)
+  }
+  return { token: parsed.token, remote: parsed.remote ?? null }
+}

package/apps/cli/src/client.ts

@@ -0,0 +1,37 @@
+import { type BazilionClient, createClient as createPackageClient } from '@bazilion/client'
+import { readAuthFile } from './auth-file.ts'
+import { resolveCliPaths } from './paths.ts'
+
+export type { BazilionClient } from '@bazilion/client'
+export { ApiClientError } from '@bazilion/client'
+
+export interface ClientConfig {
+  serverUrl: string
+  token: string
+}
+
+export function loadClientConfig(): ClientConfig {
+  const envUrl = process.env.BAZILION_SERVER
+  const envToken = process.env.BAZILION_TOKEN
+  if (envUrl && envToken) return { serverUrl: envUrl, token: envToken }
+
+  const paths = resolveCliPaths()
+  const auth = readAuthFile(paths.authFile)
+  // `bazilion login` writes `remote`; when present it targets another host
+  // (Tailscale, LAN). Env vars still win so CI / ad-hoc invocations can
+  // override without editing auth.json.
+  if (auth.remote?.server && auth.remote.token) {
+    return {
+      serverUrl: envUrl ?? auth.remote.server,
+      token: auth.remote.token,
+    }
+  }
+  return {
+    serverUrl: envUrl ?? 'http://127.0.0.1:4321',
+    token: auth.token,
+  }
+}
+
+export function createClient(cfg: ClientConfig = loadClientConfig()): BazilionClient {
+  return createPackageClient({ serverUrl: cfg.serverUrl, token: cfg.token })
+}

package/apps/cli/src/columnize.ts

@@ -0,0 +1,32 @@
+/**
+ * Render `rows` as space-aligned columns. All rows must have the same column
+ * count; empty cells are treated as `""` for width purposes. Column spacing is
+ * two spaces — wider than a tab, tighter than tabular CSV tooling expects.
+ *
+ * Used by list commands so `status` / `kind` / `name` columns don't jump when
+ * one row is `idle` (4) and another is `archived` (8). Does not truncate —
+ * long cells win the column width. Callers that want a bounded width should
+ * slice before passing.
+ */
+export function columnize(rows: string[][], gap = '  '): string[] {
+  if (rows.length === 0) return []
+  const colCount = rows[0]?.length ?? 0
+  const widths: number[] = new Array<number>(colCount).fill(0)
+  for (const row of rows) {
+    for (let i = 0; i < colCount; i++) {
+      const cell = row[i] ?? ''
+      const prev = widths[i] ?? 0
+      if (cell.length > prev) widths[i] = cell.length
+    }
+  }
+  return rows.map((row) =>
+    row
+      .map((cell, i) => {
+        // Don't pad the last column — trailing whitespace is pointless and
+        // breaks `| wc`-style pipes.
+        if (i === colCount - 1) return cell
+        return (cell ?? '').padEnd(widths[i] ?? 0)
+      })
+      .join(gap),
+  )
+}