@pikku/cli 0.12.145 → 0.12.152

package/surface.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.145",
+  "version": "0.12.152",
   "entryPoints": [
     {
       "id": "app",
@@ -87,7 +87,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -102,6 +102,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -131,7 +135,7 @@
                   "doc": "Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`."
                 },
                 {
-                  "line": "scopes?: never[]",
+                  "line": "scopes?: import(\"#pikku/scopes/pikku-scopes.gen.js\").ScopeId[]",
                   "doc": "Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access."
                 },
                 {
@@ -216,7 +220,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -231,6 +235,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunction<In, Out, RequiredWires, any> | PikkuFunctionSessionless<In, Out, RequiredWires, any, any>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."
@@ -276,7 +284,7 @@
                   "doc": "Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`."
                 },
                 {
-                  "line": "scopes?: never[]",
+                  "line": "scopes?: import(\"#pikku/scopes/pikku-scopes.gen.js\").ScopeId[]",
                   "doc": "Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access."
                 },
                 {
@@ -358,7 +366,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -373,6 +381,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunction<ListInput<F, S>, ListOutput<Row>, \"rpc\" | \"session\", WiredServices> | PikkuFunctionSessionless<ListInput<F, S>, ListOutput<Row>, \"rpc\" | \"session\", WiredServices, unknown>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."
@@ -418,7 +430,7 @@
                   "doc": "Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`."
                 },
                 {
-                  "line": "scopes?: never[]",
+                  "line": "scopes?: import(\"#pikku/scopes/pikku-scopes.gen.js\").ScopeId[]",
                   "doc": "Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access."
                 },
                 {
@@ -489,7 +501,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -504,6 +516,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: string",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -600,7 +616,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -615,6 +631,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: string",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -752,6 +772,14 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService?: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -778,6 +806,10 @@
                 {
                   "line": "emailService?: EmailService"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "logger: Logger"
                 },
@@ -867,6 +899,14 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService?: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -893,6 +933,10 @@
                 {
                   "line": "emailService?: EmailService"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "logger: Logger"
                 },
@@ -954,6 +998,14 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -968,23 +1020,27 @@
                   "line": "content?: ContentService<string>"
                 },
                 {
-                  "line": "coverageService?: CoverageService",
+                  "line": "coverageService: CoverageService",
                   "doc": "V8 precise-coverage collector (`pikku dev --coverage` only)"
                 },
                 {
-                  "line": "credentialService?: CredentialService"
+                  "line": "credentialService: CredentialService"
                 },
                 {
-                  "line": "deploymentService?: DeploymentService"
+                  "line": "deploymentService: DeploymentService"
                 },
                 {
                   "line": "emailService?: EmailService"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "logger: Logger"
                 },
                 {
-                  "line": "metaService?: MetaService"
+                  "line": "metaService: MetaService"
                 },
                 {
                   "line": "schedulerService: SchedulerService"
@@ -993,7 +1049,7 @@
                   "line": "schema: SchemaService"
                 },
                 {
-                  "line": "scopeService?: ScopeService",
+                  "line": "scopeService: ScopeService",
                   "doc": "Resolves and administers user scopes. Called when building a session, never by the function runner."
                 },
                 {
@@ -1004,15 +1060,15 @@
                   "line": "variables: VariablesService"
                 },
                 {
-                  "line": "virtualUserRunStore?: VirtualUserRunStore",
+                  "line": "virtualUserRunStore: VirtualUserRunStore",
                   "doc": "Where virtual-user runs are recorded. A run is dispatched and answered for later, so this store is the only trace it leaves — see {@link VirtualUserRunStore}."
                 },
                 {
-                  "line": "virtualUserScheduleStore?: VirtualUserScheduleStore",
+                  "line": "virtualUserScheduleStore: VirtualUserScheduleStore",
                   "doc": "Each persona's cadence, for apps that want their virtual users to keep going without being asked. Separate from the run store on purpose: wiring nothing is how an app says it only wants the runs it starts itself."
                 },
                 {
-                  "line": "webhookService?: WebhookService",
+                  "line": "webhookService: WebhookService",
                   "doc": "Queue-backed outgoing webhook delivery. The queue-only default throws on the delivery-read methods; a store-backed implementation records history."
                 },
                 {
@@ -1216,6 +1272,229 @@
             }
           ]
         },
