@pikku/core 0.12.91 → 0.12.93

package/src/function/functions.types.ts

@@ -193,30 +193,38 @@ export type CorePikkuFunctionConfig<
   OutputSchema extends StandardSchemaV1 | undefined = undefined,
   Scope extends string = string,
 > = {
+  /** A human name for this function, shown wherever it is listed rather than called. */
   title?: string
+  /** What the function does. An agent choosing between tools reads this, so it is worth more care than a comment would be. */
   description?: string
   /** Explicit logical name override; lets multiple exports share a versioned base */
   override?: string
+  /** Which version of this contract this export is. Two exports sharing an `override` and differing here are the same function at two versions. */
   version?: number
+  /** Filters this function in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** 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. */
   expose?: boolean
   /**
-   * The permission check for this function lives in its body — verifying a
-   * signed token, checking a webhook signature, matching an invite code — so
-   * it is not open despite declaring no session, scope or permission.
-   *
-   * A last resort. Prefer `permissions`, which are declared, inspectable, and
-   * reusable; reach for this only when the check cannot be expressed as one.
-   *
-   * Purely declarative — it grants nothing, and asserting it falsely disables
-   * the audit that would have caught the mistake. Requires
-   * `allow.permissionsInBody` in `pikku.config.json`.
+   * Declares that the body does its own permission check, so the function is
+   * not open despite naming no session, scope or permission. It grants
+   * nothing — asserting it falsely just disables the audit that would have
+   * caught the mistake. Requires `allow.permissionsInBody` in the config.
    */
   permissionsInBody?: boolean
+  /** Publishes the function in this package's remote surface, which is what a `wireRemoteAddon` consumer gets a typed client for. */
   remote?: boolean
+  /** Offers the function to MCP clients as a tool, without a separate `wireMCPTool`. */
   mcp?: boolean
+  /**
+   * Declares that the function only reads. It is enforced rather than
+   * decorative: a read-only session is refused any function without it, and an
+   * agent may call one without asking permission first.
+   */
   readonly?: boolean
+  /** Where this function is deployed when the build can go either way. `auto` lets the analyser decide from what the function touches. */
   deploy?: 'serverless' | 'server' | 'auto'
+  /** Under an agent's `explicit` approval policy, calling this pauses for a human to approve it. */
   approvalRequired?: boolean
   /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. Defaults to false (inline). */
   workflowQueued?: boolean
@@ -230,18 +238,21 @@ export type CorePikkuFunctionConfig<
    * and report how much of the flow each surface actually covers.
    */
   surfaces?: ScenarioSurface[]
+  /** Scenario steps only, and set by the definer rather than by hand: this step needs a persona, so the runner injects `wire.actor`. */
+  requiresActor?: boolean
   /**
-   * Scenario steps only: this step is driven by a persona, so the runner injects
-   * `wire.actor` and refuses to dispatch it without one. Set by the definer from
-   * a `browser` binding or an explicit `actor: true`, never written by hand.
+   * Records every call in the audit log. `transactional` durability writes the
+   * entry in the same transaction as the work, so the two cannot disagree;
+   * `best-effort` does not hold the request up for it.
    */
-  requiresActor?: boolean
   audit?:
     | boolean
     | {
         durability?: 'best-effort' | 'transactional'
       }
+  /** Builds the sentence a human is shown when asked to approve a call, from that call's own input. */
   approvalDescription?: any
+  /** The body. Its first parameter is the services it needs, destructured inline so the build can tree-shake the rest away. */
   func: PikkuFunction
   /**
    * Scenarios only: runs before the scenario body, with the scenario's own
@@ -260,20 +271,21 @@ export type CorePikkuFunctionConfig<
    * as skipped rather than quietly omitted; naming it in `--flows` runs it.
    */
   skip?: string
+  /** Whether calling this requires a session, wherever it is wired. A wiring can be more permissive than the function, never less. */
   auth?: boolean
-  /**
-   * Scopes the session must hold; all are required (AND) and checked before
-   * `permissions`, which OR together — a scope can only narrow access.
-   * Narrowed to the generated `ScopeId` union, so an undeclared scope is a
-   * compile error. Requires a session — see
-   * {@link CorePikkuSessionlessFunctionConfig}.
-   */
+  /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
   scopes?: Scope[]
+  /** Checks that run before the body. Grouped names OR together, so any one passing admits the caller; use `scopes` to require rather than offer. */
   permissions?: CorePermissionGroup<PikkuPermission>
+  /** Wraps this function wherever it is called from, unlike wiring middleware which only wraps one route into it. */
   middleware?: PikkuMiddleware[]
+  /** The input schema, which is also the input type — there is no separate generic to keep in step with it. */
   input?: InputSchema
+  /** The output schema, which is also the return type. Naming a type here instead is what produces PKU463. */
   output?: OutputSchema
+  /** Presentation for this function as a node in a workflow graph. */
   node?: CoreNodeConfig
+  /** Error classes this may throw, so each one's registered HTTP status is used instead of a 500. */
   errors?: Array<typeof PikkuError>
 }
 

