@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/workflow-runner/tables.ts

@@ -0,0 +1,95 @@
+import {
+  defineUnmanagedTable,
+  type EntityTableMeta,
+  index,
+  instant,
+  integer,
+  jsonb,
+  table as pgTable,
+  primaryKey,
+  text,
+  uuid,
+} from "@cosmicdrift/kumiko-framework/db";
+
+// workflow_run_pending — one row per currently-suspended workflow step.
+// Read-side of the resume loop (framework#2513 Phase 1): the wait /
+// waitForEvent / retry steps already write their suspension onto the
+// workflow-run event stream, but scanning kumiko_events for due runs
+// doesn't scale (see samples/recipes/workflow-engine/postgres-resume-loop.ts,
+// which does exactly that). This table is kept in sync by
+// pending-projection.ts's MultiStreamProjection so Phase 2's resume job can
+// do an indexed `wakeAt < now()` scan instead.
+//
+// **Unmanaged table** — same reasoning as delivery/tables.ts'
+// deliveryAttemptsTable: rows are keyed by the workflow-run's own
+// (runId, stepIndex), not by an ES-aggregate id of their own, and rows are
+// deleted outright on resume/terminal rather than soft-state-transitioned —
+// no audit trail needed for a purely operational pending-set.
+//
+// PK = (tenant_id, run_id, step_index): workflowRunAggregateId() is
+// intentionally tenant-agnostic (uuidv5 over workflowName + idempotency
+// key only, see aggregate-id.ts), so two tenants triggering the same
+// workflow with the same idempotencyKey get the SAME run_id. Without
+// tenant_id in the key, a same-stepIndex suspension from tenant B would
+// upsert onto tenant A's row and silently steal it (framework#2513).
+export const workflowRunPendingTable = pgTable(
+  "workflow_run_pending",
+  {
+    runId: uuid("run_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    workflowName: text("workflow_name").notNull(),
+    stepIndex: integer("step_index").notNull(),
+    suspensionEventType: text("suspension_event_type").notNull(),
+    // Unified `wakeAt ?? timeoutAt` from the suspension payload — one
+    // column, one index, one predicate for the resume job regardless of
+    // which step suspended.
+    wakeAt: instant("wake_at").notNull(),
+    retryAttempt: integer("retry_attempt"),
+    // Q7 snapshot fingerprint — Phase 2 compares this against the current
+    // workflow definition's fingerprint before resuming.
+    definitionFingerprint: text("definition_fingerprint"),
+    // Set only for waitForEvent suspensions; NULL for wait/retry.
+    waitEventType: text("wait_event_type"),
+    matchExpr: jsonb("match_expr"),
+    // Written by the Phase 3 event-subscriber when the awaited event
+    // arrives — always NULL in Phase 1/2.
+    triggerEventType: text("trigger_event_type"),
+    triggerPayload: jsonb("trigger_payload"),
+  },
+  (t) => [
+    primaryKey({
+      columns: [t.tenantId, t.runId, t.stepIndex],
+      name: "workflow_run_pending_pkey",
+    }),
+    // Composite, not wake_at-alone: the resume job's due-scan
+    // (feature.ts) always filters `tenant_id = $1 AND wake_at < now()`.
+    index("workflow_run_pending_tenant_wake_at_idx").on(t.tenantId, t.wakeAt),
+    index("workflow_run_pending_wait_event_type_idx").on(t.waitEventType),
+  ],
+);
+
+export const workflowRunPendingTableMeta: EntityTableMeta = defineUnmanagedTable({
+  tableName: "workflow_run_pending",
+  columns: [
+    { name: "run_id", pgType: "uuid", notNull: true },
+    { name: "tenant_id", pgType: "uuid", notNull: true },
+    { name: "workflow_name", pgType: "text", notNull: true },
+    { name: "step_index", pgType: "integer", notNull: true },
+    { name: "suspension_event_type", pgType: "text", notNull: true },
+    { name: "wake_at", pgType: "timestamptz", notNull: true },
+    { name: "retry_attempt", pgType: "integer", notNull: false },
+    { name: "definition_fingerprint", pgType: "text", notNull: false },
+    { name: "wait_event_type", pgType: "text", notNull: false },
+    { name: "match_expr", pgType: "jsonb", notNull: false },
+    { name: "trigger_event_type", pgType: "text", notNull: false },
+    { name: "trigger_payload", pgType: "jsonb", notNull: false },
+  ],
+  indexes: [
+    { name: "workflow_run_pending_tenant_wake_at_idx", columns: ["tenant_id", "wake_at"] },
+    { name: "workflow_run_pending_wait_event_type_idx", columns: ["wait_event_type"] },
+  ],
+  compositePrimaryKey: {
+    name: "workflow_run_pending_pkey",
+    columns: ["tenant_id", "run_id", "step_index"],
+  },
+});

package/packages/bundled-features/src/workflow-runner/workflow-registry.ts

@@ -0,0 +1,23 @@
+// workflow-registry — process-local lookup from workflow name to its
+// WorkflowDefinition. registerEventTrigger populates it at feature-
+// registration time; resume-run (Phase 2) is the only reader — it has
+// nothing but a workflow name on the pending row and needs the live
+// definition to rebuild the pipeline + recompute the Q7 fingerprint.
+//
+// Overwrite-on-same-name, no throw: unlike defineStep's registry (which
+// throws on a duplicate kind — a real programming error), redefining a
+// workflow under the same name is a legitimate deploy-time occurrence
+// (the whole point of Q7 is detecting exactly that changed-definition case
+// downstream, not preventing the registration).
+
+import type { WorkflowDefinition } from "@cosmicdrift/kumiko-framework/engine";
+
+const registry = new Map<string, WorkflowDefinition>();
+
+export function registerWorkflow(workflow: WorkflowDefinition): void {
+  registry.set(workflow.name, workflow);
+}
+
+export function getWorkflow(name: string): WorkflowDefinition | undefined {
+  return registry.get(name);
+}

package/samples/apps/admin-console/README.md

@@ -0,0 +1,90 @@
+# Admin Console
+
+Sample app for the bundled admin shell: one Kumiko instance with a
+tenant-admin and a platform workspace, both built from owner-feature
+screens, and role gating that decides which workspace a signed-in user
+sees.
+
+**With auth**: email/password login, three seeded users with different
+roles. For an auth-free sample, see `samples/apps/marketing-demo/`.
+
+## Run
+
+```bash
+bun kumiko dev                          # Postgres + Redis
+cd samples/apps/admin-console && bun dev
+# → http://localhost:4177
+```
+
+Port 4177 is hardcoded in the `dev` script. The server reads the root
+`.env` (`--env-file=../../../.env`).
+
+### Demo users
+
+All three log into the dev tenant "Admin Console Demo" (tenant key
+`demo`). Passwords are in `src/app/auth-constants.ts`.
+
+| Email | Role | Sees |
+|---|---|---|
+| `sysadmin@admin-console.local` | global `SystemAdmin`, tenant `Admin` | tenant-admin and platform workspaces |
+| `tenant-admin@admin-console.local` | tenant `TenantAdmin` | tenant-admin workspace only |
+| `regular@admin-console.local` | tenant `User` | no admin workspace |
+
+The SystemAdmin comes from the `auth.admin` bootstrap in
+`src/app/server.ts`; the other two are created by `seedRoleUsers` in
+`src/app/seed-users.ts`.
+
+## What's inside
+
+### Mounted features
+
+`src/run-config.ts` lists the server features: `localeDe`, `secrets`,
+`audit`, `delivery`, `jobs`, `tier-engine`, `admin-shell` and a small
+`home` feature. The client (`src/app/client.tsx`) adds the matching web
+parts: email/password login, admin shell, tenant, audit, jobs and tier
+engine.
+
+### Workspaces
+
+- `/tenant-admin/`: tenant overview dashboard, members (with invite),
+  audit log
+- `/platform/`: platform overview dashboard, only for `SystemAdmin`
+- The workspace switcher only offers the workspaces the user's roles
+  allow
+
+### Home fallback screen
+
+Every admin-shell screen is role gated, but `createKumikoApp` needs an
+open default `screenQn`. The `home` feature registers one dormant custom
+screen without `access.roles` (`home:screen:home`). A signed-in user
+without any admin role lands there and reads "No workspace available
+for your account."
+
+### Shell
+
+`src/app/shell.tsx` wraps `WorkspaceShell` with a brand tile and the
+default topbar actions (light/dark toggle via lucide icons).
+
+## E2E tests
+
+```bash
+cd samples/apps/admin-console
+bun x playwright test --config=playwright.config.ts   # server on 4183
+```
+
+- `e2e/role-gating.spec.ts`: TenantAdmin lands on the tenant overview
+  and never sees the platform tab; the invite role picker offers only
+  User, Editor and Admin; the API answers `tenant:list` for a
+  TenantAdmin with 403. SystemAdmin sees both workspaces and can switch
+  to the platform overview. A regular user sees no workspace tabs.
+- `e2e/audit-log-toolbar.spec.ts`: on a narrow viewport the date range
+  facet of the audit log toolbar wraps below the search input; on a wide
+  viewport both stay on one line.
+
+The CI e2e job runs this config together with the other sample apps.
+
+## What's NOT in here
+
+- Custom business entities (see `apps/marketing-demo/`)
+- Config keys and the settings hub (see `apps/config-demo/`)
+- Every bundled feature at once (see `apps/use-all-bundled/`)

package/samples/apps/admin-console/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-admin-console",
+  "description": "Bundled admin-shell sample — tenant vs platform workspaces with owner-feature screens.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "PORT=4177 bun --env-file=../../../.env run kumiko-dev src/app/server.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-dev-server": "workspace:*",
+    "@cosmicdrift/kumiko-dispatcher-live": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-headless": "workspace:*",
+    "@cosmicdrift/kumiko-renderer": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-web": "workspace:*",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "@cosmicdrift/kumiko-locale-de": "workspace:*"
+  }
+}

