@mseep/open-computer-use 1.0.0

package/docs/future-architecture/research/12-docker-socket-proxy.md

@@ -0,0 +1,59 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 12 — Tecnativa/docker-socket-proxy (privileged-API filter pattern)
+
+> Source: [Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy). HAProxy-based filter for the Docker API.
+> Pattern reference for Phase 2 (HTTP pool-manager sidecar — the *only* component that holds the Docker socket) and Phase 8 (egress filtering); general template for "filter access to a privileged API".
+
+## 1. Endpoint allowlist via regex + env-gated rules
+
+- **Where.** `haproxy.cfg:46-79` (frontend rules). Example `:60`:
+  ```haproxy
+  http-request allow if { path,url_dec -m reg -i ^(/v[\d\.]+)?/containers } { env(CONTAINERS) -m bool }
+  ```
+- **What.** Each API category (CONTAINERS, NETWORKS, VOLUMES, …) has a regex path matcher + an env-var boolean gate. `0 = deny`, `1 = allow`.
+- **Why for us.** Phase 2 pool-manager: same shape filters Docker socket access. Phase 8: same shape filters egress URLs.
+- **Skip.** Docker version prefix `(/v[\d\.]+)?` is Docker-specific.
+
+## 2. Method/path split — read-only by default
+
+- **Where.** `haproxy.cfg:48` (global filter), `:51-55` (per-op gates).
+- **What.** `http-request deny unless METH_GET || { env(POST) -m bool }`. GET/HEAD allowed; POST/PUT/DELETE require `POST=1`. Destructive ops (ALLOW_STOP, ALLOW_RESTARTS, …) have independent gates **even when** POST is on.
+- **Why for us.** Phase 2 — observability (list, get) ≠ mutation (delete). Phase 8 — block all egress POST/DELETE by default.
+- **Protocol-agnostic.** Works for REST, gRPC-JSON bridges.
+
+## 3. Env-var-driven config — operator UX
+
+- **Where.** `Dockerfile:4-33` (25+ env vars); `docker-entrypoint.sh:23` (template substitution).
+- **What.** Operators set `CONTAINERS=1 ALLOW_START=1` to grant only specific capabilities. Defaults conservative (most=0; only `EVENTS`, `PING`, `VERSION` = 1).
+- **Why for us.** Helm `values.yaml` exposes the same boolean knobs. No code recompile to change policy.
+- **Skip for k8s API.** Use native RBAC for k8s; env gates are best as a *secondary defense layer*.
+
+## 4. Health, observability, streaming-safe backends
+
+- **Where.** `haproxy.cfg:42-44` (special `events` backend with `timeout server 0`), `:2, 13-14` (logging), README `:198-202` (`LOG_LEVEL`).
+- **What.** Streaming endpoints (e.g. Docker `/events`, k8s watch) need **no server timeout** or they get killed mid-stream. Full request logs (httplog) feed audit.
+- **Why for us.** Phase 2 — k8s watch streams and L1 streaming exec calls require the same treatment.
+
+## 5. Least-privilege secure-by-default posture
+
+- **Where.** README `:109-147` (access matrix); Dockerfile defaults.
+- **What.** All dangerous operations default to deny (`AUTH=0`, `SECRETS=0`, `POST=0`, `CONTAINERS=0`). Only read-only basics allowed. **No catch-all "allow everything" gate.**
+- **Why for us.** Foundational; matches cross-cutting pattern 13 (NetworkPolicy default-deny). Operator must opt-in to each capability.
+
+## 6. Trust boundary at network edge — no TLS inside
+
+- **Where.** README `:26-34`.
+- **What.** No TLS inside the container network. Security relies on container/k8s networking isolation. External exposure forbidden.
+- **Why for us.** Phase 2 — pool-manager runs in sandbox pod's netns or via Unix socket / private service. No mTLS within the trust boundary. mTLS only for cross-network egress (Phase 8).
+
+## Adoption checklist
+
+1. **Config as code** — template + env vars locked at deploy time (Helm/kustomize).
+2. **Deny by default** — explicit allowlist, never blocklist.
+3. **Granular gates** — separate controls per operation class.
+4. **Audit logging** — full request log, configurable level.
+5. **Streaming-safe backends** — no server timeout on watch / events / exec.
+6. **Network-edge trust** — proxy is network-isolated; no TLS inside.
+7. **Matrix tests** — see `tests/test_service.py:10-40` for permission-matrix testing.

package/docs/future-architecture/research/14-e2b-desktop-and-surf.md

