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 complete parameter lists.
Feature guides follow one spine: Prerequisites → The code → What the framework does → Common gotchas → Live example → See also. A guide leaves out a section it has nothing to say in, a guide without code needs no “The code”, instead of padding it, and may add a topic-specific section (“why not just import the table”, “how it differs from single-stream”) where the spine has none. “Common gotchas” and “See also” belong in every guide. The three deploy guides are exempt: they describe topologies, not a code task.
Build a feature
Section titled “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 doesn’t fit; you need business rules on save. |
| Handler context and embedded fields | Keep handler transactions explicit and model repeated structure as embedded lists. |
| React to another feature’s events | Feature A reacts when feature B writes, without imports. |
| Build a read model across multiple aggregates | Aggregate events from several entities into one view. |
| Seed default data for new tenants | New tenant signs up; populate their workspace. |
| Apply one-shot data migrations via the event store | A role changed name, an admin needs an extra membership, run it once, tracked, ES-conform. |
Build a UI
Section titled “Build a UI”| Guide | When you reach for it |
|---|---|
| UI widgets | Cards, tables, charts, forms, pick the widget instead of hand-rolling one. |
| Multi-step wizards and embedded forms | A form too long for one page, or one that lives inside a Drawer instead of its own screen. |
| Dialog and Lightbox overlays | Confirm modals vs full-size image preview; Apex screenshot zoom. |
| Build a marketing landing page | An apex page composed from your own features, not a separate site. |
| Mount read-only inspector screens | See what a bundled feature stored, without building an admin UI. |
Access and security
Section titled “Access and security”| Guide | When you reach for it |
|---|---|
| Restrict a field to specific roles | A column visible to admins only, writable by everyone. |
| Expose a public, anonymous-readable endpoint | Public status pages, marketing landings, hosted reports. |
| Public share surface | A tokenized read-only link to one record, no login. |
| Call the API headlessly with a Personal Access Token | CI, a script, or a customer integration needs a long-lived, scoped bearer token. |
| Add TOTP-based 2FA to login | Users should enroll an authenticator app as a second login factor. |
| Rotate encryption keys | A KEK or blind-index key has to be replaced without downtime. |
| Make your app agent-ready | An in-app AI agent should be able to act on your records, describe the handlers, set the risk, pre-seed the approval rules. |
Ship and operate
Section titled “Ship and operate”| Guide | When you reach for it |
|---|---|
| Requirements | What has to be installed before any of this runs. |
| Upgrade Kumiko dependencies | Move an app to a newer framework release. |
| Deploy: Solo (single VM) | One box, docker-compose, your own SSL. |
| Deploy: Docker | The image itself, build stages, migrations, multi-arch. |
| Deploy: K3s (production scale) | Multiple sites on a cluster, rolling updates, backups. |
| Assign a tier to a tenant manually | Partner onboarding or a botched payment, grant a tier without billing. |
| Make your apex/content pages SEO/AEO/GEO discoverable | You mounted seo but don’t know what to actually configure to show up in search/answer engines. |
| Provenance and cost control for AI pipeline steps | You run ai.generate/ai.extract/ai.classify steps and need to know what actually ran, or your Anthropic bill is higher than it should be. |