package/samples/apps/admin-console/playwright.config.ts

@@ -0,0 +1,13 @@
+// @runtime test
+import { defineAppE2eConfig, PLAYWRIGHT_DEMO_ENV } from "@cosmicdrift/kumiko-testing/e2e";
+import { E2E_PORTS } from "../../e2e/e2e-ports";
+
+// E2E port from samples/e2e/e2e-ports.ts; 4177 stays free for manual `bun dev`.
+const PORT = E2E_PORTS["framework/admin-console"];
+
+export default defineAppE2eConfig({
+  port: PORT,
+  serverEntry: "src/app/server.ts",
+  locale: "en-US",
+  env: PLAYWRIGHT_DEMO_ENV,
+});

package/samples/apps/admin-console/src/app/auth-constants.ts

@@ -0,0 +1,10 @@
+export const DEV_TENANT_ID = "00000000-0000-4000-8000-000000000077";
+
+export const SYSADMIN_EMAIL = "sysadmin@admin-console.local";
+export const SYSADMIN_PASSWORD = "sysadmin-console";
+
+export const TENANT_ADMIN_EMAIL = "tenant-admin@admin-console.local";
+export const TENANT_ADMIN_PASSWORD = "tenant-admin-console";
+
+export const REGULAR_USER_EMAIL = "regular@admin-console.local";
+export const REGULAR_USER_PASSWORD = "regular-console";

