@fabrika/builder 0.2.0

package/decisions/technologies/bun.md

@@ -0,0 +1,51 @@
+---
+id: bun
+kind: technology
+title: Bun (JS runtime + toolchain) — PREFERRED
+slot: js-runtime
+provides: [js-runtime, package-manager, test-runner, bundler, native-bundling]
+requires: []
+recommends: [lopata]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "bun.sh/docs + bun (cloned source for internals)"
+    read: "The runtime/bundler/test-runner surface; `bun build` and bun plugins for the non-vite path."
+  - where: "Our repos that run on Bun: lopata, opice (`bun test`), pletivo"
+    read: "How our toolchain assumes Bun end to end."
+---
+
+# Bun
+
+> **Team preference.** We prefer **Bun + lopata + a non-vite stack**. Pick Bun as the
+> runtime/toolchain and Bun-native bundling (e.g. `@buzola/bun-plugin`, pletivo's
+> Bun build) wherever a decision offers it; reach for `vite` only when a chosen lib
+> still mandates it (e.g. React Router v7).
+
+## What it is
+
+The JS runtime, package manager, test runner, and bundler our stack standardizes on.
+Most of our libs assume Bun: `lopata` runs on it, `opice` runs under `bun test`,
+`pletivo` builds with it.
+
+## When & why to use
+
+- Default for every fabrika app — one fast toolchain (install, run, test, build).
+- Bun-native bundling avoids a separate vite pipeline (the **non-vite** preference).
+
+## When NOT to use
+
+- A dependency genuinely needs Node-only APIs Bun doesn't implement, or a lib hard-requires vite (then `vite` is a scoped exception, not the default).
+
+## Impacts & gotchas
+
+- `bun test` is the test runner (opice rides on it); `bunx` runs CLIs (oblaka, lopata, opice).
+- Bun-native bundling differs from vite plugins — when a lib offers both (e.g. buzola), prefer the **bun-plugin**.
+- Some Node libs assume Node built-ins; verify under Bun before depending on them.
+
+## Relationships — why
+
+- **slot `js-runtime`** — the runtime choice (vs Node).
+- **recommends `lopata`** — the preferred local CF runtime, also Bun-based.
+- Required/assumed by `pletivo`; `opice` runs under it.

package/decisions/technologies/buzola.md

