@kici-dev/compiler 0.6.1 → 0.8.0

package/dist/llm-context/llms-getting-started.txt

@@ -46,7 +46,7 @@ The lock file is the seam. Everything left of it is decided once at compile time
 
 `kici compile` loads your `.kici/workflows/*.ts`, validates dependencies (no cycles, no missing `needs`), assigns compile-time step IDs (unnamed steps become `step-1`, `step-2`, …), and writes `kici.lock.json`.
 
-The compiler runs your module's **top-level code** to build the workflow object — but that execution's side effects and in-memory state do not travel. Only the resulting workflow structure lands in the lock. Anything your top-level code computes that isn't part of the returned workflow object simply doesn't exist past this point.
+The compiler runs your module's **top-level code** to build the workflow object — but that execution's side effects and in-memory state do not travel. Only the resulting workflow structure lands in the lock. Anything your top-level code computes that isn't part of the returned workflow object doesn't exist past this point.
 
 See [compile the workflow](https://docs.kici.dev/user/getting-started/#compile-the-workflow) for the command in context.
 
@@ -202,7 +202,7 @@ kici runs logs <run-id>
 When you cannot resolve it yourself, gather a diagnostic bundle:
 
 ```bash
-kici report --run <run-id> --message "what you expected, and what happened"
+kici report --run <run-id>
 ```
 
 The command writes a ZIP and prints its path and `sha256`. It sends nothing.
@@ -309,7 +309,7 @@ npx kici init
 This will:
 
 1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`. The `types/` folder holds a local development aid — TypeScript declarations that `kici types` (and an authenticated `kici compile`) generate from your orchestrator's secret contexts. Its content is a snapshot of one org's secret keys, so it is not committed.
-2. Create a `.kiciignore` file with sensible defaults
+2. Create two `.kiciignore` files with sensible defaults: one at the repo root, which selects the working-tree files a remote run uploads, and one inside `.kici/`, which declares the paths the per-workflow content hash skips
 3. Let you choose from starter workflow templates (hello-world, pr-checks)
 4. Install dependencies using the package manager detected for your repo (npm, pnpm, or yarn)
 5. Update `.gitignore` to exclude `.kici/node_modules/`, and write `.kici/.gitignore` to keep the generated `types/` declarations untracked (`kici.lock.json` stays tracked — the orchestrator fetches it from your repo)
@@ -588,7 +588,7 @@ Point to a local SDK checkout for IDE autocompletion:
 {
   "name": "my-project-kici",
   "devDependencies": {
-    "@kici-dev/sdk": ">=0.0.1-0"
+    "@kici-dev/sdk": "latest"
   },
   "kici": {
     "sdkPath": "../../packages/sdk"
@@ -600,7 +600,7 @@ The `sdkPath` field tells the compiler where to resolve TypeScript path mappings
 
 ### KICI_DEV environment variable
 
-Set `KICI_DEV=true` to use a prerelease-compatible version range (`>=0.0.1-0`) in generated files, which resolves prerelease builds from a local Verdaccio registry:
+Set `KICI_DEV=true` to pin the SDK to the `latest` dist-tag in generated files, which resolves prerelease builds from a local Verdaccio registry:
 
 ```bash
 KICI_DEV=true npx kici init

package/dist/llm-context/llms-patterns.txt

@@ -725,6 +725,74 @@ For a **minted app token**, prefer re-deriving over transporting — those expir
 after an hour, so one minted in an earlier job is often already dead by the time
 a later job reads it. Have the later job name the same secret, or mint its own.
 
+## What a job may ask for
+
+A credential is authorized against the workflow you wrote, not against the code
+running in the job. Three things must all hold before the orchestrator resolves
+one:
+
+1. **The job declared it.** The orchestrator records the job's `gitCredentials`
+   map when it dispatches the job, and compares every request against that
+   record. A request naming a credential the job did not declare is refused.
+   This is why you pass `credential: 'forge'` — a name — rather than building a
+   credential reference in step code.
+2. **The named context admits the run.** A `prod:` reference runs the `prod`
+   context's own protection rules first: its branch restrictions, its
+   `minimumTrust`, its approval requirement. A credential named from a branch
+   the context does not allow is refused, and the git operation fails. The rule
+   that refused it is named in your orchestrator's log, not in the run — the
+   orchestrator returns a fixed error to the job rather than describing its own
+   configuration to code it does not trust.
+3. **The contributor is trusted.** A run from an untrusted ref — a fork pull
+   request — gets no declared credential at all. It still clones with the
+   source credential, so the build runs; only the declared credentials are
+   withheld. The reduced-privilege note on the run says so.
+
+The context in a reference does **not** have to appear in the job's `contexts:`
+list. The reference names its own context, and that context's rules are what
+authorize it.
+
+## Generated jobs
+
+A job produced by a `dynamicJob` generator has no entry in the lock file, so it
+cannot declare credentials of its own. The **generator** declares them, and every
+job it produces inherits that map:
+
+```typescript
+dynamicJob('shards', {
+  gitCredentials: {
+    forge: { kind: 'token', tokenSecret: 'ci:FORGE_PAT' },
+  },
+  generate: async ({ ctx }) =>
+    ctx.event.payload.targets.map((target) =>
+      job(`publish-${target}`, {
+        runsOn: 'linux',
+        run: async ({ $, repo }) => {
+          await repo.withWrite(
+            { permissions: { contents: 'write' }, credential: 'forge' },
+            async () => {
+              await $`git push origin HEAD`;
+            },
+          );
+        },
+      }),
+    ),
+});
+```
+
+Three points follow from where the declaration lives:
+
+- **All generated jobs share one map.** The generator is granted one ceiling, and
+  every job it produces gets exactly that ceiling. Use a second generator when
+  two sets of jobs need different credentials.
+- **A `gitCredentials` map on a generated job is ignored.** The generator's
+  declaration is committed source that KiCI reads from the lock file. A generated
+  job's own declaration would come from the code that produced it, which is what
+  the authorization check above exists to be independent of.
+- **The options form is required.** `dynamicJob('shards', async () => …)` — the
+  bare function form — has nowhere to put the declaration. Pass
+  `{ generate, gitCredentials }` instead; `needs` stays optional.
+
 ## How it works, and why long jobs still push
 
 An app token expires an hour after it is issued, and cannot be renewed. Rather
@@ -741,6 +809,10 @@ does at the start, and no credential is ever written into `.git/config`, into
   unaffected.
 - **The reserved `needs:` context is not resolvable yet** on a deployed
   orchestrator; naming it produces a clear error rather than a wrong credential.
+- **A credential reference built in step code is refused.** The SDK takes a
+  credential _name_; there is no way to pass a reference. Code that constructs
+  one and sends it directly is rejected by the agent and, if it reaches the
+  orchestrator, by the declaration check above.
 - **A write window is bounded by the repository and the callback, not the step.**
   Steps running concurrently in the same job can push to the same repository
   while it is open. They cannot reach a different one.
@@ -1075,8 +1147,10 @@ KiCI has no native provider for Gogs, Forgejo, or Gitea, but these forges send H
 ```bash
 # Forgejo / Gitea send event name in X-Gitea-Event and signature in X-Gitea-Signature.
 # Gogs uses X-Gogs-Event and X-Gogs-Signature (same HMAC-SHA256 hex-digest format).
+# --org must be your Platform organization id: a generic source's routing key
+# embeds it, and the Platform refuses to register a key naming another org.
 kici-admin source add generic \
-  --org my-org \
+  --org <platform-org-id> \
   --name forgejo-main \
   --verification hmac_sha256 \
   --secret @/path/to/webhook-secret.txt \
@@ -1084,7 +1158,7 @@ kici-admin source add generic \
   --rate-limit 120
 ```
 
-Note the returned source ID, then register a webhook in the forge pointing at `https://<platform>/webhooks/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL). Set content type to `application/json` and paste the same secret.
+Note the returned source ID, then register a webhook in the forge pointing at `https://<platform>/webhook/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL, which takes the source **name** in place of the id). Set content type to `application/json` and paste the same secret.
 
 **Workflow:**
 
@@ -1151,14 +1225,16 @@ HTTPS with a forge PAT works the same way — store the token as a secret, `awai
 
 ## Plain GitHub repo webhooks (no GitHub App)
 
-The Gogs/Forgejo/Gitea pattern above also applies when you want to trigger workflows from a GitHub repository **without installing the KiCI GitHub App** — for example because you lack org-admin rights, you're on a restricted GitHub Enterprise tenant, or you simply don't want an App installation. Model the repo-level webhook as a generic source, accepting the same `genericWebhook()`-only ergonomics.
+The Gogs/Forgejo/Gitea pattern above also applies when you want to trigger workflows from a GitHub repository **without installing the KiCI GitHub App**. You may lack org-admin rights, sit on a restricted GitHub Enterprise tenant, or not want an App installation. Model the repo-level webhook as a generic source, accepting the same `genericWebhook()`-only ergonomics.
 
 **Operator setup:**
 
 ```bash
 # GitHub sends event name in X-GitHub-Event and HMAC-SHA256 signature in X-Hub-Signature-256.
+# --org must be your Platform organization id: a generic source's routing key
+# embeds it, and the Platform refuses to register a key naming another org.
 kici-admin source add generic \
-  --org my-org \
+  --org <platform-org-id> \
   --name gh-repo-foo \
   --verification hmac_sha256 \
   --secret @/path/to/webhook-secret.txt \
@@ -1175,7 +1251,7 @@ curl -X PATCH https://<orchestrator>/api/v1/admin/generic-sources/<sourceId> \
 
 Then in the GitHub repo, go to **Settings → Webhooks → Add webhook**, set:
 
-- **Payload URL:** `https://<platform>/webhooks/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL)
+- **Payload URL:** `https://<platform>/webhook/<orgId>/generic/<sourceId>` (or the orchestrator's direct URL, which takes the source **name** in place of the id)
 - **Content type:** `application/json`
 - **Secret:** the same secret
 - **Events:** pick what you care about (e.g., `push`, `pull_request`)

package/dist/llm-context/llms-providers.txt

@@ -627,10 +627,14 @@ kici-admin secret set <orgId> "__source__/<sourceId>" pat --value "<your-forgejo
 Finally, configure the forge to deliver webhooks to:
 
 ```
-https://<platform-host>/webhook/<orgId>/generic/<source-name>
+https://<platform-host>/webhook/<orgId>/generic/<sourceId>
 ```
 
-with the same secret you passed to `--secret`.
+with the same secret you passed to `--secret`. `<orgId>` is your Platform
+organization id — the same value you passed to `--org`, which the source's
+routing key embeds — and `<sourceId>` is the id `source add` printed. The
+orchestrator's own ingest URL has the same shape but takes the source **name**
+in place of the id.
 
 ## SSH deploy key
 

package/dist/llm-context/llms-sdk-runtime.txt

@@ -617,7 +617,7 @@ The SDK exposes three idempotency helpers — a generic function `idempotent()`,
 2. **Apply** the change only when drift is detected.
 3. **Surface** the resource (or its identifier) on both branches, so downstream steps don't need to know whether work happened or was skipped.
 
-`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run --check` previews the drift without applying it.
+`idempotent()` and `idempotentStep()` wrap the same underlying runner and always apply on drift. Pick `idempotentStep()` when the operation is the whole job of a step; use `idempotent()` from anywhere — inside a multi-action step, a hook, or a bare async function. Pick `checkStep()` when the step should respect the run-level check mode — `kici run remote --check` previews the drift without applying it.
 
 ## `idempotent(options)`
 
@@ -712,30 +712,30 @@ export const setup = job('setup', {
 
 ## `checkStep(name, options)`
 
-The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run --check`):
+The check-mode-aware sibling of `idempotentStep()`. It takes a closely related option shape, but behaves differently when a run is started in check mode (`kici run remote --check`):
 
-| Factory          | Behavior under `kici run --check`         |
+| Factory          | Behavior under `kici run remote --check`  |
 | ---------------- | ----------------------------------------- |
 | `idempotentStep` | always applies on drift                   |
 | `checkStep`      | reports drift, applies only in apply mode |
 
-Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run --check` reports the drift and skips `apply`, `kici run --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
+Use `checkStep()` for deploy-style steps where you want a dry-run preview of pending changes before committing them, and `idempotentStep()` for steps that must always converge (for example inside a hook). A `checkStep()` desugars to the first-class step check facet (`check` / `summarize` / `run(ctx, drift)` / `whenInSync`), so it participates in run-level check mode automatically: `kici run remote --check` reports the drift and skips `apply`, `kici run remote --check --fail-on-drift` exits non-zero when drift is detected, and apply mode applies the change.
 
 ### Parameters
 
-| Name              | Type                                        | Required | Description                                                                                         |
-| ----------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                            |
-| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                |
-| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run --check`). |
-| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                |
-| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                              |
-| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                |
-| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                |
-| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                 |
-| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                        |
-| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                             |
-| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                 |
+| Name              | Type                                        | Required | Description                                                                                                |
+| ----------------- | ------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| `name`            | `string`                                    | Yes      | Step name. Appears in the run timeline and in log lines.                                                   |
+| `check`           | `(ctx) => Promise<TDrift \| null>`          | Yes      | Read-only inspection. Return `null` when the system is already in the desired state.                       |
+| `apply`           | `(ctx, drift: TDrift) => Promise<TApplied>` | Yes      | Brings the system to the desired state. Runs only in apply mode (skipped under `kici run remote --check`). |
+| `summarize`       | `(drift: TDrift) => string`                 | Yes      | Human-readable summary of what `apply()` would do; shown in check-mode drift output.                       |
+| `whenInSync`      | `(ctx) => Promise<TInSync>`                 | No       | Runs when `check()` returned `null` (already in sync).                                                     |
+| `outputs`         | `OutputSchema`                              | No       | Zod schema validating the step's outputs at runtime.                                                       |
+| `continueOnError` | `boolean`                                   | No       | When true, the job proceeds even if this step fails.                                                       |
+| `timeout`         | `number`                                    | No       | Step-level timeout in milliseconds.                                                                        |
+| `retry`           | `number \| RetryConfig`                     | No       | Retry policy for the step; `retry: N` is shorthand for `{ maxAttempts: N }`.                               |
+| `cache`           | `CacheInput`                                | No       | Declarative cache restored before the step and saved after it succeeds.                                    |
+| `rules`           | `Rule[]`                                    | No       | Step-level conditional rules, evaluated agent-side.                                                        |
 
 Everything from `outputs` down is a plain [`step()` option](https://docs.kici.dev/user/sdk/core/) forwarded to the underlying step. The three step options `checkStep` does **not** accept are `onCancel`, `cleanup`, and `approval`.
 
@@ -769,7 +769,7 @@ export const deploy = job('deploy', {
 });
 ```
 
-Run `kici run --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
+Run `kici run remote --check` against this workflow to see the drift summary without touching DNS; run it without `--check` to apply.
 
 ## Worked example: create-if-missing returning a resource id
 
@@ -1332,6 +1332,17 @@ interface StepContext<TInputs = Record<string, unknown>> {
   provider?: string;
   /** Whether this execution was triggered by `kici run remote` (developer-initiated remote run) */
   isTestRun: boolean;
+  /** The job's own checked-out repository (present for every job that checks out); `withWrite` opens a write window for it — see [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/) */
+  repo?: {
+    identifier: string;
+    path: string;
+    ref?: string;
+    sha?: string;
+    withWrite(
+      opts: { permissions?: Record<string, string>; credential?: string },
+      fn: () => Promise<void>,
+    ): Promise<void>;
+  };
   /** Registering repo of a global workflow (undefined for non-global workflows) */
   workflowRepo?: RepoInfo;
   /** Repo where the triggering event occurred (undefined for non-global workflows) */
@@ -1532,6 +1543,8 @@ const deploy = job('deploy', {
 
 Request a short-lived OIDC ID token for the current job, bound to an `audience`. The token is a signed JWT whose identity claims (`repository`, `ref`, `sha`, `kici_run_id`, `kici_job_id`) are derived by your orchestrator from the run context — a step cannot spoof them. Use it to authenticate the build to an external service that trusts the orchestrator's OIDC issuer (for example, when generating build provenance).
 
+The token also carries the event context a cloud trust policy needs to tell a fork pull request from a trusted push — `is_fork`, `head_repository`, `trust_tier`, `event_name`, and a pull-request-specific `sub`. See [ID-token claims and cloud trust policies](https://docs.kici.dev/user/provenance/#id-token-claims-and-cloud-trust-policies) for the full claim table and a worked AWS policy.
+
 ```typescript
 const publish = job('publish', {
   steps: [
@@ -1571,6 +1584,8 @@ interface HostInventoryEntry {
 
 Two dimensions describe a host. **Labels** are flat strings used for grouping and targeting (the same labels `runsOn` / `runsOnAll` match). **Properties** are typed host-vars (`string | number | boolean`) — the place for facts like `region`, `cores`, or `gpu`. A host reports its own properties via the agent's `KICI_PROPERTIES` config, and an operator can pre-declare them with `kici-admin host declare --prop key=value`; the two are shallow-merged (agent-reported keys win).
 
+`labels` and `hostname` come back lowercase — KiCI folds both, so a pool declaring `Docker` reports `docker`. Compare against a lowercase value: `h.labels.includes('gpu')`, not `h.labels.includes('GPU')`. A label selector passed to `query()` folds too, so `{ include: [['GPU']] }` matches. `agentId` and `properties` keep their case.
+
 ```typescript
 // All hosts:
 const all = await ctx.kici.inventory.query();

package/dist/llm-context/llms-sdk.txt

@@ -142,6 +142,7 @@ runsOn: { labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }
 
 - **Required labels:** The agent must have every label in the `labels` array (or the string/array form).
 - **Excluded labels:** The agent must NOT have any label in the `exclude` array. This includes auto-derived labels like `kici:arch:arm64`, `kici:os:linux`, etc.
+- **Case:** Label matching is **case-insensitive** at every step. `runsOn: 'gpu'` matches an agent that reports `GPU`, and a pool declaring `["Docker"]` serves a `runsOn: ["docker"]` job (see [auto-scaler matching rules](https://docs.kici.dev/operator/orchestrator/auto-scaler/operations/#matching-rules)). KiCI stores and displays every label in lowercase, so the dashboard, `kici-admin agent list`, and `ctx.kici.inventory[…].labels` report the folded form. Compare against a lowercase value when you read a label back in workflow code: `h.labels.includes('gpu')`, not `h.labels.includes('GPU')`.
 - **Compile-time validation:** The compiler will error if any label appears in both `labels` and `exclude` (overlap detection).
 - **Operator-declared mandatory labels:** Operators may mark a scaler with `mandatoryLabels` (Kubernetes-taint-style opt-in). When a scaler declares a mandatory label, a job is only allowed to land on it if `runsOn.labels` includes that label. A workflow targeting such a scaler must explicitly list the mandatory label in `runsOn`. See the [auto-scaler mandatory labels](https://docs.kici.dev/operator/orchestrator/auto-scaler/common-config/#mandatory--exclude-labels) for details.
 
@@ -194,6 +195,12 @@ Every selector element — in `runsOn`, in `runsOnAll`, on both the include and
 - **String with glob metacharacters (`*`, `?`, `[]`, `{}`) → glob.** `'kici:host:web-*'` matches every host label starting with `kici:host:web-`. `'kici:host:box-0[1-3]'` matches `box-01`, `box-02`, `box-03`.
 - **`RegExp` literal → regular expression.** `/kici:host:box-0[1-3]/` matches any label the expression matches.
 
+All three forms match case-insensitively. `'GPU'`, `'kici:host:Web-*'` and `/kici:host:BOX-0[1-3]/` each match a label of any case, and a `RegExp` you write with the `i` flag behaves the same. The `g` and `y` flags are dropped — a selector asks one question per label, so a sticky match would resume part-way through the next one.
+
+`kici:host:` carries the machine's hostname folded to lowercase. A host that calls itself `Build-Box-01` advertises `kici:host:build-box-01`, and both `runsOn: 'kici:host:build-box-01'` and `runsOn: 'kici:host:Build-Box-01'` match it.
+
+Case folding covers labels and hostnames only. An **agent ID** stays an opaque identifier and compares exactly, which is what keeps a per-host secret binding on `prod-01` away from an agent named `PROD-01` — see [per-host secret scoping](https://docs.kici.dev/operator/security/secrets/#per-host-secret-scoping).
+
 Both the required (include) side and the excluded side accept all three forms:
 
 ```typescript
@@ -852,11 +859,19 @@ Tag a dynamic job generator with a group name so other jobs can reference it via
 ```typescript
 function dynamicJob(
   groupName: string,
-  fnOrConfig: DynamicJobFn | { needs: DynamicJobNeed[]; generate: DynamicJobFn },
+  fnOrConfig:
+    | DynamicJobFn
+    | {
+        needs?: DynamicJobNeed[];
+        generate: DynamicJobFn;
+        gitCredentials?: GitCredentialMap;
+      },
 ): TaggedDynamicJobFn;
 ```
 
-The second argument is either a plain generator (event-only, evaluated at webhook time) or a result-aware `{ needs, generate }` config, which defers the generator until its declared upstreams complete and exposes their frozen outputs as `ctx.needs`. See [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) for the result-aware form.
+The second argument is either a plain generator (event-only, evaluated at webhook time) or an options config. An options config that declares `needs` is result-aware: it defers the generator until those upstreams complete and exposes their frozen outputs as `ctx.needs`. See [Rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) for the result-aware form.
+
+`needs` is optional. An options config without it is evaluated at webhook time, like the plain generator form. Use that form to declare `gitCredentials` on an event-only generator: every job the generator produces inherits the map, which is the only way a generated job gets named credentials. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/#generated-jobs).
 
 The generator runs twice: once in the init phase (to register expected job names) and once inside the executing agent (to produce the actual jobs). Mismatches between the two evaluations are detected as determinism drift -- see [dynamic-jobs](https://docs.kici.dev/architecture/execution/dynamic-jobs/).
 
@@ -1035,6 +1050,11 @@ The throw is a `ChangedFilesUnavailableError` (exported from `@kici-dev/sdk`, ca
 
 ### evaluateRules(rules, context, label, onRuleResult?)
 
+The agent calls this on your behalf. A workflow does not call it. It lives on
+`@kici-dev/sdk/internal`, outside semver, and stays exported from the root barrel as
+`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). It is described here
+because its return shape is what a rule's outcome looks like in the run log.
+
 Evaluate an array of rules sequentially with fail-fast behavior. Stops on the first failure.
 
 ```typescript
@@ -1102,7 +1122,7 @@ Every variant carries the shared `EventBase` fields — `type`, `action`, `targe
 
 Matrix configurations expand a single job into multiple instances, one per parameter combination. Maximum 256 combinations.
 
-Combinations must be **unique**. Two combinations that would produce the same instance name — most simply, the same value listed twice — fail the job instead of quietly running it twice.
+Combinations must be **unique**. Two combinations that would produce the same instance name — in the simplest case, the same value listed twice — fail the job instead of quietly running it twice.
 
 Expansion happens at **dispatch time**: the orchestrator materializes the matrix into N execution jobs — one per combination, each dispatched to its own agent — before any job runs. Each instance receives its combination as `ctx.matrix`. This is identical whether the workflow runs via `kici run <event> --local` or remotely through a webhook trigger, and the dashboard groups the N instances under one parent node.
 
@@ -1285,8 +1305,13 @@ isDynamicFunction(matrix); // true if async function
 
 ### Matrix expansion utilities
 
+The agent expands a matrix for you. A workflow does not call these. They live on
+`@kici-dev/sdk/internal`, outside semver, and stay exported from the root barrel as
+`@deprecated` until v1.0.0 — see [deprecations](https://docs.kici.dev/user/deprecations/). They are described
+here because they define the combinations a matrix job actually produces.
+
 ```typescript
-import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk';
+import { expandMatrix, applyIncludeExclude } from '@kici-dev/sdk/internal';
 ```
 
 `expandMatrix(matrix)` takes a string array or an object of string arrays and returns all combinations as `MatrixValues[]`. For a single-dimension array, each value becomes `{ value: '...' }`. For multi-dimensional objects, it produces the Cartesian product. Anything else throws a `MatrixShapeError` naming the expected shape; numbers and booleans inside the values are accepted and converted to strings.
@@ -1344,7 +1369,8 @@ export default workflow('ci', {
 `dynamicJob(group, fnOrConfig)` tags a generator with a group name (so static jobs can depend on it via `needs: [dynamicGroup('group')]`). It is polymorphic:
 
 - **Function form** — event-only, dispatched at webhook time: `dynamicJob('shards', async ({ ctx }) => [...])`.
-- **Options-object form** — result-aware, deferred until its declared `needs` complete, then run with the upstreams' frozen outputs as `ctx.needs`: `dynamicJob('reports', { needs, generate })`.
+- **Options-object form** — `dynamicJob('reports', { needs, generate })`. With `needs`, it is result-aware: deferred until those upstreams complete, then run with their frozen outputs as `ctx.needs`.
+  - `needs` is optional. Without it the generator is dispatched at webhook time, like the function form. That form is how a generator declares `gitCredentials`, which every job it produces inherits — see [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/#generated-jobs).
 
 ```typescript
 import { workflow, job, step, dynamicJob, dynamicGroup, z } from '@kici-dev/sdk';
@@ -1517,7 +1543,7 @@ those files contain**. It is a declarative filter on the `pr()`, `push()`, and
 at the event's commit. The orchestrator evaluates it as pure data before
 dispatching — it reads only the referenced files, never clones the whole
 repository, and never runs any of your workflow code. A workflow whose `requires`
-does not pass is simply not dispatched.
+does not pass is not dispatched.
 
 Each entry is a `ContentRequirement`:
 
@@ -1782,7 +1808,7 @@ dispatch({ types: ['deploy', 'rollback'] }); // Specific event types
 #### Typed dispatch inputs
 
 A `dispatch()` trigger can declare a typed `inputs` schema. Operators supply
-values with `kici run --input key=value`; KiCI validates, coerces, defaults, and
+values with `kici run remote --input key=value`; KiCI validates, coerces, defaults, and
 exposes them to steps and rules as `ctx.dispatchInputs`. The values are validated
 on the orchestrator from the compiled lock file — a missing required input or a
 bad value is rejected before any agent runs, without cloning the repository.
@@ -2497,6 +2523,20 @@ import { workflow, job, step, pr, push, rule, defineEvent } from '@kici-dev/sdk'
 
 For the complete list of every named export (factory functions, triggers, rules, validation, hook factories, types), see the per-topic pages above.
 
+## `@kici-dev/sdk/internal` is not a supported surface
+
+The package also publishes an `@kici-dev/sdk/internal` subpath. It carries the runtime
+contract between the SDK and the KiCI agent. Those are the functions that install the maps
+a `.result` proxy reads, build the step context your workflow body receives, evaluate its
+rules, and expand its matrix. The agent drives all of it on your behalf.
+
+It is **not covered by semver** and may change shape in any release. Do not import it from
+a workflow. Everything a workflow author needs is on the root entry point above.
+
+Those same symbols are also still exported from the root barrel, marked `@deprecated`, so
+an older SDK in a repository keeps working. They are removed from the root at v1.0.0 — see
+[deprecations](https://docs.kici.dev/user/deprecations/).
+
 ## See also
 
 - [Getting started](https://docs.kici.dev/user/getting-started/) -- install the SDK, write your first workflow, test locally

package/dist/llm-context/llms.txt

@@ -11,15 +11,15 @@ Found a mismatch between what these docs advertise and what KiCI does? Read http
 Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
 
 - [getting-started](https://docs.kici.dev/llms-getting-started.txt) (65 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
-- [patterns](https://docs.kici.dev/llms-patterns.txt) (57 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
-- [sdk](https://docs.kici.dev/llms-sdk.txt) (127 KB) — Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs
-- [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (114 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
-- [cli](https://docs.kici.dev/llms-cli.txt) (90 KB) — Running the CLI locally: compile, test, run local, hooks, lock-file drift, common failures
-- [cli-remote](https://docs.kici.dev/llms-cli-remote.txt) (106 KB) — Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to
-- [features](https://docs.kici.dev/llms-features.txt) (90 KB) — Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access
-- [features-execution](https://docs.kici.dev/llms-features-execution.txt) (121 KB) — Concurrency, dynamic values, events, container jobs, environment variables, global workflows, idempotent steps
+- [patterns](https://docs.kici.dev/llms-patterns.txt) (61 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
+- [sdk](https://docs.kici.dev/llms-sdk.txt) (131 KB) — Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs
+- [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (115 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
+- [cli](https://docs.kici.dev/llms-cli.txt) (97 KB) — Running the CLI locally: compile, test, run local, hooks, lock-file drift, common failures
+- [cli-remote](https://docs.kici.dev/llms-cli-remote.txt) (111 KB) — Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to
+- [features](https://docs.kici.dev/llms-features.txt) (97 KB) — Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access
+- [features-execution](https://docs.kici.dev/llms-features-execution.txt) (124 KB) — Concurrency, dynamic values, events, container jobs, environment variables, global workflows, idempotent steps
 - [providers](https://docs.kici.dev/llms-providers.txt) (35 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
-- [architecture](https://docs.kici.dev/llms-architecture.txt) (99 KB) — How the runtime works: three-tier relay model, data flows, configuration
+- [architecture](https://docs.kici.dev/llms-architecture.txt) (100 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
 ## Getting started
 

package/dist/local-plane/orchestrator-process.d.ts

@@ -1,11 +1,3 @@
-/**
- * Resolve a host address the plane's co-located bare-metal agent can reach for
- * cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
- * storage URL (it assumes remote agents), so the plane advertises its first
- * non-internal IPv4 (still this machine — the agent is co-located). Falls back
- * to the hostname when no external interface is present.
- */
-export declare function resolveAgentReachableHost(): string;
 /**
  * Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
  * launches in independent (offline) mode.

package/dist/local-plane/orchestrator-process.js

@@ -1,22 +1,11 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { planePaths, planePorts } from "./paths.js";
+import { rotatePlaneLogIfOversized } from "./plane-log.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import { spawn } from "node:child_process";
-import os from "node:os";
 //#region src/local-plane/orchestrator-process.ts
 /**
-* Resolve a host address the plane's co-located bare-metal agent can reach for
-* cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
-* storage URL (it assumes remote agents), so the plane advertises its first
-* non-internal IPv4 (still this machine — the agent is co-located). Falls back
-* to the hostname when no external interface is present.
-*/
-function resolveAgentReachableHost() {
-	for (const addrs of Object.values(os.networkInterfaces())) for (const a of addrs ?? []) if (a.family === "IPv4" && !a.internal) return a.address;
-	return os.hostname();
-}
-/**
 * Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
 * launches in independent (offline) mode.
 */
@@ -60,6 +49,7 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 	const { logFile, root, cacheDir } = planePaths();
 	fs.mkdirSync(root, { recursive: true });
 	fs.mkdirSync(cacheDir, { recursive: true });
+	rotatePlaneLogIfOversized(logFile);
 	const out = fs.openSync(logFile, "a");
 	const baseEnv = {};
 	for (const [key, value] of Object.entries(process.env)) if (!key.startsWith("KICI_")) baseEnv[key] = value;
@@ -68,7 +58,9 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 		KICI_PORT: String(port),
 		KICI_DATABASE_URL: databaseUrl,
 		KICI_AGENT_AUTH: "none",
+		KICI_HOST: "127.0.0.1",
 		KICI_AUTO_MIGRATE: "true",
+		KICI_CLUSTER_SINGLE_NODE: "true",
 		KICI_DATA_DIR: root,
 		KICI_BOOTSTRAP_ADMIN_TOKEN: opts.adminToken,
 		KICI_SECRET_KEY: opts.secretKey,
@@ -76,7 +68,7 @@ function spawnOrchestratorProcess(databaseUrl, opts) {
 		KICI_WEBHOOK_PUBLIC_URL: `http://127.0.0.1:${port}`,
 		KICI_STORAGE_TYPE: "filesystem",
 		KICI_STORAGE_FS_PATH: cacheDir,
-		KICI_STORAGE_FS_BASE_URL: `http://${resolveAgentReachableHost()}:${port}`
+		KICI_STORAGE_FS_BASE_URL: `http://127.0.0.1:${port}`
 	};
 	let entry;
 	let modeEnv;
@@ -124,6 +116,6 @@ async function awaitOrchestratorReady(port, attempts = 120, intervalMs = 500) {
 	throw new Error("local orchestrator did not become ready");
 }
 //#endregion
-export { awaitOrchestratorReady, orchestratorReady, resolveAgentReachableHost, resolveServerEntry, resolveStandaloneEntry, spawnOrchestratorProcess };
+export { awaitOrchestratorReady, orchestratorReady, resolveServerEntry, resolveStandaloneEntry, spawnOrchestratorProcess };
 
 //# sourceMappingURL=orchestrator-process.js.map

package/dist/local-plane/paths.d.ts

@@ -33,6 +33,7 @@ export declare function planePaths(): {
     pidfile: string;
     stampFile: string;
     logFile: string;
+    pgLogFile: string;
     socketDir: string;
     adminTokenFile: string;
     platformTokenFile: string;

package/dist/local-plane/paths.js

@@ -48,6 +48,7 @@ function planePaths() {
 		pidfile: path.join(root, "plane.pid"),
 		stampFile: path.join(root, "stamp.json"),
 		logFile: path.join(root, "orchestrator.log"),
+		pgLogFile: path.join(root, "orchestrator.log.pg"),
 		socketDir: path.join(root, "sock"),
 		adminTokenFile: path.join(root, "admin-token"),
 		platformTokenFile: path.join(root, "platform-token"),

package/dist/local-plane/plane-log.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Size at which a local dev plane log is rotated on the next plane start.
+ *
+ * The plane's orchestrator writes one JSON line per request and per
+ * scheduled-job tick, and nothing truncates the file between boots, so an
+ * unrotated log grows without bound. 50 MB is roughly 200k lines — more history
+ * than a local debugging session reads.
+ */
+export declare const PLANE_LOG_MAX_BYTES: number;
+/** The cap expressed in whole megabytes, for the messages that name it. */
+export declare const PLANE_LOG_MAX_MB: number;
+/**
+ * Rotate `file` to `<file>.1` once it reaches `PLANE_LOG_MAX_BYTES`, keeping two
+ * generations: any previous `.1` is discarded.
+ *
+ * Call this only where nothing holds the file open. A rename under a live
+ * writer leaves that writer appending to the renamed inode, so the live log
+ * would stay empty for the rest of the process's life.
+ *
+ * Every failure is swallowed on purpose. Both callers are on a plane-boot path:
+ * `startPlanePostgres` reads a throw as "embedded Postgres is unavailable" and
+ * silently falls back to a Podman container, and `spawnOrchestratorProcess`
+ * would fail the boot outright. A log that cannot be rotated must not cost the
+ * user their plane.
+ */
+export declare function rotatePlaneLogIfOversized(file: string): void;
+//# sourceMappingURL=plane-log.d.ts.map

package/dist/local-plane/plane-log.js

@@ -0,0 +1,39 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import fs from "node:fs";
+//#region src/local-plane/plane-log.ts
+/**
+* Size at which a local dev plane log is rotated on the next plane start.
+*
+* The plane's orchestrator writes one JSON line per request and per
+* scheduled-job tick, and nothing truncates the file between boots, so an
+* unrotated log grows without bound. 50 MB is roughly 200k lines — more history
+* than a local debugging session reads.
+*/
+const PLANE_LOG_MAX_BYTES = 52428800;
+/** The cap expressed in whole megabytes, for the messages that name it. */
+const PLANE_LOG_MAX_MB = PLANE_LOG_MAX_BYTES / 1048576;
+/**
+* Rotate `file` to `<file>.1` once it reaches `PLANE_LOG_MAX_BYTES`, keeping two
+* generations: any previous `.1` is discarded.
+*
+* Call this only where nothing holds the file open. A rename under a live
+* writer leaves that writer appending to the renamed inode, so the live log
+* would stay empty for the rest of the process's life.
+*
+* Every failure is swallowed on purpose. Both callers are on a plane-boot path:
+* `startPlanePostgres` reads a throw as "embedded Postgres is unavailable" and
+* silently falls back to a Podman container, and `spawnOrchestratorProcess`
+* would fail the boot outright. A log that cannot be rotated must not cost the
+* user their plane.
+*/
+function rotatePlaneLogIfOversized(file) {
+	try {
+		if (fs.statSync(file).size < 52428800) return;
+		fs.rmSync(`${file}.1`, { force: true });
+		fs.renameSync(file, `${file}.1`);
+	} catch {}
+}
+//#endregion
+export { PLANE_LOG_MAX_BYTES, PLANE_LOG_MAX_MB, rotatePlaneLogIfOversized };
+
+//# sourceMappingURL=plane-log.js.map

package/dist/local-plane/plane-manager.js

@@ -19,8 +19,8 @@ import { generateKeyPairSync, randomBytes } from "node:crypto";
 */
 function currentBuildIdentity() {
 	return {
-		version: "0.6.1",
-		buildCommit: "d32193b6b"
+		version: "0.8.0",
+		buildCommit: "57712173f"
 	};
 }
 /**