package/samples/apps/admin-console/src/app/client.tsx

@@ -0,0 +1,29 @@
+import { adminShellClient } from "@cosmicdrift/kumiko-bundled-features/admin-shell/web";
+import { auditClient } from "@cosmicdrift/kumiko-bundled-features/audit/web";
+import { emailPasswordClient } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { jobsClient } from "@cosmicdrift/kumiko-bundled-features/jobs/web";
+import { tenantClient } from "@cosmicdrift/kumiko-bundled-features/tenant/web";
+import { tierEngineClient } from "@cosmicdrift/kumiko-bundled-features/tier-engine/web";
+import { localeDeClient } from "@cosmicdrift/kumiko-locale-de/web";
+import { createKumikoApp } from "@cosmicdrift/kumiko-renderer-web";
+import { HomeScreen } from "./home-screen";
+import { AppShell } from "./shell";
+
+createKumikoApp({
+  shell: AppShell,
+  // admin-console has only role-gated screens (no open app screen), so
+  // createKumikoApp needs an explicit screenQn, otherwise firstOpenScreenQn()
+  // crashes at boot. home:screen:home is the only screen without access.roles;
+  // WorkspaceShell immediately overrides it with the role-appropriate default screen.
+  screenQn: "home:screen:home",
+  clientFeatures: [
+    localeDeClient(),
+    emailPasswordClient(),
+    { name: "home", components: { "admin-console-home": HomeScreen } },
+    adminShellClient(),
+    tenantClient(),
+    auditClient(),
+    jobsClient(),
+    tierEngineClient(),
+  ],
+});

