@fabrika/builder 0.2.0

package/decisions/technologies/oblaka.md

@@ -0,0 +1,48 @@
+---
+id: oblaka
+kind: technology
+title: oblaka (Cloudflare IaC / bindings as code)
+slot: iac
+provides: [iac, binding-definitions, wrangler-generation]
+requires: [cloudflare]
+recommends: []
+conflicts: []
+npm: ["oblaka-iac@^0.0.18"]
+status: wip
+sources:
+  - where: "oblaka (repo) + `oblaka-iac` on npm (installed types)"
+    read: "The CURRENT binding API, programmatic deploy surface and how `bunx oblaka <file>` generates wrangler.jsonc. Read the live types — do not guess."
+  - where: "vozka packages/core + vozka-config"
+    read: "How Vozka materializes the same oblaka resource graph for production while an app keeps a thin local-dev shim."
+---
+
+# oblaka
+
+## What it is
+
+A TypeScript DSL for Cloudflare IaC: define the Worker + its bindings in
+`oblaka.ts`, run `bunx oblaka oblaka.ts` to **generate `wrangler.jsonc`**. One typed
+source of truth for Workers, D1, KV, R2, Queues, DO, Analytics Engine and cron.
+Vozka uses oblaka programmatically for production provisioning; standalone
+`oblaka.ts` remains useful as the local lopata config shim.
+
+## When & why to use
+
+- Any CF stack — declare bindings as code instead of hand-writing `wrangler.jsonc`.
+- A Vozka app — the resource builder in `vozka.config.ts` is still an oblaka
+  `Worker`; reuse it from the local shim rather than duplicating the graph.
+
+## Impacts & gotchas
+
+- **`wrangler.jsonc` is GENERATED — never hand-edit it.** Change `oblaka.ts` and regenerate.
+- Standalone/local shape: `define(({ env }) => buildWorker({ env, domain: undefined }))`,
+  where `buildWorker` is exported from `vozka.config.ts`. For a non-Vozka app,
+  build the `Worker` inline as before.
+- **Verify every binding constructor against the installed `oblaka-iac` types** — it's WIP and a stack may use bindings (Queue consumer, AE, cron) the constructor surface for which moves. If a binding type is missing, generate the wrangler entry per Cloudflare docs.
+- `vozka-config` and oblaka publish raw TypeScript in some versions; if the app's
+  main `tsc` excludes config files, validate them by actually materializing the
+  config and running a wrangler dry-run/config check.
+
+## Relationships — why
+
+- **requires `cloudflare`** — it exists to configure CF. Recommended by every CF binding decision (`d1`/`kv`/`r2`/`queue`/`durable-objects`/`cron-triggers`).

package/decisions/technologies/opice.md

@@ -0,0 +1,40 @@
+---
+id: opice
+kind: technology
+title: opice (AI-driven E2E browser tests)
+slot: e2e-tests
+provides: [e2e-browser-tests, acceptance]
+requires: []
+recommends: [bun]
+conflicts: []
+npm: ["@opice/harness@^0.6.1", "@opice/cli@^0.6.1"]
+status: wip
+sources:
+  - where: "opice (repo) + `@opice/harness` / `@opice/cli` on npm (installed types)"
+    read: "How browserTest/step/invariant work and how the harness runs under `bun test`. Read the installed types — do not guess."
+  - where: "The opice-* skills (opice-plan / opice-author / opice-batch / opice-reeval)"
+    read: "The authoring procedure: skeletons → authored steps → CI re-eval."
+---
+
+# opice
+
+## What it is
+
+The acceptance layer for fabrika: markdown scenarios → LLM-generated `*.test.ts`
+under `tests/browser/` → deterministic `bun test` runs. `browserTest` + `step` +
+`invariant`, with metadata (`url`, `seeds`, `roles`) that fabrika **induces issues
+from**.
+
+## When & why to use
+
+- Always, in a fabrika builder build — opice skeletons are the contract every issue satisfies; `url`/`seeds`/`roles` drive foundation-issue induction.
+
+## Impacts & gotchas
+
+- **Skeleton metadata is a contract**: `url` → a route must exist; `seeds: ['x']` → `seeds/x.sql` must exist; `roles` → an auth foundation. fabrika `induce` unions these.
+- Selector priority: **byRole → byLabel → getByText → el(testid)**. The app must be accessibility-first (every interactive element named, every section a heading) or opice-author has no stable selector.
+- Runs against the **running** dev server (`APP_URL`); `bunx opice test <file>` for one, `bun test tests/browser` for all. WIP — read installed types.
+
+## Relationships — why
+
+- Standalone (no hard tech deps) — it tests whatever stack the app is built on; runs under **`bun test`** (recommends `bun`) and pairs with `named-seeds` for the seed contract.

