@pikku/inspector 0.12.103 → 0.12.106

package/knowledge/decisions/an-inline-wiring-function-is-sessionless-unless-built-with-pikkufunc.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An inline wiring function is sessionless unless its helper is pikkuFunc
+description: The inspector derives sessionless for a function inlined into a wiring from the name of the helper that built it
+tags: [inspector, functions, auth]
+---
+
+# An inline wiring function is sessionless unless its helper is pikkuFunc
+
+`ensureInlineWiringFunction` in `packages/inspector/src/utils/ensure-function-metadata.ts`
+registers metadata for a function written inline in a wiring (lines 329-344). The comment at
+lines 324-327 says the stub would otherwise carry no session info, and the runtime would then
+require a session for every call.
+
+After that, if the metadata's `sessionless` is still `undefined` (line 349) and the initializer
+is a call whose callee is a plain identifier (lines 350-351), `sessionless` is set to
+`callee !== 'pikkuFunc'` (line 353). The comment at lines 324-327 gives the same rule as the
+one `addFunctions` applies to named functions.
+
+If the callee is not a plain identifier, `sessionless` is left `undefined`.
+
+**What this rules out:** treating an inline wiring function as session-required because it was
+built by a helper other than `pikkuFunc`.

package/knowledge/decisions/better-auth-admin-plugin-is-refused.md

@@ -0,0 +1,24 @@
+---
+type: decision
+title: better-auth's admin plugin is refused in favour of pikkuBan
+description: Wiring admin() in pikkuBetterAuth throws at build time, and the error names pikkuBan() as the replacement
+tags: [inspector, auth, better-auth]
+---
+
+# better-auth's admin plugin is refused in favour of pikkuBan
+
+In `packages/inspector/src/add/add-auth.ts`, a plugin named `admin` inside
+`pikkuBetterAuth` throws rather than warning (lines 342-344). The error text is
+`UNSUPPORTED_ADMIN_PLUGIN` (lines 174-190). It tells the app to use `pikkuBan()`.
+
+The doc comment above the constant (lines 158-172) gives the reason. `admin()`
+authorizes against a `user.role` column, and pikku authorizes on scopes. Running
+both means projecting one onto the other, coarsely. The comment says user
+management now lives in `@pikku/addon-admin`, and the ban refusal lives in
+`pikkuBan()`.
+
+The comment at lines 170-172 says the throw is deliberate: "the failure it prevents
+is silent". An app that drops `admin()` without wiring `pikkuBan()` keeps its ban
+columns and stops enforcing bans.
+
+**What this rules out:** `admin()` as a second authorization model next to scopes.

package/knowledge/decisions/define-screens-scopes-must-be-string-literals.md

@@ -0,0 +1,18 @@
+---
+type: decision
+title: A define-screens scopes list must be string literals, or the build reports a critical error
+description: add-define-screens reads each screen's scopes by AST and reports ADDON_SCREENS_NOT_STATIC when the value is not an array of string literals
+tags: [inspector, screens, scopes]
+---
+
+# A define-screens scopes list must be string literals, or the build reports a critical error
+
+In `packages/inspector/src/add/add-define-screens.ts`, each screen's `scopes` value is read with
+`stringArray(value)` (line 110). If that returns nothing, `fail(...)` runs (lines 111-115), with the
+message "A screen's scopes must be an array of string literals".
+
+`fail` is defined at lines 60-61 as `logger.critical(ErrorCode.ADDON_SCREENS_NOT_STATIC, message)`.
+The same block requires `component` to be a literal lazy import (lines 116-120).
+
+**What this rules out:** a screen whose scopes come from a variable, a computed value or a call.
+The inspector reads scopes statically, so it cannot check a value it cannot see.

package/knowledge/decisions/index.md