package/samples/apps/admin-console/src/app/home-screen.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from "react";
+
+// Registered without access.roles (see home-feature in run-config.ts) - serves
+// as createKumikoApp's default screenQn since admin-console otherwise only has
+// role-gated screens. WorkspaceShell overrides the URL immediately for any
+// user with workspace access; only visible for authenticated users without
+// any workspace role.
+export function HomeScreen(): ReactNode {
+  return (
+    <div data-testid="admin-console-home" className="p-6 text-muted-foreground">
+      No workspace available for your account.
+    </div>
+  );
+}

package/samples/apps/admin-console/src/app/seed-users.ts

@@ -0,0 +1,42 @@
+// @runtime dev
+// Extra users for role-gated workspace demos — separate from sysadmin seed.
+
+import { hashPassword } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
+import { seedTenantMembership } from "@cosmicdrift/kumiko-bundled-features/tenant/seeding";
+import { seedUser } from "@cosmicdrift/kumiko-bundled-features/user/seeding";
+import type { SeedFn } from "@cosmicdrift/kumiko-dev-server";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  DEV_TENANT_ID,
+  REGULAR_USER_EMAIL,
+  REGULAR_USER_PASSWORD,
+  TENANT_ADMIN_EMAIL,
+  TENANT_ADMIN_PASSWORD,
+} from "./auth-constants";
+
+export const seedRoleUsers: SeedFn = async (stack) => {
+  const tenantId = DEV_TENANT_ID as TenantId;
+  const tenantAdmin = await seedUser(stack.db, {
+    email: TENANT_ADMIN_EMAIL,
+    displayName: "Tenant Admin",
+    passwordHash: await hashPassword(TENANT_ADMIN_PASSWORD),
+    emailVerified: true,
+  });
+  await seedTenantMembership(stack.db, {
+    userId: tenantAdmin.id,
+    tenantId,
+    roles: ["TenantAdmin"],
+  });
+
+  const regular = await seedUser(stack.db, {
+    email: REGULAR_USER_EMAIL,
+    displayName: "Regular User",
+    passwordHash: await hashPassword(REGULAR_USER_PASSWORD),
+    emailVerified: true,
+  });
+  await seedTenantMembership(stack.db, {
+    userId: regular.id,
+    tenantId,
+    roles: ["User"],
+  });
+};

package/samples/apps/admin-console/src/app/server.ts

