> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture decisions

> Why the repository looks the way it does.

Each ADR records one decision, its context, consequences and the check that enforces it. An accepted ADR is not rewritten: a later ADR supersedes it, in the same commit, and the old page points forward. Format and status vocabulary: [template](/adr/template).

| ADR | Decision | Status |
| - | - | - |
| [0001](/adr/0001-monorepo-layout) | Monorepo layout, catalogs and tooling | Accepted |
| [0002](/adr/0002-docs-on-mintlify) | Documentation on Mintlify in `apps/docs` | Accepted |
| [0003](/adr/0003-tier-dependency-direction) | Tier dependency direction | Accepted |
| [0004](/adr/0004-package-archetypes-and-layers) | Package archetypes and layers | Superseded by 0126 |
| [0005](/adr/0005-di-container-and-legacy-decorators) | DI container and legacy decorators | Accepted, amended by 0143, 0145, 0263 |
| [0006](/adr/0006-naming-exports-and-imports) | Naming, exports and imports | Accepted, amended by 0128, 0233 |
| [0007](/adr/0007-source-documentation-standard) | Source documentation standard | Accepted, amended by 0128, 2026-10-21 |
| [0008](/adr/0008-test-placement) | Test placement | Superseded by 0022 |
| [0009](/adr/0009-secrets-two-mechanisms) | Secrets: two mechanisms | Superseded by 0173 |
| [0010](/adr/0010-services-are-independent-workspace-members) | Services are independent workspace members | Accepted |
| [0011](/adr/0011-rejected-and-deferred-technologies) | Rejected and deferred technologies | Superseded by 0227 |
| [0012](/adr/0012-code-host-and-ci) | Code host and CI | Accepted |
| [0013](/adr/0013-versioning-and-release) | Versioning and release | Superseded by 0025 |
| [0014](/adr/0014-data-ownership-and-orm) | Data ownership and ORM | Accepted, amended by 0160 |
| [0015](/adr/0015-contract-packages) | Contract packages | Superseded by 0117 |
| [0016](/adr/0016-agents-source-of-truth) | `.agents/` is the source of truth | Accepted |
| [0017](/adr/0017-agent-roster-and-models) | Agent roster and models | Superseded by 0193 |
| [0018](/adr/0018-framework-design-record) | Framework design record | Superseded by 0228 |
| [0019](/adr/0019-supply-chain-hardening) | Supply chain hardening | Superseded by 0174 |
| [0020](/adr/0020-observability-and-crash-reporting) | Observability and crash reporting | Superseded by 0184 |
| [0021](/adr/0021-ai-engine-and-agent-write-safety) | AI engine and agent write safety | Proposed |
| [0022](/adr/0022-tests-live-in-tests-folders) | Tests live in `__tests__` folders | Accepted |
| [0023](/adr/0023-stackra-is-a-framework) | Stackra is a framework; products consume it | Accepted |
| [0024](/adr/0024-mit-license-with-exclusions) | MIT license, with stated exclusions | Accepted |
| [0025](/adr/0025-packages-publish-to-private-registry) | Packages publish to `npm.figentra.com`; every package builds to ESM dist | Superseded by 0177 |
| [0026](/adr/0026-turborepo-remote-cache-on-r2) | Turborepo remote cache self-hosted on Cloudflare R2 | Accepted |
| [0027](/adr/0027-cli-tools-pinned-in-mise) | Every CLI the repo needs is pinned in mise | Accepted |
| [0028](/adr/0028-package-categories-appear-with-first-package) | Package categories appear with their first package | Accepted, amended by 0127 |
| [0029](/adr/0029-encore-ts-one-app) | Encore.ts as one application under `services/` | Superseded by 0075 |
| [0030](/adr/0030-encore-cloud-on-owner-aws) | Encore Cloud into the owner's AWS; four environments | Superseded by 0170 |
| [0031](/adr/0031-coarse-services-split-on-evidence) | Coarse services, split on evidence | Superseded by 0200 |
| [0032](/adr/0032-rest-api-generated-client-uuidv7-ids) | REST `api()`, generated client, prefixed UUIDv7 ids | Superseded by 0142 |
| [0033](/adr/0033-pubsub-cron-transactional-outbox) | Pub/Sub and cron with a transactional outbox | Superseded by 0078 |
| [0034](/adr/0034-object-storage-malware-scan-limits) | Object storage, GuardDuty malware scan, upload limits | Superseded by 0222 |
| [0035](/adr/0035-resend-email-with-spf-dkim-dmarc) | Resend email with SPF, DKIM and DMARC | Superseded by 0191 |
| [0036](/adr/0036-idempotency-cache-and-postgres) | Idempotency in Encore cache for 24h; Postgres for money | Superseded by 0136 |
| [0037](/adr/0037-api-versioning-by-date-header) | API versioning by the `Stackra-Version` date header | Superseded by 0118 |
| [0038](/adr/0038-rate-limits-app-buckets-and-waf) | Rate limits: app token buckets and Cloudflare WAF | Superseded by 0217 |
| [0039](/adr/0039-openapi-mintlify-and-oauth-guide) | OpenAPI to Mintlify API reference; OAuth developer guide | Proposed |
| [0040](/adr/0040-ddd-feature-modules-in-services) | Services are organised as DDD feature modules | Superseded by 0130 |
| [0041](/adr/0041-decorated-controllers-and-build-time-generator) | Decorated controllers, handlers and crons via a build-time generator | Superseded by 0091 |
| [0042](/adr/0042-di-first-with-one-container-per-service) | DI-first with one container per service | Accepted, amended by 0143, 0147, 0263 |
| [0043](/adr/0043-workflow-package-medusa-style) | `@stackra/workflow` is Medusa-style steps and workflows | Superseded by 0102 |
| [0044](/adr/0044-laravel-style-package-config) | Laravel-style package configuration | Superseded by 0146 |
| [0045](/adr/0045-tenancy-package-pool-default-silo-on-demand) | `@stackra/tenancy`: pool by default, silo on demand | Superseded by 0088 |
| [0046](/adr/0046-global-data-invariants-and-per-model-opt-ins) | Global data invariants and per-model opt-ins | Superseded by 0134 |
| [0047](/adr/0047-audit-service-via-events) | Audit service fed by events | Superseded by 0212 |
| [0048](/adr/0048-point-in-time-recovery-and-quarterly-restore-drill) | Point-in-time recovery and a quarterly restore drill | Superseded by 0186 |
| [0049](/adr/0049-search-driver-interface) | `@stackra/search`: a driver interface, Postgres first | Superseded by 0089 |
| [0050](/adr/0050-ai-package-on-ai-sdk-bedrock-default) | `@stackra/ai` on AI SDK core, Bedrock by default | Superseded by 0100 |
| [0051](/adr/0051-better-auth-identity-service) | Better Auth identity service | Superseded by 0087 |
| [0052](/adr/0052-console-is-a-vite-react-spa) | The console is a Vite + React single-page app | Superseded by 0164 |
| [0053](/adr/0053-decorator-route-classes-compiled-to-router-adapters) | Routes are decorator classes compiled to router adapters; no file-based routing | Proposed |
| [0054](/adr/0054-tanstack-query-and-zustand-for-client-state) | TanStack Query for server state, Zustand for client state | Superseded by 0079 |
| [0055](/adr/0055-forms-react-hook-form-zod-heroui-adapters) | Forms use react-hook-form and Zod with thin HeroUI field adapters | Proposed |
| [0056](/adr/0056-heroui-v3-pro-on-web-share-everything-but-components) | HeroUI v3 and Pro on web; share logic and tokens, not components | Superseded by 0165 |
| [0057](/adr/0057-landing-is-react-router-framework-mode-on-workers) | The landing site is React Router 7 framework mode on Cloudflare Workers | Superseded by 0176 |
| [0058](/adr/0058-desktop-is-electron) | The desktop app is Electron | Superseded by 0181 |
| [0059](/adr/0059-offline-encrypted-query-cache-and-mutation-queue) | Mobile offline: encrypted persisted Query cache and a persisted mutation queue | Accepted, amended by 0268 |
| [0060](/adr/0060-i18n-logical-css-light-and-dark) | i18n keys and logical CSS from day one; English launch; light and dark | Superseded by 0080 |
| [0061](/adr/0061-mobile-keeps-react-navigation-and-native-tabs) | Mobile keeps React Navigation 7 and native tabs; one app | Proposed |
| [0062](/adr/0062-mobile-release-push-and-crash-reporting) | Mobile: EAS Update, Expo push and Sentry from day one | Superseded by 0180 |
| [0063](/adr/0063-cloudflare-hosts-web-surfaces) | Cloudflare hosts the web surfaces | Superseded by 0175 |
| 0064 | Unused: the number was never assigned | — |
| [0065](/adr/0065-linear-gate-is-checked-offline) | The Linear gate is checked offline | Accepted, amended by 0268 |
| [0066](/adr/0066-delegation-to-opencode-by-routing-matrix) | Claude leads; OpenCode executes routed tasks in worktrees | Accepted |
| [0067](/adr/0067-spec-kit-is-the-sdlc) | spec-kit is the SDLC, with a mandatory clarify gate | Accepted |
| [0068](/adr/0068-runway-cicd-built-inside-stackra) | runway: CI/CD built inside Stackra | Superseded by 0168 |
| [0069](/adr/0069-testing-strategy-and-coverage) | Testing strategy and coverage floors | Superseded by 0182 |
| [0070](/adr/0070-quality-budgets) | Quality budgets: accessibility, Web Vitals, bundle, mobile startup | Superseded by 0183 |
| [0071](/adr/0071-privacy-obligations) | Privacy: export, erasure, platform declarations and templates | Superseded by 0189 |
| [0072](/adr/0072-soc2-groundwork) | SOC 2 groundwork | Superseded by 0187 |
| [0073](/adr/0073-observability-better-stack-sentry-encore) | Observability: Better Stack, Sentry and Encore tracing | Superseded by 0184 |
| [0074](/adr/0074-open-core-licensing) | Open core: `@stackra-pro` on the private registry | Superseded by 0077 |
| [0075](/adr/0075-stackra-ships-packages-figentra-os-ships-services) | Stackra ships packages; Figentra OS ships the product services | Accepted |
| [0076](/adr/0076-every-package-runs-saas-on-prem-and-air-gapped) | Every package runs in SaaS, on-prem and air-gapped deployments | Proposed |
| [0077](/adr/0077-open-core-free-and-pro-lists) | Open core: the free and Pro package lists | Superseded by 0202 |
| [0078](/adr/0078-messaging-layer-eight-packages) | The messaging layer: eight packages, one question each | Accepted, amended by 0141, 0148, 0260 |
| [0079](/adr/0079-client-state-is-stackra-state) | Client state is @stackra/state (ported Figentra signals); Query owns optimism and the offline queue | Accepted |
| [0080](/adr/0080-i18n-is-the-figentra-i18n-port) | i18n is the ported Figentra i18n package; i18next is dropped | Accepted, amended by 0268 |
| [0081](/adr/0081-gate-chain-configurable-per-app) | The gate chain is fully configurable per app, with a warning when tenancy or iam is omitted | Superseded by 0138 |
| [0082](/adr/0082-public-ids-and-api-areas) | Public ids are a prefix plus base32 of one UUIDv7; four API areas | Accepted, amended by 0135 |
| [0083](/adr/0083-npm-scopes-and-cli-names) | npm scopes: @stackra for packages, @figentra for this repository's apps and services; @stackra/console is the CLI framework | Accepted |
| [0084](/adr/0084-figentra-os-package-port-plan) | Figentra OS package port plan | Accepted |
| [0085](/adr/0085-logger-reporters) | Logger reporters: CloudWatch kept; Encore log, Sentry and Better Stack added | Superseded by 0147 |
| [0086](/adr/0086-notifications-full-engine-all-channels-free) | @stackra/notifications is a full engine, with every channel free | Proposed |
| [0087](/adr/0087-identity-and-iam-are-driver-packages) | Identity and IAM are driver packages; enterprise features plug in as Pro | Superseded by 0206 |
| [0088](/adr/0088-tenancy-free-pool-pro-silo-and-scope) | @stackra/tenancy: pool and RLS are free; DB-per-tenant and the scope tree are Pro | Superseded by 0210 |
| [0089](/adr/0089-search-fresh-with-pro-engine-drivers) | @stackra/search is written fresh; Meilisearch and OpenSearch are Pro drivers | Superseded by 0221 |
| [0090](/adr/0090-codegen-discovery-by-root-module) | Codegen discovers decorators through each member's root module | Accepted, amended by 0144, 0268 |
| [0091](/adr/0091-generated-encore-app-in-stackra-folder) | The Encore app is generated into .stackra/encore; services hold no Encore files | Accepted, amended by 0158, 0268 |
| [0092](/adr/0092-ir-ported-definition-package-dropped) | The IR is ported with decorator-derived kinds; the definition package is dropped | Accepted |
| [0093](/adr/0093-better-auth-integration) | Better Auth integration: container hooks, iam-only authorization, an owned MikroORM adapter, global auth tables | Superseded by 0206 |
| [0094](/adr/0094-decorators-only-authoring) | Decorators are the only authoring style; workflows are declarative @Step graphs | Accepted, amended by 0145, 0152 |
| [0095](/adr/0095-zod-inside-field-decorators) | @stackra/validation: Laravel-style decorators compiled to one Zod schema, plus an output serializer | Accepted, amended by 0133, 0162 |
| [0096](/adr/0096-trait-naming-grammar) | Trait naming grammar and the trait list | Accepted, amended by 0133, 0162 |
| [0097](/adr/0097-model-and-database-packages) | @stackra/model and @stackra/database; gen emits MikroORM EntitySchema | Accepted, amended by 0133, 0159, 0161, 0162 |
| [0098](/adr/0098-actions-are-the-unit) | Actions are the unit of behaviour, in @stackra/actions, with one pipeline and a typed actor | Accepted, amended by 0136, 0137, 0139, 0155, 0264 |
| [0099](/adr/0099-risk-scale-l0-to-l4) | One action risk scale, L0 to L4, with derived MCP hints and effect tags; change risk is R0 to R3 | Accepted, amended by 0268 |
| [0100](/adr/0100-ai-model-and-ownership) | One free @stackra/ai: agents, tools, skills, MCP and A2A on AI SDK, every tool call an action | Accepted, amended by 0155, 0156, 0267 |
| [0101](/adr/0101-action-first-workflow-behind-when-needed) | Every operation is an action; a workflow sits behind it only when the criteria hit | Accepted, amended by 0265 |
| [0102](/adr/0102-workflow-engine-in-process-journal) | The workflow engine: in-process steps with a Postgres journal, outbox staging and hooks, ported from Medusa's MIT code | Accepted, amended by 0151, 0152 |
| [0103](/adr/0103-locking-package) | @stackra/locking: server-side named locks behind a driver | Accepted, amended by 0149 |
| [0104](/adr/0104-links-and-query-graph) | Cross-module relations are @Link declarations, read through query.graph | Accepted, amended by 0268 |
| [0105](/adr/0105-crud-generates-service-methods) | @Crud generates a model's service methods and opt-in actions | Accepted |
| [0106](/adr/0106-infisical-agent-vault-per-environment) | Infisical Agent Vault, split by environment; the model never sees a secret | Superseded by 0267 |
| [0107](/adr/0107-connections-store-and-three-key-homes) | Three homes for keys; tenant credentials live in @stackra/connections | Accepted |
| [0108](/adr/0108-scoped-settings) | Scoped settings: each service owns its values; the registry owns the schema | Accepted |
| [0109](/adr/0109-registry-manifests-published-by-ci) | The registry: build manifests published by CI to a Postgres-backed registry service | Accepted |
| [0110](/adr/0110-experience-is-the-sdui-service-at-l2) | The experience service is server-driven UI at level L2: trees of registered coded components, no code over the wire | Accepted, amended by 0139, 0154, 0164 |
| [0111](/adr/0111-module-is-the-unit-of-contribution) | The module is the unit of contribution; services and apps only host modules | Accepted, amended by 0214, 0259 |
| [0112](/adr/0112-experience-packages-and-renderer-kit) | Experience packages, @stackra/ui parity and the renderer kit | Accepted, amended by 0164 |
| [0113](/adr/0113-heroui-pro-distribution) | HeroUI Pro reaches Stackra Pro customers as a private mirror bundle, with a bring-your-own-key option | Superseded by 0197 |
| [0114](/adr/0114-page-builder-for-every-page) | The page builder builds every page, including our own marketing site; MDX and Sanity are dropped | Accepted |
| [0115](/adr/0115-form-builder) | Built forms are documents of kind form; they submit to an action; the editors are Pro | Accepted |
| [0116](/adr/0116-content-types-and-custom-fields) | @stackra/content: content types are models with a trait bundle; custom fields are a free, bounded trait | Accepted |
| [0117](/adr/0117-contracts-placement-and-decorator-ownership) | Shared primitives live in @stackra/contracts, each package has a types-only ./contracts entry, and each package owns its decorators | Accepted, amended by 0140, 0141, 0144, 0260 |
| [0118](/adr/0118-api-versioning-dormant-package) | @stackra/versioning is built now and stays dormant: date versions pinned per API key or OAuth app | Accepted, amended by 0136, 0268 |
| [0119](/adr/0119-merge-policy-and-release-authority) | Merge policy: Quality Gate is the only required check; Claude merges only through pnpm pr:merge | Accepted |
| [0120](/adr/0120-sdlc-spec-location-lanes-and-change-risk) | The SDLC: specs in .agents/specs, four lanes, and change risk R0 to R3 | Accepted |
| [0121](/adr/0121-sdlc-tooling-roles-and-linear) | SDLC tooling: sdlc retired, spec-kit pinned, a local Linear extension, the ported roles and who runs what | Accepted, amended by 0258 |
| [0122](/adr/0122-workflow-studio-three-layers) | The workflow studio: coded workflows, configurable knobs, and tenant automations as data that references code | Accepted, amended by 0153, 0154 |
| [0123](/adr/0123-delivery-order-follows-the-dependency-graph) | Delivery order follows the dependency graph: package-disjoint waves, spikes first, assumed defaults pending the owner | Accepted |
| [0124](/adr/0124-encore-is-the-generated-runtime-target) | Encore is the generated runtime target; service source stays plain TypeScript | Accepted, amended by 0158, 0159 |
| [0125](/adr/0125-constitution-amended-to-match-accepted-adrs) | The constitution is amended to match Accepted ADRs and locked owner decisions | Accepted |
| [0126](/adr/0126-member-shapes-and-scaffold-templates) | Member shapes and scaffold templates: service skeleton, entries-first packages, kind folders, four app kinds | Accepted, amended by 0234, 0249, 0259, 0264 |
| [0127](/adr/0127-package-categories-including-infrastructure) | Package categories, including infrastructure | Accepted |
| [0128](/adr/0128-code-conventions-enums-classes-components-and-kind-folders) | Code conventions: enums, classes, components and kind folders | Accepted, amended by 0268 |
| [0129](/adr/0129-house-lint-plugin-and-coding-standard) | Code standards enforced by a house lint plugin, shipped as @stackra/coding-standard | Accepted |
| [0130](/adr/0130-module-layout-by-semantic-kind) | Module layout by semantic kind; no controllers | Accepted, amended by 0259, 0264 |
| [0131](/adr/0131-module-key-version-and-deprecation) | Module key, version and deprecation | Accepted, amended by 0264 |
| [0132](/adr/0132-permissions-catalogue-and-policy-providers) | Permissions are a module catalogue; policies are providers | Accepted, amended by 0263 |
| [0133](/adr/0133-field-semantics-model-keys-rename-safe-fields-and-lifecycle-events) | Field semantics, model keys, rename-safe fields and lifecycle events | Accepted, amended by 0264 |
| [0134](/adr/0134-data-invariants-classification-and-delete-lifecycle) | Data invariants, field classification and the delete lifecycle | Accepted |
| [0135](/adr/0135-public-id-format) | Public id format: prefix plus Crockford base32 of one UUIDv7 | Accepted |
| [0136](/adr/0136-action-runtime-contract) | The action runtime contract: handler context, transaction, idempotency and versions | Accepted, amended by 0268 |
| [0137](/adr/0137-declared-action-options-and-refusal-codes) | Declared action options and refusal reasons | Accepted |
| [0138](/adr/0138-pipeline-order-is-fixed) | The pipeline order is fixed; apps toggle and parameterise gates | Accepted |
| [0139](/adr/0139-actions-declare-their-user-experience) | Actions declare their user experience | Accepted |
| [0140](/adr/0140-error-envelope-and-error-kinds) | The error envelope and error kinds | Accepted |
| [0141](/adr/0141-integration-event-names-and-envelope) | Integration event names and the envelope | Accepted, amended by 0260 |
| [0142](/adr/0142-cross-service-transport-through-drivers) | Cross-service transport goes through drivers | Accepted, amended by 0260 |
| [0143](/adr/0143-container-scopes-registration-lifecycle-and-testing) | Container scopes, module registration, lifecycle and testing | Accepted, amended by 0263 |
| [0144](/adr/0144-metadata-registry-and-explorers) | A typed MetadataRegistry, and every decorator package ships an Explorer | Accepted, amended by 0263, 0264 |
| [0145](/adr/0145-tokens-are-define-token-values-and-global-helpers-are-banned) | Tokens are defineToken values; container-backed global helpers are banned | Accepted, amended by 0247, 0263, 0264 |
| [0146](/adr/0146-package-configuration-typescript-layers-and-secret-references) | Package configuration: TypeScript files, layered overrides and secret references | Accepted, amended by 0263 |
| [0147](/adr/0147-logger-and-runtime-telemetry-defaults) | Logger and runtime telemetry defaults | Accepted |
| [0148](/adr/0148-queue-and-scheduler-full-job-features-fair-queuing-and-tenant-schedules) | Queue and scheduler: full job features, fair queuing and tenant schedules | Accepted |
| [0149](/adr/0149-locking-fencing-tokens-auto-renew-and-with-lock) | Locking: fencing tokens, auto-renew and @WithLock | Accepted |
| [0150](/adr/0150-cache-package) | @stackra/cache: memory, Valkey, Encore and Postgres drivers with tenant-namespaced keys | Accepted |
| [0151](/adr/0151-workflow-engine-is-a-port-with-native-and-temporal-drivers) | The workflow engine is a port with a native driver and a Temporal driver | Accepted |
| [0152](/adr/0152-workflow-semantics-timeouts-waits-pinned-versions-and-one-graph-format) | Workflow semantics: timeouts, waits, pinned versions, operations and one graph format | Accepted |
| [0153](/adr/0153-automations-run-as-principals-and-every-package-exposes-building-blocks) | Automations run as principals; every package exposes its capabilities as building blocks | Accepted |
| [0154](/adr/0154-tenant-code-runs-only-in-a-sandboxed-code-step) | Tenant code runs only in a sandboxed code step | Accepted |
| [0155](/adr/0155-queries-are-mcp-tools-and-all-ai-code-is-free) | AI-native rule: queries are MCP tools, and all AI code is free | Accepted |
| [0156](/adr/0156-ai-runtime-provider-drivers-memory-and-guardrails) | The AI runtime: provider drivers, a managed-runtime driver, memory and guardrails | Accepted |
| [0157](/adr/0157-stackra-inspect-and-stackra-diff) | stackra inspect and stackra diff | Accepted |
| [0158](/adr/0158-gen-artefacts-openapi-manifest-and-client) | Gen artefacts: committed OpenAPI and manifest, a CI-published client, deploy-mode targets | Accepted, amended by 0260, 0268 |
| [0159](/adr/0159-migrations-gen-ordered-sql-and-safety-rules) | Migrations: gen-ordered SQL, migrations shipped in packages, and safety rules | Accepted |
| [0160](/adr/0160-raw-sql-at-runtime-and-the-approved-postgres-extensions) | Raw SQL at runtime and the approved Postgres extensions | Accepted |
| [0161](/adr/0161-state-machine-package) | @stackra/state-machine: typed state machines on model fields, with history and surfaces | Accepted |
| [0162](/adr/0162-validation-translatable-fields-and-entityschema-placement) | Validation, translatable-field and EntitySchema clarifications | Accepted |
| [0163](/adr/0163-reports-exports-imports-and-declared-read-models) | Reports, exports, imports and declared read models | Accepted, amended by 0260 |
| [0164](/adr/0164-console-panels-are-resources-rendered-by-the-panel-package) | Console panels are Filament-style resources rendered by @stackra/panel | Accepted |
| [0165](/adr/0165-web-client-stack-ui-contract-form-adapters-and-no-nextjs) | The web client stack restated: the @stackra/ui contract, form adapters, no Next.js | Accepted, amended by 0268 |
| [0166](/adr/0166-ci-policy-runners-budgets-concurrency-and-check-matrix) | CI policy: runners, budgets, concurrency, job shape and the check matrix | Accepted |
| [0167](/adr/0167-workflow-hardening-outside-contributors-and-bot-credentials) | Workflow hardening, outside contributors and bot credentials | Accepted |
| [0168](/adr/0168-runway-public-reusable-workflows-build-order-and-runway-yaml) | Runway: public reusable workflows, build order and runway.yaml | Accepted |
| [0169](/adr/0169-topology-runway-yaml-packs-logical-services-into-deployables) | Topology: runway.yaml packs logical services into deployables | Accepted |
| [0170](/adr/0170-deployment-what-deploys-where-and-how-a-release-is-promoted) | Deployment: what deploys where, and how a release is promoted | Accepted |
| [0171](/adr/0171-infrastructure-as-code-pulumi-typescript-owned-by-stackra) | Infrastructure as code: Pulumi TypeScript packages owned by Stackra | Accepted |
| [0172](/adr/0172-aws-accounts-primary-region-and-cloud-cost-controls) | AWS accounts, primary region and cloud cost controls | Accepted |
| [0173](/adr/0173-secrets-infisical-is-the-source-of-production-secrets) | Secrets: Infisical is the source of production secrets; runway syncs them | Accepted, amended by 0267 |
| [0174](/adr/0174-supply-chain-images-signing-sbom-dependency-policy-and-rotation) | Supply chain: images, signing, SBOM, dependency policy and rotation | Accepted |
| [0175](/adr/0175-edge-domains-and-tls) | Edge, domains and TLS | Accepted |
| [0176](/adr/0176-marketing-site-placeholder-then-prerendered-from-the-experience-service) | The marketing site: a placeholder now, prerendered from the experience service later | Accepted |
| [0177](/adr/0177-package-distribution-npmjs-and-keygen) | Package distribution and release lines: npmjs for free, Keygen Cloud for Pro | Accepted |
| [0178](/adr/0178-licensing-keygen-licences-and-the-stackra-licensing-verifier) | Licensing: Keygen licences and the @stackra/licensing verifier | Accepted |
| [0179](/adr/0179-on-prem-and-air-gapped-delivery) | On-prem and air-gapped delivery | Accepted |
| [0180](/adr/0180-mobile-apps-and-release-trains) | Mobile apps and release trains | Accepted |
| [0181](/adr/0181-the-desktop-app-pipeline) | The desktop app's pipeline | Accepted |
| [0182](/adr/0182-testing-strategy-v2-tiers-coverage-infrastructure-and-policies) | Testing strategy v2: tiers, coverage, infrastructure and policies | Accepted |
| [0183](/adr/0183-quality-budgets-with-numbers) | Quality budgets with numbers | Accepted |
| [0184](/adr/0184-telemetry-opentelemetry-otlp-slis-heartbeats-and-log-retention) | Telemetry: OpenTelemetry, OTLP, SLIs, heartbeats and log retention | Accepted |
| [0185](/adr/0185-incident-response-on-call-status-page-and-support-tiers) | Incident response, on-call, the status page and support tiers | Accepted |
| [0186](/adr/0186-backups-and-disaster-recovery) | Backups and disaster recovery | Accepted |
| [0187](/adr/0187-security-and-compliance-programme) | The security and compliance programme | Accepted |
| [0188](/adr/0188-operator-access-and-the-encryption-key-hierarchy) | Operator access and the encryption key hierarchy | Accepted |
| [0189](/adr/0189-privacy-operations-and-data-retention) | Privacy operations and data retention | Accepted |
| [0190](/adr/0190-seed-profiles-and-product-analytics) | Seed profiles and our product analytics | Accepted |
| [0191](/adr/0191-email-deliverability) | Email deliverability | Accepted |
| [0192](/adr/0192-translation-workflow-and-arabic-defaults) | Translation workflow and Arabic defaults | Accepted |
| [0193](/adr/0193-agents-and-model-policy) | Agents and model policy | Accepted, amended by 0258 |
| [0194](/adr/0194-developer-and-agent-compute) | Developer and agent compute | Accepted |
| [0195](/adr/0195-organisation-legal-and-release-communication) | Organisation, legal and release communication | Accepted |
| [0196](/adr/0196-repository-config-is-yaml-wherever-the-reader-supports-it) | Repository config is YAML wherever the reader supports it | Accepted |
| [0197](/adr/0197-heroui-pro-is-used-only-in-our-own-apps) | HeroUI Pro is used only in our own apps until an OEM agreement exists | Accepted |
| [0198](/adr/0198-sdlc-spec-location-states-traceability-and-roadmap) | SDLC: spec location, spec states, traceability and roadmap structure | Accepted |
| [0199](/adr/0199-developer-experience-create-stackra-app-upgrades-stackra-dev-and-docs) | Developer experience: create-stackra-app, upgrades, stackra dev, docs and the agent kit | Accepted, amended by 0268 |
| [0200](/adr/0200-stackra-and-figentra-os-horizontal-services-private-os-repo) | Stackra and Figentra OS: horizontal services, a private OS repo and co-development | Accepted |
| [0201](/adr/0201-the-app-split-framework-platform-core-and-first-party-apps) | The app split: framework packages, platform core and first-party apps | Accepted |
| [0202](/adr/0202-stackra-pro-is-developer-side-os-capability-is-free-code) | @stackra-pro is developer-side; OS capability is free code gated by entitlements | Accepted |
| [0203](/adr/0203-the-commercial-model-billing-provider-and-tier-names) | The commercial model: billing provider, metric and tier names | Accepted |
| [0204](/adr/0204-reference-services-identity-notes-and-registry) | Reference services: identity, notes and registry | Accepted |
| [0205](/adr/0205-the-figentra-os-build-order-and-the-first-slice) | The Figentra OS build order and the first slice | Accepted |
| [0206](/adr/0206-zitadel-is-the-identity-provider-and-stackra-identity-is-provider-neutral) | ZITADEL is the identity provider; @stackra/identity is provider-neutral | Accepted, amended by 0268 |
| [0207](/adr/0207-authentication-assurance-and-machine-identities) | Authentication assurance and machine identities | Accepted |
| [0208](/adr/0208-iam-model-scope-tree-roles-conditions-deny-delegation-and-permission-names) | The IAM model: scope tree, roles, conditions and deny, delegation and permission names | Accepted |
| [0209](/adr/0209-iam-enforcement-pipeline-gate-sql-predicate-embedded-pdp-and-service-calls) | IAM enforcement: the pipeline gate, an SQL predicate, an embedded PDP and service calls | Accepted |
| [0210](/adr/0210-tenancy-recursive-tenant-tree-lifecycle-one-context-and-region) | Tenancy: a recursive tenant tree, lifecycle, one context per request, and region | Accepted |
| [0211](/adr/0211-memberships-and-support-access) | Memberships and support access | Accepted |
| [0212](/adr/0212-audit-evidence-access-logs-hash-chain-and-retention) | Audit: evidence, access logs, a hash chain and retention | Accepted |
| [0213](/adr/0213-settings-v2-cascade-flags-as-a-kind-yaml-packs-and-revisions) | Settings v2: the full cascade, flags as a settings kind, YAML packs and revisions | Accepted |
| [0214](/adr/0214-registry-v2-and-the-module-install-lifecycle) | Registry v2 and the module install lifecycle | Accepted |
| [0215](/adr/0215-entitlements) | Entitlements | Accepted |
| [0216](/adr/0216-meters-and-usage-events) | Meters and usage events | Accepted |
| [0217](/adr/0217-api-surfaces-mcp-first-plus-rest-sdks-and-rate-limits) | API surfaces: MCP first plus REST, SDKs and rate limits | Accepted |
| [0218](/adr/0218-integrations-the-connector-sdk-and-connections-per-chain-level) | Integrations: the connector SDK and connections per chain level | Accepted |
| [0219](/adr/0219-the-merchant-account-chain-and-registered-price-models) | The merchant-account chain and registered price models | Accepted |
| [0220](/adr/0220-stackra-money-and-the-ledger-package) | @stackra/money and the ledger package | Accepted, amended by 0268 |
| [0221](/adr/0221-search-postgres-hybrid-elasticsuite-parity-arabic-and-operations) | Search: Postgres hybrid, ElasticSuite parity, Arabic and operations | Accepted |
| [0222](/adr/0222-files-and-media-storage-drivers-uploads-scanning-and-public-assets) | Files and media: storage drivers, uploads, scanning and public assets | Accepted |
| [0223](/adr/0223-notifications-channels-cascading-templates-manual-sends-and-preferences) | Notifications: more channels, cascading templates, manual sends and preferences | Accepted |
| [0224](/adr/0224-stackra-webhooks) | @stackra/webhooks | Accepted |
| [0225](/adr/0225-realtime-drivers-co-editing-and-the-commentable-trait) | Realtime drivers, co-editing and the Commentable trait | Accepted |
| [0226](/adr/0226-content-tenant-defined-types-at-runtime-and-headless-delivery) | Content: tenant-defined types at runtime, and headless delivery | Accepted |
| [0227](/adr/0227-rejected-and-deferred-technologies-refreshed) | Rejected and deferred technologies, refreshed | Accepted, amended by 0267 |
| [0228](/adr/0228-proposed-adrs-settled) | Proposed ADRs settled | Accepted |
| [0229](/adr/0229-constitution-amended-for-the-2026-10-20-decisions) | The constitution amended for the 2026-10-20 decisions | Accepted |
| [0230](/adr/0230-reviewer-identity-separate-from-builder) | Reviews come from a separate reviewer identity, never the author | Accepted |
| [0231](/adr/0231-naming-and-casing-standard) | Naming and casing standard: one table for every kind of name | Accepted, amended by 0264 |
| [0232](/adr/0232-stackra-errors-package) | @stackra/errors: StackraError base, react, native, node and testing entries, reporter port | Accepted |
| [0233](/adr/0233-imports-use-subpath-aliases-only) | Imports use #subpath aliases only | Accepted |
| [0234](/adr/0234-module-assets-and-storage) | Module assets and storage: assets/ folders, @stackra/assets, @stackra/filesystem | Accepted, amended by 0263, 0264 |
| [0235](/adr/0235-devices-and-iot-minimal-now-full-later) | Devices and IoT: minimal now, full later; devices are identity principals | Accepted |
| [0236](/adr/0236-translation-providers-as-connectors) | Translation providers as connectors: machine translation and TMS sync | Accepted |
| [0237](/adr/0237-generated-api-gateway-in-four-layers) | The API gateway is generated, in four layers, with no gateway service | Accepted |
| [0238](/adr/0238-database-and-connection-model) | Database and connection model: one server per environment, one logical database per service | Accepted |
| [0239](/adr/0239-rls-shape-equality-on-tenant-id-with-read-models-for-org-views) | RLS shape: equality on tenant\_id, with read models for organisation views | Accepted |
| [0240](/adr/0240-scope-tree-is-free-code-with-depth-by-plan) | The scope tree is free code; its depth is a plan entitlement | Accepted |
| [0241](/adr/0241-identity-first-slice-central-login-app-bff-and-reference-service) | Identity first slice: central login app, the BFF and the identity reference service | Accepted, amended by 0268 |
| [0242](/adr/0242-commercial-model-plan-ladder-add-ons-metric-and-trial) | Commercial model: per-product plan ladders, shared add-ons, hybrid metric, and a 14-day trial | Accepted |
| [0243](/adr/0243-organisations-on-the-tenant-tree-consolidated-billing-guardrails-and-standalone-exit) | Organisations on the tenant tree: consolidated billing, guardrails and the standalone exit | Accepted |
| [0244](/adr/0244-markets-owned-by-pricing) | Markets, owned by pricing | Accepted |
| [0245](/adr/0245-ai-intelligence-plane-skills-prompts-context-providers-plans-and-intents) | The AI intelligence plane: skills, prompts, context providers, plans and intents | Accepted |
| [0246](/adr/0246-devtools-dev-only-for-apps-and-services) | Devtools: dev-only, for frontend and backend | Accepted |
| [0247](/adr/0247-declaration-rule-decorators-annotate-define-creates-values) | Declaration rule: decorators annotate code, define\* creates values | Accepted, amended by 0264 |
| [0248](/adr/0248-delivery-scope-saas-first-on-prem-kept-green) | Delivery scope: build everything, SaaS first, on-prem and air-gapped kept green | Accepted |
| [0249](/adr/0249-one-app-three-targets-web-pwa-and-electron) | One app, three targets: web, PWA and Electron desktop from one member | Accepted |
| [0250](/adr/0250-stackra-platform-capability-ports-drivers-and-gate) | @stackra/platform: capability ports, drivers, gate and client-manifest capability section | Accepted |
| [0251](/adr/0251-desktop-bridge-generated-from-desktop-action-and-electron-hardening) | The desktop bridge is generated from @DesktopAction; Electron hardening baseline | Accepted |
| [0252](/adr/0252-offline-on-every-client-completing-the-mutation-queue) | Offline on every client: completing the mutation queue | Proposed |
| [0253](/adr/0253-peripherals-web-api-first-and-device-presets) | Peripherals are Web-API first; native modules only on evidence; device presets | Accepted |
| [0254](/adr/0254-desktop-release-signing-update-feed-channels-and-version-policy) | Desktop release: signing, update feed, channels and version policy | Accepted |
| [0255](/adr/0255-pwa-service-worker-scope-and-push-per-platform) | PWA: vite-plugin-pwa, service worker scope and push strategy per platform | Accepted |
| [0256](/adr/0256-client-storage-one-stackra-storage-package) | Client storage: one @stackra/storage package with named stores and per-platform drivers | Accepted |
| [0257](/adr/0257-secret-manager-agent-and-the-secrets-inbox) | Secret-manager agent and the secrets inbox: values written blind, nobody reads them | Proposed |
| [0258](/adr/0258-agent-roster-v2-and-skill-fencing) | Agent roster v2, Claude-only agents and skill fencing | Accepted |
| [0259](/adr/0259-module-placement-three-homes) | Module placement: three homes and the placement test | Accepted |
| [0260](/adr/0260-cross-service-calls-through-injected-clients-and-events) | Cross-service reach: one generated client with call, command and typed events | Accepted |
| [0261](/adr/0261-generated-stackra-modules-in-stackra-gen) | Generated `#stackra/*` modules: real files in `.stackra/gen`, imported through the alias | Accepted, amended by 0265 |
| [0262](/adr/0262-module-catalogue-and-module-generator) | Module catalogue generated from code, module plans in spec folders, and the module generator | Accepted |
| [0263](/adr/0263-di-stays-and-gen-writes-the-wiring) | DI stays; gen writes the wiring: same-name tokens, inferred module edges, config layers | Accepted |
| [0264](/adr/0264-declaration-vocabulary-module-keys-define-family-and-kind-folders) | Declaration vocabulary: one module key grammar, the define family closed at eight, kind folders and one listener form | Accepted |
| [0265](/adr/0265-hook-points-transform-and-verify) | Hook points: owner-declared transform and verify hooks, with implicit Before and After on actions | Accepted |
| [0266](/adr/0266-capabilities-phase-in-one-option-one-driver-memory-first) | Capabilities phase in as one option, one config driver, and a memory driver and fake before production | Accepted |
| [0267](/adr/0267-infisical-agent-vault-deferred) | Infisical Agent Vault is deferred; the model never sees a secret, and egress is direct | Deferred |
| [0268](/adr/0268-register-answers-thin-items-r1-to-r18) | Register answers of 2026-10-21: the thin items R1 to R18 settled, each recorded on the page it changes | Accepted |

Copy the [template](/adr/template), give it the next number, and add it to this table and to `docs.json`.
Cite Stackra ADRs by path, never by a number from another repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.