@@ -0,0 +1,38 @@
+---
+type: overview
+title: Decisions
+description: Rules chosen in inspector, and what each one rules out
+---
+
+# Decisions
+
+A rule that was chosen, and what it rules out.
+
+<!-- pikku:knowledge-index -->
+- [A channel with auth false marks its connect and disconnect handlers sessionless](a-channel-with-auth-false-marks-its-connect-and-disconnect-sessionless.md) — The inspector synthesises metadata for a channel's connect and disconnect functions and sets sessionless from the channel's auth
+- [A declared scope id never shadows a definition](a-declared-scope-id-never-shadows-a-definition.md) — A bare declareScopes id is added only when no definition already holds it, so an addon's richer scope tree is kept
+- [A workflow DSL step's virtual user is the literal name written in its options object](a-dsl-step-virtual-user-is-the-literal-name-in-its-options.md) — The DSL extractor reads a step's virtual user from a property access or string-keyed element access in the options literal, and leaves it undefined when the value is not static
+- [A feature flag's anyOf is read from the AST, and an empty anyOf is refused](a-feature-flags-anyof-is-read-from-the-ast-and-an-empty-list-is-refused.md) — add-feature-flag reads the scope names in anyOf statically, refuses a non-array or empty anyOf, and refuses a flag name containing the scope separator
+- [A string array with one computed entry reads as absent, not as its literal entries](a-non-literal-string-array-reads-as-absent.md) — stringArrayProperty returns undefined unless every element of the array is a string literal
+- [A permission whose data parameter starts with an underscore takes no data](a-permission-with-an-underscore-data-parameter-takes-no-data.md) — An underscore-prefixed data parameter marks a permission as auth-only, and pikkuAuth always has no data
+- [A provider-login virtual user is never runnable, even when declared runnable](a-provider-login-virtual-user-is-never-runnable.md) — Runnable is derived from the account, so a virtual user with a provider login cannot be driven, and an explicit runnable true does not change that
+- [A remote addon's bound credential or secret id must name a wired slot, or validation reports a critical error](a-remote-addon-bound-credential-or-secret-must-be-wired.md) — validateRemoteAddonAuth checks that a literal auth.credentialId or auth.secretId on a wireRemoteAddon names a declared credential or secret, and runs in every inspector pass
+- [A route's own auth overrides its group's, and auth false on a route makes an inline function sessionless](a-route-auth-overrides-its-groups-auth.md) — The route's auth is used when it is true or false, the group's inherited value otherwise; a resolved false sets sessionless on an inline function
+- [A route requires a session when any auth signal says so](a-route-requires-a-session-when-any-auth-signal-says-so.md) — Four places can demand a session for an HTTP route and they combine with OR; a scope gate counts as a session demand
+- [A webhook source with a verify step declares a singleton credential for its secret](a-webhook-source-with-verify-gets-a-singleton-secret-credential.md) — When a webhook source has a verify step, the inspector registers a string credential named by the source unless the author sets credential
+- [A wire with auth disabled cannot point at a pikkuFunc](a-wire-with-auth-disabled-cannot-point-at-a-pikkufunc.md) — A route or wiring with auth false that names a session-requiring pikkuFunc is reported as critical, and the function is not accepted
+- [Addons may not call wiring helpers or declare middleware or permissions](addon-contracts-cannot-wire-or-declare-handlers.md) — Addon packages are banned from transport wirings, and their define* contracts may not carry middleware or permissions
+- [An addon declaration names the secrets and credentials the app lends it](addon-declarations-name-the-secrets-and-credentials-the-app-lends-it.md) — secretGrants and credentialGrants are declared on the addon instance as lists of names the addon reads
+- [An inline wiring function is sessionless unless its helper is pikkuFunc](an-inline-wiring-function-is-sessionless-unless-built-with-pikkufunc.md) — The inspector derives sessionless for a function inlined into a wiring from the name of the helper that built it
+- [better-auth's admin plugin is refused in favour of pikkuBan](better-auth-admin-plugin-is-refused.md) — Wiring admin() in pikkuBetterAuth throws at build time, and the error names pikkuBan() as the replacement
+- [A define-screens scopes list must be string literals, or the build reports a critical error](define-screens-scopes-must-be-string-literals.md) — add-define-screens reads each screen's scopes by AST and reports ADDON_SCREENS_NOT_STATIC when the value is not an array of string literals
+- [A non-literal global grant is recorded as its source text, not dropped](inspector-records-a-non-literal-global-grant-as-source-text.md) — globalSecrets and globalCredentials on a wireAddon keep a computed value as the expression's source text
+- [Only one pikkuBetterAuth export is allowed per codebase](only-one-pikku-better-auth-export-per-codebase.md) — pikkuBetterAuth must be an exported const, and a second definition is refused with the first file named
+- [An undeclared scope and a secret service passed under another name are critical diagnostics](scope-references-and-secret-aliases-are-critical-diagnostics.md) — Post-processing reports a function that requires an undeclared scope, and a function-facing service that is a SecretService under another name
+- [Scope segments may not be wildcards or contain colons](scope-segments-may-not-be-wildcards-or-contain-colons.md) — The inspector refuses an empty scope segment, a segment containing the separator, and a literal wildcard segment
+- [Shorthand permission entries are extracted, so the audit never reads a guarded function as open](shorthand-permission-entries-are-extracted.md) — extractPermissionPikkuNames reads { canAdminOrg } shorthand entries in a permissions record as names, as the runtime does
+- [System roles must declare literal, unqualified scopes](system-roles-declare-literal-unqualified-scopes.md) — A system role needs a literal scopes array of string literals, and its name may not contain the scope separator
+- [The inspector records an agent's permissions only to aggregate the services they need, never to check access](the-inspector-records-agent-permissions-only-to-aggregate-services.md) — addAgent adds the agent's permission names to usedPermissions, and post-process reads that set only to collect each permission's services
+- [Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only](vault-secrets-reach-no-sink-and-pii-stays-out-of-logs-and-webhooks.md) — check-classified-sinks rejects revealed secrets in every listed sink and PII only in the logger, console and webhook sinks
+- [Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call](webhook-gateway-wrappers-are-sessionless-and-gateway-auth-runs-inside-the-handler.md) — The inspector and the runtime both register a webhook gateway's POST and verify routes as sessionless with auth false, so the route never demands a session and the gateway's own auth flag is applied only when the handler runs
+<!-- /pikku:knowledge-index -->

package/knowledge/decisions/inspector-records-a-non-literal-global-grant-as-source-text.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: A non-literal global grant is recorded as its source text, not dropped
+description: globalSecrets and globalCredentials on a wireAddon keep a computed value as the expression's source text
+tags: [inspector, addons, grants]
+---
+
+# A non-literal global grant is recorded as its source text, not dropped
+
+In `packages/inspector/src/add/add-wire-addon.ts`, the `globalSecrets` and
+`globalCredentials` properties of a `wireAddon` call are read in the same loop as the
+other options (lines 216-225). A string literal is stored as its text. Any other
+expression is stored as `prop.initializer.getText()` (lines 219-221 and 223-225).
+
+The comment at lines 217-218 gives the reason: "The grant is real at runtime whatever the
+reason evaluates to, so a non-literal is recorded as its source text rather than dropped."
+
+**What this rules out:** discarding a global grant because its value is computed. The
+inspector does not evaluate the expression, so the recorded text is what a later reader
+sees.

package/knowledge/decisions/only-one-pikku-better-auth-export-per-codebase.md

@@ -0,0 +1,19 @@
+---
+type: decision
+title: Only one pikkuBetterAuth export is allowed per codebase
+description: pikkuBetterAuth must be an exported const, and a second definition is refused with the first file named
+tags: [inspector, auth, better-auth]
+---
+
+# Only one pikkuBetterAuth export is allowed per codebase
+
+`addAuth` in `packages/inspector/src/add/add-auth.ts` requires `pikkuBetterAuth(...)`
+to be assigned to an exported `const` (lines 242-248). The message says the CLI has
+to import it.
+
+A second definition is refused as critical `DUPLICATE_AUTH_DEFINITION` (lines
+250-256). The message says "Only one pikkuBetterAuth(...) is allowed per codebase"
+and names both the new file and the first one.
+
+**What this rules out:** two better-auth configurations in one codebase, so the
+CLI always has a single auth definition to read.

package/knowledge/decisions/scope-references-and-secret-aliases-are-critical-diagnostics.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: An undeclared scope and a secret service passed under another name are critical diagnostics
+description: Post-processing reports a function that requires an undeclared scope, and a function-facing service that is a SecretService under another name
+tags: [inspector, scopes, secrets, post-process]
+---
+
+# An undeclared scope and a secret service passed under another name are critical diagnostics
+
+Both checks run from `packages/inspector/src/inspector.ts`: `validateNoSecretAliasServices` at line
+539, and `validateScopeReferences` at line 579.
+
+`validateScopeReferences` in `packages/inspector/src/utils/post-process.ts` (lines 1671-1703) checks each
+function's scopes against the set declared with `defineScope`. A trailing `:*` is stripped before the
+lookup (line 1684). A bare `*` is reported (lines 1686-1692), and an undeclared scope is reported with
+the list of available scopes (lines 1694-1700). Both are `logger.critical` with `ErrorCode.INVALID_VALUE`.
+
+`validateNoSecretAliasServices` (lines 1484-1522) reports a function-facing service whose type is a
+`SecretService` under another name. The comment at lines 1479-1482 says a name-based rule would miss
+`pikkuServices(async ({ secrets }) => ({ cfg: secrets }))`, so the check uses the type.
+
+**What this rules out:** a function that requires a scope no `defineScope` declares, and a function
+receiving a secret service under a different name.

package/knowledge/decisions/scope-segments-may-not-be-wildcards-or-contain-colons.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: Scope segments may not be wildcards or contain colons
+description: The inspector refuses an empty scope segment, a segment containing the separator, and a literal wildcard segment
+tags: [inspector, scopes]
+---
+
+# Scope segments may not be wildcards or contain colons
+
+`isValidSegment` in `packages/inspector/src/add/add-scope.ts` checks one segment at a
+time and reports each failure as critical:
+
+- an empty segment is refused (lines 21-27);
+- a segment containing `:` is refused, with the message telling the author to nest
+  with the `scopes` property instead (lines 28-35);
+- a segment equal to `*` is refused, because `*` is reserved for granting a scope
+  and its descendants (lines 36-43).
+
+`declareScopes` ids are split on `:` and every segment is checked (line 161). Nested
+`scopes` keys are checked the same way (line 77).
+
+**What this rules out:** a declared scope that is itself a wildcard, and a scope
+name that hides a second level of nesting inside one segment.

package/knowledge/decisions/shorthand-permission-entries-are-extracted.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Shorthand permission entries are extracted, so the audit never reads a guarded function as open
+description: extractPermissionPikkuNames reads { canAdminOrg } shorthand entries in a permissions record as names, as the runtime does
+tags: [inspector, permissions, audit]
+---
+
+# Shorthand permission entries are extracted, so the audit never reads a guarded function as open
+
+`extractPermissionPikkuNames` in `packages/inspector/src/utils/permissions.ts` (line 15) reads a
+permissions value in two shapes. An array is walked element by element (lines 44-48). An object
+literal is walked property by property (lines 49-62).
+
+For a `PropertyAssignment` the initializer is extracted (line 53). For a
+`ShorthandPropertyAssignment`, such as `permissions: { canAdminOrg }`, the property name is
+extracted (lines 54-60).
+
+The comment at lines 55-59 says the runtime resolves the shorthand the same way as the longhand
+form, and that dropping it once reported a guarded function as having no permissions.
+
+**What this rules out:** an audit that skips shorthand permission entries and so shows a guarded
+function as open.

package/knowledge/decisions/system-roles-declare-literal-unqualified-scopes.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: System roles must declare literal, unqualified scopes
+description: A system role needs a literal scopes array of string literals, and its name may not contain the scope separator
+tags: [inspector, roles, scopes]
+---
+
+# System roles must declare literal, unqualified scopes
+
+`addSystemRole` in `packages/inspector/src/add/add-system-role.ts` applies these rules
+to each `defineSystemRole` entry:
+
+- `scopes` must be present and must be an array literal. A missing or non-literal
+  `scopes` is reported as critical and the role is dropped (lines 37-54, and the
+  skip at 143-146). The message asks for `scopes: []` when a role grants nothing
+  (line 40).
+- Each element of `scopes` must be a string literal. A non-literal element is
+  reported as critical and skipped (lines 57-66). The reason given is that scopes
+  are read by AST, so a computed value cannot be checked (line 63).
+- A role name containing `:` is refused (lines 126-133), because `:` delimits scope
+  ids and "a role named like a scope reads as one" (line 130).
+- An empty role name is refused (lines 118-124).
+
+The doc comment on `extractScopes` (lines 20-23) says the empty array and the
+absent property are kept distinct on purpose.
+
+**What this rules out:** a role whose scopes cannot be checked statically, and a
+role name that looks like a scope id.

package/knowledge/decisions/the-inspector-records-agent-permissions-only-to-aggregate-services.md

@@ -0,0 +1,14 @@
+---
+type: decision
+title: The inspector records an agent's permissions only to aggregate the services they need, never to check access
+description: addAgent adds the agent's permission names to usedPermissions, and post-process reads that set only to collect each permission's services
+tags: inspector, agents, permissions
+---
+
+# The inspector records an agent's permissions only to aggregate the services they need, never to check access
+
+`addAgent` resolves the agent's permissions and adds their names to `state.serviceAggregation.usedPermissions` (`packages/inspector/src/add/add-agent.ts:612`, `:618-620`). `post-process.ts` reads the same set at `packages/inspector/src/utils/post-process.ts:160`, and at `:206-209` it adds each used permission's `services` to the service list.
+
+Within the inspector source those are the only readers. `serialize-inspector-state.ts` copies the set in and out (`packages/inspector/src/utils/serialize-inspector-state.ts:294`, `:522`, `:746`). Nothing in the inspector compares a caller against the set.
+
+**What this rules out:** reading the inspector's agent permission list as evidence that an agent is guarded, and adding an access decision to the inspector's aggregation step.

package/knowledge/decisions/vault-secrets-reach-no-sink-and-pii-stays-out-of-logs-and-webhooks.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only
+description: check-classified-sinks rejects revealed secrets in every listed sink and PII only in the logger, console and webhook sinks
+tags: [inspector, pii, secrets, lint]
+---
+
+# Vault secrets reach no sink, and PII is kept out of logs, the console and webhooks only
+
+The sink table in `packages/inspector/src/utils/check-classified-sinks.ts` (lines 44-59) lists
+which methods count as sinks and what each one rejects:
+
+- `Logger`, every method, rejects `secret` and `pii` (line 49);
+- `WebhookService.send` rejects `secret` and `pii` (line 50);
+- `QueueService.add` rejects `secret` only (line 51);
+- `EmailService.send` rejects `secret` only (line 52);
+- `AuditService` `audit` and `write` reject `secret` only (lines 53-57);
+- `AuditLog.write` rejects `secret` only (line 58).
+
+`console` is handled separately and rejects both (line 62).
+
+The comment at lines 23-38 gives the reasons. A vault secret is wrong in every sink (lines 23-24).
+PII is wrong only where it leaves the operator's control or lands somewhere never meant to hold
+it. Lines 37-38 say a queue payload "stays on the operator's own infrastructure", and lines 33-34
+say an email is addressed to the data subject.
+
+Lines 40-42 say `private` is absent from the table on purpose.
+
+**What this rules out:** a revealed secret reaching any listed sink, and PII reaching a logger,
+the console or a webhook. PII is allowed into queues, email and audit by this table.

package/knowledge/decisions/webhook-gateway-wrappers-are-sessionless-and-gateway-auth-runs-inside-the-handler.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call
+description: The inspector and the runtime both register a webhook gateway's POST and verify routes as sessionless with auth false, so the route never demands a session and the gateway's own auth flag is applied only when the handler runs
+tags: inspector, gateway, webhook, auth, sessionless
+---
+
+# Webhook gateway wrappers are registered sessionless, and gateway auth is enforced inside the handler call
+
+**Build time.** For a webhook gateway, `addGateway` writes two function metas, `gateway__<name>__post` and `gateway__<name>__verify`, and their HTTP routes (`packages/inspector/src/add/add-gateway.ts:105-109`). Each function meta is written with `sessionless: true` (`add-gateway.ts:117-122`). The comment on the wrapper says "no middleware here — the gateway POST wrapper runs it itself" (`add-gateway.ts:111`).
+
+The gateway's own `auth` flag is not used there. It is recorded only on the gateway meta, as `auth` on `state.gateways.meta[name]` (`add-gateway.ts:135`).
+
+**Run time.** `wireWebhookGateway` in `packages/core/src/wirings/gateway/gateway-runner.ts` mirrors this. The POST and verify handlers are both registered with `auth: false` (`gateway-runner.ts:117`, `:141`), and so are their routes (`gateway-runner.ts:130`, `:154`).
+
+The POST wrapper, `createWebhookPostHandler` (`gateway-runner.ts:163`), does three things in order:
+
+1. If the adapter has `verifyWebhook` and it verifies the request, it returns the adapter's response immediately (`gateway-runner.ts:175-179`). The handler is not reached.
+2. It parses the body; an unparseable body returns `{ ok: true }` (`gateway-runner.ts:182-185`).
+3. It invokes the handler through `runPikkuFunc('gateway', name, handlerFuncId, { ..., auth: config.auth, ... })` (`gateway-runner.ts:196-204`), with gateway middleware running first (`gateway-runner.ts:207-211`).
+
+So the session check for a webhook is applied from `CoreGateway.auth`, inside the runner call at `gateway-runner.ts:201`. It is not applied on the HTTP route, which is `auth: false` and sessionless.
+
+The synthetic handler registration that this call goes through, and how it inherits the wired function's metadata, is described in [Gateway handlers run through the function runner gate](../../../core/knowledge/decisions/security/gateway-handlers-run-through-the-function-runner-gate.md).
+
+**What this rules out:** adding `auth: true` to the POST or verify route to "harden" a webhook. That would reject every platform call, which carries no user session. It also rules out assuming that the route-level metadata shows whether a gateway needs a session. Check `CoreGateway.auth` and the handler's own declaration instead.

package/knowledge/index.md

@@ -0,0 +1,14 @@
+---
+type: overview
+title: Knowledge
+description: Why the inspector reads and refuses declarations the way it does
+---
+
+# Knowledge
+
+Why the inspector reads and refuses declarations the way it does — the reasoning that is not visible in the code.
+
+<!-- pikku:knowledge-index -->
+- [decisions](decisions/index.md) — a rule that was chosen, and what it rules out
+- [questions](questions/index.md) — something asked and not yet answered
+<!-- /pikku:knowledge-index -->

package/knowledge/questions/does-a-non-literal-remote-addon-auth-get-checked.md

@@ -0,0 +1,26 @@
+---
+type: question
+title: Does a non-literal auth on wireRemoteAddon get checked?
+description: A non-literal auth value is recorded exactly like an omitted one, so the consumer's credential and secret checks never run for it
+tags: [inspector, addon, auth]
+---
+
+# Does a non-literal auth on wireRemoteAddon get checked?
+
+`addWireRemoteAddon` in `packages/inspector/src/add/add-wire-remote-addon.ts` reads
+`auth` only when it is an object literal (lines 42-46). Otherwise `hasAuth` stays
+`false` (line 31) and `authCredentialId` and `authSecretId` stay undefined.
+
+The comment at lines 27-30 says `hasAuth` separates "public" (omitted) from "bound
+via a custom resolve()" (present, with no static id). A non-literal `auth` value
+therefore looks the same as an omitted one. The declaration is written at lines
+71-78, with `hasAuth` at line 75.
+
+Nothing in the inspector reads `hasAuth`. Its only other mentions are the type at
+`packages/inspector/src/types.ts:749` and serialization at
+`packages/inspector/src/utils/serialize-inspector-state.ts:172`. The post-process
+checks run only when an id is set: the credential id at
+`packages/inspector/src/utils/post-process.ts:841` and the secret id at line 847.
+
+Question: should a non-literal `auth` be treated as a binding the consumer has to
+satisfy, or as public? The code currently does neither and logs nothing.

package/knowledge/questions/index.md

@@ -0,0 +1,16 @@
+---
+type: overview
+title: Questions
+description: Things asked of inspector and not yet answered
+---
+
+# Questions
+
+Something asked and not yet answered. The choice stays, the doubt gets recorded.
+
+<!-- pikku:knowledge-index -->
+- [Does a non-literal auth on wireRemoteAddon get checked?](does-a-non-literal-remote-addon-auth-get-checked.md) — A non-literal auth value is recorded exactly like an omitted one, so the consumer's credential and secret checks never run for it
+- [Should an incomplete oauth2 block be dropped without a log?](is-an-incomplete-oauth2-block-dropped-without-a-log.md) — An oauth2 block missing any required field is silently left undefined, and an empty scopes array passes the check
+- [Should an app function named like scenario instrumentation be silently skipped?](should-app-functions-named-like-scenario-instrumentation-be-refused.md) — Five instrumentation names are skipped by name in every project, so an app's own function with one of those names disappears without a log
+- [Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?](should-the-openapi-document-default-every-operation-to-a-bearer-or-api-key.md) — The OpenAPI serializer emits one top-level security default for all operations and does not read the auth or session metadata of any route
+<!-- /pikku:knowledge-index -->

package/knowledge/questions/is-an-incomplete-oauth2-block-dropped-without-a-log.md

@@ -0,0 +1,23 @@
+---
+type: question
+title: Should an incomplete oauth2 block be dropped without a log?
+description: An oauth2 block missing any required field is silently left undefined, and an empty scopes array passes the check
+tags: [inspector, credentials, oauth]
+---
+
+# Should an incomplete oauth2 block be dropped without a log?
+
+In `packages/inspector/src/add/add-credential.ts`, `oauth2` is set only when
+`appCredentialSecretId`, `authorizationUrl`, `tokenUrl` and `scopes` are all truthy
+(lines 144-155). There is no `else` branch, and nothing in that block calls the
+logger. The credential is still recorded, with `oauth2` undefined.
+
+`scopes` comes from `getArrayPropertyValue`, which returns `string[] | null`
+(`packages/inspector/src/utils/get-property-value.ts:22`). An array literal returns
+its string elements even when there are none (lines 31-35). An empty array is
+truthy, so `scopes: []` passes the check.
+
+Question: should a half-filled `oauth2` block be reported as critical, as the other
+other validation in the same file is (logger calls at lines 49, 57 and 65)? And should `scopes: []` be
+allowed to satisfy the check at all? The code currently does neither, and no
+comment or test in this path says why.

package/knowledge/questions/should-app-functions-named-like-scenario-instrumentation-be-refused.md

@@ -0,0 +1,28 @@
+---
+type: question
+title: Should an app function named like scenario instrumentation be silently skipped?
+description: Five instrumentation names are skipped by name in every project, so an app's own function with one of those names disappears without a log
+tags: [inspector, scenarios, functions]
+---
+
+# Should an app function named like scenario instrumentation be silently skipped?
+
+`SCENARIO_INSTRUMENTATION_FUNCTIONS` in
+`packages/inspector/src/add/scenario-instrumentation.ts` lists five names (lines
+22-28). `isScenarioInstrumentationFunction` matches them on the id before any `@`
+(lines 40-42).
+
+In `packages/inspector/src/add/add-functions.ts`, a function whose id or name matches
+is returned before it is registered (lines 571-576). No logger call happens there.
+The file's comment says the function is "not application code" and must not be
+registered.
+
+The file comment gives the reason for matching by name: it keeps an existing
+project's checked-in `scenarios.gen.ts` from deploying (lines 12-15). Lines 17-20
+say `pikkuScenarioGradeRun` is reserved "so an application cannot claim it". No
+comment says the same about the other four names.
+
+Question: should an application's own function named `pikkuScenarioResetStubs`,
+`pikkuScenarioGetStubCalls`, `pikkuScenarioTakeLiveCoverage` or
+`pikkuScenarioResetLiveCoverage` be refused with a critical, as the reserved name
+would be, rather than dropped silently?

package/knowledge/questions/should-the-openapi-document-default-every-operation-to-a-bearer-or-api-key.md

@@ -0,0 +1,22 @@
+---
+type: question
+title: Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?
+description: The OpenAPI serializer emits one top-level security default for all operations and does not read the auth or session metadata of any route
+tags: [inspector, openapi, auth]
+---
+
+# Should the OpenAPI document apply an ApiKey-or-Bearer security default to every operation, including auth false routes?
+
+`generateOpenAPISpec` in `packages/inspector/src/utils/serialize-openapi-json.ts` writes two security
+schemes, `ApiKeyAuth` (an `x-api-key` header) and `BearerAuth`, unless the caller supplies its own
+(lines 254-264). It then writes a top-level `security` array with one entry for each scheme
+(lines 266-273), unless the caller supplies one.
+
+In OpenAPI a top-level `security` applies to every operation that does not set its own. This file
+does not write per-operation `security`, and a search of the file for `requiresSession` and
+`sessionless` finds nothing. So an operation for a route marked `auth: false` would carry the same
+default as one that requires a session.
+
+Question: should `auth: false` routes and sessionless functions be written with an empty
+`security` list, and should the default be applied per operation? The code does not say whether the
+default is meant for the whole API or only as a placeholder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.103",
+  "version": "0.12.106",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -54,10 +54,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.139"
+    "@pikku/core": "^0.12.142"
   },
   "devDependencies": {
-    "@pikku/core": "^0.12.139",
+    "@pikku/core": "^0.12.142",
     "@types/node": "^24.13.3"
   },
   "engines": {

package/dist/add/add-personas.d.ts

@@ -1,13 +0,0 @@
-import type { AddWiring } from '../types.js';
-/**
- * Inspector for `definePersonas()` calls.
- *
- * A persona is entirely declaration — a person, their roles, what they want —
- * so there is no code body and nothing to resolve at runtime. What is read here
- * is the whole thing, and it is generated straight to `personas.gen.json` for
- * the CLI and the console to read without loading the app.
- *
- * `name` is the one field that cannot be defaulted. A persona without one is
- * not a person, and the console has nothing to show.
- */
-export declare const addPersonas: AddWiring;