package/src/middleware/auth-apikey.ts

@@ -2,7 +2,14 @@ import {
   pikkuMiddleware,
   pikkuMiddlewareFactory,
 } from './middleware-factories.js'
+/**
+ * Reads an API key from the request and JWT-decodes it into a session. Leaves
+ * an existing session alone, so it composes with other auth middleware.
+ *
+ * @example snippet: machineAuth
+ */
 export const authAPIKey = pikkuMiddlewareFactory<{
+  /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
   source: 'header' | 'query' | 'all'
 }>(({ source }) =>
   pikkuMiddleware(

package/src/middleware/auth-bearer.ts

@@ -17,8 +17,11 @@ const constantTimeEqual = (a: string, b: string): boolean => {
  * Validates a bearer token: JWT-decoded by default, or compared in constant
  * time against a static `value` or a `secretId` resolved through the secrets
  * service per request.
+ *
+ * @example snippet: machineAuth
  */
 export const authBearer = pikkuMiddlewareFactory<{
+  /** Omit to JWT-decode the token. Set it to accept one fixed token instead, matched in constant time. */
   token?:
     | {
         value: string

package/src/middleware/auth-cookie.ts

@@ -6,10 +6,6 @@ import {
 import type { RelativeTimeInput } from '../time-utils.js'
 import { getRelativeTimeOffsetFromNow } from '../time-utils.js'
 
-/**
- * Reads a JWT session from a cookie, and re-issues the cookie after the
- * request whenever the session changed (e.g. after login).
- */
 /** Standard JWT registered claims — present on a token even with no session. */
 const JWT_REGISTERED_CLAIMS = new Set([
   'iat',
@@ -31,9 +27,18 @@ const hasSessionIdentity = (session: unknown): boolean => {
   return Object.keys(session).some((key) => !JWT_REGISTERED_CLAIMS.has(key))
 }
 
+/**
+ * Reads a JWT session from a cookie, and re-issues the cookie after the
+ * request whenever the session changed (e.g. after login).
+ *
+ * @example snippet: machineAuth
+ */
 export const authCookie = pikkuMiddlewareFactory<{
+  /** Cookie name to read and write. */
   name: string
+  /** Serialize options merged over the defaults, which are httpOnly and sameSite lax. */
   options: SerializeOptions
+  /** How long the re-issued cookie lives, as a relative time such as `'7d'`. */
   expiresIn: RelativeTimeInput
 }>(({ name, options, expiresIn }) => {
   const mergedOptions: SerializeOptions = {

package/src/middleware/cors.ts

@@ -8,13 +8,21 @@ import {
  * matching origin and otherwise sends no `Access-Control-Allow-Origin` at all,
  * so the browser reports "origin not allowed" rather than an origin mismatch
  * against whichever entry happened to be first.
+ *
+ * @example snippet: corsMiddleware
  */
 export const cors = pikkuMiddlewareFactory<{
+  /** Which origins may call. Defaults to `*`, which the browser rejects alongside `credentials: true` — name the origins instead. */
   origin?: string | string[] | true
+  /** Methods a cross-origin caller may use. Defaults to the common six; a method missing here fails preflight rather than the request. */
   methods?: string[]
+  /** Request headers a caller may send. Defaults to content-type, authorization and x-api-key. */
   headers?: string[]
+  /** Response headers the browser will let the caller's JavaScript read. Everything else is hidden from it even on a 200. */
   exposeHeaders?: string[]
+  /** Whether cookies and auth headers ride along. Requires a named origin, never `*`. */
   credentials?: boolean
+  /** Seconds the browser may cache this preflight. Defaults to a day. */
   maxAge?: number
 }>(
   ({

package/src/middleware/middleware-factories.ts

@@ -39,6 +39,10 @@ export const pikkuMiddlewareFactory = <In = any>(
   return factory
 }
 
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export const pikkuChannelMiddleware = <
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,
   Event = unknown,
@@ -48,12 +52,22 @@ export const pikkuChannelMiddleware = <
   return middleware
 }
 
+/**
+ * Declares channel middleware that takes options, so one definition can be
+ * wired several times with different configuration.
+ *
+ * @example snippet: channelMiddlewareFactory
+ */
 export const pikkuChannelMiddlewareFactory = <In = any>(
   factory: CorePikkuChannelMiddlewareFactory<In>
 ): CorePikkuChannelMiddlewareFactory<In> => {
   return factory
 }
 
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ */
 export const pikkuAgentMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   SingletonServices extends CoreSingletonServices = CoreSingletonServices,

package/src/services/local-secrets.test.ts

@@ -22,7 +22,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 
@@ -44,7 +44,7 @@ describe('LocalSecretService', () => {
     const vars = new LocalVariablesService({})
     const service = new LocalSecretService(vars)
     await assert.rejects(() => service.getSecret('MISSING'), {
-      message: 'Requested secret not found',
+      message: 'Requested secret not found: MISSING',
     })
   })
 

package/src/services/local-secrets.ts

@@ -32,7 +32,7 @@ export class LocalSecretService implements SecretService {
     if (value) {
       return createSecretValue(this.parseSecret<T>(value))
     }
-    throw new Error('Requested secret not found')
+    throw new Error(`Requested secret not found: ${key}`)
   }
 
   public async setSecret(key: string, value: unknown): Promise<void> {

package/src/services/persona-sign-in.test.ts

@@ -8,8 +8,9 @@ import { establishOperatorSession } from './persona-sign-in.js'
 const OPERATOR_TOKEN = 'operator.jwt.token'
 
 /**
- * Minimal deployed stage: the fabric plugin's sign-in, the admin plugin's
- * user endpoints, and an RPC route that reports back who it was addressed as.
+ * Minimal deployed stage: the fabric plugin's sign-in, which resolves the
+ * account to act as in the same request, and an RPC route that reports back who
+ * it was addressed as.
  */
 const startStage = async (seeded: Array<{ id: string; email: string }>) => {
   const users = [...seeded]
@@ -28,38 +29,30 @@ const startStage = async (seeded: Array<{ id: string; email: string }>) => {
           res.writeHead(401).end(JSON.stringify({ message: 'bad token' }))
           return
         }
-        res.setHeader('set-cookie', ['session=operator; Path=/; HttpOnly'])
-        res.writeHead(200).end(JSON.stringify({ token: 'operator' }))
-        return
-      }
-
-      // The admin plugin refuses an unauthenticated caller, and saying so here
-      // is the point: a handshake that dropped the operator session between
-      // sign-in and lookup would otherwise pass this stage happily.
-      if (url.pathname.startsWith('/api/auth/admin/')) {
-        if (!/(^|;\s*)session=operator(;|$)/.test(req.headers.cookie ?? '')) {
-          res.writeHead(401).end(JSON.stringify({ message: 'no session' }))
-          return
+        let actAs: { userId: string } | undefined
+        if (body.actAs) {
+          let user = users.find((u) => u.email === body.actAs.email)
+          if (!user) {
+            if (!body.actAs.create) {
+              res
+                .writeHead(404)
+                .end(
+                  JSON.stringify({
+                    message: `No account on this stage for ${body.actAs.email}`,
+                  })
+                )
+              return
+            }
+            created++
+            user = { id: `made-${created}`, email: body.actAs.email }
+            users.push(user)
+          }
+          actAs = { userId: user.id }
         }
-      }
-
-      if (url.pathname === '/api/auth/admin/list-users') {
-        const wanted = url.searchParams.get('filterValue')
-        res
-          .writeHead(200, { 'content-type': 'application/json' })
-          .end(
-            JSON.stringify({ users: users.filter((u) => u.email === wanted) })
-          )
-        return
-      }
-
-      if (url.pathname === '/api/auth/admin/create-user') {
-        created++
-        const user = { id: `made-${created}`, email: body.email }
-        users.push(user)
+        res.setHeader('set-cookie', ['session=operator; Path=/; HttpOnly'])
         res
           .writeHead(200, { 'content-type': 'application/json' })
-          .end(JSON.stringify({ user, sawPassword: Boolean(body.password) }))
+          .end(JSON.stringify({ token: 'operator', actAs }))
         return
       }
 
@@ -134,7 +127,7 @@ describe('operator persona sign-in', () => {
 
     await assert.rejects(
       () => personas.customer!.invoke('whoami', {}),
-      /no account on the target for persona 'customer'/
+      /operator sign-in failed for 'customer' \(404\)/
     )
     assert.equal(stage.createdCount, 0)
   })
@@ -178,12 +171,13 @@ describe('operator persona sign-in', () => {
     assert.equal(minted, 1)
   })
 
-  test('carries the operator session into the admin lookup', async () => {
+  test('resolves the account to act as without a second request', async () => {
     const stage = await startStage([{ id: 'user-9', email: 'susan@acme.test' }])
     servers.push(stage.server)
 
     // Plain fetch keeps no cookies, which is the browser provider's situation:
-    // it plants them on a Playwright context only once this has returned.
+    // it plants them on a Playwright context only once this has returned. The
+    // handshake must not need a session of its own to resolve the persona.
     const { userId } = await establishOperatorSession(
       fetch,
       stage.apiUrl,

package/src/services/persona-sign-in.ts

@@ -99,17 +99,10 @@ export interface OperatorSignInOptions {
    * for. Turn it on for throwaway stages.
    */
   createMissing?: boolean
-  /** Admin endpoint prefix under apiUrl. Default `/auth/admin`. */
-  adminPath?: string
   /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
   signInPath?: string
 }
 
-interface AdminUser {
-  id?: unknown
-  email?: unknown
-}
-
 /** What an operator handshake yields: the session, and who to act as. */
 export interface OperatorSessionResult {
   /** `Set-Cookie` values the operator sign-in returned. */
@@ -142,7 +135,15 @@ export const establishOperatorSession = async (
   const res = await fetchImpl(`${apiUrl}${signInPath}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json', ...extraHeaders },
-    body: JSON.stringify({ token }),
+    body: JSON.stringify({
+      token,
+      actAs: {
+        email: persona.email,
+        name: persona.name,
+        create: options.createMissing ?? false,
+        ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+      },
+    }),
   })
   if (!res.ok) {
     throw await failed('operator sign-in', persona.id, res)
@@ -154,90 +155,17 @@ export const establishOperatorSession = async (
     )
   }
 
-  // The lookup runs on the session this handshake just established, and a
-  // plain `fetch` keeps no cookies — the browser path in particular hands the
-  // jar's contents to Playwright only after this returns. Forwarding them
-  // explicitly is what keeps the admin calls authenticated for every caller.
-  const session = setCookies
-    .map((raw) => raw.split(';')[0])
-    .filter((pair): pair is string => Boolean(pair))
-    .join('; ')
-
-  const userId = await resolveUserId(fetchImpl, apiUrl, persona, options, {
-    ...extraHeaders,
-    cookie: session,
-  })
-  return { setCookies, userId }
-}
-
-/**
- * The target's own id for this persona's address, since impersonation names a
- * user id and a persona only knows an email.
- *
- * Looked up before creating, so a persona that already exists is never
- * duplicated and the run reads as "act as this person" rather than "make one".
- */
-const resolveUserId = async (
-  fetchImpl: typeof fetch,
-  apiUrl: string,
-  persona: ResolvedPersona,
-  options: OperatorSignInOptions,
-  extraHeaders: Record<string, string>
-): Promise<string> => {
-  const adminPath = options.adminPath ?? '/auth/admin'
-  const query = new URLSearchParams({
-    filterField: 'email',
-    filterValue: persona.email,
-    filterOperator: 'eq',
-    limit: '1',
-  })
-  const found = await fetchImpl(`${apiUrl}${adminPath}/list-users?${query}`, {
-    headers: { accept: 'application/json', ...extraHeaders },
-  })
-  if (!found.ok) {
-    throw await failed('persona lookup', persona.id, found)
-  }
-  const listed = (await found.json().catch(() => null)) as {
-    users?: AdminUser[]
-  } | null
-  const existing = listed?.users?.find((u) => u.email === persona.email)
-  if (existing?.id) {
-    return String(existing.id)
-  }
-
-  if (!options.createMissing) {
-    throw new Error(
-      `[scenario] no account on the target for persona '${persona.id}' (${persona.email}) — ` +
-        'provision it, or set createMissing on the operator credentials'
-    )
-  }
-
-  const created = await fetchImpl(`${apiUrl}${adminPath}/create-user`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json', ...extraHeaders },
-    body: JSON.stringify({
-      email: persona.email,
-      name: persona.name,
-      // Never used and never returned: the run impersonates rather than signs
-      // in, so the account is reachable only by someone already holding an
-      // operator token. A derivable password would undo exactly that.
-      password: globalThis.crypto.randomUUID(),
-      ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
-    }),
-  })
-  if (!created.ok) {
-    throw await failed('persona creation', persona.id, created)
-  }
-  const body = (await created.json().catch(() => null)) as {
-    user?: AdminUser
+  const body = (await res.json().catch(() => null)) as {
+    actAs?: { userId?: unknown }
   } | null
-  const id = body?.user?.id
-  if (!id) {
+  const userId = body?.actAs?.userId
+  if (!userId) {
     throw new Error(
-      `[scenario] creating persona '${persona.id}' returned no user id`
+      `[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
+        'the target is running a @pikku/better-auth too old to resolve one'
     )
   }
-  return String(id)
+  return { setCookies, userId: String(userId) }
 }
 
 /**

package/src/services/personas-service.ts

@@ -38,6 +38,8 @@ export interface ScenarioHttpResponse<T = unknown> {
  * `invokeRaw` returns this, and a step that has to reach past a persona — a
  * route with no RPC, an identity no persona can hold — reaches for this rather
  * than writing the same record by hand.
+ *
+ * @example snippet: scenarioPolling
  */
 export const readScenarioHttpResponse = async <T = unknown>(
   res: Response
@@ -84,6 +86,8 @@ export interface ScenarioJsonRequest {
  * outright when the target answers an empty body or an HTML error page. A
  * refusal is the expected outcome of a permissions scenario, so it has to
  * survive as data.
+ *
+ * @example snippet: scenarioHttpStep
  */
 export const postScenarioJson = async <T = unknown>(
   url: string,

package/src/services/secret-service.ts

@@ -4,7 +4,6 @@ import type { SecretValue } from '../classification/secret-value.js'
 export type SecretValues<T> = { [K in keyof T]: SecretValue<T[K]> }
 
 export interface SecretService {
-  /** Throws if the secret is not found. Unwrap the result with `.reveal()`. */
   getSecret<T = string>(key: string): Promise<SecretValue<T>>
   /** Answers for any key, including a disallowed one — it must not throw. */
   hasSecret(key: string): Promise<boolean>

package/src/testing/service-tests/secret-service-tests.ts

@@ -44,7 +44,7 @@ export const defineSecretServiceTests = (
     test('getSecret throws for missing key', async () => {
       const service = await factory({ key: kek })
       await assert.rejects(() => service.getSecret('nonexistent'), {
-        message: 'Requested secret not found',
+        message: 'Requested secret not found: nonexistent',
       })
     })
 

package/src/types/core.types.ts

@@ -373,10 +373,15 @@ export type CommonWireMeta = {
   pikkuFuncId: string
   packageName?: string
 
+  /** A human name for this wiring, shown wherever it is listed rather than called. */
   title?: string
+  /** Filters this wiring in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
+  /** A one-line description for listings, where the full `description` is too long. */
   summary?: string
+  /** What this does, for whoever is reading the wiring rather than writing it. */
   description?: string
+  /** Names of error classes this may throw, so each one's registered status is used instead of a 500. */
   errors?: string[]
 
   middleware?: MiddlewareMetadata[]

package/src/wirings/addon/addon-auth-tags.test.ts

@@ -7,7 +7,7 @@ import {
   addTagMiddleware,
   clearMiddlewareCache,
 } from '../../middleware-runner.js'
-import { ForbiddenError } from '../../errors/errors.js'
+import { ForbiddenError, MissingSessionError } from '../../errors/errors.js'
 import { resolveAddonAuth, resolveAddonTags, wireAddon } from './wire-addon.js'
 
 const ADDON_PACKAGE = '@addon/console'
@@ -114,7 +114,7 @@ describe('wireAddon auth on direct wirings', () => {
 
     await assert.rejects(
       () => callOverDirectWiring('credentialGet'),
-      ForbiddenError
+      MissingSessionError
     )
   })
 
@@ -141,7 +141,7 @@ describe('wireAddon auth on direct wirings', () => {
 
     await assert.rejects(
       () => callOverDirectWiring('credentialGet', { auth: true }),
-      ForbiddenError
+      MissingSessionError
     )
   })
 
@@ -161,7 +161,7 @@ describe('wireAddon auth on direct wirings', () => {
     ]) {
       await assert.rejects(
         () => callOverDirectWiring('credentialGet', { wireType }),
-        ForbiddenError,
+        MissingSessionError,
         `${wireType} should have been gated`
       )
     }

package/src/wirings/addon/wire-addon.ts

@@ -2,35 +2,31 @@ import { pikkuState } from '../../pikku-state.js'
 import { getTagGroups } from '../../utils.js'
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js'
 export type WireAddonConfig = {
+  /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
   name: string
+  /** The npm package the addon ships in. */
   package: string
+  /** Where to reach the addon when it runs as its own service rather than in-process. */
   rpcEndpoint?: string
+  /** Requires a session for every function in the addon, whatever each one declares. Gates an addon whose functions are individually open. */
   auth?: boolean
+  /** Offers the addon's functions to MCP clients as tools, without wiring each one. */
   mcp?: boolean
+  /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
   tags?: string[]
   /** Required of every function in the addon, on top of the function's own. */
   scopes?: string[]
+  /** Points a secret the addon reads at a different key in this deployment, so two instances can hold different credentials. */
   secretOverrides?: Record<string, string>
+  /** Points a variable the addon reads at a different key in this deployment. */
   variableOverrides?: Record<string, string>
+  /** Points a credential the addon reads at a different key in this deployment. */
   credentialOverrides?: Record<string, string>
-  /**
-   * Secrets this instance may read on top of the ones it declared, named as the
-   * addon reads them — the scope check runs before `secretOverrides` renames
-   * them, so an overridden secret is named here by its addon-side key. Listing
-   * one in `secretOverrides` grants it too.
-   *
-   * For an addon whose secret names come off its input rather than its own
-   * source, this is how the host lends names the addon could not declare.
-   */
+  /** Extra secrets this instance may read, named as the addon reads them — the scope check runs before `secretOverrides` renames them. */
   secretGrants?: string[]
   /** Credentials this instance may read on top of the ones it declared. */
   credentialGrants?: string[]
-  /**
-   * Hands this instance the whole `SecretService` instead of one scoped to the
-   * secrets it declared. The value is the reason, recorded in the deploy
-   * manifest — an addon that names secrets at runtime cannot be scoped, and
-   * only the consuming app, never the addon, can grant it.
-   */
+  /** Hands over the whole `SecretService` unscoped. The value is the reason, recorded in the deploy manifest. */
   globalSecrets?: string
   /**
    * Hands this instance the whole `CredentialService` instead of one narrowed
@@ -40,6 +36,12 @@ export type WireAddonConfig = {
   globalCredentials?: string
 }
 
+/**
+ * Installs an addon into this project: its functions, wirings and scopes become
+ * part of the app, under the namespace and options given here.
+ *
+ * @example snippet: addonWiring
+ */
 export const wireAddon = (config: WireAddonConfig): void => {
   pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,

package/src/wirings/addon/wire-remote-addon.ts

@@ -25,6 +25,10 @@ export type WireRemoteAddonConfig = {
   tags?: string[]
 }
 
+/**
+ * Installs an addon that runs as its own deployed service: the contract is
+ * local, the calls go over the wire to the addon's own host.
+ */
 export const wireRemoteAddon = (config: WireRemoteAddonConfig): void => {
   pikkuState(null, 'addons', 'packages').set(config.name, {
     package: config.package,