@@ -0,0 +1,107 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 14 — e2b/desktop + e2b/surf (full-desktop vs CDP-direct)
+
+> Source: [e2b-dev/desktop](https://github.com/e2b-dev/desktop) and [e2b-dev/surf](https://github.com/e2b-dev/surf).
+> Decision point for Phase 7: evolve toward Xfce/VNC or stay CDP-direct?
+
+**Verdict: stay CDP-direct.** Details below.
+
+## 1. Desktop — Xvfb + Xfce4 + resolution
+
+- **Where.** `packages/python-sdk/e2b_desktop/main.py:263-277` (`Sandbox.create`).
+- **What.** Xvfb at `1024x768`, DPI 96, display `:0`. `startxfce4` background. Liveness via `xdpyinfo`.
+- **Cost for us.** Full WM + panels + desktop icons we never render. Adds ~700 MB image + ~200 MB RAM per sandbox.
+- **Skip.** CDP-direct doesn't need any of this.
+
+## 2. Desktop — VNC + noVNC over WebSocket
+
+- **Where.** `e2b_desktop/main.py:84-202` (`_VNCServer`).
+- **What.** `x11vnc` on 5900 (RFB), `noVNC` (WebSocket wrapper) on 6080 over HTTPS. Optional password.
+- **Trade-off.** VNC is low-latency for humans; **high-bandwidth for rapid AI actions** (full-screen re-encode per frame). noVNC adds 100–200 ms.
+- **For us.** Headless agent ≠ human viewer → skip VNC. Chromium CDP screencast (binary frames, 30–60 fps) is cheaper. Surf uses VNC purely for **developer observation**, not the agent control path.
+
+## 3. Desktop — `xdotool` input (X11 events)
+
+- **Where.** `e2b_desktop/main.py:424-488`.
+- **What.** `xdotool mousemove`, `xdotool click`, `xdotool key`, `xdotool type --delay`. Pixel coords. Screen size via `xrandr`.
+- **Limitation.** Pure visual grounding — no OCR, no DOM. Agent must parse the screenshot.
+- **For us.** CDP path unlocks **DOM queries** (`document.evaluate`, element bounding boxes). Far more reliable than visual coord guessing.
+
+## 4. Desktop — screenshot via `scrot` to disk
+
+- **Where.** `e2b_desktop/main.py:406-422`.
+- **What.** `scrot --pointer` → PNG to disk → SDK reads → SDK deletes. ~50–100 ms roundtrip.
+- **For us.** CDP `Page.captureScreenshot` is async, batched with actions, no disk I/O. CDP wins.
+
+## 5. Surf — action loop pattern
+
+- **Where.** `lib/streaming/openai.ts:336-575` (`stream()` async generator).
+- **Loop.**
+  1. Screenshot → base64.
+  2. POST to OpenAI with `tools: [{ type: "computer" }]` (OpenAI's Computer tool).
+  3. Response: structured `output[]` with `computer_call` items, each containing batched `actions[]`.
+  4. Execute actions sequentially (click/type/scroll/…) via desktop SDK.
+  5. Capture screenshot after batch (with configurable fallback delay for async DOM).
+  6. Feed screenshot + reasoning into next iteration (context reset per turn).
+  7. **Bail** when no more `computer_call` returned.
+- **For us.** **Adopt this loop in Phase 7.** Same shape for Claude Computer Use. Not bespoke — OpenAI codified it.
+
+## 6. Surf — coordinates + safety
+
+- **Where.** `lib/streaming/openai.ts:267-334` (`executeAction`); `types/openai.ts`.
+- **Actions.** `click(x, y, button)`, `type(text)`, `scroll(x, y, dx, dy)`, `drag(path: [{x,y}, ...])`, `keypress(keys: string[])`, `wait(ms)`.
+- **Footguns Surf ignores.**
+  - **No coordinate-bounds validation.** Agent picks (10000, 10000) → silent fail or Chromium crash.
+  - **Chunked typing** (`chunkSize=50`, `delayMs=25`) **required** for terminal input buffers.
+  - **Trailing wait deferred.** If last actions are `wait`, bundle into screenshot capture delay instead of sleeping.
+- **For us.** Phase 7 — **add coordinate clipping** (validate within viewport). Adopt chunked typing for our `terminal_type` tool.
+
+## 7. Surf — async settle delay
+
+- **Where.** `lib/streaming/openai.ts:171-189, 232-265` (`shouldApplyFallbackDelay`, `captureBatchScreenshot`).
+- **What.** If a batch contains `click`/`scroll`/`drag` or async keypresses (Enter/Tab/Escape) → wait 100 ms before screenshot. DOM may not settle immediately.
+- **For us.** CDP has the same issue. `Page.captureScreenshot` right after a click can capture stale layout. **Always insert a small post-batch delay** (configurable per action type). Document the latency trade-off.
+
+## 8. Surf — SSE streaming UI
+
+- **Where.** `app/api/chat/route.ts:12-91`; `lib/streaming/index.ts`.
+- **Events.** `SANDBOX_CREATED`, `REASONING`, `ACTION`, `ACTION_COMPLETED`, `SCREENSHOT`, `ERROR`, `DONE`.
+- **Lazy sandbox.** Created on first message; reused for conversation.
+- **No multi-turn memory** — each OpenAI call independent.
+- **For us.** SSE is clean for developer/admin observation surfaces. For Phase 7 headless agent, log locally or stream via our own L4 channel.
+
+## 9. Desktop image — `template/template.py:1-128`
+
+- **Stack.** Ubuntu 22.04 + Xorg + Xvfb + xauth + xdotool + scrot + Xfce4 + x11vnc + noVNC + websockify + Firefox + Chrome + VS Code + LibreOffice + gedit + pcmanfm.
+- **Image size.** ~2–3 GiB uncompressed. Startup: 10–20 s.
+- **Our path.** Chromium alone: 200–300 MiB. No WM, no panels. Faster spawn, cheaper RAM, lower screenshot latency.
+
+## 10. Comparison table
+
+| Dimension | E2B Desktop + Surf | Our CDP-direct (Phase 7) |
+|---|---|---|
+| Display backend | Xvfb (X11) + Xfce4 | Chromium `--disable-gpu` / headless |
+| Screenshot | scrot → disk; poll ~10 Hz | CDP `Page.captureScreenshot` / screencast; up to 60 Hz |
+| Input | xdotool (X11 events, pixel coords) | CDP `Input.dispatchMouseEvent` (CSS pixels) |
+| Action→shot latency | ~150–250 ms | ~50–100 ms |
+| Coord origin | Screen pixels | Viewport CSS pixels (supports scroll offset) |
+| DOM access | None | Full (`document.evaluate`, element boxes) |
+| Multi-app | Yes (any X11 app) | Browser-only (terminal via separate MCP tool) |
+| Sandbox startup | 10–20 s | 2–5 s |
+| Sandbox image | 2–3 GiB | 300–500 MiB |
+| Agent reliability | Visual + OCR risk | Semantic (DOM) + visual fallback |
+
+## Verdict for Phase 7
+
+1. **Stay CDP-direct.** VNC/Xfce overhead is not justified for first Computer Use agent. Browser is the primary target; terminal tasks handled by separate MCP tool.
+2. **Screenshot strategy.** `Page.startScreencast` for live frames (30–60 fps); `captureScreenshot` for explicit "pause and analyze". Surf only polls — we can do better.
+3. **Input primitives.** Adopt Surf's schema (`click`/`type`/`scroll`/`keypress`/`drag`/`wait`). Add coord validation + DOM-query layer (CDP `Runtime.evaluate`).
+4. **Async settle.** Insert 100–150 ms delay after action batches containing clicks/scrolls/async keys.
+5. **Error recovery.** Not in Surf — we add retry + Chromium restart on CDP connection loss.
+6. **Multi-turn memory.** Surf resets per turn. We consider lightweight session state (screenshot/action history) for coherent long-form tasks.
+
+## When to revisit
+
+If we ever need **multi-app Computer Use** (e.g., AI agent that switches between browser + VS Code + terminal in the same display) → revisit Xfce/VNC. For now, single-app + separate tool channels keeps the stack lean.

package/docs/future-architecture/research/18-open-webui-terminals-observed.md

@@ -0,0 +1,135 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# 18 — Open WebUI `open-terminal` + `terminals` (observed)
+
+> Source: [`open-webui/open-terminal`](https://github.com/open-webui/open-terminal) (sandbox shell server) and [`open-webui/terminals`](https://github.com/open-webui/terminals) (per-user orchestrator). Reviewed 2026-05.
+>
+> Status: **observation, hypothesis only.** Their target audience is single-user / SMB self-host. Our target is multi-tenant enterprise (financial-sector infosec, multi-cluster, BYOK, compliance-grade audit). This document records what they do at the wire-protocol level, and frames one open hypothesis about reusing that wire protocol as an external dialect — nothing here locks any architectural decision.
+
+## 1. What the two projects are
+
+- **`open-terminal`**: a FastAPI service that runs inside a single container and exposes a REST API + WebSocket terminal. Tools: bash exec, file CRUD, document extraction, port reverse-proxy, Jupyter kernels, optional in-process MCP via `FastMCP.from_fastapi(app)`.
+- **`terminals`**: a separate FastAPI control-plane that provisions one `open-terminal` container *per `(user_id, policy_id)`* and reverse-proxies requests to it. Three backends: Docker socket, Kubernetes direct, Kubernetes via Kopf operator + `Terminal` CRD (`openwebui.com/v1alpha1`).
+
+Open WebUI integrates both natively. The backend (`backend/open_webui/routers/configs.py:277-323`) auto-detects which one the user pointed at:
+
+```text
+GET {url}/api/v1/policies → 200 → server_type = "orchestrator"  (terminals)
+GET {url}/api/config      → 200 → server_type = "terminal"      (open-terminal)
+```
+
+For an orchestrator, requests are routed as `/p/{policy_id}/{path}`. For a single terminal, paths pass through as-is.
+
+## 2. Audience and scope difference
+
+This is **not a critique** — these are different products solving different problems.
+
+| Dimension | Open WebUI stack | Our target |
+|---|---|---|
+| Primary user | Self-hoster, single-team install | Multi-tenant enterprise, paid SaaS |
+| Tenancy boundary | Linux UID inside one container (multi-user mode) or one container per user (orchestrator) | One sandbox per session, microVM-isolated for untrusted tier |
+| Runtime isolation | `runc` only | runc / sysbox / gVisor / kata-fc / kata-ch per template ([04-layer2-runtimes.md](../architecture/04-layer2-runtimes.md)) |
+| Cluster model | Single cluster, single namespace | Multi-cluster, multi-AZ, federated |
+| Identity | Static API key or Open WebUI JWT | OIDC + per-session JWT + secret broker ([07-security.md](../architecture/07-security.md)) |
+| Secrets | env vars / K8s `Secret` | Per-session STS, key rotation ≤90d without restart |
+| Egress | iptables + dnsmasq inside each container | Centralized JWT-allowlist egress proxy with audit pipeline ([08-networking.md](../architecture/08-networking.md), Phase 8) |
+| Storage | `/home/user` bind-mount or PVC | 4-tier (image / squashfs skills / ephemeral workspace / S3 user-data) ([06-storage.md](../architecture/06-storage.md)) |
+| Audit | SQL `audit_log` table | Append-only S3 with object-lock, ≥90d retention |
+| HA control plane | Single process, in-memory `_instances` dict | 3+ replicas, leader election via `coordination.k8s.io/Lease`, external KV |
+| Compliance posture | None specifically targeted | SOC2 / PCI / FedRAMP-class workloads in scope |
+
+Their stack would be a regression for our targets. Ours would be over-engineering for theirs. Both can be correct.
+
+## 3. Wire contract (what Open WebUI expects)
+
+Useful to record verbatim because the protocol is what unlocks native integration in Open WebUI's UI.
+
+### 3.1 Auto-detection probes
+
+```text
+GET /api/v1/policies          → orchestrator dialect
+GET /api/config               → single-terminal dialect, returns { features: { terminal: bool } }
+```
+
+### 3.2 Orchestrator dialect (used by `terminals`)
+
+- `GET /api/v1/policies` — list policies (`PolicyData`: image, env, cpu_limit, memory_limit, storage, storage_mode, idle_timeout_minutes)
+- `POST/PUT/DELETE /api/v1/policies/{id}` — CRUD from admin UI
+- `ALL /p/{policy_id}/{path:path}` — reverse-proxy to the provisioned sandbox; `X-User-Id` header required; orchestrator resolves `(user_id, policy_id) → sandbox`, replaces auth with the sandbox's internal API key, streams body bidirectionally
+- `WS /p/{policy_id}/api/terminals/{session_id}` — WebSocket proxy with first-message `{"type":"auth","token":"..."}` handshake
+
+### 3.3 Single-terminal dialect (used by `open-terminal`)
+
+The endpoints under `/p/{policy_id}/` in orchestrator mode are exactly the endpoints `open-terminal` exposes at root. Open WebUI clients used by the UI:
+
+- `GET /openapi.json` — OpenAPI 3.0 spec; tools from this spec are surfaced to the model as function-calling tools
+- `GET /files/cwd`, `POST /files/cwd` — session-scoped CWD (keyed on `X-Session-Id`)
+- `GET /files/list?directory=`, `GET /files/read?path=`, `GET /files/view?path=`
+- `POST /files/upload?directory=` (multipart), `POST /files/mkdir`, `DELETE /files/delete`, `POST /files/move`, `POST /files/archive`
+- `POST /api/terminals` → `{ id }`; then `WS /api/terminals/{id}` with first-message auth, binary frames for PTY I/O, JSON `{type:"resize",cols,rows}` / `{type:"ping"}` for control
+
+All HTTP requests authenticated by `Authorization: Bearer <key>`; `X-Session-Id` keys per-chat state; `X-User-Id` keys per-user provisioning in orchestrator mode.
+
+### 3.4 What Open WebUI gives back if a server implements this
+
+- **`FileNav.svelte`** — full file browser in the chat sidebar (list, read, upload via drag-drop, download, mkdir, delete, move, archive)
+- **`XTerminal.svelte`** — embedded xterm.js with the WebSocket protocol above
+- **Tool calling** — OpenAPI tools auto-injected into the inference loop when the model has `capabilities.terminal = true`
+- **`AddTerminalServerModal.svelte`** — admin / per-user UI to add a server, with orchestrator-mode policy editor
+- **Per-chat `X-Session-Id`** — Open WebUI passes the chat id automatically, sandboxes can scope CWD and state to a session
+
+## 4. Hard constraint: client parity
+
+Current explicit requirement: **Open WebUI and n8n must reach an identical capability surface** so that skills are portable between clients. The MCP protocol is the only common denominator across the target clients today (Open WebUI MCP support, n8n MCP nodes, OpenAI Agents SDK, LiteLLM, Claude Desktop). See [`../../MCP.md`](../../MCP.md), [`../../COMPARISON.md`](../../COMPARISON.md).
+
+This constraint **takes precedence** over any UX gain from native Open WebUI integration. Anything that splits the skill surface — i.e. tools that work in Open WebUI but not in n8n, or vice versa — is rejected by definition. ADR-0005 (MCP as user-facing control-plane gateway, frozen contract) stands.
+
+## 5. Hypothesis (open, not decided)
+
+Add an **external protocol dialect** to L4 that speaks the orchestrator wire contract from §3.2 alongside the primary MCP endpoint, while internal tool execution stays MCP-shaped end-to-end.
+
+```text
+                  ┌─── /mcp                        primary, frozen          (n8n, Claude Desktop, LiteLLM, OpenAI Agents)
+L4 (Go) ──────────┼─── /api/v1/policies, /p/...    Open WebUI native UX     (FileNav, XTerminal, OpenAPI tools)
+                  ├─── /v1/chat/completions        OpenAI-compat            (future, for OpenAI-API consumers)
+                  └─── /admin/*                    operator UI
+```
+
+All four are adapters over the same internal connect-go RPC ([ADR-0008](../adr/0008-internal-grpc-external-rest-mcp.md)).
+
+### What this would unlock
+
+- Open WebUI users get the native file browser + embedded terminal + OpenAPI-tool injection out of the box, without our `computer_link_filter` and Open WebUI source patches.
+- No regression for n8n / Claude Desktop / LiteLLM — they keep using `/mcp` unchanged.
+
+### What still has to be proven before this becomes decision-grade
+
+1. **Skill parity check.** The Open WebUI dialect would deliver tools via OpenAPI 3.0, not MCP `tools/call`. We have to confirm that for every skill we ship, the OpenAPI representation and the MCP representation produce identical model behaviour. If not, the dialect splits the skill surface and §4 forces rejection.
+2. **CDP and live browser viewer.** Open WebUI's terminal dialect has no concept of a Chrome DevTools Protocol stream. Either we extend the dialect with our own WebSocket endpoint under `/p/{policy_id}/devtools/...` (and patch Open WebUI to recognise it — back to the patch-maintenance problem), or we accept that Computer Use's primary fronted-killer feature is unavailable through this path.
+3. **`computer_link_filter` value.** Today the filter injects skill descriptions into the system prompt and rewrites output URLs into iframe previews. Open WebUI's native flow injects OpenAPI tool descriptions automatically but does **not** rewrite output URLs. We have to decide whether the URL-rewriting UX is essential — if yes, we still need the filter even when using the native dialect, and the simplification budget shrinks.
+4. **State of the contract.** `open-webui/terminals` is at `v0.0.3` with an Enterprise License. Backwards-compat guarantees on the orchestrator wire format are unclear; pinning to a specific Open WebUI version range may be necessary.
+5. **`X-Session-Id` semantics.** Open WebUI assumes sessions outlive single requests (CWD persists). Our session model is sandbox-per-chat with a TTL. Confirm the mapping doesn't surprise anyone — e.g. what happens to file ops sent during sandbox cold-start.
+
+### Phase to evaluate
+
+If pursued, this is a Phase 6 concern (L4 rewrite) at the earliest — the adapter lives in L4 and benefits from connect-go's HTTP+JSON pluralism. Not earlier: doing it on top of the current FastAPI server would create migration debt.
+
+## 6. Patterns observed, not borrowed
+
+For completeness, things their code does competently that we should make sure are covered in our own design (these are CNCF / k8s-api-convention basics, not their inventions — listing only to confirm we don't drop them):
+
+- Status `phase` + `conditions[]` array on the CRD (k8s API conventions). Their flat `cpuLimit: "2"` vs nested `resources.limits.cpu` is the opposite — non-standard, breaks generic k8s tooling. **Antipattern note added below.**
+- Finalizer-driven teardown (`settings.persistence.finalizer = "..."`) — standard. Required for our S3-cleanup / secret-revocation / egress-JWT-invalidation flows.
+- PVC lifecycle separated from CR lifecycle (PVC outlives the controller object). Useful pattern for stateful workloads; **not directly applicable to us** since our default workspace home is ephemeral and persistence is S3-mediated.
+- Reverse-proxy with retry on cold-start (5 attempts, 1s backoff) — required behaviour for warm-pool misses; should be explicit in [`03-layer3-providers.md`](../architecture/03-layer3-providers.md) and [`02-layer4-control-plane.md`](../architecture/02-layer4-control-plane.md).
+
+## 7. Antipattern note candidate
+
+For [`../antipatterns.md`](../antipatterns.md):
+
+> **Flat resource fields on a CRD spec.** Using `spec.cpuLimit: "2"` and `spec.memoryLimit: "4Gi"` instead of the canonical `spec.resources.limits.{cpu,memory}` breaks `kubectl explain`, generic policy admission controllers (Kyverno, Gatekeeper templates that target `resources.limits`), and Helm-chart introspection tooling. Save the typing, lose the ecosystem. Always nest under `resources`.
+
+## 8. Summary
+
+`open-terminal` and `terminals` are well-scoped products for a different audience. Their wire protocol is the one piece worth recording for possible reuse as an external dialect of our L4 — strictly as a **hypothesis** subordinated to the MCP-first / client-parity constraint. No architecture commitment is made by this file.

package/docs/future-architecture/research/bank-buyer.md

@@ -0,0 +1,96 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: research-draft
+last-reviewed: 2026-05-24
+owner: architecture
+applies-to: next/v1
+---
+
+Evidence brief for the bank-buyer half of `manifesto/01-audience-and-buyer.md`; audience is the architect drafting §01.
+
+## Buyer chain in a tier-1 US/EU bank
+
+Singular "the buyer" does not exist. A purchase of an in-perimeter AI-agent platform at a tier-1 bank requires alignment across four parallel chains, each with veto power:
+
+1. **Business sponsor + budget.** Increasingly a Chief AI Officer with a P&L. HSBC appointed David Rice as inaugural CAIO effective 1 Apr 2026 ([Banking Dive](https://www.bankingdive.com/news/hsbc-david-rice-ai-chief-cto-mario-shamtani-expanded-role-elhedery/815655/)). UBS named Daniele Magazzeni CAIO starting 1 Jan 2026 ([fintechfutures](https://www.fintechfutures.com/job-cuts-new-hires/hsbc-appoints-david-rice-as-its-inaugural-chief-ai-officer)). CBA appointed Ranil Boteju (Dec 2025); NatWest named Dr Maja Pantic Chief AI Research Officer (Jun 2025). JPMorgan has not announced a single CAIO title but routes AI through Mary Erdoes and the firm-wide AI/ML platform org. Assumption (uncited): the CAIO function exists in some form at every tier-1 by end-2026; in banks without the title, the sponsor is the COO of the largest LOB.
+2. **Technical owner.** CIO or Head of Engineering Platforms. Buys the runtime, owns SLOs, signs the bill.
+3. **Gatekeeper stack.** CISO + Chief Risk Officer + Chief Compliance Officer + Data Protection Officer. Any one of them can kill a deal during InfoSec or third-party-risk review.
+4. **Procurement + Legal.** Run TPRM intake, redline the contract, escalate license oddities to outside counsel.
+
+Gartner frames the analyst-side reading: by 2028, AI agents will handle 90% of B2B purchasing decisions, channelling >$15T ([digitalcommerce360](https://www.digitalcommerce360.com/2025/11/28/gartner-ai-agents-15-trillion-in-b2b-purchases-by-2028/)). For now (2026), the human chain above is what closes the deal — and Gartner also forecasts that >40% of agentic AI projects will be cancelled by end-2027 ([Gartner press 2025-06-25](https://www.gartner.com/en/newsroom/press-releases/2025-06-25-gartner-predicts-over-40-percent-of-agentic-ai-projects-will-be-canceled-by-end-of-2027)). Default sales motion is "land with the CAIO, survive the gatekeepers, close through procurement."
+
+## Deal-killers (review boards that veto)
+
+| Board | What kills the deal | Citation |
+|---|---|---|
+| **Vendor Risk / TPRM** | NYDFS 21 Oct 2025 industry letter on TPSPs — covered entities must add contractual clauses on AI usage, training-data limits, sub-processor disclosure, exit obligations. Missing any = vendor cannot be onboarded. | [NYDFS IL 2025-10-21](https://www.dfs.ny.gov/industry-guidance/industry-letters/il20251021-guidance-managing-risks-third-party); [Inside Privacy](https://www.insideprivacy.com/cybersecurity-2/nydfs-publishes-industry-guidance-on-managing-cyber-risks-related-to-third-party-service-providers/) |
+| **InfoSec architecture** | No proof of in-perimeter execution; no demonstrated egress controls against indirect prompt injection / data exfiltration; no signed audit trail under one retention policy. | [Purplesec on data exfiltration via prompt injection](https://purplesec.us/learn/data-exfiltration-ai-prompt-injection/); [dev.to AI governance gap](https://dev.to/ashutoshrana/every-enterprise-ai-framework-has-a-compliance-gap-heres-the-architecture-that-closes-it-20np) |
+| **DORA (EU)** | Active enforcement began 2026; fines up to 2% of global turnover (entities) or €5M + 1% daily turnover (critical ICT TPPs); supervisors can suspend service. ~50% of regulated entities entered 2026 with known gaps (Deloitte). | [regulation-dora.eu enforcement](https://www.regulation-dora.eu/blog/dora-2026-enforcement-what-changes); [regulation-dora.eu penalties](https://www.regulation-dora.eu/blog/dora-penalties-fines-enforcement-guide-2025) |
+| **Model Risk (was SR 11-7)** | SR 26-2 (17 Apr 2026, jointly Fed/OCC/FDIC) explicitly **excludes** generative and agentic AI from MRM scope as "novel and rapidly evolving" — but bank-wide risk-management and governance expectations still apply. The model-risk path WEAKENS; the broader operational-risk / TPRM / cyber path STRENGTHENS. | [SR 26-2 PDF](https://www.federalreserve.gov/supervisionreg/srletters/SR2602.pdf); [Sullivan & Cromwell memo](https://www.sullcrom.com/insights/memo/2026/April/OCC-Fed-FDIC-Issue-Revised-Guidance-Model-Risk-Management); [cutover.com analysis](https://cutover.com/blog/what-sr-26-2-means-for-banks-deploying-agentic-ai) |
+| **Legal / Procurement** | FSL-1.1-Apache-2.0 is not on standard license whitelists. Procurement will escalate to outside counsel; expect questions on the 2-year Apache-2.0 conversion and the anti-SaaS clause. Plan one-pager + redlined MSA before first call. | (assumption, uncited; banks default to OSI-approved list) |
+| **DPO / GDPR** | Sub-processor sprawl in public SaaS; data-residency commitments via cloud-provider regional inference are conditional. Claude default routes through US infra ([github issue 40526](https://github.com/anthropics/claude-code/issues/40526)). | [claudereadiness.com](https://claudereadiness.com/blog/claude-security-privacy-enterprise/) |
+
+## Why-now 2026 forcing functions
+
+- **EU AI Act timeline relief (and trap).** Digital Omnibus political agreement 7 May 2026: standalone Annex III high-risk deferred to **2 Dec 2027**; product-embedded high-risk to **2 Aug 2028** ([Consilium press 2026-05-07](https://www.consilium.europa.eu/en/press/press-releases/2026/05/07/artificial-intelligence-council-and-parliament-agree-to-simplify-and-streamline-rules/); [Hogan Lovells](https://www.hoganlovells.com/en/publications/eu-legislators-agree-to-delay-for-highrisk-ai-rules); [White & Case](https://www.whitecase.com/insight-alert/eu-agrees-digital-omnibus-deal-simplify-ai-rules)). Banks read this as "more time to do it right," not "skip it." Agentic systems will almost certainly land in Annex III when scoped against credit decisioning, KYC, employee monitoring.
+- **DORA enforcement live.** Regulation in force since 17 Jan 2025; 2026 is the first full year of active supervisory action. First compulsion payments issued; cross-checks against the Register of Information automated ([regulation-dora.eu 2026 changes](https://www.regulation-dora.eu/blog/dora-2026-enforcement-what-changes)).
+- **Shadow-AI cost is now a board metric.** IBM Cost of a Data Breach 2025: 20% of breached orgs had a shadow-AI incident; avg total cost $4.63M (vs $4.44M baseline) — $670K premium per breach; 97% of AI-breach victims lacked basic AI access controls ([VentureBeat](https://venturebeat.com/security/ibm-shadow-ai-breaches-cost-670k-more-97-of-firms-lack-controls); [IBM newsroom](https://newsroom.ibm.com/2025-07-30-ibm-report-13-of-organizations-reported-breaches-of-ai-models-or-applications,-97-of-which-reported-lacking-proper-ai-access-controls); [Kiteworks summary](https://www.kiteworks.com/cybersecurity-risk-management/ibm-2025-data-breach-report-ai-risks/)).
+- **Public-SaaS Computer Use blockers in banking.** Anthropic's enterprise plan blocks financial-services categories by default in the Claude in Chrome extension ([Harmonic guide](https://www.harmonic.security/resources/securing-claude-cowork-a-security-practitioners-guide)); EU residency requires deployment via Bedrock/Vertex/Foundry rather than native Anthropic API ([github issue 40526](https://github.com/anthropics/claude-code/issues/40526)). Result: every bank that wants Computer Use must either (a) accept a sub-processor stack 3-deep or (b) self-host.
+
+## Top use-cases that close vs theoretical
+
+| Use-case | Close window in 2026 | Evidence |
+|---|---|---|
+| **KYC / AML investigator assistance** (alert-to-case-closure copilot, transaction-monitoring triage) | Closes now. 58% of banks already use AI for AML/KYC; a Dutch tier-1 reports 90% reduction in onboarding time, 30% staff workload cut. McKinsey writes specifically about agentic AI for client-onboarding and sanctions/fraud investigations. | [McKinsey on agentic AI for KYC/AML](https://www.mckinsey.com/capabilities/risk-and-resilience/our-insights/how-agentic-ai-can-change-the-way-banks-fight-financial-crime); [Deloitte AI adoption in FIs](https://www.deloitte.com/middle-east/en/services/consulting/perspectives/ai-adoption-in-financial-institutions-balancing-growth-and-governance.html) |
+| **Internal IT helpdesk automation** | Closes now. Lowest regulatory exposure, internal user, defensible RoI. | (assumption; commonly named in BCG/Deloitte FI surveys) |
+| **Developer productivity (sandboxed Computer Use for engineers)** | Closes 2026 if self-hosted; blocked on public SaaS by procurement. | (assumption from sub-processor and residency evidence above) |
+| **Compliance evidence collection / control testing** | Closes 2026-2027. On-prem deployments make audit easier — "every artifact lives in one place under one retention policy with one signed audit trail" ([dev.to](https://dev.to/ashutoshrana/every-enterprise-ai-framework-has-a-compliance-gap-heres-the-architecture-that-closes-it-20np)). | |
+| **Ops / back-office automation** | Closes 2026 in narrow workflows; broad deployment is year+ away. Only ~10% of FIs apply AI at scale per BCG; 75% still experimenting ([BCG retail banking report 2025](https://web-assets.bcg.com/9e/6f/ee4a643a48f9b4133de389e10386/2025-retail-banking-report-nov-2025-n.pdf); [BCG "AI reckoning"](https://web-assets.bcg.com/1a/b0/007d0359442eb77e5f3aaf07b5c1/for-banks-the-ai-reckoning-is-here-may-2025.pdf)). | |
+| **Credit decisioning, customer-facing advisory** | Theoretical for v1. Annex III high-risk; SR 26-2 carve-out plus broad governance still attach; reputational risk too high without a track record. | EU AI Act + cited MRM evidence above. |
+
+## Competitive gap in 2026
+
+| Competitor | Posture | Gap they leave open |
+|---|---|---|
+| **Anthropic Enterprise** (Code with Claude, London 19 May 2026) | Self-hosted sandboxes in public beta; MCP tunnels in research preview. Tool execution moves customer-side; **orchestration, context, recovery stay Anthropic-side** ([InfoQ](https://www.infoq.com/news/2026/05/claude-mcp-tunnels/); [The New Stack](https://thenewstack.io/anthropic-mcp-tunnels-sandboxes/); [9to5Mac](https://9to5mac.com/2026/05/19/anthropic-enhances-claude-managed-agents-with-two-new-privacy-and-security-features/)). | Agent-loop control plane is a foreign dependency; model-lock-in is structural; not multi-provider. |
+| **UiPath Automation Suite — on-prem agentic AI (5 May 2026)** | Self-hosted runtime, supports cloud or self-hosted LLMs. Public-sector launch but explicitly extended to banking. ([UiPath IR](https://ir.uipath.com/news/detail/446/uipath-automation-suite-delivers-on-premises-agentic-ai-for-the-public-sector); [DIGITIMES](https://www.digitimes.com/news/a20260522PD207/security-data.html); [Let's Data Science](https://letsdatascience.com/news/uipath-launches-on-premises-agentic-ai-for-public-sector-9d98d910)) | RPA shape (workflow-orchestrator first, computer-use second); commercial license; lock-in to UiPath skill format. The "agent gives you what you want only inside the UiPath product surface" trap. |
+| **OpenAI Enterprise** | Hosted only; no in-perimeter agent loop GA. | Same as Anthropic but worse residency story. |
+| **Microsoft Copilot Studio** | Tied to Azure tenant; assumes M365 + Graph + Azure OpenAI. | Not model-agnostic; not deployable outside Azure; not in-perimeter for non-Azure banks. |
+| **Skyvern (OSS)** | AGPL-3.0 core; SOC2 Type II + HIPAA in managed cloud. Self-hostable via Docker. ([GitHub](https://github.com/Skyvern-AI/skyvern); [skyvern pricing](https://www.skyvern.com/pricing)) | **AGPL-3.0 is the gap.** Banks running a customised in-perimeter fork would face source-disclosure pressure if they ever exposed it as a "service" — most legal teams reject AGPL by policy. |
+
+Gap that remains for an FSL-1.1-Apache-2.0, model-agnostic, in-perimeter platform with a customer-controlled agent loop: real, but narrower than 12 months ago. Differentiation must rest on (a) full agent loop in-perimeter (not just tool execution), (b) model-agnosticism with no Anthropic/OpenAI tax, (c) bank-acceptable license, (d) audit-evidence pipeline as a first-class component — not a UiPath/Anthropic afterthought.
+
+## Domain-expert failure modes
+
+Concrete patterns that kill enterprise AI deals in 2024-2026 compliance review:
+
+1. **Mock-only on-prem path.** Vendor claims "self-hostable" but the orchestration/agent loop still phones home (Anthropic's first cut of Managed Agents was exactly this until the May 2026 update). Auditor asks for a network diagram, finds an outbound dependency on a public endpoint, deal stalls.
+2. **BYOK theater.** Customer brings the KMS, but vendor still decrypts plaintext on vendor-managed servers. Fails any DPO review where the threat model includes the vendor.
+3. **Sub-processor sprawl.** Single AI feature ends up with 4-deep sub-processor chain (LLM vendor → hyperscaler → vector-DB SaaS → observability SaaS). NYDFS Oct 2025 letter and DORA's third-party register both make this fatal: each link is a separate due-diligence file.
+4. **Missing or non-tamper-evident audit trail.** 97% of orgs that suffered AI-related breaches in 2025 lacked basic AI access controls ([IBM newsroom](https://newsroom.ibm.com/2025-07-30-ibm-report-13-of-organizations-reported-breaches-of-ai-models-or-applications,-97-of-which-reported-lacking-proper-ai-access-controls)). Banks demand WORM-style append-only logs covering prompt, tool call, retrieved context, model output, human override.
+5. **AGPL-via-the-back-door.** OSS component (Skyvern, browserless, similar) buried in the product, surfaced only at the OSS-license scan stage of TPRM. Auto-rejection in most banks.
+6. **EU residency claimed via "we can deploy on Bedrock."** Conditional residency is not residency; the customer has to own the deployment to claim the control. Procurement reads this in 5 minutes.
+7. **Pilot that never scales because risk controls were retrofitted.** 42% of orgs abandoned most AI initiatives in 2025; primary cause cited is compliance and governance, not technical ([dev.to](https://dev.to/ashutoshrana/every-enterprise-ai-framework-has-a-compliance-gap-heres-the-architecture-that-closes-it-20np)). The "we'll add audit later" architecture loses at the InfoSec review.
+8. **Shadow-AI bypass.** Sanctioned tool too painful to use → users go back to ChatGPT on a personal phone. IBM: 20% of breaches now involve shadow AI ([VentureBeat](https://venturebeat.com/security/ibm-shadow-ai-breaches-cost-670k-more-97-of-firms-lack-controls)). A platform with friction higher than the public-SaaS alternative loses through this channel even after winning the deal.
+
+## What this means for Manifesto §01
+
+8 recommendations the architect should write into `manifesto/01-audience-and-buyer.md`:
+
+1. **MUST** name the buyer as a chain, not a role. List the four chains (business sponsor / technical owner / gatekeeper stack / procurement-legal) with veto-mapping. One sentence each.
+2. **MUST** name the CAIO as the modal sponsor for 2026-2028, with HSBC/UBS/CBA/NatWest as anchor citations. State the assumption that the function exists even when the title does not.
+3. **MUST** name the top three deal-killers explicitly: TPRM/NYDFS, InfoSec architecture review, DORA active enforcement. One paragraph each, with the citations from this brief.
+4. **MUST NOT** rest the thesis on "only enterprise in-perimeter Computer Use." UiPath shipped 5 May 2026; Anthropic shipped self-hosted sandboxes 19 May 2026. The defensible framing is "full agent loop in-perimeter, multi-provider, FSL-licensed, audit-evidence as first-class component" — pick at least two and stake them.
+5. **MUST** state the SR 26-2 carve-out and its consequence: model-risk path weakens, TPRM / operational-risk / cyber path strengthens. v1 architecture must over-invest in the second, not the first.
+6. **MUST NOT** cite the McKinsey "$200-340B" headline. Use BCG "~10% at scale, 75% still experimenting" and the IBM shadow-AI cost figures instead.
+7. **SHOULD** list the v1 closing use-cases (KYC/AML copilot, internal IT helpdesk, developer productivity, compliance evidence) and explicitly mark credit decisioning + customer-facing advisory as out-of-scope for v1.
+8. **SHOULD** include a "failure modes that kill the deal" table mirroring §Domain-expert failure modes above, abbreviated to one line each. Banks recognise their own review processes; this signals we know what theirs look like.
+9. **SHOULD** keep §01 to ≤80 lines and stop. Detail belongs in component specs and ADRs; §01 names who buys and what stops them.
+
+## Open questions
+
+- Is "CAIO is the modal sponsor" true at JPMorgan / Goldman / Morgan Stanley, where AI is run from existing CTO/COO structures? Needs sponsor research.
+- What is the actual procurement experience of FSL-1.1 in 3+ tier-1 banks? Currently an uncited assumption.
+- Does the Anthropic 19 May 2026 release route the agent loop entirely customer-side in self-hosted-sandboxes mode, or only tool execution? Re-read the InfoQ + Anthropic docs before §01 lands.

package/docs/future-architecture/research/enthusiast-audience.md

@@ -0,0 +1,106 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-24
+owner: nick
+applies-to: docs/architecture/manifesto/01-audience-and-buyer.md
+---
+
+Research brief for the secondary (solo enthusiast) audience of `next/v1`; input to Manifesto §01.
+
+## Is the OSS to enterprise funnel real for self-hostable infra?
+
+Evidence is genuine but uneven. Three patterns dominate.
+
+**Funnel works when the OSS product is the same engine as the paid product.** Sentry: self-hosted free version drove top-of-funnel; major customers (Instacart, GitHub, Disney, Atlassian, Reddit, Slack) started self-hosted, then bought hosted as scale made DIY uneconomic. Self-serve is ~70% of revenue as of May 2024 (4M developers, 90K orgs).<sup>[1]</sup> Sentry's FSL license is the direct precedent for this repo's license choice.
+
+**Funnel works when bottom-up adoption produces internal champions.** HashiCorp Vault and Terraform — Community Editions onboard practitioners; HCP/Enterprise upsell triggers at the governance / scale / risk boundary. HashiConf 2024 explicitly markets a "Terraform migrate" beta to move CE workflows into HCP.<sup>[2]</sup> dbt followed the same shape: 5+ years of free `dbt Core` adoption, then dbt Cloud crossed $100M ARR by 2024 (Fortune 500 adoption +85% YoY).<sup>[3]</sup> Grafana: 25M users feed 5,000+ paying customers (Bloomberg, Citigroup, Dell, Salesforce); $6B valuation in 2024.<sup>[4]</sup>
+
+**Funnel breaks when you cut off the free engine.** Buoyant stopped publishing stable Linkerd binaries for orgs >50 employees in February 2024. The 2024 CNCF Annual Survey shows service-mesh adoption fell from 50% to 42% YoY despite Kubernetes climbing to 93%.<sup>[5]</sup> Buoyant's own velocity rebounded (IPv6, Gateway API, post-quantum shipped within 18 months), so the company survived — but the *community funnel* did not. This is the cautionary anchor for any decision to gate features behind the paid tier.
+
+For Computer Use specifically: Coder.com (self-hostable workspaces with developer-first DX, then enterprise governance) is the closest live analog and the most relevant funnel shape to copy.<sup>[6]</sup>
+
+## Personas for in-perimeter Computer Use platform
+
+Ranked by v1 relevance.
+
+| Rank | Persona | What they contribute |
+|------|---------|----------------------|
+| 1 | Indie agent builder | Evals, bug reports, novel skill recipes, public writeups that bank InfoSec then forwards internally |
+| 2 | Internal-IT / platform team at non-bank SMB | Real-world deployment friction; same threat model as enterprise just smaller; revenue path via mid-market |
+| 3 | OSS maintainer / contributor | Code, integrations (LangChain/Dify/Haystack adapters), MCP server contributions |
+| 4 | Privacy-focused self-hoster (Nextcloud/Immich crowd)<sup>[7]</sup> | Hardening reports, default-closed advocacy, attack-surface audits — directly aligned with bank threat model |
+| 5 | AI researcher / grad student | Reproducible evals, paper citations, novel agent recipes |
+| — | Solo SaaS founder | DROP. The license forbids competing hosted services — this persona is a license violation by definition |
+
+Bank-employed staff engineers exploring at home read as Persona 1 or 4 by behaviour; they sit inside the enterprise funnel by employer.
+
+## Domain-expert DX patterns that make OSS docs delightful
+
+- **Stripe three-column layout**<sup>[8]</sup>: persistent nav | concept | runnable curl/SDK side-by-side. Hover synchronises prose and code. Result: zero context-switch from "what is this" to "paste this". For our docs: every `getting-started/` page exposes a runnable command in the right gutter; reference docs show the YAML and the CLI invocation together.
+- **Rust Book pull-model teaching**<sup>[9]</sup>: direct "you" address, explicit "skip ahead if you want", deliberate non-compiling examples with the exact compiler error printed. The book teaches *how to read errors*, not how to avoid them. For our docs: include the failure path for every happy path — what the audit log shows when policy denies, what the CLI returns when SCIM fails.
+- **FastAPI auto-generated correctness from types**<sup>[10]</sup>: the OpenAPI spec is generated from Python type hints; docs cannot drift from code because they are the same artifact. For our docs: the Helm `values.yaml` reference, OpenAPI for the broker API, and CLI `--help` are all generated, never hand-edited.
+- **Fly.io EffortPost format**<sup>[11]</sup>: bold lede, 2000+ words, runnable code, claims defended with measurements. Fly is moving away from optimising every post for HN — the format still works for one-shot deep dives (e.g. the threat-model walkthrough, the audit-trail design post).
+- **Tailwind reference docs**<sup>[12]</sup>: every utility documented with the exact CSS it generates and a copy button. Equivalent for us: every NFR scenario in the manifesto shows the measurable target *and* the test command that verifies it.
+
+Stripe/Rust/FastAPI/Fly all share one trait that distinguishes them from corporate ISMS docs: prose paragraphs are short, every claim is verifiable, no marketing voice.
+
+## Tensions between bank and enthusiast requirements
+
+| Tension | Resolution mechanism in v1 |
+|---------|----------------------------|
+| Image tags (mutable `latest` for hacking; pinned + cosign for procurement) | Publish both. `:edge` for enthusiasts, `:vX.Y.Z` + signed digest for banks. Documented in release notes. |
+| IdP (Keycloak/Entra mandatory vs none-at-all) | `auth.mode: local` env flag ships local-only with single admin token; `auth.mode: oidc` enforces SCIM/SAML. Default in Helm chart: `oidc`; default in Compose quickstart: `local`. |
+| Audit sinks (Splunk/QRadar vs filesystem) | `audit.sink` interface with `filesystem`, `syslog`, `splunk-hec`, `qradar` implementations. Filesystem ships with the repo; the rest are integration docs. |
+| Threat-model placement (visible vs hidden) | Diátaxis split absorbs: `docs/architecture/security/threat-model.md` for bank InfoSec; `docs/getting-started/security-defaults.md` for enthusiast (one screen, "these are the defaults that protect you"). |
+| Support model | Bank-only contract. No tension — enthusiasts get GitHub issues + community Discord, banks pay for SLA. State this once in the manifesto, not on every doc page. |
+| Doc voice | Diátaxis quadrant decides voice, not audience. `architecture/` and `compliance/` are reference + explanation (formal, NFR-style). `getting-started/`, `operating/`, `contributing/` are tutorial + how-to (direct "you", runnable). |
+| Default-closed network posture | Default-closed everywhere. The enthusiast tradeoff is a one-line env override (`network.egress.mode: allow-localhost`) documented in `getting-started/local-development.md`. No special build, no soft default. |
+
+The mechanism that does *not* work: a single doc that tries to address both audiences in alternating paragraphs.
+
+## Cope-check: did anyone die from dual-audience?
+
+The Authentik 2024 incident is the live cautionary tale.<sup>[13]</sup> A community PR to add an SSO source was rejected because SAML connections were in the paid tier. The community read this as "SSO is security tablestakes in 2024, you cannot gate it behind enterprise." Authentik responded with a blog post conceding the framing, then shipped SCIM/OAuth/SAML/Plex *source* mappings in 2024.8 to the open-source product. The lesson: *security primitives cannot be the paid moat for an OSS security product*. For Computer Use this means SCIM/SAML, audit-trail integrity, signed releases, and threat-model docs must all live in the OSS product; the moat is operational (managed deployment, paid SLA, certification packs), not capability.
+
+Honest read on "dual audience": the constraint is load-bearing for licensing (FSL-1.1-Apache-2.0 only makes sense if enthusiasts can use it) and load-bearing for credibility (banks distrust OSS products with no real community), but it is *not* load-bearing for §01 of the Manifesto. §01 should name the primary buyer cleanly and treat the enthusiast as a downstream consequence of the licensing decision, not a co-equal persona in the buyer document. Treating it as co-equal is the procrastination risk.
+
+## Domain-expert failure modes
+
+Patterns where projects pretend to serve both audiences and serve neither:
+
+1. **Marketing-tone README the bank rejects, dense ADRs the enthusiast skips.** A README opening with "industry-leading, battle-tested, enterprise-grade AI agents" signals to bank InfoSec that the project has no audit posture; signals to enthusiasts that it is vapourware. Banned vocab list in this repo's CLAUDE.md exists for this reason.
+2. **Half-OSS / half-paid security primitives.** Authentik 2024 above. Any project where SSO, audit, or RBAC sits behind paywall loses the OSS community immediately and gains zero bank trust (banks read the same news).
+3. **Quickstart that needs Kafka + Vault + Keycloak.** If the "5-minute getting started" requires the enterprise stack, no enthusiast tries it; the funnel never opens. Counter-pattern: Dify and n8n ship `docker compose up` with sane local defaults.<sup>[14]</sup>
+4. **Threat model written as marketing.** "Defense in depth", "zero trust", "secure by design" with no DFD, no STRIDE table, no measured posture. Bank InfoSec discards on first read; enthusiast cannot tell what the defaults actually do.
+5. **ADRs that mix decision with rationale with implementation.** Nygard format exists for a reason; bank reviewers grep for `Decision:` and bail when they cannot find it.
+
+## What this means for Manifesto §01
+
+1. State the primary buyer in one sentence: tier-1 US/EU bank InfoSec procuring an in-perimeter Computer Use platform.
+2. State the licensing consequence next: FSL-1.1-Apache-2.0 means anyone can self-host, fork, and modify — therefore an OSS community exists and is a permanent part of the project's surface.
+3. Frame the enthusiast as a *consequence of the license*, not a *co-primary persona*. One paragraph, not a parallel section.
+4. List the four enthusiast contributions §01 expects: evals, hardening reports, MCP/skill contributions, public writeups. Tie each to a measurable feedback channel (GitHub issue label, eval submission, Discord channel).
+5. Hard rule: security primitives (SCIM/SAML, audit integrity, signed releases, default-closed network, threat-model docs) are in the OSS product. The moat is operational, not capability. Cite Authentik 2024 as the anti-pattern. Cite Linkerd 2024 as the funnel-break anti-pattern.
+6. Move audience-specific DX guidance out of §01 into a separate Manifesto entry on documentation discipline (already drafted as banned-vocab list in CLAUDE.md). §01 is "who and why", not "how we write".
+7. Demote the solo SaaS founder persona explicitly — the license forbids that customer. Stating this in §01 prevents a recurring product-design argument.
+8. End §01 with one anti-example: "We will not write a README that opens with marketing adjectives, because both audiences read the same first paragraph and both lose trust differently." This is the single sentence that operationalises dual-audience without giving it a co-equal section.
+
+## Sources
+
+[1] [Sentry self-serve funnel](https://research.contrary.com/company/sentry); [Sentry FSL licensing](https://open.sentry.io/licensing/)
+[2] [HashiConf 2024 — Terraform migrate, CE to Enterprise](https://www.globenewswire.com/news-release/2024/10/15/2963222/0/en/HashiConf-2024-brings-community-and-customers-together-to-do-cloud-right-with-best-practices-for-cloud-infrastructure-automation.html); [HashiCorp CE→Enterprise strategy](https://medium.com/continuous-insights/from-oss-to-enterprise-when-hashicorp-terraform-and-vault-need-to-grow-with-you-f97d1048b8ef)
+[3] [dbt Labs Snowflake / $100M ARR / source-available](https://www.runtime.news/dbt-labs-source-available-bet-pays-off-at-snowflake/); [dbt Core vs dbt Cloud framing](https://www.getdbt.com/blog/how-we-think-about-dbt-core-and-dbt-cloud)
+[4] [Grafana Labs $6B valuation, 25M users, 5,000+ customers](https://research.contrary.com/company/grafana); [Grafana 2024 year in review](https://grafana.com/blog/open-source-at-grafana-labs-2024-year-in-review/)
+[5] [Linkerd stable-binary policy change Feb 2024](https://www.buoyant.io/linkerd-vs-istio); [Service Mesh at a Crossroads — CNCF survey 50%→42%](https://cloudnativenow.com/features/service-mesh-at-a-crossroads-istios-graduation-and-the-road-ahead/)
+[6] [Coder enterprise AI development infrastructure](https://coder.com/blog/coder-enterprise-grade-platform-for-self-hosted-ai-development); [Coder + Linkerd partner-of-year](https://coder.com/blog/coder-named-hashicorp-integration-partner-of-the-year-for-2024)
+[7] [Immich + Nextcloud self-hoster persona](https://cloudbasedbackup.com/en/blog/nextcloud-vs-immich-choosing-the-right-self-hosted-photo-and-cloud-solution); [self-hoster trade-offs](https://bhaveshmishra.dev/blog/self-host-curse/)
+[8] [Stripe docs teardown — three-column](https://www.moesif.com/blog/best-practices/api-product-management/the-stripe-developer-experience-and-docs-teardown/); [Stripe docs case study](https://ninadpathak.com/marketing-research/stripe-documentation-case-study/)
+[9] [The Rust Programming Language — Introduction](https://doc.rust-lang.org/book/ch00-00-introduction.html); [Why Rust Docs Are the Gold Standard](https://medium.com/@syntaxSavage/why-rust-docs-are-the-gold-standard-and-every-language-should-copy-them-4ec8f1edc14b)
+[10] [FastAPI OpenAPI auto-generation](https://fastapi.tiangolo.com/reference/openapi/docs/); [type-safe SDK generation from FastAPI](https://www.speakeasy.com/openapi/frameworks/fastapi)
+[11] [Fly.io — A Blog, If You Can Keep It (EffortPost retrospective)](https://fly.io/blog/a-blog-if-kept/)
+[12] [Tailwind CSS docs and IntelliSense](https://floatui.com/blog/tailwind-css-documentation-the-essential-guide)
+[13] [Authentik response — Nov 2024](https://goauthentik.io/blog/2024-11-21-if-your-open-source-project-competes-with-your-paid-project/); [Authentik 2024.8 release shipping SCIM/SAML sources to OSS](https://docs.goauthentik.io/releases/2024.8/)
+[14] [Self-hostable AI agent platforms 2025/2026 — n8n, Dify, Haystack](https://www.knowlee.ai/blog/self-hosted-ai-agent-platforms-2026); [Microsoft Agent Governance Toolkit](https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/)