@pikku/core 0.12.72 → 0.12.74

package/knowledge/decisions/internals/ai-agent-agui-bridge-obeys-the-client-ordering-contract.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: The AG-UI bridge obeys the client's event-ordering contract exactly
+description: RUN_STARTED opens lazily, RUN_FINISHED fires once on done, and step names are globally sequential — a violation makes the client drop the whole stream
+tags: ai-agent
+---
+
+# The AG-UI bridge obeys the client's event-ordering contract exactly
+
+`wrapChannelWithAGUI` in `packages/core/src/wirings/ai-agent/ai-agent-agui.ts`
+translates pikku stream events into AG-UI events under three rules that
+`@ag-ui/client`'s `verifyEvents` enforces on the browser side:
+
+`RUN_STARTED` is emitted lazily, from the first translated event, because the
+client rejects anything that arrives before it — and because the real
+`AIRunStateService` run id only exists after the channel has been wrapped, which
+is why `AGUIChannelOptions.getRunId` and `StreamAIAgentOptions.onRunCreated`
+exist as late-bound sources. `RUN_FINISHED` is terminal for the client, so it is
+sent exactly once, on `done`, carrying usage accumulated across all steps; per-step
+`usage` events must not finish the run, or a multi-step tool run would emit later
+steps after the terminal event and the client would drop the whole stream.
+Step names must be unique among active steps, and sub-agents reuse step numbers
+on the shared channel, so each `step-start` closes the previous step and takes a
+sequential name. `ai-agent-agui.test.ts` re-implements those ordering rules so
+the bridge is checked against the same contract the browser applies.
+
+**What this rules out:** emitting `RUN_STARTED` eagerly at wrap time; finishing
+the run on the `usage` event so token counts arrive earlier; and naming AG-UI
+steps after `event.stepNumber`.

package/knowledge/decisions/internals/ai-agent-audio-chunks-carry-the-format-the-provider-returned.md

@@ -0,0 +1,20 @@
+---
+type: decision
+title: Audio chunks are labelled with the format the provider actually returned
+description: The configured format is only a request, so the response's own format wins with the request and pcm16 as fallbacks
+tags: ai-agent
+---
+
+# Audio chunks are labelled with the format the provider actually returned
+
+`synthesizeAudio` in `packages/core/src/wirings/ai-agent/voice-output.ts` labels
+each `audio-delta` event with `result.audio.format` first, falling back to the
+requested `config.format` and finally to `pcm16`.
+
+Speech providers treat the output format as a preference: an unsupported or
+omitted value silently yields whatever the provider defaults to. Stamping the
+requested format on the chunk would tell the client to decode bytes it did not
+receive, producing noise rather than an error.
+
+**What this rules out:** labelling chunks from `config.format` because "we asked
+for it", and dropping the fallback chain to a single source.

package/knowledge/decisions/internals/ai-agent-credential-suspensions-hide-the-tool-result.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A credential-required tool result never reaches the client or the transcript
+description: The run suspends with credential-request events instead, leaving the tool call unresulted so it can be resumed after connecting
+tags: ai-agent
+---
+
+# A credential-required tool result never reaches the client or the transcript
+
+When a tool returns the `__credentialRequired` marker,
+`streamAIAgent` in `packages/core/src/wirings/ai-agent/ai-agent-stream.ts`
+filters that `tool-result` out of the channel before it can be streamed or
+persisted, and `handleCredentialRequests` suspends the run and emits
+`credential-request` events carrying the `runId` instead. Those events — not the
+tool result — are what tells a client to show Connect/Ignore, mirroring how
+approval suspensions work.
+
+Leaving the tool call unresulted in the persisted history is what makes the
+resume possible: once the credential is connected, `/resume` re-executes the call
+against a history that does not already contain a bogus answer. `runStreamStepLoop`
+still appends the step messages before returning the credential outcome, so the
+assistant's tool call itself survives into the resume.
+
+**What this rules out:** streaming the marker result as a normal tool result and
+filtering it client-side; persisting it as the tool's answer; and skipping
+`appendStepMessages` on the credential path because the run is about to suspend.