+        {
+          "specifier": "#pikku/analytics",
+          "name": "analytics",
+          "step": "enhance it",
+          "summary": "The events a project can measure, declared by name so the generated ingest knows what to accept. Where they go is an AnalyticsService on singleton services; what a function records into is the analytics service on the invocation.",
+          "skill": null,
+          "symbols": [
+            {
+              "name": "AnalyticsClientContext",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Its presence, not `at`, is what marks a record as relayed from a browser — a beacon is free to omit `at`.",
+              "docs": "Its presence, not `at`, is what marks a record as relayed from a browser — a\nbeacon is free to omit `at`.",
+              "members": [
+                {
+                  "line": "at?: number"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsEventBase",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "The constraint a project's declared event union is checked against.",
+              "docs": "The constraint a project's declared event union is checked against.\n\nOnly `name` is fixed, because the name is the whole of what pikku itself\nreads — everything else on an event belongs to the app and to the sinks it\nwires, and narrowing it here would make the generic useless for anyone whose\nevents carry more than a fixed set of props.",
+              "members": [
+                {
+                  "line": "name: string"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsEventDefinitions",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Events keyed by name; each value is the schema for that event's props.",
+              "docs": "Events keyed by name; each value is the schema for that event's props."
+            },
+            {
+              "name": "AnalyticsEventPropsSchema",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "The schema for one event's props. The generated ingest rebuilds each member of the union as `z.object(schema.shape)` so it can attach the event name, so a schema with no `shape` — a union, a primitive, a schema from a library that does not expose one — is not something an event can be declared with, and saying so here fails at the declaration rather than in generated code.",
+              "docs": "The schema for one event's props. The generated ingest rebuilds each member\nof the union as `z.object(schema.shape)` so it can attach the event name, so\na schema with no `shape` — a union, a primitive, a schema from a library\nthat does not expose one — is not something an event can be declared with,\nand saying so here fails at the declaration rather than in generated code.",
+              "members": [
+                {
+                  "line": "~standard: StandardSchemaV1.Props<unknown, unknown>",
+                  "doc": "The Standard Schema properties."
+                },
+                {
+                  "line": "shape: Record<string, unknown>"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsIdentity",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Stamped server-side from the session and never read from the request body, which is what makes an unauthenticated ingest safe to expose.",
+              "docs": "Stamped server-side from the session and never read from the request body,\nwhich is what makes an unauthenticated ingest safe to expose.",
+              "members": [
+                {
+                  "line": "anonymousId?: string",
+                  "doc": "A device-scoped id for a visitor with no session, minted by pikku rather than by a vendor. Distinct from `pikkuUserId`, which is derived from a session and is therefore absent for exactly the visitor this identifies. Without it a product-analytics sink has no honest option for anonymous traffic: keying on a shared literal collapses every visitor into one person, and dropping the event loses the whole pre-signup funnel."
+                },
+                {
+                  "line": "consent?: Record<string, boolean>",
+                  "doc": "What the visitor agreed to, keyed by purpose. A sink gated on a purpose absent here does not send. Open-ended rather than a fixed pair, because the purposes are the consent tool's vocabulary and jurisdictions do not agree on them. Undefined means the app wired no consent resolver, not that consent was refused — the gate belongs to the sink, which is where the app decides what absence means."
+                },
+                {
+                  "line": "orgId?: string"
+                },
+                {
+                  "line": "pikkuUserId?: string"
+                },
+                {
+                  "line": "userId: string | null"
+                },
+                {
+                  "line": "vendorIds?: Record<string, string>",
+                  "doc": "Identifiers a destination keys on that pikku does not mint — GA4's `client_id`, Meta's `fbp` and `fbc`, a vendor's own device id. All of them originate in the browser, and a sink that cannot produce one does not degrade, it sends nothing usable. Resolved server-side from first-party cookies on the request, never read from the event body, on the same reasoning as the rest of this object: a crafted client call must not be able to attribute an event to someone else."
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsLog",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "`services.analytics`: buffered for the invocation, flushed when it ends, always best-effort. `record` is a method rather than a property so an app can narrow `Events` in its own `SingletonServices`.",
+              "docs": "`services.analytics`: buffered for the invocation, flushed when it ends,\nalways best-effort. `record` is a method rather than a property so an app can\nnarrow `Events` in its own `SingletonServices`.",
+              "signature": "AnalyticsLog<Events>",
+              "members": [
+                {
+                  "line": "close: () => Promise<void>"
+                },
+                {
+                  "line": "flush: () => Promise<void>"
+                },
+                {
+                  "line": "record: (event: Events, client?: AnalyticsClientContext) => Promise<void>"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsRecord",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "What an event becomes once pikku has accepted it, and the only shape an {@link AnalyticsService} is ever handed.",
+              "docs": "What an event becomes once pikku has accepted it, and the only shape an\n{@link AnalyticsService} is ever handed.\n\nDistinct from {@link AnalyticsEventInput}, which is what a caller submits:\nthe identity, the trace and the origin are stamped server-side on the way\nthrough, so a sink never has to trust — or re-derive — any of them.",
+              "members": [
+                {
+                  "line": "at?: number"
+                },
+                {
+                  "line": "functionId?: string"
+                },
+                {
+                  "line": "name: string"
+                },
+                {
+                  "line": "occurredAt: string"
+                },
+                {
+                  "line": "props?: Record<string, unknown>"
+                },
+                {
+                  "line": "source: \"server\" | \"client\""
+                },
+                {
+                  "line": "traceId?: string"
+                },
+                {
+                  "line": "userIdentity: AnalyticsIdentity"
+                },
+                {
+                  "line": "wireType?: PikkuWiringTypes"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsService",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Where accepted events go. Pikku validates, identifies and batches them; it does not store them.",
+              "docs": "Where accepted events go. Pikku validates, identifies and batches them; it\ndoes not store them.\n\nOne method, taking a batch, because a batch is what a destination is always\nhanded: the invocation buffers and flushes once, and a lone event is a batch\nof one. A single-event method beside it would be a second path every sink had\nto implement and every caller had to choose between.",
+              "members": [
+                {
+                  "line": "write: (batch: AnalyticsRecord[]) => Promise<void>"
+                }
+              ]
+            },
+            {
+              "name": "defineAnalyticsEvents",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Declare what a module can measure. Call it as often as suits the project; the CLI unions every declaration into the ingest schema.",
+              "docs": "Declare what a module can measure. Call it as often as suits the project; the\nCLI unions every declaration into the ingest schema.\n\nIt must stay an exported const — the schema pipeline reads the value by name.\nIt registers nothing at runtime: where events go is an `AnalyticsService` on\nsingleton services.",
+              "signature": "<const Events extends AnalyticsEventDefinitions>(events: Events) => Events"
+            },
+            {
+              "name": "flattenAnalyticsEvent",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Removes the discriminator, so `props` is free of the series key.",
+              "docs": "Removes the discriminator, so `props` is free of the series key.",
+              "signature": "(event: AnalyticsEventBase, at?: number) => AnalyticsEventInput",
+              "members": [
+                {
+                  "line": "name: string"
+                }
+              ]
+            },
+            {
+              "name": "LoggerAnalyticsService",
+              "kind": "class",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "What an app gets before it has chosen a store. There is deliberately no noop: a validated wire with nowhere for the events to go is indistinguishable from a broken one.",
+              "docs": "What an app gets before it has chosen a store. There is deliberately no noop:\na validated wire with nowhere for the events to go is indistinguishable from\na broken one.\n\nAt `debug` so attaching a real store does not report every event twice.",
+              "signature": "new LoggerAnalyticsService(logger: Logger)",
+              "members": [
+                {
+                  "line": "logger: any"
+                },
+                {
+                  "line": "write: (batch: AnalyticsRecord[]) => Promise<void>"
+                }
+              ]
+            }
+          ]
+        },
         {
           "specifier": "#pikku/error",
           "name": "error",
@@ -1335,6 +1614,21 @@
               "signature": "new ExpectationFailedError(message?: string)",
               "status": 417
             },
+            {
+              "name": "FeatureUnavailableError",
+              "kind": "class",
+              "origin": {
+                "via": "core",
+                "subpath": "./errors"
+              },
+              "signature": "new FeatureUnavailableError(feature: string)",
+              "members": [
+                {
+                  "line": "payload: { error: \"feature_unavailable\"; feature: string; }"
+                }
+              ],
+              "status": 503
+            },
             {
               "name": "ForbiddenError",
               "kind": "class",
@@ -3404,6 +3698,20 @@
           "summary": "The scopes a caller can hold and the roles that grant them, gating a call outside the permission pool.",
           "skill": "pikku-auth",
           "symbols": [
+            {
+              "name": "defineFeatureFlags",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./flag"
+              },
+              "summary": "No-op function for declaring feature flags. This exists purely for TypeScript type checking and will be tree-shaken. The CLI extracts metadata via AST parsing and generates a `FeatureFlagName` union, so `flags.calList` is a compile error rather than a silent `false`.",
+              "docs": "No-op function for declaring feature flags.\nThis exists purely for TypeScript type checking and will be tree-shaken.\nThe CLI extracts metadata via AST parsing and generates a `FeatureFlagName`\nunion, so `flags.calList` is a compile error rather than a silent `false`.\n\nThat typing is load-bearing rather than a convenience: flags fail closed, so\na typo'd flag reads `false`, hides its feature permanently, and leaves every\ntest, screenshot and gate green. An untyped key makes a missing product\nindistinguishable from a working one.\n\nRemoval is deliberately not destructive. Deleting a declaration leaves the\nrow in the store, marked undeclared and inert, until `pikku flags prune` —\nthe same additive contract `defineScope` and `defineSystemRole` have, and for\nthe same reason: a mid-deploy revocation is not something a code edit should\nbe able to cause.",
+              "signature": "(_config: CoreFeatureFlags) => void",
+              "examples": [
+                "```typescript\ndefineFeatureFlags({\n  takeInBike: {\n    description: 'Book a bike in at the counter',\n    anyOf: ['bikes:intake'],\n  },\n  aiAssistant: {\n    description: 'The assistant panel',\n    // no anyOf — the switch is the whole answer\n  },\n})\n```"
+              ]
+            },
             {
               "name": "defineScope",
               "kind": "function",
@@ -3431,6 +3739,46 @@
               "examples": [
                 "```typescript\ndefineSystemRole({\n  buyer: {\n    displayName: 'Buyer',\n    description: 'Can browse the catalogue and place orders',\n    scopes: ['catalogue:read', 'orders:create'],\n  },\n  admin: {\n    description: 'Everything',\n    scopes: ['admin'],\n  },\n})\n```"
               ]
+            },
+            {
+              "name": "FEATURE_FLAGS",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "The declared flag set, for a FeatureFlagStore to sync into its store.",
+              "docs": "The declared flag set, for a FeatureFlagStore to sync into its store.\n\nDerived from the metadata sidecar rather than inlined, so the import above\nforces tsc to emit the .json alongside this file — an addon publishes only\nits compiled output, and a host reads that .json to merge the addon's flags\ninto its own union.\n\nAdditive on removal: a deleted declaration leaves the row marked\n`declared: false` rather than switching a feature off on deploy. Use\n`pikku flags prune` to remove them.",
+              "signature": "DeclaredFlag[]"
+            },
+            {
+              "name": "FEATURE_FLAGS_FALLBACK",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "What a flag source falls back to when its backing store cannot be read: every declared flag on, no rollout, no overrides.",
+              "docs": "What a flag source falls back to when its backing store cannot be read: every\ndeclared flag on, no rollout, no overrides.\n\nFailing open is deliberate. A flag store is not an authorization boundary —\n`scopes:` is — so an unreadable config must not take the product down with\nit.",
+              "signature": "FlagConfigSnapshot"
+            },
+            {
+              "name": "FEATURE_FLAGS_META",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "Declared flags, keyed by name. Rendered by the console beside each switch.",
+              "docs": "Declared flags, keyed by name. Rendered by the console beside each switch.\n\nKeyed by `FeatureFlagName` so a misspelled lookup is a type error, which is\nthe whole point of generating the union. The assertion is what\n`Object.fromEntries` costs — it returns an index signature — and it is\nsound here because both this object and the union are built from\n`FEATURE_FLAGS`, so every key of the union is present.",
+              "signature": "Record<never, DeclaredFlag>"
+            },
+            {
+              "name": "FeatureFlagName",
+              "kind": "type",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "Every feature flag declared in this application.",
+              "docs": "Every feature flag declared in this application.",
+              "signature": "never"
             }
           ]
         },
@@ -3568,7 +3916,7 @@
                   "doc": "Who the agent is. Joined with `personality` and `goal`, in that order, to form the system prompt."
                 },
                 {
-                  "line": "scopes?: never[]",
+                  "line": "scopes?: import(\"#pikku/scopes/pikku-scopes.gen.js\").ScopeId[]",
                   "doc": "Scopes the session must hold to run this agent. All of them are required (AND), and they are checked before `permissions` — unlike permissions, which OR together, a scope can only narrow access. Narrowed to the generated `ScopeId` union in a project's own `#pikku/scopes`, so an undeclared scope is a compile error."
                 },
                 {
@@ -3754,7 +4102,7 @@
                   "doc": "Unique across the project. It is how the graph is started and how its runs are grouped."
                 },
                 {
-                  "line": "nodes: Record<string, 43 names (pikku meta)>",
+                  "line": "nodes: Record<string, 118 names (pikku meta)>",
                   "doc": "The graph's steps, keyed by node id, each naming a function. `pikku meta` lists the names available here."
                 },
                 {
@@ -4024,7 +4372,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4039,6 +4387,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunctionScenario<In, Out, Out>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."
@@ -4084,7 +4436,7 @@
                   "doc": "Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`."
                 },
                 {
-                  "line": "scopes?: never[]",
+                  "line": "scopes?: import(\"#pikku/scopes/pikku-scopes.gen.js\").ScopeId[]",
                   "doc": "Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access."
                 },
                 {
@@ -4429,7 +4781,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4444,6 +4796,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -4558,7 +4914,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4573,6 +4929,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunction<In, Out, RequiredWires, any> | PikkuFunctionSessionless<In, Out, RequiredWires, any, any>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."
@@ -4700,7 +5060,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4715,6 +5075,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunction<ListInput<F, S>, ListOutput<Row>, \"rpc\" | \"session\", WiredServices> | PikkuFunctionSessionless<ListInput<F, S>, ListOutput<Row>, \"rpc\" | \"session\", WiredServices, unknown>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."
@@ -4831,7 +5195,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4846,6 +5210,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: string",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -4942,7 +5310,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -4957,6 +5325,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: string",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "mcp?: boolean",
                   "doc": "Offers the function to MCP clients as a tool, without a separate `wireMCPTool`."
@@ -5103,6 +5475,18 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analytics?: AnalyticsLog<AnalyticsEventBase>",
+                  "doc": "Request-scoped buffer writing into `analyticsService`. Narrow it to the app's own event union in `SingletonServices` to type `record()`."
+                },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService?: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -5136,6 +5520,10 @@
                 {
                   "line": "eventHub?: EventHubService<Record<string, any>>"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "jwt?: JWTService"
                 },
@@ -5243,6 +5631,18 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analytics?: AnalyticsLog<AnalyticsEventBase>",
+                  "doc": "Request-scoped buffer writing into `analyticsService`. Narrow it to the app's own event union in `SingletonServices` to type `record()`."
+                },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService?: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -5276,6 +5676,10 @@
                 {
                   "line": "eventHub?: EventHubService<Record<string, any>>"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "jwt?: JWTService"
                 },
@@ -5352,6 +5756,18 @@
                 {
                   "line": "aiEmbedding?: AIEmbeddingService"
                 },
+                {
+                  "line": "analytics?: AnalyticsLog<AnalyticsEventBase>",
+                  "doc": "Request-scoped buffer writing into `analyticsService`. Narrow it to the app's own event union in `SingletonServices` to type `record()`."
+                },
+                {
+                  "line": "analyticsIdentity?: AnalyticsIdentityResolver",
+                  "doc": "Resolves the browser-originated half of an event's identity — vendor ids and consent — from the wire. Unset means a sink sees only what the session carries, which is enough for a product-analytics tool and not enough for an ad platform."
+                },
+                {
+                  "line": "analyticsService?: AnalyticsService",
+                  "doc": "Where product-analytics events go; unset means the logger."
+                },
                 {
                   "line": "audit?: AuditService"
                 },
@@ -5385,6 +5801,10 @@
                 {
                   "line": "eventHub?: EventHubService<Record<string, any>>"
                 },
+                {
+                  "line": "featureFlags?: FeatureFlagSource",
+                  "doc": "The global feature-flag config, read by the function runner to enforce a flag's availability. Inert when absent: a project that declares no flag carries nothing, and a `featureFlag:` with no source registered is a no-op rather than a closed door."
+                },
                 {
                   "line": "jwt?: JWTService"
                 },
@@ -5556,6 +5976,229 @@
             }
           ]
         },
+        {
+          "specifier": "#pikku/addon/analytics",
+          "name": "analytics",
+          "step": "enhance it",
+          "summary": "The events a project can measure, declared by name so the generated ingest knows what to accept. Where they go is an AnalyticsService on singleton services; what a function records into is the analytics service on the invocation.",
+          "skill": null,
+          "symbols": [
+            {
+              "name": "AnalyticsClientContext",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Its presence, not `at`, is what marks a record as relayed from a browser — a beacon is free to omit `at`.",
+              "docs": "Its presence, not `at`, is what marks a record as relayed from a browser — a\nbeacon is free to omit `at`.",
+              "members": [
+                {
+                  "line": "at?: number"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsEventBase",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "The constraint a project's declared event union is checked against.",
+              "docs": "The constraint a project's declared event union is checked against.\n\nOnly `name` is fixed, because the name is the whole of what pikku itself\nreads — everything else on an event belongs to the app and to the sinks it\nwires, and narrowing it here would make the generic useless for anyone whose\nevents carry more than a fixed set of props.",
+              "members": [
+                {
+                  "line": "name: string"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsEventDefinitions",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Events keyed by name; each value is the schema for that event's props.",
+              "docs": "Events keyed by name; each value is the schema for that event's props."
+            },
+            {
+              "name": "AnalyticsEventPropsSchema",
+              "kind": "type",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "The schema for one event's props. The generated ingest rebuilds each member of the union as `z.object(schema.shape)` so it can attach the event name, so a schema with no `shape` — a union, a primitive, a schema from a library that does not expose one — is not something an event can be declared with, and saying so here fails at the declaration rather than in generated code.",
+              "docs": "The schema for one event's props. The generated ingest rebuilds each member\nof the union as `z.object(schema.shape)` so it can attach the event name, so\na schema with no `shape` — a union, a primitive, a schema from a library\nthat does not expose one — is not something an event can be declared with,\nand saying so here fails at the declaration rather than in generated code.",
+              "members": [
+                {
+                  "line": "~standard: StandardSchemaV1.Props<unknown, unknown>",
+                  "doc": "The Standard Schema properties."
+                },
+                {
+                  "line": "shape: Record<string, unknown>"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsIdentity",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Stamped server-side from the session and never read from the request body, which is what makes an unauthenticated ingest safe to expose.",
+              "docs": "Stamped server-side from the session and never read from the request body,\nwhich is what makes an unauthenticated ingest safe to expose.",
+              "members": [
+                {
+                  "line": "anonymousId?: string",
+                  "doc": "A device-scoped id for a visitor with no session, minted by pikku rather than by a vendor. Distinct from `pikkuUserId`, which is derived from a session and is therefore absent for exactly the visitor this identifies. Without it a product-analytics sink has no honest option for anonymous traffic: keying on a shared literal collapses every visitor into one person, and dropping the event loses the whole pre-signup funnel."
+                },
+                {
+                  "line": "consent?: Record<string, boolean>",
+                  "doc": "What the visitor agreed to, keyed by purpose. A sink gated on a purpose absent here does not send. Open-ended rather than a fixed pair, because the purposes are the consent tool's vocabulary and jurisdictions do not agree on them. Undefined means the app wired no consent resolver, not that consent was refused — the gate belongs to the sink, which is where the app decides what absence means."
+                },
+                {
+                  "line": "orgId?: string"
+                },
+                {
+                  "line": "pikkuUserId?: string"
+                },
+                {
+                  "line": "userId: string | null"
+                },
+                {
+                  "line": "vendorIds?: Record<string, string>",
+                  "doc": "Identifiers a destination keys on that pikku does not mint — GA4's `client_id`, Meta's `fbp` and `fbc`, a vendor's own device id. All of them originate in the browser, and a sink that cannot produce one does not degrade, it sends nothing usable. Resolved server-side from first-party cookies on the request, never read from the event body, on the same reasoning as the rest of this object: a crafted client call must not be able to attribute an event to someone else."
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsLog",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "`services.analytics`: buffered for the invocation, flushed when it ends, always best-effort. `record` is a method rather than a property so an app can narrow `Events` in its own `SingletonServices`.",
+              "docs": "`services.analytics`: buffered for the invocation, flushed when it ends,\nalways best-effort. `record` is a method rather than a property so an app can\nnarrow `Events` in its own `SingletonServices`.",
+              "signature": "AnalyticsLog<Events>",
+              "members": [
+                {
+                  "line": "close: () => Promise<void>"
+                },
+                {
+                  "line": "flush: () => Promise<void>"
+                },
+                {
+                  "line": "record: (event: Events, client?: AnalyticsClientContext) => Promise<void>"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsRecord",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "What an event becomes once pikku has accepted it, and the only shape an {@link AnalyticsService} is ever handed.",
+              "docs": "What an event becomes once pikku has accepted it, and the only shape an\n{@link AnalyticsService} is ever handed.\n\nDistinct from {@link AnalyticsEventInput}, which is what a caller submits:\nthe identity, the trace and the origin are stamped server-side on the way\nthrough, so a sink never has to trust — or re-derive — any of them.",
+              "members": [
+                {
+                  "line": "at?: number"
+                },
+                {
+                  "line": "functionId?: string"
+                },
+                {
+                  "line": "name: string"
+                },
+                {
+                  "line": "occurredAt: string"
+                },
+                {
+                  "line": "props?: Record<string, unknown>"
+                },
+                {
+                  "line": "source: \"server\" | \"client\""
+                },
+                {
+                  "line": "traceId?: string"
+                },
+                {
+                  "line": "userIdentity: AnalyticsIdentity"
+                },
+                {
+                  "line": "wireType?: PikkuWiringTypes"
+                }
+              ]
+            },
+            {
+              "name": "AnalyticsService",
+              "kind": "interface",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Where accepted events go. Pikku validates, identifies and batches them; it does not store them.",
+              "docs": "Where accepted events go. Pikku validates, identifies and batches them; it\ndoes not store them.\n\nOne method, taking a batch, because a batch is what a destination is always\nhanded: the invocation buffers and flushes once, and a lone event is a batch\nof one. A single-event method beside it would be a second path every sink had\nto implement and every caller had to choose between.",
+              "members": [
+                {
+                  "line": "write: (batch: AnalyticsRecord[]) => Promise<void>"
+                }
+              ]
+            },
+            {
+              "name": "defineAnalyticsEvents",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Declare what a module can measure. Call it as often as suits the project; the CLI unions every declaration into the ingest schema.",
+              "docs": "Declare what a module can measure. Call it as often as suits the project; the\nCLI unions every declaration into the ingest schema.\n\nIt must stay an exported const — the schema pipeline reads the value by name.\nIt registers nothing at runtime: where events go is an `AnalyticsService` on\nsingleton services.",
+              "signature": "<const Events extends AnalyticsEventDefinitions>(events: Events) => Events"
+            },
+            {
+              "name": "flattenAnalyticsEvent",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "Removes the discriminator, so `props` is free of the series key.",
+              "docs": "Removes the discriminator, so `props` is free of the series key.",
+              "signature": "(event: AnalyticsEventBase, at?: number) => AnalyticsEventInput",
+              "members": [
+                {
+                  "line": "name: string"
+                }
+              ]
+            },
+            {
+              "name": "LoggerAnalyticsService",
+              "kind": "class",
+              "origin": {
+                "via": "core",
+                "subpath": "./analytics"
+              },
+              "summary": "What an app gets before it has chosen a store. There is deliberately no noop: a validated wire with nowhere for the events to go is indistinguishable from a broken one.",
+              "docs": "What an app gets before it has chosen a store. There is deliberately no noop:\na validated wire with nowhere for the events to go is indistinguishable from\na broken one.\n\nAt `debug` so attaching a real store does not report every event twice.",
+              "signature": "new LoggerAnalyticsService(logger: Logger)",
+              "members": [
+                {
+                  "line": "logger: any"
+                },
+                {
+                  "line": "write: (batch: AnalyticsRecord[]) => Promise<void>"
+                }
+              ]
+            }
+          ]
+        },
         {
           "specifier": "#pikku/addon/error",
           "name": "error",
@@ -5675,6 +6318,21 @@
               "signature": "new ExpectationFailedError(message?: string)",
               "status": 417
             },
+            {
+              "name": "FeatureUnavailableError",
+              "kind": "class",
+              "origin": {
+                "via": "core",
+                "subpath": "./errors"
+              },
+              "signature": "new FeatureUnavailableError(feature: string)",
+              "members": [
+                {
+                  "line": "payload: { error: \"feature_unavailable\"; feature: string; }"
+                }
+              ],
+              "status": 503
+            },
             {
               "name": "ForbiddenError",
               "kind": "class",
@@ -6944,6 +7602,20 @@
           "summary": "The scopes a caller can hold and the roles that grant them, gating a call outside the permission pool.",
           "skill": "pikku-auth",
           "symbols": [
+            {
+              "name": "defineFeatureFlags",
+              "kind": "function",
+              "origin": {
+                "via": "core",
+                "subpath": "./flag"
+              },
+              "summary": "No-op function for declaring feature flags. This exists purely for TypeScript type checking and will be tree-shaken. The CLI extracts metadata via AST parsing and generates a `FeatureFlagName` union, so `flags.calList` is a compile error rather than a silent `false`.",
+              "docs": "No-op function for declaring feature flags.\nThis exists purely for TypeScript type checking and will be tree-shaken.\nThe CLI extracts metadata via AST parsing and generates a `FeatureFlagName`\nunion, so `flags.calList` is a compile error rather than a silent `false`.\n\nThat typing is load-bearing rather than a convenience: flags fail closed, so\na typo'd flag reads `false`, hides its feature permanently, and leaves every\ntest, screenshot and gate green. An untyped key makes a missing product\nindistinguishable from a working one.\n\nRemoval is deliberately not destructive. Deleting a declaration leaves the\nrow in the store, marked undeclared and inert, until `pikku flags prune` —\nthe same additive contract `defineScope` and `defineSystemRole` have, and for\nthe same reason: a mid-deploy revocation is not something a code edit should\nbe able to cause.",
+              "signature": "(_config: CoreFeatureFlags) => void",
+              "examples": [
+                "```typescript\ndefineFeatureFlags({\n  takeInBike: {\n    description: 'Book a bike in at the counter',\n    anyOf: ['bikes:intake'],\n  },\n  aiAssistant: {\n    description: 'The assistant panel',\n    // no anyOf — the switch is the whole answer\n  },\n})\n```"
+              ]
+            },
             {
               "name": "defineScope",
               "kind": "function",
@@ -6971,6 +7643,46 @@
               "examples": [
                 "```typescript\ndefineSystemRole({\n  buyer: {\n    displayName: 'Buyer',\n    description: 'Can browse the catalogue and place orders',\n    scopes: ['catalogue:read', 'orders:create'],\n  },\n  admin: {\n    description: 'Everything',\n    scopes: ['admin'],\n  },\n})\n```"
               ]
+            },
+            {
+              "name": "FEATURE_FLAGS",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "The declared flag set, for a FeatureFlagStore to sync into its store.",
+              "docs": "The declared flag set, for a FeatureFlagStore to sync into its store.\n\nDerived from the metadata sidecar rather than inlined, so the import above\nforces tsc to emit the .json alongside this file — an addon publishes only\nits compiled output, and a host reads that .json to merge the addon's flags\ninto its own union.\n\nAdditive on removal: a deleted declaration leaves the row marked\n`declared: false` rather than switching a feature off on deploy. Use\n`pikku flags prune` to remove them.",
+              "signature": "DeclaredFlag[]"
+            },
+            {
+              "name": "FEATURE_FLAGS_FALLBACK",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "What a flag source falls back to when its backing store cannot be read: every declared flag on, no rollout, no overrides.",
+              "docs": "What a flag source falls back to when its backing store cannot be read: every\ndeclared flag on, no rollout, no overrides.\n\nFailing open is deliberate. A flag store is not an authorization boundary —\n`scopes:` is — so an unreadable config must not take the product down with\nit.",
+              "signature": "FlagConfigSnapshot"
+            },
+            {
+              "name": "FEATURE_FLAGS_META",
+              "kind": "const",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "Declared flags, keyed by name. Rendered by the console beside each switch.",
+              "docs": "Declared flags, keyed by name. Rendered by the console beside each switch.\n\nKeyed by `FeatureFlagName` so a misspelled lookup is a type error, which is\nthe whole point of generating the union. The assertion is what\n`Object.fromEntries` costs — it returns an index signature — and it is\nsound here because both this object and the union are built from\n`FEATURE_FLAGS`, so every key of the union is present.",
+              "signature": "Record<never, DeclaredFlag>"
+            },
+            {
+              "name": "FeatureFlagName",
+              "kind": "type",
+              "origin": {
+                "via": "generated"
+              },
+              "summary": "Every feature flag declared in this application.",
+              "docs": "Every feature flag declared in this application.",
+              "signature": "never"
             }
           ]
         },
@@ -7564,7 +8276,7 @@
                   "doc": "Scenarios only: runs before the scenario body, with the scenario's own signature. Throwing skips the body and fails the run, but `after` still runs."
                 },
                 {
-                  "line": "deploy?: \"auto\" | \"serverless\" | \"server\"",
+                  "line": "deploy?: \"auto\" | \"server\" | \"serverless\"",
                   "doc": "Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches."
                 },
                 {
@@ -7579,6 +8291,10 @@
                   "line": "expose?: boolean",
                   "doc": "Makes the function callable from outside as `POST /rpc/<name>`. Without a session requirement, a permission or an addon gate, that means callable by anyone."
                 },
+                {
+                  "line": "featureFlag?: undefined",
+                  "doc": "The feature this function belongs to. Singular: a function implements part of one feature, and needing two is a sign it does two things. Resolved at runtime on every call, unlike `tags:` — a flag is meant to be flipped in a running system, so nothing here filters a build. Checked for AVAILABILITY only, never capability — if the runner enforced the capability half a flag would become a second authorization path with OR-ish semantics against `scopes:`. Authorization is always `scopes:`. Runs after `scopes:` so an unauthorized caller gets a 403 whether or not the feature is up, rather than learning that it exists and is off."
+                },
                 {
                   "line": "func: PikkuFunctionScenario<In, Out, Out>",
                   "doc": "The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away."