Guides

Guides show you how to complete a specific task. Read the relevant Concepts page first, then follow the recipe here.

A guide is short and runnable. It links to Concepts for background and Reference for parameter lists. Build guides usually follow Prerequisites → The code → What the framework does → Common gotchas → Live example → See also. Deployment pages use their own structure because they describe an environment rather than one code change.

Build a feature

Guide	When you reach for it
Add an entity to a feature	A second entity in a feature you already have.
Write a custom write handler	Default CRUD does not fit and you need business rules on save.
Handler context and embedded fields	Keep handler transactions explicit or model repeated structure as an embedded list.
React to another feature’s events	Feature A reacts when feature B writes, without importing feature B’s internals.
Build a read model across multiple aggregates	Aggregate events from several entities belong in one view.
Seed default data for new tenants	A new tenant should receive initial workspace data.
Apply one-shot data migrations via the event store	Existing aggregate state needs a tracked, event-store-backed correction.
Add a WebSocket endpoint	Client and server exchange messages in both directions, for example streamed audio and live transcripts.
The test standard	Set up tests the way the framework and kumiko new app do.
When a test goes red	A test is red or flaky and you need the cause, not a longer timeout.

Build a UI

Guide	When you reach for it
UI widgets	Pick a card, table, chart, or form widget instead of hand-rolling one.
Multi-step wizards and embedded forms	A form is too long for one page or belongs inside a Drawer.
Dialog and Lightbox overlays	Confirm an action or show an image at full size.
Editable content collections	Editors need to manage tenant or user content through a generated editor.
Build a marketing landing page	Compose an Apex page from your features.
Mount read-only inspector screens	Inspect data from a bundled feature without building a separate admin UI.
Metrics and dashboard data	Show counts and trends from your tables on the admin overview or your own dashboard.
Tables: what users can do	Let users pick columns, pin and group them, select rows for bulk actions, export to Excel and keep their filters.
Design mail and PDF templates	Admins change mail and PDF templates in the browser; you declare placeholders and defaults.

Access and security

Guide	When you reach for it
Restrict a field to specific roles	A field is visible to or writable by only selected roles.
Expose a public, anonymous-readable endpoint	A public status page, marketing endpoint, or hosted report needs anonymous reads.
Public share surface	Share one read-only record through a revocable token link.
Call the API headlessly with a Personal Access Token	CI, a script, or a customer integration needs a scoped bearer token.
Add TOTP-based 2FA to login	Users should enroll an authenticator app as a second login factor.
Production security baseline	Turn the security concepts into a staged launch gate with evidence and stop conditions.
Load encryption keys from a key manager	A production app should resolve its KEK and blind-index key at boot.
Rotate encryption keys	A KEK or blind-index key must be replaced.
Make your app agent-ready	An in-app AI agent should act on records under explicit handler rules.
Production AI governance	Prepare provider keys, data boundaries, approvals, provenance, caps, and failure handling before launch.
Enterprise AI	Choose an assistant, document extraction, triage, feature-builder, or policy-driven AI workflow.

Ship and operate

Guide	When you reach for it
Requirements	Check local tools and ports before starting development.
Upgrade Kumiko dependencies	Move an app to a newer framework release.
Expand/Contract for managed-projection changes	A destructive change to a managed table should span two releases instead of one.
Deploy: Solo (single VM)	Run one app, Postgres, and Redis on one VM.
Deploy: Docker	Build the production image and apply its schema.
Deploy: K3s (production scale)	Deploy a server app to the Pulumi-managed cluster.
Assign a tier to a tenant manually	Grant a tier without a billing purchase.
Make your apex/content pages SEO/AEO/GEO discoverable	Configure mounted SEO features for search and answer engines.
Provenance and cost control for AI pipeline steps	Inspect what an AI pipeline step ran and control its provider cost.

See also

• Recipes, runnable end-to-end examples.
• Concepts, the mental model behind the guides.
• Platform, deployment topologies and operational pages.