package/knowledge/decisions/internals/ai-agent-delegate-and-supervise-hide-different-text.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: Delegate mode hides the parent's later text, supervise mode hides the sub-agent's
+description: Exactly one voice reaches the client per agent-mode; approvals and tool events always flow through either way
+tags: ai-agent
+---
+
+# Delegate mode hides the parent's later text, supervise mode hides the sub-agent's
+
+An agent with sub-agents runs in one of two modes. In `'delegate'` (the default,
+handled in `streamAIAgent` in `ai-agent-stream.ts`) the parent's `text-delta` and
+`reasoning-delta` events are suppressed *after* the first sub-agent call —
+`delegateState.delegated` is the latch — so a parent that answers directly still
+streams normally, while a parent that hands off does not narrate over its
+sub-agent. In `'supervise'` (handled where the sub-agent channel is built in
+`buildToolDefs` in `ai-agent-prepare.ts`) the inverse holds: the sub-agent's text
+and reasoning are dropped and only the supervisor speaks.
+
+Suppression is confined to text and reasoning. Approval requests, tool calls,
+tool results, usage and errors flow through in both modes, because a suppressed
+approval would deadlock the run.
+
+**What this rules out:** filtering sub-agent events at the transport instead of
+at the scoped channel; suppressing parent text unconditionally in delegate mode
+(direct answers would vanish); and adding new event types to either filter
+without checking they are not part of the approval handshake.

package/knowledge/decisions/internals/ai-agent-llm-tool-arguments-have-nulls-stripped.md

