RFCs

README

agent-console-RFC-001-foundations

ai-RFC-001-generative-ui-via-kvg

apidocs-RFC-001-foundations

billing-RFC-001-foundations

Brand assets (logo, color, typography, icon, downloads, press, legal) live as subpages of the existing `brand.koder.dev` Jet vhost, which is the Area-9-of-9 hub of the Koder ecosystem ("How the ecosystem shows itself to the world. Marketing sites, brand assets, public documentation"). The Area-9 hero stays at `/`; the brand-assets pages land at `/logo/`, `/color/`, `/typography/`, `/icon/`, `/downloads/`, `/press/`, `/legal/`. Path C of three reconciliation paths considered; preserves the 9-Area URL symmetry, implements the textual promise of the Area-9 hub, zero migration. KDS at `kds.koder.dev` remains the dev reference.

brand-RFC-001-brand-site-architecture

cache-RFC-001-foundations

canvas-RFC-001-a2ui

classify-RFC-001-foundations

curator-RFC-001-foundations

dataset-RFC-001-foundations

design-RFC-001-koder-design-system

design-RFC-002-responsiveness-sdk-extraction

design-RFC-003-facets-as-cross-cutting-tags

Evaluates 3 options for shipping a live, interactive component preview alongside the KDS site — Storybook proper, Ladle / Histoire (lighter alternatives), or a Koder-native HTMX-driven sandbox using the existing design-gen + templ pipeline. Recommendation: Koder-native v0; promote to external tooling later if breadth justifies.

design-RFC-004-component-preview-tooling