package/decisions/technologies/pletivo.md

@@ -0,0 +1,53 @@
+---
+id: pletivo
+kind: technology
+title: pletivo — Bun-native SSG (Astro-compatible) — fits the bun/non-vite preference
+slot: site-framework
+provides: [ssg, astro-compat, jsx-pages, content-collections, islands, file-routing]
+requires: [bun]
+recommends: [preact, tailwind]
+conflicts: [nuasite]
+npm: ["pletivo@^0.1", "@pletivo/astro-jsx-pages@^0.0.1"]
+status: experimental
+sources:
+  - where: "pletivo/README.md + CLAUDE.md"
+    read: "Compatibility matrix, project structure, and the critical invariants (island registry reset, JSON-serializable island props)."
+  - where: "pletivo/packages/pletivo/src/{index.ts,config.ts,build.ts}"
+    read: "Public exports (defineCollection/getCollection, PletivoConfig), the render loop, and page emission."
+  - where: "pletivo/packages/pletivo/src/runtime/{island.ts,hydration.ts}"
+    read: "Island registration/reset + client hydration strategies (load/idle/visible/media)."
+---
+
+# pletivo
+
+## What it is
+
+A **Bun-powered static site generator**, ~2× faster than Astro and a near drop-in for
+it: compiles `.astro` pages + JSX/TSX to static HTML at build, file-based routing
+(`src/pages/`), content collections (Zod), and **Preact islands** with multiple
+hydration strategies. Runs on **Bun** (not Node) — a natural fit for our bun /
+non-vite preference (builds with Bun's pipeline, no separate vite app server).
+
+## When & why to use
+
+- A **content-focused static site** (blog, docs, marketing) where Astro builds are too slow.
+- You want Astro compatibility (`.astro`, content collections) + lightweight Preact islands, on Bun.
+
+## When NOT to use
+
+- You need **SSR / per-request dynamic routes** → use a Workers SSR app (`react-router`) instead; pletivo is SSG-only (pre-declare dynamic routes via `getStaticPaths`).
+- A visual-CMS content site → `nuasite`.
+- Very large sites (>5k pages) or Node-only deps.
+
+## Impacts & gotchas
+
+- **Bun-locked** build/dev; CI needs Bun.
+- **Islands must be JSON-serializable props** (embedded in `data-props`); functions/Dates/circular refs break.
+- **Island registry must reset between pages** (`resetIslandRegistry()`) — the build does it; custom render paths must too, or island metadata bleeds across pages.
+- Client is **Preact**, not React (no React-only island libs).
+
+## Relationships — why
+
+- **requires `bun`** — it's a Bun CLI/runtime (no Node SSR).
+- **recommends `preact`** (islands) + **`tailwind`** (styling).
+- **conflicts `nuasite`** — same `site-framework` slot; pletivo = fast minimal SSG, nuasite = Astro + visual CMS. Pick one site approach.

package/decisions/technologies/postgres.md

@@ -0,0 +1,47 @@
+---
+id: postgres
+kind: technology
+title: PostgreSQL (relational database)
+slot: relational-db
+provides: [relational-db, sql, mutable-state, transactions]
+requires: []
+recommends: []
+conflicts: [d1]
+npm: []
+status: stable
+sources:
+  - where: "postgresql.org/docs + the driver you use (e.g. `pg`, `postgres`)"
+    read: "Connection/pooling model, transactions, and row-level security if you use it directly."
+  - where: "contember-oss/docker-compose.yaml + packages/database"
+    read: "A real Postgres-backed setup (Contember Engine) and a fluent query/pool layer over `pg`."
+---
+
+# PostgreSQL
+
+## What it is
+
+The general-purpose relational database for stacks that need a **full SQL server**
+(rich types, transactions, extensions, mature tooling) rather than edge SQLite.
+Required by `contember`; the default store when you run a **Node backend** instead
+of Workers + D1.
+
+## When & why to use
+
+- You adopt `contember` (it mandates Postgres) or any Node backend needing a real RDBMS.
+- You need Postgres-specific features (JSONB, full-text search, extensions, strong transactional guarantees) D1/SQLite lacks.
+
+## When NOT to use
+
+- **Cloudflare Workers-first** apps → use `d1` (edge SQLite, local-first, no server). Workers can't open a raw Postgres TCP connection without Hyperdrive/a proxy.
+- A small local-first app where SQLite is plenty.
+
+## Impacts & gotchas
+
+- You **run and operate a Postgres server** (managed service, container, or self-hosted) — connection strings, pooling, backups.
+- From Workers, direct connections need **Hyperdrive or an HTTP proxy**; the natural home is a long-lived Node process.
+- Migrations are yours (or your framework's, e.g. Contember's diff-generated ones).
+
+## Relationships — why
+
+- **conflicts `d1`** — same `relational-db` slot; one relational store per app. Postgres = server-side RDBMS, D1 = edge SQLite.
+- **required by `contember`** — its schema/migration/ACL layer is Postgres-specific.

package/decisions/technologies/preact.md

@@ -0,0 +1,44 @@
+---
+id: preact
+kind: technology
+title: Preact (small React-compatible UI framework)
+slot: ui-framework
+provides: [ui-framework, components]
+requires: []
+recommends: [tailwind]
+conflicts: [react]
+npm: ["preact@^10"]
+status: stable
+sources:
+  - where: "preactjs.com + installed preact types"
+    read: "The Preact 10 API, `preact/hooks`, and the differences from React (events, `jsxImportSource: preact`)."
+  - where: "pletivo islands + preactjs.com"
+    read: "Where Preact shows up in our stack: pletivo's islands run on Preact."
+---
+
+# Preact
+
+## What it is
+
+A ~4 KB React-compatible UI framework. Largely JSX/hooks-compatible with React but
+smaller, with subtle differences. In our stack, `pletivo`'s islands run on Preact.
+
+## When & why to use
+
+- You want a tiny client runtime (islands, embeddable widgets) — e.g. `pletivo` islands.
+- Bundle size on the client matters more than the React ecosystem's breadth.
+
+## When NOT to use
+
+- You need the full React ecosystem (`react-router`, `buzola`, `bindx`, Contember admin all assume React) → use `react`.
+
+## Impacts & gotchas
+
+- `jsxImportSource: preact` in tsconfig; `preact/hooks` for hooks. **Don't mix React and Preact in one bundle.**
+- **DOM-standard event names** (`onchange`, not React's `onChange`) — an easy bug when porting React code.
+- React-only libs (Suspense-dependent, `bindx`, RRv7) won't run on Preact.
+
+## Relationships — why
+
+- **conflicts `react`** — same `ui-framework` slot; one per app.
+- **recommends `tailwind`** for styling; used by `pletivo`'s islands (no hard requirer — it's the Preact option for island-style UIs).

package/decisions/technologies/propustka.md

@@ -0,0 +1,137 @@
+---
+id: propustka
+kind: technology
+title: Propustka — native login, authorization and audit
+slot: authz
+provides: [authentication, sso, authorization, audit, api-tokens]
+requires: [cloudflare, d1]
+recommends: [vozka, buzola]
+conflicts: [cloudflare-access, auth-password-kv]
+npm: ["@propustka/client@^0.0.6", "@propustka/core@^0.0.6"]
+status: wip
+sources:
+  - where: "propustka — README.md, architecture.md, packages/core/src/, packages/worker/src/"
+    read: "Native session/login architecture, app gates, token/JWKS contract, central human identity and D1 policy/audit model."
+  - where: "@propustka/client (installed packages/client/src/{session,client,fake,types}.ts)"
+    read: "The current PropustkaAuth, AuthContext, AppGates, setCookie/loginUrl and FakeIamClient surfaces. Version 0.x moves quickly; read the source."
+  - where: "propustka examples"
+    read: "Runtime gates, local operator context, SSO redirects, response cookies, schemas, and IAM bindings."
+---
+
+# Propustka
+
+## What it is
+
+The native identity, authorization and audit service for Cloudflare Workers apps.
+There is **no Cloudflare Access edge** in front of a native Propustka app.
+Propustka owns human SSO sessions, per-app permission tokens, `px_` service keys,
+authorization policy and audit logs.
+
+An app integrates over an `IAM` Worker-to-Worker service binding and uses
+`PropustkaAuth` as its single request-auth seam. `PropustkaAuth` applies ordered
+per-path gates, verifies cached permission JWTs locally against Propustka's JWKS,
+and only calls the binding when it must exchange a session/key or write audit.
+
+## When & why to use
+
+- An internal Cloudflare app needs human login plus role/scope-based permissions.
+- The same API supports logged-in people and `px_` service credentials.
+- You want a central people directory, app-defined roles/scopes, revocable keys
+  and an audit trail.
+- The target Cloudflare account already runs Propustka (normally alongside Vozka).
+
+## When NOT to use
+
+- The app is not a Cloudflare Worker; the integration is a service binding.
+- There are no real authz/audit needs and a central IAM dependency is unjustified.
+- The product requires app-owned signup/password recovery; use a product auth
+  system instead.
+- Strict hierarchical scopes are fundamental. Propustka scope dimensions are
+  flat; containment must be resolved by the app.
+
+## Runtime integration
+
+```ts
+import type { AppGates, IamRpc } from '@propustka/client'
+import { PropustkaAuth } from '@propustka/client'
+
+const gates: AppGates = {
+	rules: [
+		{ path: '/rpc', kind: 'service' },
+		{ path: '/rpc', kind: 'human' },
+	],
+}
+
+const result = await new PropustkaAuth(env.IAM as IamRpc, APP_ID, {
+	issuer: env.PROPUSTKA_URL,
+	gates,
+}).authenticate(request)
+
+if (!result.ok) {
+	return Response.json(
+		{ error: { message: result.reason, loginUrl: result.loginUrl } },
+		{ status: result.status },
+	)
+}
+
+if (!result.context.can('site.write', { type: 'site', value: siteId })) {
+	return new Response('Forbidden', { status: 403 })
+}
+
+ctx.waitUntil(result.context.audit({
+	action: 'site.write',
+	resourceType: 'site',
+	resourceId: siteId,
+}))
+```
+
+When `result.setCookie` is present, append it to the outgoing response. It is the
+short-lived per-app `px_token`; dropping it forces repeated session exchanges and
+can make login appear broken.
+
+## Gates and login behavior
+
+- `AppGates` are **runtime code**, not deploy-time schema. They replaced
+  Cloudflare Access policies and are passed directly to `PropustkaAuth`.
+- Rules are ordered. A common protected path has `service` first and `human`
+  second, so a present service key is terminal while a missing key falls through
+  to the browser session.
+- A `public` rule creates an anonymous context. A path matching no rule is denied
+  (`no_rule`) — native auth is fail-closed.
+- A human miss includes `loginUrl`. The SPA should redirect there and set its
+  return URL to the current page, with a short bounce guard so an unprovisioned
+  identity does not loop forever.
+
+## Authorization model
+
+- Keep action ids, scope dimensions and the app id as shared constants. Runtime
+  `can()` checks and Vozka's `AppSchema` must use the same vocabulary.
+- `can(action, scope?)` and `scopedTo(action, dimension)` are local pure checks on
+  the minted permission set. `scopedTo` returns `null` (all), `[]` (none), or an
+  exact list.
+- Audit is the operation that reaches the binding on the hot path; schedule it
+  with `ctx.waitUntil`.
+- The app's `schema` (actions/scopes/roles) is reconciled by Vozka during deploy.
+
+## Local development and opice
+
+Do not require a live IAM Worker locally. An explicit `DEV` var should select a
+deterministic app-local `AuthContext` for a known operator persona. Current
+`FakeIamClient` covers management methods such as principal listing and key
+issue/revoke; it is **not** the replacement for `PropustkaAuth.authenticate()`.
+
+Omit the external `IAM` service binding in the local resource graph when the
+local runtime cannot resolve it. Off-local, fail loudly if `IAM` or
+`PROPUSTKA_URL` is missing.
+
+## Relationships — why
+
+- **requires `cloudflare`** — request auth and audit use a Worker service binding.
+- **requires `d1`** — the separately deployed Propustka service stores identity,
+  policy, sessions and audit data in D1.
+- **conflicts `cloudflare-access`** — native Propustka replaces the Access edge;
+  combining both creates two competing login/gate systems.
+- **conflicts `auth-password-kv`** — Propustka owns login and sessions; do not add
+  a parallel app-owned password session.
+- **recommends `vozka`** for schema reconciliation and **`buzola`** for internal
+  app SPAs.

package/decisions/technologies/queue.md

@@ -0,0 +1,55 @@
+---
+id: queue
+kind: technology
+title: Cloudflare Queues (async buffering)
+slot: null
+provides: [message-queue, async-buffering]
+requires: [cloudflare]
+recommends: [r2, oblaka]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/queues (producer send, consumer queue() handler, batching, retries)"
+    read: "Producer .send()/.sendBatch(), the queue(batch, env) consumer handler shape, batch size/retry config."
+---
+
+# Cloudflare Queues
+
+## What it is
+
+Managed async message queue to **decouple requests/schedules from slow or bursty
+work**. A producer `env.QUEUE.send(msg)` returns fast; a consumer
+`queue(batch, env)` processes messages with retries — e.g. write payloads to R2,
+or run one bounded background audit while D1 tracks its lease/status.
+
+## When & why to use
+
+- Bursty/spiky ingest (error storms, webhooks) where the request must return immediately (202) and work happens async.
+- Batching expensive writes (R2 puts, D1 upserts) instead of doing them per-request.
+- Long-running background jobs that need retry and bounded concurrency without
+  tying their lifetime to an HTTP `waitUntil`.
+
+## When NOT to use
+
+- Work must complete before the response (synchronous result needed).
+- Trivial, low-volume writes — the queue is overhead.
+
+## Impacts & gotchas
+
+- Export a **`queue(batch, env)`** handler from the Worker alongside `fetch`. Check the lopata/RRv7 example for the exact export shape.
+- Delivery is **at least once**. Make the consumer idempotent; for long jobs use a
+  D1 lease/attempt token and explicit terminal states so a retry cannot run two
+  copies or overwrite a newer attempt.
+- Handle every message explicitly with `message.ack()` or `message.retry()` and
+  catch failures per message. An uncaught exception can retry the whole batch;
+  a message with no disposition is retried according to the consumer policy.
+- Configure batch size, timeout, retry delay, max retries, concurrency and
+  visibility timeout from the real job envelope. A single expensive job often
+  wants `maxBatchSize: 1`.
+- For ingest, return **202 fast** and let the consumer do R2 + D1. See
+  `write-split`. Do not force that batching shape onto one-job-per-message work.
+
+## Relationships — why
+
+- **requires `cloudflare`** — CF binding. **recommends `r2`** (the usual payload sink) and **`oblaka`** (declare producer + consumer).

package/decisions/technologies/r2.md

@@ -0,0 +1,41 @@
+---
+id: r2
+kind: technology
+title: Cloudflare R2 (object storage)
+slot: null
+provides: [object-storage, blobs]
+requires: [cloudflare]
+recommends: [oblaka, queue]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/r2 (Workers binding: get/put/delete, multipart)"
+    read: "The R2 binding API for storing/retrieving objects from a Worker."
+---
+
+# Cloudflare R2
+
+## What it is
+
+S3-compatible object storage with no egress fees. Used for **large/append-style
+payloads** — full event bodies, uploads, source maps — keyed by id. Bound as
+`env.R2`.
+
+## When & why to use
+
+- Storing payloads too big or too numerous for D1 rows (event bodies, files, source maps).
+- Write-heavy blob ingest, especially batched through a `queue`.
+
+## When NOT to use
+
+- Small structured records you query by field → `d1`. Hot small keys → `kv`.
+
+## Impacts & gotchas
+
+- Objects are addressed by key; design a stable key scheme (e.g. `events/<projectId>/<id>`).
+- Pair with `queue` for bursty writes: enqueue → consumer batches puts to R2 (keeps the request path fast). See `write-split`.
+
+## Relationships — why
+
+- **requires `cloudflare`** — CF binding. **recommends `oblaka`** (declare `R2Bucket`) and **`queue`** (buffer bursty payload writes).

package/decisions/technologies/react-router.md

@@ -0,0 +1,47 @@
+---
+id: react-router
+kind: technology
+title: React Router v7 (SSR on Workers)
+slot: router
+provides: [router, ssr, loader-action-data]
+requires: [react, vite]
+recommends: [d1]
+conflicts: [buzola]
+npm: ["react-router@^7.13", "@react-router/dev@^7.13", "@react-router/node@^7.13", "isbot@^5"]
+status: stable
+sources:
+  - where: "reactrouter.com (RRv7 SSR/loader/action) + installed package types"
+    read: "Current SSR/loader/action API and the EXACT import paths — they move between minors. Verify against the installed version."
+  - where: "lopata/examples/react-router/ — the canonical RRv7-SSR-on-Workers example"
+    read: "Worker entry, entry.server, route table wired against CF bindings. The #1 ground truth for this decision."
+---
+
+# React Router v7 (SSR on Workers)
+
+## What it is
+
+Full-stack React Router v7 doing **server-side rendering on the Worker**:
+`app/routes/*.tsx` with a server `loader`/`action` over CF bindings + a default
+component. Self-contained, no RPC/Contember layer — lopata's own example path.
+
+## When & why to use
+
+- Server-rendered app reading data directly in loaders from `context.env.DB` etc.
+- fabrika's default app architecture when SSR and route loaders fit better than a client-rendered SPA.
+
+## When NOT to use
+
+- A pure client SPA (no SSR), especially a Contember-style admin → `buzola`.
+
+## Impacts & gotchas — the load-bearing ones (anti-staleness)
+
+- **Worker entry** (`workers/app.ts`): `createRequestHandler` from **`react-router`** (NOT `@react-router/dev/server`) over `virtual:react-router/server-build`; `fetch` passes `{ env, ctx }` as the load context so loaders read `context.env.DB`. **This is the #1 thing stale memory gets wrong** — check the lopata example.
+- **SSR renderer** (`app/entry.server.tsx`): `renderToReadableStream` from **`react-dom/server.browser`** (NOT `react-dom/server`) + `<ServerRouter>`.
+- **Route table** (`app/routes.ts`): from `@react-router/dev/routes` — `export default [ index('routes/home.tsx'), route('cart','routes/cart.tsx'), … ]`. **Each route URL must match the opice skeleton `url` (contract).**
+- `react-router.config.ts`: `{ ssr: true }`. tsconfig: RRv7 typegen via `rootDirs` (`.react-router/types`).
+
+## Relationships — why
+
+- **requires `react` + `vite`** (it's a React framework with a vite plugin).
+- **recommends `d1`** — loaders/actions read/write D1 directly.
+- **conflicts `buzola`** — same `router` slot. RRv7 = SSR; buzola = SPA. One router per stack.

package/decisions/technologies/react.md

@@ -0,0 +1,37 @@
+---
+id: react
+kind: technology
+title: React (UI framework)
+slot: ui-framework
+provides: [ui-framework, components]
+requires: []
+recommends: [react-router, tailwind]
+conflicts: [preact]
+npm: ["react@^19", "react-dom@^19"]
+status: stable
+sources:
+  - where: "react.dev + installed react/react-dom types"
+    read: "Current React 19 APIs; for SSR-on-Workers note the server.browser render entry (see react-router)."
+---
+
+# React
+
+## What it is
+
+The UI framework for fabrika's generated apps (React 19). Paired with a router:
+`react-router` renders SSR on the Worker, while `buzola` builds a client SPA that
+the Worker can serve as static assets.
+
+## When & why to use
+
+- Default UI layer — the routers, opice selector conventions, and design-token mockups all assume React.
+
+## Impacts & gotchas
+
+- SSR on Workers renders via **`renderToReadableStream` from `react-dom/server.browser`** (NOT `react-dom/server`) — the Web Streams path. (Detail lives on `react-router`.)
+- Build accessible markup: every interactive element needs an accessible name (`<label>`/text/`aria-label`) so opice has stable selectors (see `opice`).
+
+## Relationships — why
+
+- **recommends `react-router`** (default SSR-on-Workers router; `buzola` is the SPA alternative, both require react) **+ `tailwind`** (styling).
+- **conflicts `preact`** — same `ui-framework` slot; `preact` is the smaller alternative (pletivo's islands run on it).

package/decisions/technologies/roj.md

@@ -0,0 +1,51 @@
+---
+id: roj
+kind: technology
+title: roj — agent SDK (@roj-ai/*) for building AI agents
+slot: agent-sdk
+provides: [agent-runtime, llm-orchestration, streaming, sessions, event-sourcing, plugins]
+requires: []
+recommends: [cloudflare, durable-objects, d1, r2, react]
+conflicts: []
+npm: ["@roj-ai/sdk@^0.1.18", "@roj-ai/transport@^0.1.18", "@roj-ai/client@^0.1.18", "@roj-ai/client-react@^0.1.18"]
+status: wip
+sources:
+  - where: "roj/CLAUDE.md + packages/sdk/src/index.ts"
+    read: "The plugin DSL, event sourcing, preset/agent builders, session management, and LLM provider surface (Anthropic/OpenRouter/mock)."
+  - where: "roj/packages/demo/"
+    read: "A full e2e example: preset + standalone server + React SPA + snapshot tests."
+---
+
+# roj
+
+## What it is
+
+An **agent SDK** (`@roj-ai/*`, the OSS successor to buresh): a TypeScript framework
+for multi-agent systems with persistent sessions, event sourcing, a plugin
+architecture (filesystem/shell/chat/limits/skills/…), and streaming LLM inference.
+Apps define **presets** (agents + plugins + system prompt), wire an LLM provider
+(Anthropic native, OpenRouter, or mock), and expose a REST/WebSocket API. It is
+LLM-provider-agnostic and host-agnostic. It can be composed with Workers, Durable
+Objects, WebSockets, D1, and R2 for a production deployment.
+
+## When & why to use
+
+- **Building AI agents/assistants** into an app (codegen, research, automation) with multi-turn, stateful tool calls.
+- You want **event-sourced** sessions (auditable, replayable) and pluggable tool/skill libraries without provider lock-in.
+
+## When NOT to use
+
+- **One-off inference** (single prompt→response) → use the Anthropic SDK / OpenRouter directly.
+- No multi-turn/stateful needs.
+
+## Impacts & gotchas
+
+- **Client/server split + async sessions** — agents run server-side; the client creates a session and streams updates over WebSocket. Plan UX for async + reconnection.
+- **LLM key handling** — provide and encrypt the provider key; never log it. The default uses Anthropic/Claude.
+- **Tool/sandbox security** — plugins execute shell/filesystem in a sandbox (E2B / `edvabe` locally); sanitize tool inputs.
+- **DO hibernation** — on CF, the in-memory runtime is rebuilt from the event log via an alarm; don't delete session records.
+
+## Relationships — why
+
+- **slot `agent-sdk`** — the agent layer; composes with any UI/backend.
+- **recommends `cloudflare` + `durable-objects`** (one DO per agent instance), **`d1`/`r2`** (session/artifact storage), **`react`** (`@roj-ai/client-react` chat UI). The SDK itself requires none of these — it runs on Bun/Node too. Pairs with `edvabe` for local sandboxed tool execution.

package/decisions/technologies/sentry.md

@@ -0,0 +1,49 @@
+---
+id: sentry
+kind: technology
+title: Sentry (error tracking)
+slot: error-tracking
+provides: [error-tracking, exception-capture, source-maps, session-replay]
+requires: []
+recommends: [observability]
+conflicts: []
+npm: ["@sentry/cloudflare", "@sentry/react", "@sentry/vite-plugin", "toucan-js"]
+status: stable
+sources:
+  - where: "Sentry Cloudflare Workers and React SDK documentation"
+    read: "SDK initialization, environment and release tags, trace propagation, logger integration, and error boundaries."
+  - where: "Sentry docs: Cloudflare Workers (@sentry/cloudflare or toucan-js), source-map upload (@sentry/vite-plugin / wrangler upload_source_maps), beforeSend + fingerprinting"
+    read: "Init options, source maps with SENTRY_AUTH_TOKEN, redaction, and fingerprinting for grouping."
+---
+
+# Sentry
+
+## What it is
+
+The error-tracking option: capture exceptions + stack traces (with source maps) and
+group them. On Workers via **`@sentry/cloudflare`** (or `toucan-js` for a lighter
+footprint), in the browser via **`@sentry/react`**, with source maps uploaded by
+**`@sentry/vite-plugin`** or wrangler's `upload_source_maps` (gated on
+`SENTRY_AUTH_TOKEN`). Plugs into `structured-logging` as a handler that forwards
+`logger.error` to `captureException` at warn+.
+
+## When & why to use
+
+- You want managed error aggregation + alerting (and optional browser session replay) rather than building it.
+- Production apps where un-grouped, un-sourcemapped stack traces aren't enough.
+
+## When NOT to use
+
+- You specifically want **self-hosted** error tracking (the `cf-fat`/error-tracker style — store issues in D1/DO, query via admin) for data residency/cost.
+- Trivial apps where structured logs + AE metrics are enough.
+
+## Gotchas
+
+- **Redact in `beforeSend`** — strip auth headers / PII before send; errors easily carry secrets.
+- **`enableRpcTracePropagation: true`** — or Durable Object / service-binding errors appear isolated from the originating request.
+- **Source maps must be uploaded in CI** (SENTRY_AUTH_TOKEN) or stacks are minified-useless.
+- **Control cardinality with `fingerprint`** — don't put request ids in the error message or grouping explodes; use intent-based fingerprints. Use `replaysOnErrorSampleRate`, not full session replay, for cost.
+
+## Relationships — why
+
+- **slot `error-tracking`** — the errors arm of `observability`; **recommends `observability`** (errors enrich traces/metrics). Bridged from `structured-logging` via a Sentry log handler.