@kici-dev/compiler 0.6.0 → 0.7.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.
@@ -243,6 +243,10 @@ Reports contain your data, so there is no public tracker for them. Add
 kici report --run <run-id> --upload --message "matrix job hangs on macOS"
 ```
 
+A defect in KiCI itself is different: if you can reproduce it without your own
+data — the docs promise something the tool does not do — it belongs in the
+public tracker instead. See [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/).
+
 The command prints a reference id. Quote it in any conversation about the
 problem. The bundle goes straight from your machine to KiCI storage over a
 one-time upload link — it never passes through the dashboard.
@@ -271,7 +275,7 @@ someone who has left.
 ## Reporting a security issue
 
 Do not use `kici report` for a suspected vulnerability. Follow the disclosure
-process in [SECURITY.md](https://github.com/kici-dev/kici/blob/master/SECURITY.md)
+process in [SECURITY.md](https://github.com/kici-dev/kici-public/blob/main/SECURITY.md)
 instead.
 
 ## See also
@@ -305,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)
@@ -629,7 +633,7 @@ For coding agents that want the entire documentation set up front, KiCI follows
 
 - `https://kici.dev/llms.txt` — curated link index grouped by SDK / patterns / CLI / architecture.
 - `https://kici.dev/llms-full.txt` — concatenated markdown of every page indexed above.
-- `kici docs llm` — print the same curated `llms.txt` index to stdout, offline, straight from the installed `@kici-dev/compiler` package. `kici docs llm <topic>` prints one task bundle (`getting-started`, `patterns`, `sdk`, `sdk-runtime`, `cli`, `features`, `features-execution`, `providers`, `architecture`), and `kici docs llm full` prints the whole `llms-full.txt`. Add `--out <path>` to write to a file. The agent can pipe the output into its own context buffer with no network call.
+- `kici docs llm` — print the same curated `llms.txt` index to stdout, offline, straight from the installed `@kici-dev/compiler` package. `kici docs llm <topic>` prints one task bundle (`getting-started`, `patterns`, `sdk`, `sdk-runtime`, `cli`, `cli-remote`, `features`, `features-execution`, `providers`, `architecture`), and `kici docs llm full` prints the whole `llms-full.txt`. Add `--out <path>` to write to a file. The agent can pipe the output into its own context buffer with no network call.
 - `kici docs` — open the docs site in your browser.
 
 The offline bundle is regenerated from `docs/` every time the package is built, so it always matches the version of KiCI you've installed.
@@ -839,6 +843,12 @@ KiCI offers two equally-supported quickstart paths. Pick the one that fits your
 
 Each guide is split into two parts. **Part 1** gets you a green run against your own orchestrator with `kici run remote` — no GitHub App needed, just sign up, bring up the stack, and run. **Part 2** then wires up real GitHub pushes so your team's commits trigger runs automatically. You can stop after Part 1 and come back to Part 2 whenever you're ready.
 
+## Bring a coding agent
+
+Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/docs/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
+
+If your agent finds that these docs promise something KiCI does not do, that is worth telling us — `kici feedback` prints how to report it, and [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/) is the full guide.
+
 ## Option A — Docker / Podman (recommended)
 
 Two containers brought up with `docker compose up -d` (orchestrator + PostgreSQL), plus one short-lived agent container spawned per job by the container scaler. Minimal host setup, perfect for a laptop, home server, or a tiny VM. No need to install PostgreSQL or any other system service.
@@ -869,6 +879,143 @@ Both quickstarts deploy a real orchestrator + agent. If you only want to write a
 
 ---
 