Evaluates 3 mechanisms for keeping a Koder Design Figma kit in lockstep with ratified Verge tokens (Tokens Studio plugin vs Specify CLI vs custom Figma plugin reading from `dist/tokens/tokens.json`). Recommendation: custom plugin v0 consuming the already-emitted `tokens.json` (per design-gen #059).

design-RFC-005-figma-kit-and-token-sync

Decides how koder_kit (Flutter / Dart) and koder_web_kit (JS) and future native consumers (Kotlin Android, Swift iOS, Rust embedded) receive the canonical Verge tokens. Evaluates copy-on-build vs publish-and-import. Recommendation: copy-on-build via CI workflow for v0; promote to a published koder_design_tokens package per language when consumer count crosses 3.

design-RFC-006-cross-language-token-distribution

Surveys whether Verge should evolve from its current FLAT token model (`bg`, `surface`, `text`, `accent`, `border`, `focus` declared directly per preset) to a 3-tier hierarchy modeled on Ant Design — **seed tokens** (small input set), **map tokens** (derived by algorithm: light / dark / compact), **alias tokens** (semantic names consumed by components). Owner sign-off required to ratify; this RFC LAYS OUT the three options and trade-offs without picking one.

design-RFC-007-token-hierarchy-seed-map-alias

Evaluated whether KDS should introduce a **Pro layer** above its primitive components — pre-bundled toolbars, saved views, density toggles, column visibility menus, export hooks — to spare every Koder admin tool (Forge, Kdrive admin, Hub publisher, …) from re-wiring the same boilerplate. **Ratified Option C (recipe doc only)** on 2026-05-23 — see `specs/patterns/admin-data-table.kmd`. Re-evaluation trigger documented in R5: when a third admin tool re-derives the same toolbar, re-open this RFC.

design-RFC-008-pro-opinionated-wrappers

Today `make gen` in `tools/design-gen` always full-renders the entire KDS site — ~480 pages × ~3 locales + tokens + OG images + JSON APIs + sitemap + llms.txt. Observed wall-clock: ~10m27s for 226 specs (2026-05-24 timing). Dev iteration cost grows linearly with the corpus. This RFC ratifies the **content-hash + manifest** incremental-build approach (Option A) before implementation begins, with the file-watcher dev mode (Option B) layered on top, and the Bazel-style dependency graph (Option C) deferred until KDS exceeds 1000 pages.

design-RFC-009-incremental-build

Expose the Koder Design System as a hosted Model Context Protocol endpoint at `kds.koder.dev/mcp/` so AI agents (Claude Code, Cursor, Codex, Windsurf) query specs/tokens/components live over streamable-http instead of static-pulling llms.txt + JSON. Strict descendant of stack-RFC-002. KEY CORRECTION to ticket #117: the stdio MCP server ALREADY EXISTS in `koder-design-lsp --mcp` with the 5 core tools; this RFC extends THAT binary with a streamable-http transport rather than building a duplicate `cmd/kds-mcp-server/`.

design-RFC-010-kds-mcp-server

design-gen wires ~29 page renderers by hand in cmd/design-gen/main.go, each as a repetitive stats.Phase(...) block. This RFC ratifies a self-registration framework (Option A) for those page renderers so a new renderer is added by dropping a file that calls kinds.Register in init(), not by editing main.go. KEY CORRECTION to ticket #109: new SPEC families already render with zero code via the generic spec-doc fallback — the real boilerplate is main.go's manual page-renderer wiring, not per-spec kinds. Recommends Option A (registration) over Option B (convention), because Option B's zero-code path already exists.

design-RFC-011-kinds-framework

design-RFC-012-sunken-surface-role

design-RFC-013-verge-expressive-surface-register

embed-RFC-001-foundations

erp-RFC-000-architecture-overview

erp-RFC-001-licitacao-vertical-engine

erp-RFC-002-bpm-workflow-engine

erp-RFC-003-travel-expense-engine

erp-RFC-004-fiscal-brazilian-engine

erp-RFC-005-legal-vertical-engine

errors-RFC-001-error-reporting-framework

extract-RFC-001-foundations

gate-RFC-001-multi-channel-notifications

gate-RFC-002-identity-aware-proxy

hub-RFC-001-delta-delivery

hub-RFC-002-federation-protocol

hub-RFC-003-build-attestation

hub-RFC-004-upgrade-chains

hub-RFC-005-migration-manifests

hub-RFC-006-unification-and-rename

Estender o Koder Hub pra hospedar pacotes `.deb` arm64-Bionic (formato Termux) expondo uma fachada `apt`-compatible em `hub.koder.dev/apt/`. Posicionar o KTermux (fork do termux-app — RFC adjacente) como cliente primário desse surface: `pkg install <slug>` resolve via Hub apt repo. `khub` CLI ganha resolver multi-formato (apk/deb/kpkg/...). Mantém-se `.kpkg` como envelope canônico Koder; `.deb` é export target conforme `specs/kpkg/format.kmd §1`.

hub-RFC-007-apt-deb-surface-and-termux-consumer

id-RFC-015-authorization-groups-and-conditional-scopes

id-RFC-016-kodix-koder-id-joined-os-login

id-RFC-017-identity-bound-full-disk-encryption

id-app-RFC-001-stack-portal-consolidation

imaging-RFC-001-foundations

infra-RFC-001-koder-runtime-strategy

infra-RFC-002-self-hosted-runner-pool

infra-RFC-003-ephemeral-compute-lease-protocol

infra-RFC-004-fleet-global-control-plane

infra-RFC-005-maintenance-window-control-plane

infra-RFC-006-backup-dr-target-architecture

infra-RFC-007-service-discovery-and-edge-routing

infra-RFC-008-krdp-remote-access-protocol-and-module

kdx-RFC-001-koder-document-exchange

kli-RFC-001-persistent-workspace

kmd-RFC-001-page-theme-contract-and-kvg-embed

koder-exec-kit-RFC-001-execution-backends

koder-pair-RFC-001-architecture

Architectural direction for layering a workspace abstraction over the single-user Koder Kodix desktop, so a single installed system can host multiple isolated user contexts (work / personal / per-client) switchable from the kolide-shell panel — without falling back to the much heavier "second Linux user account + relogin" pattern. Each workspace owns its own per-user storage tree, Koder ID binding, apps catalogue, and kolide-shell settings. Apps stay multi-tenant by default (`policies/multi-tenant-by-default.kmd`) so this RFC is the desktop-side surface that finally makes the policy visible to the end user.

kodix-RFC-001-multi-tenant-desktop

Direction for OS-level updates on installed Koder Kodix: how a running system discovers, downloads, applies, and (eventually) rolls back updates to its base system + the koder-suite packages that came from hook 0060. Today the only way to "update" a Koder Kodix install is to re-flash the ISO or run `apt upgrade` per-package; this RFC defines the user-facing CLI (`koder-os-update`), the underlying transport, and the trade-offs between three candidate mechanisms (ostree, apt-only, delta packs). Recommended path: **apt-only over Koder Hub** for v0 (ships in weeks, reuses #012/#116/#117), with A/B partition / ostree evaluated for v1+ once #018's CLI is live.

kodix-RFC-002-os-update-mechanism

The rollback-capable transactional-root mechanism that kodix-RFC-002 (§Decision, §Migration) deferred to "kodix-RFC-003 when written", now also framed by the owner-declared full-live-system objective (#081): the userspace/image half (#082) of "update ANY component with zero physical reboot". Scores three A/B-root candidates — btrfs subvolume snapshots, systemd-sysupdate A/B partitions, ostree/bootc — against RFC-002's five criteria plus reuse-first. Recommended path: **btrfs subvolume A/B (snapshot → atomic default-switch → healthcheck → rollback)**, because Kodix root is already btrfs (#068/#070), so it needs no FS reorg (unlike ostree's `/usr` rdonly) and no doubled root partitions (unlike sysupdate, which also fights the #070 raid1-split layout). FINAL adoption is gated on RFC-002's measurement gate (≥3 months of v0 apt failure-rate telemetry) + owner sign-off — recommendation now, ratification on data (D12: no decision on an unmeasured premise).

kodix-RFC-003-os-rollback

kompass-RFC-001-identity-and-org-unification

Extends kompass-RFC-001 (Person/Membership unification, Phase 0) with two capabilities the unified model implies but did not yet make first-class: (1) **attachable verified identifiers** — identity is the immutable `Person`/`koder_user_id` anchor, and email/handle/passkey/external-email become rows in a `person_identifiers` table attached to it, each carrying a verification method, an assurance level, and a purpose; the single-domain thesis of RFC-012 is preserved as a *policy default*, not as the DB CHECK constraint it is today; and (2) **per-org identity policy** — the org owner configures membership prerequisite, external-representation authority, and a data-custody/offboarding regime, exposed as named "org type" presets (corporate / collective / DAO) over three orthogonal axes (authentication, membership, representation). Mechanism is separated from policy: the data model carries the superset; per-Stack and per-org policy decide what is exposed. Uniqueness/auth invariants are pinned to the kdb `strong:` tier (single-primary), reads served from local followers. Resolves the vocabulary drift across RFC-002/012/017/019 + kompass-RFC-001 by adopting Org→Workspace→Project + Person/Membership as canonical.

kompass-RFC-002-attachable-identifiers-and-org-identity-policy

kover-RFC-001-foundations

kpc-RFC-001-foundations

kruze-RFC-001-companion-multibrowser-extension

kruze-RFC-002-mosaic-tile-tabs

kvg-RFC-001-interactive-profile

kvg-RFC-002-kad-visual-editor-product

kvg-RFC-003-print-profile-and-pdf-content-backend

kvs-RFC-001-worktree-per-session-isolation

kvs-RFC-002-concurrent-ai-first-forge-on-kdb

kvs-RFC-003-slice-d-virtual-working-copy

kvs-RFC-004-build-cache-key-contract

mcp-registry-RFC-001

media-dicom-RFC-001-pacs-gateway

memory-RFC-001-foundations

modelreg-RFC-001-foundations

monorepo-RFC-001-area-first-directory-structure

monorepo-RFC-002-directory-nomenclature

monorepo-RFC-003-l1-domain-taxonomy

monorepo-RFC-004-l2-area-definition

monorepo-RFC-005-l3-sector-definition

monorepo-RFC-006-l4-distribution-forms

monorepo-RFC-007-l2-audience-model-nomenclature

monorepo-RFC-008-l5-language-conventions

monorepo-RFC-009-meta-internal-split

monorepo-RFC-010-component-frameworks

observe-RFC-001-multi-dc-telemetry-ingress

observe-RFC-002-koder-push

playground-RFC-001-foundations

policies-RFC-001-reuse-first-hierarchy

policies-RFC-002-self-hosted-first

policies-RFC-003-component-policies-hierarchy

policies-RFC-003-rfc-phase-pickup

prompt-RFC-001-foundations

sandbox-RFC-001-architecture

sandbox-RFC-001-foundations

sandbox-RFC-002-runtime-tiers-and-placement

scene3d-RFC-001-foundations

scheduler-RFC-001

search-RFC-001-engine-and-cli

search-RFC-001-foundations

signing-RFC-001-multi-jurisdiction

signs-RFC-001-architecture-overview

snapshots-RFC-001-architecture

stack-RFC-001-kdb-as-unified-data-plane

stack-RFC-002-mcp-integration

stack-RFC-003-koder-icons-shared-ui-library

stack-RFC-004-verge-scope-expansion

stack-RFC-005-full-headless-testability

stack-RFC-006-object-storage-plane-and-trust-tiering

stack-RFC-007-credential-ownership-and-byo-provider-keys

stack-RFC-008-autonomous-model-curation

stack-RFC-009-internal-service-mtls-pki

Proposta de arquitetura para um componente Koder na categoria do Parsec: acesso remoto de baixa latência à GPU/desktop de máquinas no data center, servindo (a) cloud gaming (jogos-como-serviço) e (b) workstation GPU remota (render/IA). Frame o pipeline capture→encode(kodec)→transport(WebRTC/relay) →decode→input-return, o orçamento de latência, e a decisão build-vs-adopt sob o gate self-hosted-first. Decisões owner-gated (nome, placement L1/L2, build-vs-adopt) ficam DEFERIDAS à ratificação — este é um draft.

stack-RFC-010-gpu-streaming-platform

stack-RFC-011-shadow-parallel-run-validation

stack-RFC-012-ui-interaction-perf-corpus

stack-RFC-013-spec-driven-requirement-scenario-and-spec-delta

stack-RFC-014-spec-adherence-harness

stack-RFC-015-kanon-declarative-rule-engine

stack-RFC-016-koder-governance-plane

stack-RFC-017-self-hosted-source-catalog-and-radar

stack-RFC-018-clean-urls-locale-negotiation-static-sites

stack-RFC-019-koder-twillio-cpaas-control-plane

Proposes the long-term UI architecture for the Koder Stack: converge every surface of every component onto ONE Koder-owned Rust UI framework — the Verge design system as a shared widget/scene layer, rendered by a single wgpu/Vello backend that becomes native GPU (Vulkan/Metal/DX12/WebGPU) per platform "for free". This removes the Flutter desktop-feel tax and the GTK dependency at the convergence target, and makes Verge pixel-identical everywhere while Koder owns the whole UI stack (the Koda/kdb/kodec "own-your-primitives" line). Because a UI framework is the single largest software undertaking and the frontier is immature for mobile/web/a11y, the Stack is NOT bet on a deliberation: the decision is GATED by a measured proof-slice (the terminal as first consumer) that must clear a11y + headless-testability + startup/feel before any broad migration; if it fails, fall back to a native GTK4/Libadwaita desktop kit (option b).

stack-RFC-019-koder-ui-render-strategy

Makes explicit the Koder Stack's long-term AI model-COMPUTE strategy (the tensor kernels for inference + fine-tuning), which is already implicit in its existing components + the self-hosted-first shadow-flip model. Decision: (a) the mature external GPU ML stack (CUDA/ROCm + axolotl/unsloth/transformers for fine-tuning; Ollama/llama.cpp/vLLM for inference; frontier APIs for the hardest reasoning) is CANONICAL, because it is the only option that passes self-hosted-first G2 (perf parity) today; (b) a Koder-owned, vendor-neutral Rust-ML runtime (candle/burn over wgpu+CUDA) is run as a tracked SHADOW-ACTIVE maturation track that flips per case-of-use only when it clears G2 (≤×1.05) + G3 (≥3 stable releases) — exactly the kodec model. The Stack OWNS the layers where it is already competitive (serving/orchestration/data: gateway, kdb-vector, rag, memory — native Rust/Go). This is ORTHOGONAL to Kanvas (GPU-for-UI ≠ GPU-for-tensors).

stack-RFC-020-ai-compute-strategy

Estabelece a fundação arquitetural para o objetivo "Kode como cockpit operador": o owner conversa com o Kode (a IA da Koder) por surfaces ricas (Kode app primário; Koder Chat/Talk secundárias) e executa trabalho de ponta a ponta na Koder Stack (conectores, CI/deploy/DNS, releases, relatórios), substituindo a dependência do notebook. Define (1) o modelo de DOIS PLANOS — operador (toca dev+infra) × tenant (usa produtos) — com parede entre eles; (2) o Kode Agent service único e surface-agnóstico (cérebro), com os planos como tiers e os apps como clientes finos; (3) o Apex Root (único principal-ápice do owner, peça nova); (4) dois invariantes de segurança (instrução×dados + enclave por plano). Não redesenha a multi-tenancy — adota id-RFC-017 (ratificada).

stack-RFC-020-operator-plane-apex-root-and-kode-agent

Co-design the Koder native GPU UI toolkit (Kroma, stack-RFC-019) WITH the Koder display server (kompose — a wlroots Wayland compositor) and the desktop environment (Kolide), the way GTK/GNOME/Mutter co-evolved — but as CLEAN PROTOCOLS between independent layers, NOT a monolith. The high-leverage decision, taken now because the Kroma windowing layer (S4e) is about to be wired: Kroma's window/surface layer is a BACKEND ABSTRACTION (GDK-style) so it stays multi-backend + standalone. Backends: HeadlessBackend (testing), WinitBackend (#1, generic Wayland/X11/Win/Mac — already runs on kompose), KoderWaylandBackend (#2, deep kompose/Kolide integration: wlr-layer-shell, tiling, session, a11y, Koder CSD). Shared seams: Verge (the design system, across shell + apps), one language-agnostic tiling tree (port koder_tiling Dart → neutral/Rust), AccessKit → the Koder a11y bus, dmabuf zero-copy present. The Kroma Wayland backend is validated headlessly against kompose via koder_test_compositor.

stack-RFC-021-kroma-compositor-de-contract

Resolve a causa-raiz da análise superficial das IAs sobre a Koder Stack: não falta "um índice", falta um GRAFO completo e sempre-atual de componentes E das conexões entre eles (hoje deferido no programa #151, travado em dado esparso), e falta um glossário de termos/siglas. Define: (1) o Stack Graph é GERADO por binário (estendendo o `koder-stack-graph` existente) sobre uma SSOT de arestas DECLARADAS em `koder.toml` (sempre-atual por construção, zero drift — Code First); (2) saída dupla de um gerador único — camada de dependências no Graph Explorer (#151, humano) + `stack-graph.json` + digest por-componente (consumo da IA); (3) glossário gerado (termos/siglas × componentes × specs); (4) enforcement por extensão do JIT existente (RFC-014 fase 3) para ser COMPONENT-aware + Regra 11 apontando pro Stack Graph — SEM gate-root novo (tecnicamente impossível em hooks Claude Code e contra o design da RFC-014). Expande o #151 e a RFC-014; não cria mecanismo paralelo.

stack-RFC-021-stack-graph-connections-glossary

stack-RFC-022-kroma-web-backend

stack-RFC-023-kroma-web-module-packaging

Resolve a colisão tripla do nome "Atlas" e a incoerência do portal de docs, decidindo a identidade e a URL pública de cada superfície de conhecimento da Koder Stack. Decisões: (1) **"Atlas" = cartografia/geo apenas** — fica exclusivo do serviço Koder Atlas (mapas, ex-Maps); nenhuma outra superfície usa "Atlas". (2) O compêndio enciclopédico de IA que vínhamos chamando de "Atlas da IA" passa a ser o **Compêndio de IA** (forma modular ilustrada, 7 partes), e **absorve** o `compendium/` denso antigo como camada de referência (fonte única por domínio, zero duplicação — D6). (3) Os três compêndios (IA, Criptografia, Blockchain) ganham um portal próprio **`compendium.koder.dev`**, separados do portal de engenharia por audiência. (4) O atual `meta.koder.dev` é renomeado (URL pública) para **`stack.koder.dev`** — o explorador do mapa da arquitetura da Koder Stack (grafo + cânone de engenharia); `meta/` permanece como path interno do monorepo (taxonomia RFC-003), inalterado. (5) O renderer (`koder-docs-render`) ganha o path do Compêndio de IA (`meta/docs/ia/compendium-ia/`), destravando a publicação — hoje o conteúdo construído não tem rota.

stack-RFC-024-knowledge-surfaces-naming-and-portals

Define COMO componentes da Koder Stack decidem em qual GPU física rodar (iGPU integrada vs dGPU discreta, em máquinas híbridas) e como gerenciam a energia da dGPU. A decisão central é **separar política de mecanismo**: (1) **Contrato/política compartilhado (camada 1)** — um único modelo que todos os componentes herdam: preferência por-superfície (`auto`/`igpu`/`dgpu`), heurística de "este workload merece a dGPU", lifecycle de power-management (dGPU dorme em runtime-D3 quando ociosa), modelo de override do usuário e naming. Vive no backbone **Kore** como spec normativa + um helper fino no SDK (`koder_kit`). (2) **Backends por-engine (camada 2)** — cada engine de render implementa o mecanismo conformando ao contrato: **Kroma** (apps nativos, via seleção de adapter wgpu) → todos os apps Kroma herdam de graça; **Kruze** (Chromium/CEF, via GPU-process pinning — KRUZE-277); **caminho de vídeo** (decode HW VA-API/NVDEC). (3) **Apps (camada 3)** — herdam via seu engine, sem código próprio de GPU. Decisão explícita: **NÃO** centralizar a implementação inteira no Kore/Kroma (impossível para o Kruze, que embarca um engine de terceiro com subsistema de GPU próprio), e **NÃO** reimplementar por módulo (drift de thresholds/power-lifecycle/UX). O comum sobe como contrato; o específico fica no engine.

stack-RFC-025-gpu-device-selection-and-power-policy

synth-RFC-001-foundations

take-RFC-001-architecture-overview

tools-RFC-001-foundations

trace-RFC-001-foundations

training-RFC-001-foundations

translate-RFC-001-foundations

tribus-RFC-001-foundations

video-RFC-001-foundations

vision-RFC-001-foundations

workflow-RFC-001-foundations