@@ -0,0 +1,35 @@
+// @runtime dev
+import { runDevApp } from "@cosmicdrift/kumiko-dev-server";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { APP_FEATURES } from "../run-config";
+import { DEV_TENANT_ID, SYSADMIN_EMAIL, SYSADMIN_PASSWORD } from "./auth-constants";
+import { seedRoleUsers } from "./seed-users";
+
+await runDevApp({
+  features: APP_FEATURES,
+  port: Number.parseInt(process.env["PORT"] ?? "4177", 10),
+  // Invite drawer on /members needs auth-email-password invite-create wired.
+  clientEntry: "./src/app/client.tsx",
+  htmlPath: "./public/index.html",
+  watchDirs: ["./src", "../../../packages/*/src"],
+  seeds: [seedRoleUsers],
+  auth: {
+    invite: {
+      appUrl: `http://localhost:${Number.parseInt(process.env["PORT"] ?? "4177", 10)}/invite/accept`,
+    },
+    admin: {
+      email: SYSADMIN_EMAIL,
+      password: SYSADMIN_PASSWORD,
+      displayName: "Platform Operator",
+      globalRoles: ["SystemAdmin"],
+      memberships: [
+        {
+          tenantId: DEV_TENANT_ID as TenantId,
+          tenantKey: "demo",
+          tenantName: "Admin Console Demo",
+          roles: ["Admin"],
+        },
+      ],
+    },
+  },
+});

package/samples/apps/admin-console/src/app/shell.tsx

@@ -0,0 +1,48 @@
+import {
+  DefaultTopbarActions,
+  useShellUser,
+} from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { type AppSchema, WorkspaceShell } from "@cosmicdrift/kumiko-renderer-web";
+import { MoonStar, Sun } from "lucide-react";
+import type { ReactNode } from "react";
+
+const APP_NAME = "Admin Console";
+
+// Logo-Kachel + Wortmarke — wie SidebarBrand (sidebar-brand.tsx). Die
+// Kachel bleibt collapsed stehen (liest sich als Logo, nicht als
+// zufaelliger Buchstabe), nur die Wortmarke daneben blendet aus.
+const Brand = (): ReactNode => (
+  <div className="flex items-center gap-2 group-data-[collapsible=icon]:justify-center">
+    <div className="flex aspect-square size-8 shrink-0 items-center justify-center rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+      <span className="text-sm font-semibold">{APP_NAME.charAt(0)}</span>
+    </div>
+    <strong className="truncate text-foreground tracking-tight group-data-[collapsible=icon]:hidden">
+      {APP_NAME}
+    </strong>
+  </div>
+);
+
+export function AppShell({
+  children,
+  schema,
+}: {
+  readonly children: ReactNode;
+  readonly schema: AppSchema;
+}): ReactNode {
+  const user = useShellUser();
+  return (
+    <WorkspaceShell
+      brand={<Brand />}
+      schema={schema}
+      topbarActions={
+        <DefaultTopbarActions
+          lightIcon={<Sun className="h-4 w-4" />}
+          darkIcon={<MoonStar className="h-4 w-4" />}
+        />
+      }
+      {...(user !== undefined && { user })}
+    >
+      {children}
+    </WorkspaceShell>
+  );
+}

package/samples/apps/admin-console/src/run-config.ts

@@ -0,0 +1,60 @@
+import { createAdminShellFeature } from "@cosmicdrift/kumiko-bundled-features/admin-shell";
+import { createAuditFeature } from "@cosmicdrift/kumiko-bundled-features/audit";
+import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { createJobsFeature } from "@cosmicdrift/kumiko-bundled-features/jobs";
+import {
+  activeTenantsMetric,
+  auditWritesMetric,
+  createMetricsFeature,
+  createSystemMetricsFeature,
+  deliveriesByChannelMetric,
+  failedDeliveriesMetric,
+  failedJobRunsMetric,
+  jobRunsByStatusMetric,
+  tenantJobFailuresMetric,
+} from "@cosmicdrift/kumiko-bundled-features/metrics";
+import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import { tierEngineFeature } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { localeDe } from "@cosmicdrift/kumiko-locale-de";
+
+// Only screen without access.roles in this app - admin-console otherwise
+// consists solely of role-gated admin-shell screens, but createKumikoApp
+// needs an open default screenQn (see client.tsx).
+const homeFeature = defineFeature("home", (r) => {
+  r.screen({
+    id: "home",
+    type: "custom",
+    renderer: { react: { __component: "admin-console-home" } },
+    dormant: true,
+  });
+  r.translations({
+    keys: { "screen:home.title": { de: "Start", en: "Home" } },
+  });
+});
+
+// No sessions feature in this app, so no active-users metric.
+const CONSOLE_METRICS = [
+  jobRunsByStatusMetric,
+  failedJobRunsMetric,
+  tenantJobFailuresMetric,
+  deliveriesByChannelMetric,
+  failedDeliveriesMetric,
+  activeTenantsMetric,
+  auditWritesMetric,
+] as const;
+
+export const APP_FEATURES = [
+  localeDe(),
+  createSecretsFeature(),
+  createAuditFeature(),
+  createDeliveryFeature(),
+  createJobsFeature(),
+  tierEngineFeature,
+  createMetricsFeature({ metrics: CONSOLE_METRICS }),
+  createSystemMetricsFeature({ metrics: CONSOLE_METRICS }),
+  createAdminShellFeature({ metrics: CONSOLE_METRICS }),
+  homeFeature,
+] as const;
+
+export const HAS_AUTH = true;