+## Reporting a discrepancy
+
+Source: https://docs.kici.dev/user/reporting-discrepancies/
+
+This page is addressed to a **coding agent** working with KiCI. KiCI is built to
+be driven by an LLM, so an agent is often the first to notice a mismatch. A
+documented flag does not exist; a command prints something the docs never
+promised. You can report that.
+
+A human reader can use this page too. The rules below exist because the tracker
+is public and you are filing under someone else's GitHub identity.
+
+Run `kici feedback` to print this contract in your terminal, or
+`kici feedback --json` to read it as structured data.
+
+## The rule, in one sentence
+
+You find a checkable mismatch between what the docs or the CLI advertise and
+what KiCI actually does. You draft an issue carrying a reproduction and a
+justification, and show it to the person you are working with. You file it only
+after they say yes.
+
+You never file on your own initiative.
+
+## What qualifies
+
+Report it when you can point at the claim and at the contradicting behaviour:
+
+- A documented flag, command, or option that does not exist in the version you ran.
+- Documented output — a shape, a field, an exit code — that differs from what the command produced.
+- A CLI `--help` description that contradicts the published docs.
+- A documented behaviour that does not happen, or a documented guarantee that does not hold.
+- A documented error or limit that the tool does not actually enforce.
+
+Two conditions apply to all of them. You ran the command and saw the result —
+inference from reading the docs is not a reproduction. And you ran a published
+version: check with `kici --version`.
+
+## What does not qualify
+
+- Usage questions, or behaviour you find surprising but that the docs describe correctly.
+- Feature requests and design preferences.
+- Anything you inferred from reading docs without running the command.
+- Anything reproduced only on a locally built or unreleased version.
+- A failure that is your workflow, your credentials, or your environment.
+
+If you are unsure whether the docs are wrong or you misread them, you are not
+ready to file. Say so to the person you are working with and let them decide.
+
+## Never file these publicly
+
+**A suspected vulnerability is never a public issue.** Do not file it, and do
+not describe it in one. Open a private
+[security advisory](https://github.com/kici-dev/kici-public/security/advisories/new)
+instead, or tell the person you are working with to. This holds even if the
+issue looks minor to you.
+
+**A problem with someone's own runs is not a tracker issue.** That covers a
+failing run, a broken deployment, and anything that needs their logs. Use the
+private path in [Getting help](https://docs.kici.dev/user/getting-help/) instead:
+`kici report --run <run-id> --upload` sends a redacted bundle straight to KiCI.
+
+**Never put customer data in a public issue:**
+
+- No secrets, tokens, or credentials — not even redacted-looking ones.
+- No private repository names, internal hostnames, organization ids, or run ids.
+- No log excerpts you have not read line by line.
+- Reproduce with a minimal synthetic workflow, never the real one you were working on.
+
+Rewriting the reproduction against a throwaway workflow in an empty directory is
+the reliable way to satisfy all four at once.
+
+## Search before you draft
+
+The tracker is small. The same finding arriving once per agent that reads the
+docs is worse than not hearing it at all:
+
+```bash
+gh issue list --repo kici-dev/kici-public --search "<terms>" --state all
+```
+
+Search closed issues too — a closed one may carry the answer, or the decision
+that the behaviour is intended. If a matching issue is open, add your
+reproduction as a comment instead of opening a second one, under the same
+approval rule.
+
+## What the report must carry
+
+Five things. A report missing any of them cannot be acted on:
+
+| Field                                 | What it holds                                                                                                        |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| What the docs or CLI advertise        | The exact claim, quoted, plus its source: a docs URL or the command whose `--help` says it.                          |
+| What actually happened                | The real output or behaviour, quoted, with any error text.                                                           |
+| Minimal reproduction, including setup | Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran. |
+| Version and environment               | Output of `kici --version`, plus Node version and OS.                                                                |
+| Why this is a discrepancy             | One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed.        |
+
+The last field is the one agents skip, and it is the one that makes a report
+usable. "The docs say `--foo` exists and it does not" is a claim. "`--foo` is
+documented at <url>, and `kici bar --help` on 0.1.16 lists no such flag" is a
+finding someone can act on in one pass.
+
+Include setup steps whenever your reproduction needed any. A reproduction that
+starts from state a maintainer cannot recreate is not a reproduction.
+
+## Filing it
+
+The tracker is [kici-dev/kici-public](https://github.com/kici-dev/kici-public),
+and the form is **Agent report**:
+
+```bash
+kici feedback --open
+```
+
+Draft the complete body first. Show it to the person you are working with —
+the whole body, not a summary of it. File only after they say yes:
+
+```bash
+gh issue create --repo kici-dev/kici-public --template agent_report.yml
+```
+
+The form asks you to confirm the report was drafted by an agent and reviewed by
+a person before filing. Answer honestly; it is what lets maintainers triage
+agent-filed reports as a group.
+
+If they say no, that is the end of it. Do not re-file the same finding in
+another form, and do not open it as a question instead.
+
+## See also
+
+- [Getting help](https://docs.kici.dev/user/getting-help/) — the private path for a problem with your own runs
+- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) — the MCP server, and the agent safety model
+- [Common failures](https://docs.kici.dev/user/common-failures/) — check here before concluding the docs are wrong
+
+---
+
 ## Why KiCI
 
 Source: https://docs.kici.dev/user/why-kici/

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
 
@@ -1532,6 +1532,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 +1573,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