@pikku/core 0.12.92 → 0.12.94

package/src/wirings/credential/credential.types.ts

@@ -1,12 +1,19 @@
 import type { OAuth2CredentialConfig } from '../secret/secret.types.js'
 
 export type CoreCredential<T = unknown> = {
+  /** How the credential is asked for in code. Generated into `CredentialsMap`, so it is what `credentials.get` autocompletes. */
   name: string
+  /** The name shown to whoever has to supply the value, who is often not the person who wrote this. */
   displayName: string
+  /** What the credential is for and where to obtain one. */
   description?: string
+  /** `singleton` is one value for the whole deployment; `wire` is one per user, supplied by them and stored against their account. */
   type: 'singleton' | 'wire'
+  /** The shape of the value, validated when it is supplied rather than when it is first used. */
   schema: T
+  /** Where to go to create one, shown next to the field asking for it. */
   docsUrl?: string
+  /** Makes this an OAuth connection rather than a value pasted in: the user is sent to the provider and the tokens are stored for them. */
   oauth2?: OAuth2CredentialConfig & {
     appCredentialSecretId: string
   }

package/src/wirings/gateway/gateway-authorization.test.ts

@@ -280,7 +280,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/declared-session')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(
         calls,
         [],
@@ -339,7 +339,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/gw-auth')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 
@@ -365,7 +365,7 @@ describe('gateway handler authorization', () => {
 
       const response = await postMessage('/webhooks/handler-auth')
 
-      assert.equal(response.status, 403)
+      assert.equal(response.status, 401)
       assert.deepEqual(calls, [], 'auth: true must require a session')
     })
 

package/src/wirings/gateway/gateway.types.ts

@@ -17,6 +17,10 @@ export interface GatewayAttachment {
   filename?: string
 }
 
+/**
+ * One message arriving from a gateway, normalised: who sent it, in which
+ * conversation, and what they said.
+ */
 export interface GatewayInboundMessage {
   /** Platform-specific: a phone number, a Slack user id, and so on. */
   senderId: string
@@ -26,15 +30,27 @@ export interface GatewayInboundMessage {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * One message to send back through a gateway — plain text, or the provider's
+ * own rich content.
+ */
 export interface GatewayOutboundMessage {
   text?: string
   richContent?: Record<string, unknown>
   attachments?: GatewayAttachment[]
 }
 
+/**
+ * What a gateway's `verifyWebhook` returns — verified, with the response the
+ * provider expects back, or not.
+ */
 export type WebhookVerificationResult =
   { verified: true; response: unknown } | { verified: false }
 
+/**
+ * What a gateway integration implements: parse an incoming event into a
+ * message, send one back, and open and close the connection.
+ */
 export interface GatewayAdapter {
   name: string
   /** Return null to ignore the event, e.g. a delivery receipt. */
@@ -70,14 +86,21 @@ export type CoreGateway<
 > = Partial<
   Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>
 > & {
+  /** Unique across the project. It is how the gateway is addressed in `pikku meta` and in logs. */
   name: string
+  /** How the platform reaches us: a `webhook` it posts to, a `websocket` it holds open, or a `listener` we open outward. */
   type: GatewayTransportType
   /** Required for 'webhook' and 'websocket'; unused for 'listener'. */
   route?: string
+  /** Which service this speaks to — slack, whatsapp, discord. It selects the adapter's dialect, not the transport. */
   platform?: string
+  /** Translates between the platform's message format and pikku's. A factory is called with services, for an adapter that needs a token or a client. */
   adapter: GatewayAdapter | GatewayAdapterFactory
+  /** The function to run per inbound message. It receives the normalised message, not the platform's raw payload. */
   func: PikkuFunctionConfig
+  /** Wraps every inbound message: signature verification, tracing, rate limiting. */
   middleware?: CorePikkuMiddlewareGroup<any, any>
+  /** Filters this gateway in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
   /** Unset lets the handler's own `auth` govern; gateway handlers are sessionless by default. */
   auth?: boolean

package/src/wirings/http/http-runner-addon-ref.test.ts

@@ -233,6 +233,6 @@ describe('http routes wired with ref() to an addon function', () => {
 
     const response = await fetch(new ParamsRequest('/addon/greet', 'get'))
 
-    assert.strictEqual(response.status, 403)
+    assert.strictEqual(response.status, 401)
   })
 })

package/src/wirings/http/http.types.ts

@@ -48,15 +48,19 @@ export type HTTPHeadersSchema = StandardSchemaV1<
 >
 
 export type HTTPRouteBaseConfig = {
+  /** How the body is serialised. Defaults to JSON; `xml` is for routes a caller you do not control insists on. */
   contentType?: 'xml' | 'json'
+  /** Seconds before the request is abandoned. Work that can outlast a request should be dispatched instead, not given a longer timeout. */
   timeout?: number
+  /** Filters this route in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** A schema the request headers are validated against, so a missing or malformed header fails before the function body runs. */
   headers?: HTTPHeadersSchema
 }
 
 export type CoreHTTPFunction = HTTPRouteBaseConfig & {
   route: string
-  eventChannel?: false
+  /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
   returnsJSON?: false
 }
 
@@ -70,100 +74,121 @@ export type PikkuQuery<T = Record<string, string | undefined>> = Record<
   string | T | null | Array<T | null>
 >
 
-export type CoreHTTPFunctionWiring<
+/**
+ * The keys every HTTP wiring takes, whatever it is wired to. The three that
+ * are not here — `method`, `auth` and `func` — are correlated rather than
+ * independent, and live in the unions below.
+ */
+type HTTPWiringShared<
+  R extends string,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
+> = CoreHTTPFunction & {
+  /**
+   * The path this wiring answers on. `:name` marks a parameter, and every
+   * parameter in the path must be a key of the function's input schema —
+   * a mismatch is a compile error rather than a 404 at runtime.
+   */
+  route: R
+  /** Wraps every request to this route: auth, tracing, rate limiting. Runs before the permissions on `func`. */
+  middleware?: PikkuMiddleware[]
+}
+
+/**
+ * `auth` decides which kind of function this route can point at, so the two
+ * travel together: a route that requires a session gets a function that is
+ * handed one, and an open route gets a sessionless function that has none to
+ * read. Splitting them would let a function ask for a session the route never
+ * establishes.
+ */
+type HTTPWiringAuth<
   In,
   Out,
-  R extends string,
-  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> =
-    CorePikkuFunction<In, Out>,
+  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any>,
   PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
     In,
     Out,
     any,
     any,
     any
-  > = CorePikkuFunctionSessionless<In, Out>,
-  PikkuPermission extends CorePikkuPermission<In, any, any> =
-    CorePikkuPermission<In, any, any>,
-  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
-    any,
-    any
   >,
+  PikkuPermission extends CorePikkuPermission<In, any, any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any>,
 > =
-  | (CoreHTTPFunction & {
-      route: R
-      method: HTTPMethod
+  | {
+      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+      auth?: true
+      /** The function to run. It is handed the session this route required. */
       func: CorePikkuFunctionConfig<
         PikkuFunction,
         PikkuPermission,
         PikkuMiddleware
       >
-      auth?: true
-      middleware?: PikkuMiddleware[]
-      sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: HTTPMethod
+    }
+  | {
+      /** Whether reaching this route requires a session. Defaults to true — a route is closed unless it says otherwise. */
+      auth?: false
+      /** On an open route there is no session, so this must be a sessionless function. */
       func: CorePikkuFunctionConfig<
         PikkuFunctionSessionless,
         PikkuPermission,
         PikkuMiddleware
       >
-      auth?: false
-      middleware?: PikkuMiddleware[]
+    }
+
+/**
+ * `sse` and `query` are each valid on one method only, so the method carries
+ * them: streaming is a GET, and naming which input keys arrive in the query
+ * string is only a question on a POST, where the rest of the input is a body.
+ */
+type HTTPWiringMethod<In> =
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
+      method: HTTPMethod
       sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
+    }
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
       method: 'get'
-      func: CorePikkuFunctionConfig<
-        PikkuFunction,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: true
-      middleware?: PikkuMiddleware[]
-      sse?: boolean
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: 'get'
-      func: CorePikkuFunctionConfig<
-        PikkuFunctionSessionless,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: false
-      middleware?: PikkuMiddleware[]
+      /** Streams the response as server-sent events instead of returning it once. GET only. */
       sse?: boolean
-    })
-  | (CoreHTTPFunction & {
-      route: R
+    }
+  | {
+      /** The HTTP method. A route and method together address one wiring. */
       method: 'post'
-      func: CorePikkuFunctionConfig<
-        PikkuFunction,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: true
-      middleware?: PikkuMiddleware[]
+      /** Input keys that arrive in the query string rather than the body. POST only, where the body is the default home for input. */
       query?: Array<keyof In>
       sse?: undefined
-    })
-  | (CoreHTTPFunction & {
-      route: R
-      method: 'post'
-      func: CorePikkuFunctionConfig<
-        PikkuFunctionSessionless,
-        PikkuPermission,
-        PikkuMiddleware
-      >
-      auth?: false
-      middleware?: PikkuMiddleware[]
-      query?: Array<keyof In>
-      sse?: undefined
-    })
+    }
+
+export type CoreHTTPFunctionWiring<
+  In,
+  Out,
+  R extends string,
+  PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> =
+    CorePikkuFunction<In, Out>,
+  PikkuFunctionSessionless extends CorePikkuFunctionSessionless<
+    In,
+    Out,
+    any,
+    any,
+    any
+  > = CorePikkuFunctionSessionless<In, Out>,
+  PikkuPermission extends CorePikkuPermission<In, any, any> =
+    CorePikkuPermission<In, any, any>,
+  PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<
+    any,
+    any
+  >,
+> = HTTPWiringShared<R, PikkuMiddleware> &
+  HTTPWiringAuth<
+    In,
+    Out,
+    PikkuFunction,
+    PikkuFunctionSessionless,
+    PikkuPermission,
+    PikkuMiddleware
+  > &
+  HTTPWiringMethod<In>
 
 export type HTTPFunctionMetaInputTypes = {
   params?: string

package/src/wirings/mcp/mcp.types.ts

@@ -76,16 +76,27 @@ export type CoreMCPResource<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the client addresses this resource. `{name}` marks a parameter, and every parameter must be a key of the function's input schema. */
   uri: string
+  /** The name a human sees in a client's resource list. */
   title: string
+  /** What the resource holds, written for the model deciding whether to read it. */
   description: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The media type of what the function returns, so the client knows whether it is text, JSON or an image. */
   mimeType?: string
+  /** Size in bytes, where it is known ahead of the read. A client uses it to decide whether to fetch at all. */
   size?: number
+  /** Whether the function returns the content in chunks rather than at once. */
   streaming?: boolean
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 
@@ -96,14 +107,23 @@ export type CoreMCPTool<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the model calls this tool. It is the tool's identity, so renaming it breaks any client that already knows it. */
   name: string
+  /** The name a human sees, where the calling `name` is not readable. */
   title?: string
+  /** What the tool does and when to reach for it. This is what the model decides on, so it earns more care than the rest of this object. */
   description?: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Whether the function returns its result in chunks rather than at once. */
   streaming?: boolean
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 
@@ -114,12 +134,19 @@ export type CoreMCPPrompt<
   PikkuPermission = CorePikkuPermission<any, any>,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** How the client asks for this prompt. */
   name: string
+  /** What the prompt is for, written for the human picking it out of a list. */
   description: string
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** Names of error classes this may throw, so the client is told which failures are its own fault. */
   errors?: string[]
+  /** The function to run. It is sessionless: an MCP client is not a logged-in user. */
   func: PikkuFunctionConfig
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every call: tracing, rate limiting, whatever the transport does not do. */
   middleware?: PikkuMiddleware[]
 }
 

package/src/wirings/persona/index.ts

@@ -16,6 +16,11 @@ export type {
   PersonaEnvironmentSubject,
 } from './persona-environments.js'
 export { personaEmail, personaEmails } from './persona-email.js'
+export {
+  APP_SCOPE_ROOT,
+  appScopeId,
+  buildAppScopeDefinition,
+} from './persona-app-scopes.js'
 export type {
   MailboxAllowlist,
   PersonaMailbox,

package/src/wirings/persona/persona-app-scopes.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+import {
+  appScopeId,
+  buildAppScopeDefinition,
+  declaredApps,
+} from './persona-app-scopes.js'
+
+const persona = (id: string, app?: string) =>
+  ({ id, name: id, roles: [], goals: [], tags: [], runnable: true, app }) as any
+
+describe('declaredApps', () => {
+  test('deduplicates and sorts the apps the personas name', () => {
+    assert.deepEqual(
+      declaredApps([
+        persona('a', 'staff'),
+        persona('b', 'portal'),
+        persona('c', 'staff'),
+      ]),
+      ['portal', 'staff']
+    )
+  })
+
+  test('ignores personas that name no app', () => {
+    assert.deepEqual(declaredApps([persona('a'), persona('b', '')]), [])
+  })
+})
+
+describe('buildAppScopeDefinition', () => {
+  test('renders one grantable child per app under the app root', () => {
+    const definition = buildAppScopeDefinition([
+      persona('a', 'staff'),
+      persona('b', 'portal'),
+    ])
+
+    assert.equal(definition?.name, 'app')
+    assert.deepEqual(Object.keys(definition?.scopes ?? {}).sort(), [
+      'portal',
+      'staff',
+    ])
+    assert.equal(appScopeId('staff'), 'app:staff')
+  })
+
+  test('is null for a single-frontend product', () => {
+    assert.equal(buildAppScopeDefinition([persona('a')]), null)
+  })
+})

package/src/wirings/persona/persona-app-scopes.ts

@@ -0,0 +1,74 @@
+import type { ScopeDefinitionMeta, ScopeNodeMeta } from '../scope/scope.types.js'
+import type { PersonaMeta } from './persona.types.js'
+
+/**
+ * The root every app grant hangs off. One segment, so a grant of `app` alone
+ * means "may use all of them" under the same parent-grant rule the admin tree
+ * relies on — which is what a support operator or an internal tool wants, and
+ * what a per-app boolean column could never express.
+ */
+export const APP_SCOPE_ROOT = 'app'
+
+/** `app:staff` for `staff`. */
+export const appScopeId = (app: string) => `${APP_SCOPE_ROOT}:${app}`
+
+/**
+ * The apps named across the declared personas, sorted and deduplicated.
+ *
+ * The personas *are* the registry. There is no separate list of apps to keep in
+ * step, because a frontend nobody signs into is not a thing the auth layer has
+ * an opinion about — and the moment somebody does sign into it, they are a
+ * persona and they name it.
+ */
+export const declaredApps = (personas: PersonaMeta[]): string[] =>
+  [
+    ...new Set(
+      personas
+        .map((persona) => persona.app)
+        .filter((app): app is string => typeof app === 'string' && app !== '')
+    ),
+  ].sort()
+
+/**
+ * The `app` scope tree, synthesised from the personas that name an app.
+ *
+ * Which frontend a person may sign into is a different question from what they
+ * may do once inside it, but it is the same *kind* of question — a grant that
+ * an admin can make and revoke at runtime, that resolves at the session
+ * boundary, and that a restricted API key can decline to inherit. So it is
+ * carried as a scope rather than a `can_access_<app>` column: no migration per
+ * app, one query for "which apps may this user reach", and no second
+ * authorization mechanism to keep honest.
+ *
+ * Synthesised rather than written by hand because the declaration already
+ * exists. Asking an app to also spell out `defineScope({ app: { staff: {} } })`
+ * beside its personas invites the two to drift, and the failure that produces —
+ * a persona provisioned with a grant the vocabulary no longer declares — is one
+ * `pikku scopes prune` away from silently revoking sign-in.
+ *
+ * Null when no persona names an app, which is the single-frontend case: nothing
+ * to declare, and no empty root cluttering the console's grant list.
+ */
+export const buildAppScopeDefinition = (
+  personas: PersonaMeta[]
+): ScopeDefinitionMeta | null => {
+  const apps = declaredApps(personas)
+  if (apps.length === 0) {
+    return null
+  }
+
+  const scopes: Record<string, ScopeNodeMeta> = {}
+  for (const app of apps) {
+    scopes[app] = {
+      displayName: app,
+      description: `May sign in to the ${app} app`,
+    }
+  }
+
+  return {
+    name: APP_SCOPE_ROOT,
+    displayName: 'Apps',
+    description: 'Which frontend a person may sign in to',
+    scopes,
+  }
+}

package/src/wirings/queue/queue.types.ts

@@ -135,11 +135,17 @@ export type CoreQueueWorker<
   PikkuFunctionConfig extends CorePikkuFunctionConfig<any, any, any> =
     CorePikkuFunctionConfig<any, any, any>,
 > = {
+  /** The queue this worker consumes. Whoever enqueues a job names the same string, so it is the contract between producer and consumer. */
   name: string
+  /** The function to run per job. Its `input` schema is the job payload's schema — a job that does not match is rejected before the body runs. */
   func: PikkuFunctionConfig
+  /** Concurrency, retry and backoff, passed through to the queue service backing this worker. Defaults come from the service, not from here. */
   config?: PikkuWorkerConfig
+  /** Names of error classes that mean the job is bad rather than the run — thrown, they fail the job permanently instead of being retried. */
   errors?: string[]
+  /** Filters this worker in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every job. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
   middleware?: PikkuFunctionConfig['middleware']
 }
 

package/src/wirings/scheduler/scheduler.types.ts

@@ -21,10 +21,15 @@ export type CoreScheduledTask<
   >,
   PikkuMiddleware = CorePikkuMiddleware<any>,
 > = {
+  /** Unique across the project. It is how the task is addressed in logs, in `pikku meta`, and by a scheduler service asked to run it now. */
   name: string
+  /** A five-field cron expression: minute, hour, day of month, month, day of week. `0 9 * * 1` is 09:00 every Monday. Interpreted in the deployment's timezone, not the author's. */
   schedule: string
+  /** The function to run. It receives no session and no input: a scheduled task has no caller, so it must be sessionless. */
   func: PikkuFunctionConfig
+  /** Filters this task in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** Wraps every execution. There is no request to read from, so this is for tracing, locking and teardown rather than auth. */
   middleware?: PikkuMiddleware[]
 }
 

package/src/wirings/secret/secret.types.ts

@@ -4,21 +4,9 @@ export type CoreSecret<T = unknown> = {
   description?: string
   secretId: string
   schema: T
-  /**
-   * A secret is REQUIRED by default because `getSecret` throws when the value is
-   * missing — a deploy without it is a runtime failure waiting to happen, so the
-   * deploy gate refuses it. Mark a secret `optional` when absence is a supported
-   * state the app handles (a feature that simply stays off): the generated map
-   * emits it as an optional property and `getSecret` resolves `undefined`
-   * instead of throwing.
-   */
+  /** Required by default: this says absence is a supported state, and `getSecret` resolves `undefined` rather than throwing. */
   optional?: boolean
-  /**
-   * Where a user goes to obtain this value — a provider's API-key page, a setup
-   * guide, an internal runbook. Consoles and deploy UIs surface it beside a
-   * missing value. The same field on every credential/variable definition means
-   * the same thing.
-   */
+  /** Where a user goes to obtain this value, surfaced beside a missing one. */
   docsUrl?: string
   /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
   rotationPeriod?: string
@@ -64,4 +52,11 @@ export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>
 
 export type SecretDefinitions = SecretDefinitionMeta[]
 
+/**
+ * Declares a secret this project needs, with the shape of its value. The CLI
+ * collects every declaration into `CredentialsMap`, which is what makes
+ * `secrets.getSecret('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: secrets
+ */
 export const defineSecret = <T>(_config: CoreSecret<T>): void => {}

package/src/wirings/trigger/trigger.types.ts

@@ -72,11 +72,14 @@ export const pikkuTriggerFunc = <
 }
 
 export interface CoreTrigger<PikkuFunctionConfig = any> {
+  /** What a `wireTriggerSource` points at to fire this trigger. It is the contract between the two, so both must spell it the same. */
   name: string
+  /** The function to run each time the trigger fires. */
   func: PikkuFunctionConfig
+  /** What firing this trigger means, for whoever is reading the wiring rather than writing it. */
   description?: string
+  /** Filters this trigger in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
-  graph?: true
 }
 
 export interface TriggerInstance {

package/src/wirings/variable/variable.types.ts

@@ -1,23 +1,17 @@
 export type CoreVariable<T = unknown> = {
+  /** How the variable is asked for in code. Generated into `VariablesMap`, so it is what `variables.get` autocompletes. */
   name: string
+  /** The name shown to whoever configures the deployment. */
   displayName: string
+  /** What the value does, for the person setting it rather than the one reading it. */
   description?: string
+  /** The environment variable this reads, which is the name that has to exist on the host. */
   variableId: string
+  /** The shape of the value. It arrives as a string, so this is also what parses it. */
   schema: T
-  /**
-   * A variable is REQUIRED by default, and marking it `optional` is how a
-   * declaration says its absence is a supported state. Same flag, same
-   * polarity and same meaning as `CoreSecret.optional` — one word to learn
-   * rather than two with opposite senses.
-   *
-   * Defaulting to required rather than following `variables.get`'s
-   * `T | undefined` return is deliberate. That signature describes what a
-   * caller must HANDLE, not whether a deployment is correct without the value:
-   * an undefined feature flag is fine, an undefined API base URL is an outage
-   * that the type system cannot tell apart. Declaring the difference is the
-   * point of the flag, and the safe default for an undeclared one is to ask.
-   */
+  /** Required by default: this says the deployment is still correct without it. */
   optional?: boolean
+  /** Where to go to work out what to set this to. */
   docsUrl?: string
 }
 
@@ -36,4 +30,11 @@ export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>
 
 export type VariableDefinitions = VariableDefinitionMeta[]
 
+/**
+ * Declares an environment variable this project needs, with the shape of its
+ * value. The CLI collects every declaration into `VariablesMap`, which is what
+ * makes `variables.get('NAME')` return the right type instead of `unknown`.
+ *
+ * @example snippet: variables
+ */
 export const defineVariable = <T>(_config: CoreVariable<T>): void => {}