package/samples/apps/admin-console/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@cosmicdrift/kumiko-framework/*": [
+        "../../../packages/framework/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-bundled-features/*": [
+        "../../../packages/bundled-features/src/*/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server": [
+        "../../../packages/dev-server/src/index.ts"
+      ],
+      "@cosmicdrift/kumiko-dev-server/*": ["../../../packages/dev-server/src/*"]
+    },
+    "noEmit": true,
+    "rootDir": "../../..",
+    "jsx": "react-jsx",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "types": ["bun-types"]
+  },
+  "include": ["src"]
+}

package/samples/apps/cap-billing-demo/README.md

@@ -0,0 +1,151 @@
+# Cap-Billing Demo
+
+Sample app showing how a Kumiko app wires **tier-engine** + **cap-counter** + **mail-foundation plugin API** together to enforce per-tenant caps on newsletter sends — including a soft-hit notification and a hard block.
+
+The sample doubles as **living documentation** for the pattern: read the code top-to-bottom and you've understood the cap engine.
+
+## What the demo does
+
+A tiny newsletter app with two tiers:
+
+| Tier | Newsletters per month | Soft warning at | Hard block at |
+|------|-----------|-------------------|-----------------|
+| free | 10 | 11 (110%) | 12 (120%) |
+| pro | 100 | 110 (110%) | 120 (120%) |
+
+Mails land in an **in-memory transport** (`mail-transport-inmemory`).
+There's no real SMTP server — perfect for the demo, no Mailpit/Mailcrab
+needed. The inbox is read via a helper function.
+
+## Architecture in 4 layers
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ src/feature.ts                                               │
+│   newsletter:write:send (cap-aware)                          │
+│   ├── inner handler: createTransportForTenant + .send()      │
+│   └── wrapper: withCapEnforcement                            │
+│       ├── pre: enforceCapAndMaybeNotify (tier-conditional)   │
+│       │     └── notifier: sends warning mail to admin        │
+│       └── post: incrementCap (+1)                            │
+└──────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│ src/tier-map.ts                                              │
+│   DEMO_TIER_MAP: Record<TierName, {features, caps}>          │
+│   resolveTier(ctx) → 1. subscription row (provider webhook)  │
+│                      2. config "newsletter:config:tier"      │
+│                      3. default "free"                       │
+└──────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│ src/run-config.ts                                            │
+│   APP_FEATURES = [secrets, cap-counter, mail-foundation,     │
+│                   mail-transport-inmemory,                   │
+│                   billing-foundation, newsletter]            │
+└──────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│ bundled-features (no code in the app)                        │
+│   tier-engine: composeApp + TierMap type                     │
+│   cap-counter: enforceCap + withCapEnforcement + counter ES  │
+│   mail-foundation: plugin API for transports                 │
+│   mail-transport-inmemory: per-tenant in-memory inbox        │
+│   billing-foundation: provider plugin host (Stripe/          │
+│                            Mollie). Demo mounts no           │
+│                            providers — tests call process-   │
+│                            event directly; your own app adds │
+│                            createSubscriptionStripeFeature() │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Demo story as a test
+
+The most thorough doc for the demo is the integration test itself:
+
+```bash
+bun test
+```
+
+`src/__tests__/cap-billing-demo.integration.test.ts` boots the full
+dispatcher + DB and proves step by step:
+
+- 10 newsletters sent without warning
+- 12th newsletter triggers the soft-hit notification once
+- 13th newsletter is hard-blocked (CapExceededError)
+- Pro tenant unaffected by the free tenant's cap
+- **Mid-period tier change:** free→pro upgrade keeps the counter
+  intact + immediately uses the higher cap (= the real Stripe-webhook
+  path). pro→free downgrade blocks immediately when the counter is
+  above the new hard limit.
+
+Read the test file top-to-bottom — it's written as a living doc.
+
+## Run locally
+
+```bash
+bun kumiko dev      # Postgres + Redis
+bun install
+cd samples/apps/cap-billing-demo
+bun dev             # → http://localhost:4290
+```
+
+| Login | Value |
+|-------|------|
+| URL | `http://localhost:4290` |
+| Email | `admin@cap-demo.local` |
+| Password | `changeme` |
+| Tenant | "Cap-Billing-Demo" |
+
+In the browser, use the Designer/Admin UI to set the config key
+`newsletter:config:tier` to `"free"` or `"pro"` and trigger the
+`newsletter:write:send` handler. The "sent" mails land in
+`getInbox(tenantId)` from
+`@cosmicdrift/kumiko-bundled-features/mail-transport-inmemory` —
+there's no HTTP endpoint for it because the sample shows the
+architecture, not an inbox UI.
+
+If you want clickable: write a small `r.queryHandler("inbox:list")`
+that returns `getInbox(ctx.user.tenantId)`. ~20 LOC, deliberately
+omitted to keep the focus on cap+tier.
+
+## How do I port this to a real app?
+
+The sample is intentionally minimal. For a production app, swap:
+
+| Demo component | Production replacement |
+|-----------------|-------------------|
+| `mail-transport-inmemory` | `mail-transport-smtp` (BYOK) or a custom plugin |
+| Hardcoded `DEMO_TIER_MAP` | stays — tier definitions are static, the subscription row only writes the `tier` key |
+| Tier switch via webhook (test-only) | mount a real plugin: `createSubscriptionStripeFeature(...)` and/or `createSubscriptionMollieFeature(...)` in the run config |
+| 2 tiers (free/pro) | any number, see `samples/apps/platform/src/tier-map.ts` for a 4-tier example |
+| Newsletter domain | your own feature with `withCapEnforcement(handler, capResolver)` |
+
+The **plugin API switch** between demo and production is a single
+config value: `mail-foundation:config:provider` flips from
+`"inmemory"` to `"smtp"`, no code refactor.
+
+## Key files
+
+- **`src/feature.ts`** — the wrapped send handler. Here you see how
+  `withCapEnforcement` turns a normal handler into a cap-aware one
+- **`src/tier-map.ts`** — DEMO_TIER_MAP + tier-name whitelist
+- **`src/run-config.ts`** — feature composition (which bundled-features
+  the demo mounts)
+- **`src/__tests__/cap-billing-demo.integration.test.ts`** — the played-out
+  story (10/11/12/13 newsletters, soft+hard transitions, tenant
+  isolation)
+
+## Questions / weaknesses this demo exposes
+
+The sample is meant as a doc test. Concrete weaknesses we see here:
+
+- **Notifier address hardcoded.** `buildSoftHitNotifier` in
+  `feature.ts` sends to `admin@tenant-${id.slice(-4)}.demo`. A real
+  app would query tenant config or the users table.
+- **Tier lookup per send call.** `resolveTier(ctx)` runs a DB query on
+  the subscription row on every send — for busy tenants caching would
+  be sensible. The demo skips it because it distracts from the cap
+  pattern.
+- **No provider mount in the demo itself.** The tests call
+  `billing-foundation:write:process-event` directly; in production an
+  app mounts `createSubscriptionStripeFeature(...)` or
+  `createSubscriptionMollieFeature(...)` and Mollie/Stripe webhooks
+  hit `/api/subscription/webhook/:providerName`.