@@ -0,0 +1,80 @@
+---
+id: buzola
+kind: technology
+title: Buzola — type-safe SPA router for React (Navigation API)
+slot: router
+provides: [router, spa, file-based-routing, type-safe-routes, loaders]
+requires: [react]
+recommends: [bun]
+conflicts: [react-router]
+npm: ["@buzola/router@^0.0.12", "@buzola/vite-plugin@^0.0.12", "@buzola/bun-plugin@^0.0.12", "@buzola/codegen@^0.0.12"]
+status: wip
+sources:
+  - where: "buzola/packages/buzola/src/define/create-page.tsx + src/react/{hooks.ts,link.tsx}"
+    read: "The createPage() builder + the React surface (useNavigate/useParams/useRoute, Link, Outlet, BuzolaProvider)."
+  - where: "buzola/packages/{vite-plugin,bun-plugin,codegen}/src/"
+    read: "How codegen emits src/buzola.gen.ts + the virtual:buzola/routes module, wired via EITHER the vite-plugin OR the bun-plugin (the non-vite path)."
+  - where: "propustka/packages/admin-ui/src/{buzola.gen.ts,routes/principals/detail.tsx,routes/_layout.tsx}"
+    read: "A real app: codegen output, chained loaders + error boundary + type-safe Link, layout nesting."
+---
+
+# Buzola
+
+## What it is
+
+A **type-safe SPA router for React** built over the browser **Navigation API**, with
+**file-based routing** and **type codegen**. Routes are defined with a `createPage()`
+builder; codegen emits `src/buzola.gen.ts` + a `virtual:buzola/routes` module and
+augments a `BuzolaPageMap` so `navigate(pageId, params)` and `<Link to params>` are
+fully typechecked. It is suitable for Contember-style admin SPAs, including Propustka's public admin UI.
+Ships **both** a `@buzola/vite-plugin` and a **`@buzola/bun-plugin`** — the bun-plugin
+is the **non-vite path** that fits our bun preference.
+
+## When & why to use
+
+- A client-rendered **SPA / admin panel** (auth-gated dashboards) where SSR isn't needed.
+- You want **type-safe page ids + params** with zero manual route registration.
+- Our **bun / non-vite** preference: drive codegen with `@buzola/bun-plugin` when
+  the app has no other reason for Vite. Use the Vite plugin for a client-rendered
+  two-process SPA/Worker stack.
+
+## When NOT to use
+
+- You need **SSR / data in loaders on the Worker** → `react-router`.
+- You must support **Safari/Firefox or old browsers** — buzola **requires the Navigation API** (Chrome/Edge/Opera only); it throws at `BuzolaProvider` mount otherwise.
+
+## Routing API (real shape)
+
+```ts
+export default createPage()
+	.params({ id: 'string' }) // typed params (or a Standard Schema)
+	.loader(async ({ params, redirect }) => { // chainable; results merge, first redirect wins
+		const user = await fetchUser(params.id)
+		if (!user) return redirect('login', {})
+		return { user }
+	})
+	.route('/principals/:id') // URL pattern — comes ONLY from .route(), not the filename
+	.render(({ params, data, invalidate, isLoading }) => (
+		<Detail user={data.user} />
+	))
+```
+
+Routes live in `src/routes/` (`_layout.tsx`, `_404.tsx`, `index.tsx`, `(group)/` are
+special); the **page id** is the file path (`principals/detail.tsx` → `'principals/detail'`).
+
+## Load-bearing gotchas (anti-staleness)
+
+- **URL comes only from `.route()`**, never the filename — agents assuming Next-style file routing will get 404s. Check `buzola.gen.ts`.
+- **`.render()` is required** — without it `createPage()` is incomplete and codegen drops the page.
+- **Navigation API is mandatory** — no SSR, no old browsers; polyfill or use a memory adapter in tests.
+- **Codegen needs a real module loader** — the vite-plugin/bun-plugin passes one (`ssrLoadModule` under vite); a bare Node `import()` silently loses routes.
+- **Single `<Outlet/>` per layout** — no React-Router-style parallel/named outlets.
+
+## Best practices (testability)
+
+- Semantic markup + accessible names (`<Link>Dashboard</Link>`, `<label htmlFor>`, `role="alert"`) so opice selects by role/text, not brittle classes.
+
+## Relationships — why
+
+- **requires `react`** (it's a React router). Bundle via `@buzola/bun-plugin` (preferred, non-vite) or `@buzola/vite-plugin`; hence **recommends `bun`** rather than hard-requiring `vite`.
+- **conflicts `react-router`** — same `router` slot; SPA (buzola) vs SSR (RRv7). One per app.

package/decisions/technologies/cloudflare-access.md

@@ -0,0 +1,50 @@
+---
+id: cloudflare-access
+kind: technology
+title: Cloudflare Access (legacy/alternate edge authentication)
+slot: authentication
+provides: [authentication, sso]
+requires: [cloudflare]
+recommends: []
+conflicts: [auth-password-kv, propustka]
+npm: ["jose@^5"]
+status: stable
+sources:
+  - where: "developers.cloudflare.com/cloudflare-one/policies/access (Access JWT, application audience, identity)"
+    read: "How Access fronts a Worker, the JWT it injects, and how to validate it (aud/iss, JWKS)."
+  - where: "A legacy app that still uses Access JWT validation"
+    read: "A live example of validating the Access JWT and resolving identity downstream; do not copy it into native Propustka apps."
+---
+
+# Cloudflare Access (authentication)
+
+## What it is
+
+Cloudflare's zero-trust **authentication** layer sitting in front of a Worker. It
+handles "who you are" (SSO / IdP / one-time PIN), injects a signed JWT, and the
+Worker validates it (via `jose` — `aud`, `iss`, JWKS). It owns _authentication
+only_. This is now the legacy/alternate front door for apps that have **not**
+adopted native Propustka sessions.
+
+## When & why to use
+
+- Self-hosted / internal tools where you want SSO without building login yourself.
+- You intentionally keep an older Access-fronted app and are not migrating it to
+  native Propustka sessions yet.
+
+## When NOT to use
+
+- Public sign-up product (consumers can't be behind Access) → use `auth-password-kv` or an IdP-direct flow.
+- You need app-owned credential lifecycle (password reset, invites) as a product feature.
+
+## Impacts
+
+- Production traffic must pass through Access; **local dev needs a dev-only
+  identity shim**.
+- The Worker trusts the Access JWT — validate `aud`/`iss` against your application audience + team JWKS, never skip it.
+
+## Relationships — why
+
+- **conflicts `propustka`** — current Propustka owns native SSO sessions and
+  in-process path gates; it no longer expects a Cloudflare Access edge.
+- **conflicts `auth-password-kv`** — both fill the `authentication` slot. Access = managed SSO; auth-password-kv = app-owned password+session. Pick one.

package/decisions/technologies/cloudflare-vite-plugin.md

@@ -0,0 +1,43 @@
+---
+id: cloudflare-vite-plugin
+kind: technology
+title: "@cloudflare/vite-plugin (real-CF dev via workerd)"
+slot: cf-dev-runtime
+provides: [cf-dev-server, workerd-runtime, local-bindings]
+requires: [cloudflare, vite, wrangler]
+recommends: [oblaka]
+conflicts: [lopata]
+npm: ["@cloudflare/vite-plugin@^1", "wrangler@^4"]
+status: stable
+sources:
+  - where: "developers.cloudflare.com/workers/vite-plugin + installed @cloudflare/vite-plugin types"
+    read: "Plugin options and how it runs the Worker under workerd in dev, reading wrangler.jsonc bindings."
+---
+
+# @cloudflare/vite-plugin
+
+## What it is
+
+Cloudflare's official vite plugin: runs the Worker in dev under **real workerd**
+(miniflare), emulating D1/KV/R2/Queue/Cron locally from `wrangler.jsonc`. The
+real-CF dev path (vs lopata's Bun-based emulation).
+
+## When & why to use
+
+- You use more/fresher CF primitives than lopata emulates (Queue, AE-adjacent, etc.) and want production-fidelity local behavior.
+- The cf-fat path.
+
+## When NOT to use
+
+- You want the lightest local-first loop with the lopata dashboard and don't need workerd fidelity → use `lopata`.
+
+## Impacts & gotchas
+
+- `vite.config.ts`: `@cloudflare/vite-plugin` + the RRv7 plugin, SSR environment configured for Workers. Verify options against installed versions.
+- Reads bindings from `wrangler.jsonc` (generated by `oblaka`); local D1 via `wrangler d1 … --local`.
+- **`analytics-engine` is still not emulated** even here — counts go through `count-store`.
+
+## Relationships — why
+
+- **requires `cloudflare` + `vite` + `wrangler`** (workerd/miniflare + CLI).
+- **conflicts `lopata`** — same `cf-dev-runtime` slot; pick one dev runtime (often env-toggled with `CF=1`). **`lopata` is our preferred default**; use this plugin when you specifically need workerd fidelity (e.g. Queue/Cron) lopata doesn't emulate yet.

package/decisions/technologies/cloudflare.md

@@ -0,0 +1,50 @@
+---
+id: cloudflare
+kind: technology
+title: Cloudflare Workers (platform)
+slot: platform
+provides: [platform, edge-compute, serverless]
+requires: []
+recommends: [d1, durable-objects, kv, r2, queue, oblaka, wrangler]
+conflicts: []
+npm: ["@cloudflare/workers-types@^4", "wrangler@^4"]
+status: stable
+sources:
+  - where: "developers.cloudflare.com/workers (fetch/queue/scheduled handlers, bindings, compatibility flags)"
+    read: "The Worker handler shapes (fetch/queue/scheduled), how bindings reach the handler via env, and compatibility flags (nodejs_compat)."
+  - where: "oblaka and lopata public examples"
+    read: "Resource definitions, local bindings, and multi-worker composition."
+---
+
+# Cloudflare Workers
+
+## What it is
+
+The serverless edge-compute platform fabrika's generated apps target: V8-isolate
+Workers with first-party bindings to storage and messaging primitives
+(`d1`, `kv`, `r2`, `queue`, `analytics-engine`, `durable-objects`) and
+`cron-triggers` and Workers AI. Bindings arrive on `env`; a Worker exports
+`fetch`, optionally `queue(batch, env)` and `scheduled(event, env)`.
+
+## When & why to use
+
+- The default platform for fabrika apps — SSR React + a database in one deployable unit, no cold-start servers.
+- You want managed primitives (SQLite/KV/object-store/queue) without operating infrastructure.
+
+## When NOT to use
+
+- You need a long-lived process, raw TCP, or a runtime workerd/lopata can't emulate.
+- Hard requirement on a non-CF managed service with no equivalent binding.
+
+## Impacts
+
+- App is a Worker: code runs in a V8 isolate (web APIs, `nodejs_compat` flag for selected Node built-ins) — **not** full Node.
+- Bindings are defined in an oblaka resource graph, directly in `oblaka.ts` or
+  through `vozka.config.ts` for a Vozka-managed app; never hand-edit the generated
+  `wrangler.jsonc`.
+- Local dev emulates D1/KV/R2/Queue/Cron (`lopata` or `wrangler dev`/workerd). **`analytics-engine` has no local runtime** (see `count-store`).
+
+## Recommendations — why
+
+- **d1 / durable-objects / kv / r2 / queue** — the storage/messaging menu; pick per workload (relational state → `d1`, coordination/strong-consistency → `durable-objects`, hot keys/sessions → `kv`, blobs → `r2`, buffering bursts → `queue`).
+- **oblaka** — define bindings as code; **wrangler** — CLI for d1/dev/deploy.

package/decisions/technologies/contember.md

@@ -0,0 +1,65 @@
+---
+id: contember
+kind: technology
+title: Contember — GraphQL CMS / backend framework
+slot: backend
+provides: [graphql-api, content-model, acl, admin-ui, migrations, tenant-auth, multi-tenant]
+requires: [postgres]
+recommends: [react, bindx]
+conflicts: []
+npm: ["@contember/schema-definition", "@contember/react-binding", "@contember/interface", "@contember/client-content", "@contember/cli"]
+status: stable
+sources:
+  - where: "contember-oss — packages/schema-definition (c.* DSL + @c.Allow ACL), CLAUDE.md, docker-compose.yaml"
+    read: "The schema-as-code DSL (entities/relations/validation), predicate-based ACL, the engine architecture (Content/System/Tenant API), and local Postgres bootstrap."
+  - where: "@contember/* on npm (installed types) + packages/client-content/tests/schema.ts"
+    read: "The package surface an app imports (schema-definition, react-binding, client-content, cli) + a real sample schema."
+  - where: "contember-oss/packages/playground/"
+    read: "A minimal working app: schema + CLI config + admin wiring."
+---
+
+# Contember
+
+## What it is
+
+A **batteries-included GraphQL CMS/backend framework**. You declare the data model,
+ACL, and validation as TypeScript decorators (`@contember/schema-definition`); the
+engine auto-generates a GraphQL Content API (with row/field-level ACL enforced in
+SQL), Postgres migrations (by diffing schema versions), a React admin UI, and a
+tenant/identity system (sign-up, projects, memberships, roles, API keys). It is a
+monolithic Node service speaking GraphQL over HTTP against Postgres — not a library
+you compose, a stack you adopt.
+
+## When & why to use
+
+- You need a **working admin UI** + schema-as-code + Postgres migrations out of the box.
+- **Row/field-level ACL** matters (author-only rows, role-hidden fields) — predicates baked into the query layer.
+- **Multi-tenant + member roles** (per-project teams, invites) — the tenant API gives it free.
+- You can run a **standalone Node backend** with a managed Postgres.
+
+## When NOT to use
+
+- You're committed to **Cloudflare Workers + D1** — Contember's engine is a Node service on Postgres; it does **not** run on Workers (this is the big architectural fork vs the cf-* stacks).
+- You need a headless-only API with no React/admin → roll a thinner GraphQL layer yourself, or use `kvalt`.
+- Bespoke SQL / aggregations the generated GraphQL fights.
+
+## Impacts (what adopting it forces)
+
+- **Postgres** as the relational store (so `d1` is out — see the `relational-db` slot). You run/manage Postgres.
+- A **Node backend service** separate from any Workers SSR frontend — the deployment shape differs from cf-lightweight/cf-fat.
+- **Schema is code**; migrations are diff-generated TypeScript committed under `.contember/migrations/`. Regenerate the snapshot whenever you add one or fresh DBs drift.
+- A **projects/memberships** model (tenancy) even for single-tenant apps.
+- The admin UI + data binding are **React 19** (see `bindx` / `@contember/react-binding`).
+
+## Gotchas
+
+- **ACL is per-field predicates**, declared on the entity (`@c.Allow(role, { when, read, … })`) and injected into SQL — not per-resolver. Complex scoping needs entity variables.
+- **Tenant API owns identity** — custom auth (SAML, external JWT, machine principals) means bridging it, not swapping it.
+- **No built-in realtime** — admin uses HTTP GraphQL; live updates need your own WS/polling.
+- Migrations are diff-generated; hand-editing one (e.g. a data backfill) drops you into the migration format's internals.
+
+## Relationships — why
+
+- **requires `postgres`** — the entire schema/migration/ACL story is Postgres-specific (transitively excludes `d1`, same `relational-db` slot).
+- **recommends `react` + `bindx`** — the admin UI and data binding are React; `bindx`/`@contember/react-binding` is the typed binding layer over its GraphQL API.
+- **slot `backend`** — the backend choice (one backend per app). It also subsumes auth/identity, so it overlaps `auth-password-kv`/`propustka` conceptually — if Contember owns tenancy, don't double up.

package/decisions/technologies/cron-triggers.md

@@ -0,0 +1,46 @@
+---
+id: cron-triggers
+kind: technology
+title: Cloudflare Cron Triggers (scheduled jobs)
+slot: null
+provides: [scheduled-jobs, cron]
+requires: [cloudflare]
+recommends: [oblaka]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/workers/configuration/cron-triggers (scheduled handler, triggers.crons)"
+    read: "The scheduled(event, env) handler and triggers.crons config in wrangler."
+---
+
+# Cloudflare Cron Triggers
+
+## What it is
+
+Scheduled invocation of a Worker on a cron expression. The Worker exports
+`scheduled(event, env)`; the schedule is `triggers.crons` in `wrangler.jsonc`. For
+periodic work — spike/anomaly detection, digests, cleanup.
+
+## When & why to use
+
+- Periodic background work with no incoming request (alert spike detection, rollups, GC of expired sessions).
+
+## When NOT to use
+
+- Sub-minute or event-driven timing → use `queue` (event-driven) or a `durable-objects` alarm (precise per-object timer).
+
+## Impacts & gotchas
+
+- Export a **`scheduled(event, env)`** handler alongside `fetch`/`queue`. Emulated locally by workerd/lopata; trigger manually in dev.
+- Schedule lives in `triggers.crons` — declare it via `oblaka.ts`, never hand-edit the generated `wrangler.jsonc`.
+- Put the real operation in a reusable function and call it from both
+  `scheduled()` and a protected manual/internal endpoint used by local tests.
+  Do not make the scheduled handler call its own public HTTP endpoint.
+- When several schedules share one Worker, branch on `event.cron` explicitly;
+  keep recovery/sweep operations idempotent because a trigger can overlap a
+  queue retry or a manual run.
+
+## Relationships — why
+
+- **requires `cloudflare`** — platform feature. **recommends `oblaka`** to declare the cron trigger.

package/decisions/technologies/d1.md

@@ -0,0 +1,51 @@
+---
+id: d1
+kind: technology
+title: Cloudflare D1 (relational database)
+slot: relational-db
+provides: [relational-db, sql, mutable-state]
+requires: [cloudflare]
+recommends: [oblaka]
+conflicts: [postgres]
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/d1 (bindings, migrations, query API)"
+    read: "The D1 binding API (prepare/bind/all/run), local migrations, and the execute CLI."
+  - where: "lopata + examples/react-router (local D1 via lopata d1)"
+    read: "How D1 is bound and queried in the canonical local-first RRv7-on-Workers example."
+---
+
+# Cloudflare D1
+
+## What it is
+
+SQLite-at-the-edge: the relational store for an app's **mutable, human-driven
+state**. Bound as `env.DB` and queried inside the Worker (request/RPC handlers,
+services, queue or scheduled handlers). SSR loaders/actions are one possible
+transport; a Buzola SPA reaches D1 only through the Worker API. Migrations are
+SQL files; local D1 lives under `.lopata/` (lopata) or `--local` (wrangler).
+
+## When & why to use
+
+- Default store for relational/mutable state (users, projects, config, issues…).
+- You want SQL + local-first dev with no account.
+
+## When NOT to use
+
+- **High-frequency append/counter workload** (per-event count UPDATE = hot-row contention) → use `analytics-engine` behind `count-store`, append don't UPDATE.
+- Coordination / strong single-object consistency → `durable-objects`.
+- Large binary payloads → `r2`.
+
+## Impacts & gotchas
+
+- **Migrations are idempotent**: `migrations/NNNN_name.sql`, `CREATE TABLE IF NOT EXISTS`. Dir = oblaka `migrationsDir`.
+- Keep D1 behind the Worker boundary. Inject `env.DB` into handlers/services;
+  never import a Worker binding into client SPA code.
+- Apply: `lopata d1 migrations apply` (local-first) or `wrangler d1 migrations apply DB --local`.
+
+## Relationships — why
+
+- **requires `cloudflare`** — it's a CF binding.
+- **recommends `oblaka`** — declare the `D1Database` binding in `oblaka.ts` rather than hand-editing `wrangler.jsonc`.
+- **conflicts `postgres`** — same `relational-db` slot (edge SQLite vs a Postgres server). A `contember` stack uses Postgres, not D1.

package/decisions/technologies/durable-objects.md

@@ -0,0 +1,44 @@
+---
+id: durable-objects
+kind: technology
+title: Cloudflare Durable Objects (coordination / strong consistency)
+slot: null
+provides: [coordination, stateful-objects, strong-consistency, websockets]
+requires: [cloudflare]
+recommends: [oblaka]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/durable-objects (class binding, storage API, alarms, WebSocket hibernation)"
+    read: "The DO class + binding model, transactional storage, alarms, and WebSocket hibernation."
+---
+
+# Cloudflare Durable Objects
+
+## What it is
+
+Single-instance stateful objects addressed by id, giving **strong single-object
+consistency** and **coordination** — the thing D1/KV can't: a serialized point of
+truth per entity. Each DO has transactional storage, alarms, and WebSocket support.
+
+## When & why to use
+
+- Per-entity coordination: rate limiters, locks, counters that must be exact, live presence.
+- Real-time: WebSocket fan-out / rooms (hibernation keeps idle sockets cheap).
+- A serialized actor where concurrent requests to the same id must not race.
+
+## When NOT to use
+
+- Plain relational/queryable state → `d1`. Hot cache/sessions → `kv`.
+- High-cardinality append metrics (one DO per series doesn't scale) → `analytics-engine`.
+
+## Impacts & gotchas
+
+- Routed by id (`idFromName`/`idFromString`) — design the id space deliberately; all requests for one id serialize through one instance.
+- Storage API is transactional but per-object; no cross-object queries.
+- Local emulation under workerd/lopata; declare the class binding + migration in `oblaka.ts`.
+
+## Relationships — why
+
+- **requires `cloudflare`** — CF binding. **recommends `oblaka`** to declare the DO namespace/class.

package/decisions/technologies/kv.md

@@ -0,0 +1,42 @@
+---
+id: kv
+kind: technology
+title: Cloudflare KV (key-value store)
+slot: null
+provides: [kv-store, sessions, dedup-cache]
+requires: [cloudflare]
+recommends: [oblaka]
+conflicts: []
+npm: []
+status: stable
+sources:
+  - where: "developers.cloudflare.com/kv (get/put/delete, TTL, eventual consistency)"
+    read: "The KV binding API and its eventual-consistency / TTL semantics."
+---
+
+# Cloudflare KV
+
+## What it is
+
+Eventually-consistent key-value store. Used for **session tokens**, **API
+keys / DSN lookups**, and **dedup caches** — small values read on the hot path,
+keyed by a stable id. Bound as `env.KV`.
+
+## When & why to use
+
+- Session storage (`auth-password-kv`), API-key validation on ingest, idempotency/dedup keys.
+- Hot-path lookups where eventual consistency is acceptable.
+
+## When NOT to use
+
+- Read-after-write strong consistency required → `d1` or `durable-objects`.
+- Relational queries / joins → `d1`.
+
+## Impacts & gotchas
+
+- **Eventually consistent** — a freshly written key may not be readable immediately everywhere; don't rely on it for read-after-write invariants.
+- Values are opaque blobs (string/ArrayBuffer); model structure yourself. Use TTL for ephemeral session/dedup keys.
+
+## Relationships — why
+
+- **requires `cloudflare`** — CF binding. **recommends `oblaka`** — declare `KVNamespace` in `oblaka.ts`.

package/decisions/technologies/lopata.md

@@ -0,0 +1,55 @@
+---
+id: lopata
+kind: technology
+title: lopata (local Cloudflare runtime, local-first)
+slot: cf-dev-runtime
+provides: [local-cf-runtime, cf-dev-server, local-d1, local-bindings]
+requires: [cloudflare]
+recommends: [oblaka, bun, vite]
+conflicts: [cloudflare-vite-plugin]
+npm: ["lopata@^0.18.4"]
+status: wip
+sources:
+  - where: "lopata (repo) + installed CLI/plugin source"
+    read: "Worker entry, standalone dev command, optional vite-plugin wiring and the d1 CLI."
+  - where: "lopata examples"
+    read: "Vite integration, resource config, development commands, and multi-worker service bindings."
+---
+
+# lopata
+
+## What it is
+
+A drop-in CF runtime for **local dev** that runs on Bun (not workerd). Bindings are
+backed by SQLite + FS under `.lopata/`, with a dashboard at `/__dashboard`. Lets
+the whole stack run locally with **no CF credentials**.
+
+## When & why to use
+
+- Local-first development: D1/KV/R2 emulated on disk, zero account.
+- The cf-lightweight path; `bunx lopata d1 …` for migrations/seeds/queries.
+
+## When NOT to use
+
+- You need the **real workerd** behavior or a binding lopata doesn't emulate yet → use `cloudflare-vite-plugin` (workerd) instead. lopata is **WIP — expect churn**, so verify what it emulates.
+
+## Impacts & gotchas
+
+- **Buzola SPA / Worker split:** run lopata as the standalone Worker dev server;
+  run Vite separately and proxy only `/rpc`/`/api`/`/internal` to it. No lopata
+  Vite plugin is needed in this shape.
+- **Integrated SSR shape:** when using `lopata/vite-plugin`, verify its current
+  `viteEnvironment`/config options. The `'ssr'` environment is specific to the
+  SSR-on-Workers path, not a requirement for a client-only SPA.
+- `CF=1` can swap lopata → `@cloudflare/vite-plugin` (real workerd) in stacks that
+  explicitly implement that seam. The two share the `cf-dev-runtime` slot.
+- Local D1 under `.lopata/d1/*.sqlite`; CLI `bunx lopata d1 migrations apply` / `execute DB --file …`.
+- Generate `wrangler.jsonc` from oblaka/the shared Vozka resource builder before
+  starting lopata. Never maintain local bindings in a second hand-written config.
+
+## Relationships — why
+
+- **requires `cloudflare`** (it emulates CF). Vite is recommended, not required:
+  lopata can run the Worker separately from a Vite SPA.
+- **conflicts `cloudflare-vite-plugin`** — same `cf-dev-runtime` slot; they're swappable dev paths (env-toggled), not used together. **lopata is our preferred default** (local-first, Bun); reach for the cloudflare-vite-plugin only when you need workerd fidelity.
+- **recommends `bun`** — lopata is Bun-based; part of our bun/lopata preference.

package/decisions/technologies/nuasite.md

@@ -0,0 +1,50 @@
+---
+id: nuasite
+kind: technology
+title: Nua Site — Astro meta-package + visual CMS
+slot: site-framework
+provides: [astro-site, visual-cms, markdown, seo-checks, sitemap]
+requires: []
+recommends: [tailwind, cloudflare]
+conflicts: [pletivo]
+npm: ["@nuasite/nua@^0.43", "@nuasite/cms@^0.43", "@nuasite/cli@^0.43", "@nuasite/components@^0.43", "@nuasite/checks@^0.43"]
+status: stable
+sources:
+  - where: "nuasite/README.md + packages/nua/README.md"
+    read: "The meta-package (pins Astro 6 + Tailwind 4 + MDX + sitemap) and how to configure it."
+  - where: "nuasite/packages/cms/README.md"
+    read: "The visual editor: how it injects data-cms-id markers and writes edits back to .astro source via HMR."
+---
+
+# Nua Site
+
+## What it is
+
+A published set of **Astro meta-packages** for building **content sites with a visual
+CMS**. `@nuasite/nua` pins the toolchain (Astro 6, Tailwind 4, MDX, sitemap);
+`@nuasite/cms` is an Astro integration that serves a visual editor in dev and writes
+edits straight back to `.astro` source files; `@nuasite/checks` validates SEO/a11y/perf
+at build. It mirrors the hosted Nua Site service so local builds match production.
+
+## When & why to use
+
+- A **marketing/docs/blog site** that needs **in-place visual editing** with edits flowing back to Git-tracked source.
+- You want a validated Astro toolchain + LLM-friendly content export (`.md` endpoints, `AGENTS.md`).
+
+## When NOT to use
+
+- A dynamic **app** (SPA/SSR) → `react-router` / `buzola`.
+- You want the fastest minimal SSG with no CMS → `pletivo`.
+- **Note vs our bun/non-vite preference:** Astro is vite-based, so nuasite leans on vite under the hood — fine for content sites, but it's not the bun-native path.
+
+## Impacts & gotchas
+
+- Pages must be **`.astro`** for CMS editing (React/TSX components are islands, not CMS-marked).
+- **Locked dependency versions** (the meta-package pins Astro/Tailwind) — you upgrade when Nua Site releases.
+- The CMS editor parses **Tailwind `class="…"`** (style via utilities, not inline) and has **no built-in auth** — front it with `cloudflare-access` if edits must be gated.
+- (Optional) `@pletivo/astro-jsx-pages` / `astro-jsx-pages` lets you author pages in `.tsx` instead of `.astro` — pre-release; not for the CMS-editing workflow.
+
+## Relationships — why
+
+- **conflicts `pletivo`** — same `site-framework` slot.
+- **recommends `tailwind`** (the CMS depends on utility classes) + **`cloudflare`** (a common deploy target).