@@ -0,0 +1,23 @@
+---
+type: decision
+title: Nulls are stripped from approved tool arguments before execution
+description: LLMs emit null for optional fields where the schema layer expects undefined, so a resumed tool call is cleaned recursively first
+tags: ai-agent
+---
+
+# Nulls are stripped from approved tool arguments before execution
+
+`resumeAIAgentSync` in
+`packages/core/src/wirings/ai-agent/ai-agent-runner.ts` runs `stripNulls` over
+the persisted arguments of an approved tool call before invoking the tool.
+
+Models routinely fill every property in a JSON schema, using `null` to mean "not
+provided". Pikku's validation layer models an absent optional field as
+`undefined`, and a `null` fails the check outright. The value is stored as the
+model produced it — the approval prompt should show what the model actually asked
+for — so the cleanup happens at execution time, recursively, including inside
+arrays and nested objects.
+
+**What this rules out:** normalizing the arguments at approval-capture time
+(the approval UI would no longer reflect the model's real request), and a
+shallow single-level null strip.

package/knowledge/decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Model resolution stays a single seam even though it is currently a passthrough
+description: resolveModelConfig looks removable but is the one merge point for per-request model overrides
+tags: ai-agent
+---
+
+# Model resolution stays a single seam even though it is currently a passthrough
+
+`resolveModelConfig` in
+`packages/core/src/wirings/ai-agent/ai-agent-model-config.ts` returns the
+agent's `model`, `temperature` and `maxSteps` unchanged, and ignores its
+`_agentName` argument. It reads as dead indirection and is not.
+
+Models are declared per agent in the provider-qualified `provider/model` form
+(`openai/gpt-5-mini`); there is no config-level alias map to consult, which is
+why the current body is a copy. The function exists so that every caller —
+`prepareAgentRun`, both resume paths, and the per-request `input.model` /
+`input.temperature` overrides applied in `ai-agent-prepare.ts` — assembles the
+effective config the same way, through one place that can grow an alias map,
+per-tenant defaults or provider fallbacks without touching them.
+
+**What this rules out:** inlining `agent.model` / `agent.temperature` at the four
+call sites and deleting the function, and dropping the unused `_agentName`
+parameter from the signature.

package/knowledge/decisions/internals/ai-agent-onerror-hooks-cannot-change-the-failure.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: An aiMiddleware onError hook cannot change how a run fails
+description: Hook throws are swallowed so observability code can never convert, mask, or replace the original error
+tags: ai-agent
+---
+
+# An aiMiddleware onError hook cannot change how a run fails
+
+Every `onError` invocation on the agent failure paths — in `streamAIAgent` and
+`continueAfterToolResult` (`ai-agent-stream.ts`) and in `runAIAgent` and
+`continueAfterToolResultSync` (`ai-agent-runner.ts`) — is wrapped in its own
+`try/catch` that discards whatever the hook throws. The run is then marked
+`failed` with the original error message, and the original error propagates.
+
+`onError` is an observability hook: logging, metrics, alerting. A logger that is
+itself broken must not turn a diagnosable agent failure into a confusing one, and
+must not stop the remaining hooks from running or the run state from being
+updated.
+
+**What this rules out:** awaiting the hooks without a guard, and using `onError`
+as an error-transformation hook whose throw replaces the original failure.

package/knowledge/decisions/internals/ai-agent-runner-methods-must-keep-their-receiver.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: AI runner methods must be called on the runner, never as detached references
+description: Implementations use this internally, so grabbing transcribe or generateSpeech as a bare function loses the receiver and throws at runtime
+tags: ai-agent
+---
+
+# AI runner methods must be called on the runner, never as detached references
+
+The voice middlewares in `voice-input.ts` and `voice-output.ts` invoke
+`aiAgentRunner.transcribe(...)` and `aiAgentRunner.generateSpeech?.(...)` as
+method calls on the service object, and only ever test them for presence.
+
+`AIAgentRunnerService` is an interface implemented by classes — the reference
+implementation's `transcribe` calls `this.getModel(...)`. Extracting the method
+into a local (`const { transcribe } = services.aiAgentRunner`) type-checks
+cleanly and then fails at runtime with `this` undefined. The regression is
+pinned by a runner in `voice-input.test.ts` whose `transcribe` deliberately reads
+instance state through `this`.
+
+**What this rules out:** destructuring runner methods for brevity, and passing
+`runner.transcribe` as a callback without binding it.

package/knowledge/decisions/internals/ai-agent-stream-persistence-is-best-effort.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: Persisting an agent stream from send is best-effort and must never reject
+description: The persisting channel flushes fire-and-forget because send is synchronous; a storage failure degrades the transcript instead of killing the process
+tags: ai-agent
+---
+
+# Persisting an agent stream from send is best-effort and must never reject
+
+`createPersistingChannel` in
+`packages/core/src/wirings/ai-agent/ai-agent-stream.ts` accumulates step text,
+tool calls and tool results, and writes them via `flushDetached` on the `usage`
+and `done` events. `AIStreamChannel.send` is synchronous, so it cannot await the
+write. An unawaited rejection has nothing to propagate to and surfaces as an
+`unhandledRejection`, which takes the whole server process down — a model
+reusing a `toolCallId`, which is a primary key in AI storage, is enough to
+trigger it. `flushDetached` therefore catches and logs, and the run carries on.
+
+The awaited `flush()` on the suspend paths (`handleApprovals`,
+`handleCredentialRequests`) is the seam that still surfaces persistence failures
+to a caller. The regression test lives in `ai-agent-stream.test.ts`; because the
+floating promise settles on a later macrotask, the assertion has to wait a real
+timer before checking that no `unhandledRejection` fired.
+
+**What this rules out:** letting `flushStep()` be called bare from `send`,
+rethrowing from the catch to "not hide" storage errors, and asserting on
+unhandled rejections synchronously after the last event.

package/knowledge/decisions/internals/ai-agent-sub-agents-inherit-the-parent-context-block.md

@@ -0,0 +1,26 @@
+---
+type: decision
+title: A delegated sub-agent inherits the parent run's context block
+description: The sub-agent tool schema carries only message and session, so the parent's identifier block is forwarded rather than re-typed by the model
+tags: ai-agent
+---
+
+# A delegated sub-agent inherits the parent run's context block
+
+`buildSubAgentRunInput` in
+`packages/core/src/wirings/ai-agent/ai-agent-prepare.ts` forwards the parent
+run's `AIAgentInput.context` — the "Current context" identifier block with
+organization, project and stage ids — into every delegated sub-agent run, on
+both the streaming and non-streaming paths. `buildToolDefs` threads it down as
+`parentContext` for the same reason.
+
+A sub-agent is exposed to the parent model as a tool whose input schema is only
+`{ message, session }`. Without inheritance the sub-agent never sees the
+authoritative ids and has to rely on the parent model re-typing them into
+`message`. Weaker models mangle that, and the result is schema and permission
+rejections followed by retry loops rather than a clean failure.
+
+**What this rules out:** constructing the sub-agent run input inline from
+`{ message, threadId, resourceId }`, widening the sub-agent tool schema so the
+model supplies the ids itself, and dropping `parentContext` from `buildToolDefs`
+because "nothing reads it here".

package/knowledge/decisions/internals/ai-agent-tool-execute-failures-are-logged-unconditionally.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: A tool's execute() failure is logged before the AI SDK swallows it
+description: Every agent tool is wrapped in a logging try/catch, because a thrown tool error otherwise becomes a conversational reply and is invisible server-side
+tags: ai-agent
+---
+
+# A tool's execute() failure is logged before the AI SDK swallows it
+
+`buildToolDefs` in `packages/core/src/wirings/ai-agent/ai-agent-prepare.ts`
+wraps every tool it builds — RPC tools, sub-agent delegations and workflow tools
+alike — in a `try/catch` that logs through `singletonServices.logger` and
+rethrows.
+
+A tool's `execute()` can throw for ordinary reasons: bad model-supplied input, an
+RPC failure, a database error. The AI SDK catches that at the tool-call boundary
+and turns it into a conversational "tool error" reply to the model. The exception
+never reaches pikku's own logger, so without this wrapper a consistently failing
+tool is undiagnosable from the server side — the only symptom is an agent that
+keeps apologising. The wrapper is applied unconditionally, not only when an
+`aiMiddleware` `afterToolCall` hook happens to be registered.
+
+**What this rules out:** folding the logging into the optional middleware
+wrapper below it, and relying on the AI SDK's own error reporting for tool
+failures.

package/knowledge/decisions/internals/ai-agent-voice-input-transcribes-audio-parts-in-place.md

@@ -0,0 +1,22 @@
+---
+type: decision
+title: Voice input transcribes audio parts sequentially and in place
+description: Each audio part is replaced by its text where it sat, one at a time, bounding concurrent downloads and preserving content order
+tags: ai-agent
+---
+
+# Voice input transcribes audio parts sequentially and in place
+
+The `voiceInput` middleware in
+`packages/core/src/wirings/ai-agent/voice-input.ts` walks the last user
+message's content parts in order and swaps each audio part for a text part at the
+same index, awaiting one transcription before starting the next.
+
+Order matters because the surrounding text parts are the user's own framing of
+the audio; hoisting transcripts to the end would reorder the prompt. Sequencing
+matters because a message can carry many attachments: a `Promise.all` would fan
+out an unbounded number of concurrent multi-megabyte downloads and provider
+transcription calls from a single request.
+
+**What this rules out:** parallelizing the loop with `Promise.all`, and
+collecting transcripts into a separate block appended to the message.

package/knowledge/decisions/internals/ai-agent-working-memory-is-persisted-only-when-valid.md

@@ -0,0 +1,25 @@
+---
+type: decision
+title: Working memory is persisted only when the merged value validates
+description: A failed schema check logs and drops the update rather than saving it, because invalid state poisons every later read
+tags: ai-agent
+---
+
+# Working memory is persisted only when the merged value validates
+
+`createWorkingMemoryMiddleware` in
+`packages/core/src/wirings/ai-agent/ai-agent-memory.ts` parses the model's
+`<working_memory>` block, deep-merges it into the stored value, validates the
+merge against the agent's working-memory schema when one is declared, and calls
+`saveWorkingMemory` only if the merge is valid. An invalid merge is logged as a
+warning and discarded.
+
+Working memory is read back into the system prompt on every subsequent run of the
+thread, so a bad write is not a one-turn mistake — it is a permanently malformed
+prompt that the model then has to reason around, and which the model itself
+cannot repair. Dropping the update is recoverable; the next turn simply tries
+again.
+
+**What this rules out:** saving first and validating on read, persisting the raw
+model output before the merge, and treating a validation failure as fatal to the
+run.

package/knowledge/decisions/internals/channel-message-handlers-accept-three-config-shapes.md

@@ -0,0 +1,30 @@
+---
+type: decision
+title: Channel message handlers accept three config shapes
+description: onMessage may be a function config, a wrapper with middleware, or a wrapper around a function config — the runtime discriminates structurally
+tags: channel
+---
+
+# Channel message handlers accept three config shapes
+
+`processMessageHandlers` in
+`packages/core/src/wirings/channel/channel-handler.ts` has to tell apart three
+things a caller may put on `onMessage` or inside `onMessageWiring`:
+
+- a direct function config, where `onMessage.func` is a plain `Function`;
+- a wrapper, where `onMessage.func` is itself a `CorePikkuFunctionConfig` and so
+  has its own nested `.func`;
+- a simple wrapper, which carries a plain `Function` under `func` *and* a
+  sibling `middleware` array.
+
+The `isWrapper` check tests exactly that: an object with `func`, where either
+`func` is an object that itself has `func`, or the object also has `middleware`.
+Only a wrapper contributes message-level middleware; a direct config contributes
+none. `wireChannel` in `channel-runner.ts` performs the mirror-image unwrapping
+when registering the function, using `(handler as any).func instanceof Function`
+to decide whether to register the handler or its inner `func`.
+
+**What this rules out:** narrowing on a single property (`'middleware' in
+onMessage` alone misclassifies a nested function config; `'func' in onMessage`
+alone misclassifies a direct config), and reducing the accepted shapes without
+updating both this discriminator and the registration path in `wireChannel`.

package/knowledge/decisions/internals/channel-middleware-caches-only-statically-resolved-middleware.md

@@ -0,0 +1,31 @@
+---
+type: decision
+title: Channel middleware caching covers only statically resolved middleware
+description: Inherited tag/named middleware is cached per uid; per-run closures are appended fresh every call, at the cost of re-allocating the array
+tags: channel
+---
+
+# Channel middleware caching covers only statically resolved middleware
+
+`combineChannelMiddleware` in
+`packages/core/src/wirings/channel/channel-middleware-runner.ts` caches only the
+`wireInheritedChannelMiddleware` slice — the tag groups and named middleware
+resolved out of `pikkuState` — under the key `${wireType}:${uid}`. That slice is
+deterministic for a given `uid`. `wireChannelMiddleware` is not: it is a per-run
+set of closures, such as an AI agent's per-invocation stream middleware holding
+that run's thread and session state. Caching it would let a later run of the same
+`uid` reuse an earlier run's closures, leaking that run's state into a different
+user's stream and growing memory run over run. It is therefore appended fresh on
+every call, after the cached inherited slice.
+
+The `uid` matters as much as the cache split. `processMessageHandlers` in
+`channel-handler.ts` builds it from the channel name *plus* the routing property
+and router value (`${name}:${routingProperty}:${routerValue}`, or
+`${name}:default`), because several message routes on one channel may point at
+the same function — a key based on the function alone would serve one route's
+middleware chain to another. Ordering within the combined chain is also fixed:
+channel-level `middleware` runs before message-level `middleware`.
+
+**What this rules out:** extending the cache key's value to include
+`wireChannelMiddleware`, memoising the whole combined array, or simplifying the
+cache key down to the channel or function name.

package/knowledge/decisions/internals/channel-state-is-per-socket-session-state-is-per-user.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: Channel state is per-socket, session state is per-user
+description: ChannelStore holds connection-scoped scratch data keyed by channelId, deliberately separate from the pikkuUserId-keyed SessionStore
+tags: channel
+---
+
+# Channel state is per-socket, session state is per-user
+
+`ChannelStore.setState` / `getState` / `clearState` in
+`packages/core/src/wirings/channel/channel-store.ts` are keyed by `channelId` and
+hold scratch data that belongs to one socket: a per-connection subscription
+filter, the current step of a connection-bound state machine, the last command
+this socket sent. The store clears it when the channel is removed. `SessionStore`
+is keyed by `pikkuUserId` and holds the user session, which is shared across HTTP
+and channel transports and outlives any one connection.
+
+The two are separate stores because their lifetimes and their scopes differ. One
+user may hold several sockets at once; writing socket-local data into the session
+would let those sockets overwrite each other and would leak connection state into
+HTTP requests. The serverless runner in `serverless/serverless-channel-runner.ts`
+rebinds `channel.setState/getState/clearState` onto the `ChannelStore` on every
+connect, message and disconnect precisely because there is no in-process channel
+object to hang the state off between invocations.
+
+**What this rules out:** backing `channel.setState` with the session store, or
+merging the two stores behind one interface "since both are key-value". Also
+rules out assuming channel state survives a reconnect — a new socket is a new
+`channelId` and starts empty.

package/knowledge/decisions/internals/channel-user-id-is-persisted-after-onconnect-middleware-runs.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: A channel's user id is persisted only after onConnect middleware has run
+description: The channelId to pikkuUserId mapping is written post-onConnect, because auth middleware is what establishes the session
+tags: channel
+---
+
+# A channel's user id is persisted only after onConnect middleware has run
+
+`runChannelConnect` in
+`packages/core/src/wirings/channel/serverless/serverless-channel-runner.ts`
+reads `userSession.getPikkuUserId()` and calls `channelStore.setPikkuUserId`
+*after* `runChannelLifecycleWithMiddleware` has executed the `onConnect`
+lifecycle, not before.
+
+Auth middleware runs as part of that lifecycle — it is what inspects the upgrade
+request's cookie or token and calls `setSession`. Before it runs there is no
+`pikkuUserId` to store, so an earlier write would persist `undefined` and the
+channel would stay anonymous for its whole life. That mapping is what
+`runChannelMessage` and `runChannelDisconnect` later use to rehydrate the session
+from the `sessionStore` on each subsequent invocation, since serverless keeps
+nothing in memory between them.
+
+**What this rules out:** moving the `setPikkuUserId` call up next to
+`channelStore.addChannel` to group the store writes together, and assuming a
+session exists on the wire before `onConnect` has completed. It also means an
+`onConnect` handler that throws leaves the channel with no user mapping — the
+error path deliberately does not persist one.

package/knowledge/decisions/internals/cli-option-names-are-camelcase-in-state-and-kebab-on-the-command-line.md

@@ -0,0 +1,27 @@
+---
+type: decision
+title: CLI option names are camelCase in state and kebab-case on the command line
+description: Option keys match the function's input field names so they can be plucked by schema, and are converted to kebab only for display and parsing
+tags: cli
+---
+
+# CLI option names are camelCase in state and kebab-case on the command line
+
+Every option key in `CLIOptions`, `CLICommandMeta.options` and the parsed
+`ParsedCommand.options` is camelCase, because it must line up with a field name
+on the command function's input type — that is what makes
+`pluckCLIData` in `packages/core/src/wirings/cli/cli-runner.ts` able to select
+fields by schema property name. Users type kebab-case.
+
+`toCamelCase` and `toKebabCase` in
+`packages/core/src/wirings/cli/command-parser.ts` are the only two points where
+the conversion happens. The parser normalises every incoming `--from-plan` to
+`fromPlan` on the way in, and both `formatOptions` (help text) and the
+"Missing required option" / "Invalid value for" errors render back to kebab on
+the way out. `suggestOption` deliberately compares the typed string against
+*both* forms, so `--autoApply` and `--auto-apply` both find `autoApply`.
+
+**What this rules out:** storing option keys kebab-cased anywhere in CLI state or
+metadata — the schema pluck would then match nothing and every option would be
+dropped. It also rules out emitting camelCase in help text or error messages,
+which would tell users to type a flag spelling that works only by accident.

package/knowledge/decisions/internals/cli-parse-errors-are-routed-by-message-prefix.md

@@ -0,0 +1,28 @@
+---
+type: decision
+title: CLI parse errors are routed by message prefix
+description: The CLI runners decide between printing help and printing errors by string-matching the prefixes the parser writes, so those message strings are an interface
+tags: cli
+---
+
+# CLI parse errors are routed by message prefix
+
+`parseCLIArguments` in `packages/core/src/wirings/cli/command-parser.ts` returns
+a flat `string[]` of errors. It has no error codes and no error types. The
+consumers — `executeCLI` in `cli-runner.ts` and `handleRawCLI` in
+`channel/cli-raw-channel-runner.ts` — decide whether the user made a routing
+mistake (show the help text) or a value mistake (print the errors) by
+`error.startsWith(...)` against three literals: `'Unknown command:'`,
+`'Command not found:'` and `'Missing subcommand:'`.
+
+This is why the parser pushes `Missing subcommand: <path>` for a group command
+that has subcommands but no `pikkuFuncId` of its own, rather than simply
+returning the command meta and letting the runner discover it is unrunnable. The
+message *is* the routing signal. Rewording any of those three strings, or
+localising them, silently turns "show me the subcommands" into a raw error dump.
+
+**What this rules out:** editing those error message prefixes without updating
+every `startsWith` site, and adding a new "this is a routing problem" parse error
+without registering its prefix in both runners. If this needs to grow, replace
+the whole scheme with a discriminated error type in one change — do not add a
+fourth magic prefix.

package/knowledge/decisions/internals/cli-stdout-is-reserved-for-machine-readable-output.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: CLI stdout is reserved for machine-readable output
+description: The default renderer emits single-line NDJSON, diagnostics go to stderr, and --json only hijacks rendering for commands that declared a renderer
+tags: cli
+---
+
+# CLI stdout is reserved for machine-readable output
+
+`defaultJSONRenderer` in `packages/core/src/wirings/cli/cli-runner.ts` (and its
+twin in `channel/cli-channel-runner.ts`) calls `JSON.stringify` without an
+indent argument. That is not laziness: one result per line is NDJSON, which stays
+parseable when a command streams multiple results through the CLI channel.
+Pretty-printing spreads one record over many lines and breaks every line-oriented
+consumer downstream.
+
+Two rules follow from the same principle in `executeCLI`. Parse warnings —
+non-fatal by design, see the unknown-options decision — are written with
+`console.error`, so they never interleave into a command's machine-readable
+stdout. And `--json` / `--output json` only substitutes `defaultJSONRenderer`
+when the command declared its own `render`; a command with no renderer is one
+that prints inline as it works, and forcing its return value through the JSON
+renderer would append a stray record after output that was never structured to
+begin with. The `commandRenderer !== undefined` guard in the render block is what
+enforces that.
+
+Error formatting follows too: `isExpectedError(error)` prints `error.message`
+alone with no `Error:` prefix, because an expected `PikkuError` (a build gate
+tripping, a validation failure) has a message written to be read as the whole
+output. Anything else is logged as an object so its stack survives.
+
+**What this rules out:** adding an indent argument to `defaultJSONRenderer`,
+routing warnings or progress messages to stdout, and dropping the
+`commandRenderer !== undefined` condition so `--json` applies uniformly.

package/knowledge/decisions/internals/cli-unknown-long-options-warn-instead-of-failing.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: CLI unknown long options warn instead of failing
+description: Unrecognised --long options are accepted, warned about and dropped so older binaries tolerate newer invocations, while unknown short flags stay hard errors
+tags: cli
+---
+
+# CLI unknown long options warn instead of failing
+
+`warnUnknownOption` in `packages/core/src/wirings/cli/command-parser.ts` pushes
+onto `ParsedCommand.warnings`, not `ParsedCommand.errors`, so an unrecognised
+`--long` option does not abort the command. The value is still parsed into
+`optionArgs`, but `pluckCLIData` in `cli-runner.ts` drops anything absent from
+the function's input schema — so the option is silently ignored at execution
+time. The warning exists precisely so that dropping is not silent.
+
+The reason is forward compatibility: a script or wrapper written against a newer
+command version may pass options an older installed binary does not know, and
+failing hard there turns a harmless extra flag into a broken pipeline.
+`RESERVED_OPTIONS` exempts flags the runner handles itself (`help`) from the
+warning. Unknown *short* flags are treated differently — they go to
+`result.errors` and do fail — because a bundled short-flag cluster like `-abc`
+cannot be reliably attributed, and a typo'd short flag is far more likely than a
+version skew.
+
+**What this rules out:** promoting unknown long options to errors "for
+strictness", and removing the warning on the grounds that the schema pluck
+already handles it — that restores the silent drop this was added to end. It also
+rules out making unknown short flags non-fatal for symmetry.

package/knowledge/decisions/internals/core-data-classification-brand-is-an-optional-property.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: The data-classification brand is an optional property
+description: Making __classification__ required would break ordinary Kysely operands, so the brand only constrains values flowing out
+tags: core
+---
+
+# The data-classification brand is an optional property
+
+`Private<T>`, `Pii<T>` and `Secret<T>` in
+`packages/core/src/data-classification.ts` brand a type with
+`{ readonly __classification__?: 'private' | 'pii' | 'secret' }` — and the
+marker is **optional on purpose**.
+
+A required property would make a plain value unassignable to a branded column: a
+`string` could no longer be passed where `Private<string>` is expected, which
+breaks every ordinary Kysely query operand — `where('email', '=', someString)`,
+inserts, and `.set(...)`. Making it optional keeps the brand structurally present
+so static analysis still sees it, while letting plain values flow *in*. The
+asymmetry is the point: the brand constrains what comes out of a query, not what
+goes into one.
+
+The consumer is `@pikku/inspector`, whose `findPiiPaths` reads the level union
+directly and whose PKU910 output check detects the brand on a function's return
+type. The brands are populated from `-- @private` / `-- @secret` / `-- @public`
+SQL comment annotations via `pikku db migrate`, which regenerates
+`outDir/db/schema.d.ts` and `outDir/db/classification.gen.ts`.
+
+**What this rules out:** making `__classification__` required to get stronger
+guarantees, or replacing the optional property with a unique symbol / nominal
+brand that behaves like a required one. Either change compiles here and then
+breaks every generated Kysely call site in every downstream project. It also
+rules out renaming the property or narrowing its literal union without updating
+`findPiiPaths` in the inspector, which matches on both.