@kici-dev/compiler 0.4.0 → 0.6.0

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

@@ -34,19 +34,19 @@ Your workflow is plain TypeScript, but different parts of it run at three distin
 
 ## The three phases
 
-| Phase            | Where it runs                            | What runs                                                                                                                                                     | When                      |
-| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| **Compile**      | Your dev machine or CI (`kici compile`)  | Load your workflow modules, validate the DAG, assign step IDs, analyze dynamic-value purity, emit `kici.lock.json`                                            | Before anything is pushed |
-| **Orchestrator** | Your orchestrator (no repo clone)        | Match triggers against the lock, evaluate **pure** inline dynamic values in a sandboxed JavaScript VM, dispatch jobs                                          | On each incoming event    |
-| **Agent**        | An ephemeral agent (fresh clone per job) | Load the workflow module, evaluate job and step rules, run step bodies and hooks, run impure dynamic-value init jobs and `dynamicJob` generators (both forms) | After dispatch            |
+| Phase            | Where it runs                            | What runs                                                                                                                                               | When                      |
+| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| **Compile**      | Your dev machine or CI (`kici compile`)  | Load your workflow modules, validate the DAG, assign step IDs, emit `kici.lock.json`                                                                    | Before anything is pushed |
+| **Orchestrator** | Your orchestrator (no repo clone)        | Match triggers against the lock and dispatch jobs; it never evaluates workflow code                                                                     | On each incoming event    |
+| **Agent**        | An ephemeral agent (fresh clone per job) | Load the workflow module, evaluate job and step rules, run step bodies and hooks, run dynamic-value init steps and `dynamicJob` generators (both forms) | After dispatch            |
 
 The lock file is the seam. Everything left of it is decided once at compile time and frozen into JSON; everything right of it reads that JSON. See [the lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/) and [the three-tier architecture](https://docs.kici.dev/architecture/overview/) for the wider picture.
 
 ## 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`, …), runs purity analysis over every dynamic-value function, and writes `kici.lock.json`.
+`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 (plus the serialized source of pure dynamic-value functions) 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 simply 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.
 
@@ -57,7 +57,7 @@ The lock is portable JSON. It carries:
 - Workflow and trigger metadata.
 - The job and step DAG, with compile-time step IDs.
 - Static values, verbatim.
-- The **source text** of pure dynamic-value functions, as inline expressions.
+- Markers noting which fields are dynamic, so the orchestrator knows to resolve them on the agent's init step.
 
 It does **not** carry:
 
@@ -70,11 +70,15 @@ The consequence is blunt: if a value isn't in the lock, the orchestrator can't s
 
 ## Orchestrator time
 
-On each event the orchestrator matches triggers using only the lock — it never clones your repository. Pure dynamic `context`, `env`, and `concurrencyGroup` functions are evaluated here, as inline expressions in a sandboxed JavaScript VM (~0ms overhead), instead of dispatching a separate job to resolve them.
+On each event the orchestrator matches triggers using only the lock — it never clones your repository and never evaluates workflow code. Dynamic `context`, `env`, and `concurrencyGroup` functions are not run here: the orchestrator dispatches a short init step to an agent to resolve them (see below).
 
-A runtime error in an inline expression fails the job immediately — there is no automatic fallback to the clone-and-evaluate path. The orchestrator does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
+Trigger matching can query the **contents** of individual source files, not just their paths: a `pr()`, `push()`, or `tag()` trigger with a [`requires`](https://docs.kici.dev/user/sdk/triggers/#content-requirements-requires) filter is matched by reading the named files at the event's commit and evaluating the filter as declarative data — still with no repository clone and no workflow code executed. A `requires` regex is checked for catastrophic (ReDoS) shapes at `kici compile` time and rejected there, so only safe patterns reach the orchestrator.
 
-See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for the exact rules that make a function pure or impure.
+The orchestrator also does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
+
+A workflow-level `filter` predicate is the same shape: the orchestrator sees only the lock's `hasFilter` flag, never the predicate, so it dispatches an evaluation job and lets an agent decide whether the workflow applies. Prefer the declarative filters where they answer the question — `commitMessage` on the trigger and `requires` over source files cost no evaluation job at all.
+
+See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for how dynamic `context`, `env`, and `concurrencyGroup` functions resolve.
 
 ## Agent time
 
@@ -82,23 +86,35 @@ After dispatch, each job runs in its own ephemeral agent sandbox: a shallow clon
 
 1. **Job-level rules** are evaluated. By this point the agent has already spawned and the source has already been restored, so a job that its rules skip has **still** paid for that spawn and clone; only its steps are avoided.
 2. **Step-level rules**, then each step's `run()` body and its hooks.
-3. **Impure** dynamic values are resolved here too, via an init job that clones and evaluates the function (~5–10s) before the real job runs.
+3. **Dynamic values** (`context`, `env`, `concurrencyGroup` functions) are resolved here, via a short `__init__` job that runs the function before the real job runs; this shows in the run timeline as an `Init:` entry.
 4. **`dynamicJob` generators run here — both forms.** The event-only (function) form runs in a dedicated evaluation job dispatched at event time; the result-aware (options) form is deferred until its declared `needs` complete, then run with the upstream outputs frozen as `ctx.needs`.
+5. **A workflow-level `filter` predicate runs here too**, before the jobs it gates. A global workflow evaluates it once per (event × workflow repo), before any run row exists, so a `false` verdict leaves no run at all. A same-repo workflow evaluates it once per job that reaches dispatch and once per job generator, after the run row exists, so a `false` verdict leaves a run whose only entries are the evaluation jobs. Keep the predicate cheap, pure, and side-effect free — a ten-job workflow calls it ten times for one event. See [narrowing with a filter](https://docs.kici.dev/user/global-workflows/#narrowing-with-a-filter).
 
 See [job execution](https://docs.kici.dev/architecture/execution/job-execution/) and [hooks and rules](https://docs.kici.dev/user/hooks/) for the details.
 
+## How a reused agent stays clean between jobs
+
+An ephemeral agent is discarded after one job, so residue never matters. A **reused agent** — a long-lived process on a shared host (the bare-metal profile) — serves many jobs in turn. Between them, the agent runs a supervisor-owned cleanup phase so one job's leftovers never reach the next:
+
+1. **It reaps the finished job's process tree.** A step may background a daemon that outlives the job. The agent runs each job's process in its own process group and signals the whole group when the job ends, so a stray daemon does not survive into the next job. Set `KICI_AGENT_ORPHAN_CLEANUP=false` to keep only the runner and leave a backgrounded process alive on purpose.
+2. **It re-runs declared cleanup after a hard kill.** A job's `cleanup` / `onFailure` hooks normally run in the job process. If that process is killed hard (out of memory, forced stop), the agent re-runs the declared cleanup against the preserved work directory.
+3. **It deletes the work directory.**
+4. **It runs an optional operator reset command.** Set `KICI_AGENT_BETWEEN_JOBS_RESET_COMMAND` to a host-reset command (for example, pruning a container cache). It runs after the reap and work-directory deletion. A failure never fails the finished job.
+
+This phase is the primary cross-job cleanup. The agent's startup temp-directory sweep stays as a backstop for anything a between-jobs phase missed. See [agent configuration](https://docs.kici.dev/operator/agent/configuration/) for the full env-var reference.
+
 ## What re-evaluates where
 
-| Construct                    | Runs on          | When                            |
-| ---------------------------- | ---------------- | ------------------------------- |
-| Static value                 | Compile → lock   | Never re-evaluated              |
-| Pure dynamic value           | Orchestrator VM  | Per event                       |
-| Impure dynamic value         | Agent init job   | Per event                       |
-| Job-level rules              | Agent            | After clone                     |
-| Step-level rules             | Agent            | Per step                        |
-| `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time        |
-| `dynamicJob` (options form)  | Agent            | Deferred until `needs` complete |
-| Step / job body + hooks      | Agent            | Per job                         |
+| Construct                    | Runs on          | When                                                 |
+| ---------------------------- | ---------------- | ---------------------------------------------------- |
+| Static value                 | Compile → lock   | Never re-evaluated                                   |
+| Dynamic value                | Agent init step  | Per event                                            |
+| Job-level rules              | Agent            | After clone                                          |
+| Step-level rules             | Agent            | Per step                                             |
+| `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time                             |
+| `dynamicJob` (options form)  | Agent            | Deferred until `needs` complete                      |
+| Workflow `filter` predicate  | Agent (eval job) | Per event (global) / per job + generator (same-repo) |
+| Step / job body + hooks      | Agent            | Per job                                              |
 
 **Determinism note.** `ctx.event` and `ctx.needs` are frozen snapshots — captured once and replayed unchanged on any re-evaluation. A generator that derives its output from them is stable across re-evaluations; one that reads the wall clock (`Date.now()`) or a random source (`Math.random()`) is not.
 
@@ -132,12 +148,11 @@ Outputs are typed across the job boundary too: reading `jobRef.result.…` or `c
 
 ## Common footguns
 
-| Symptom                                                                                                                        | Why                                                                                                                             | Fix                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| A top-level `let seen = 0` (or a cache filled in job A) is empty in job B                                                      | Each job loads the workflow module fresh in its own agent process after its own clone — there is no shared memory between jobs  | Pass data through step/job **outputs** (`OutputProxy` / `needs`), not module variables                                                   |
-| `context: (event) => event.ref + SUFFIX`, where `SUFFIX` is a module constant, silently falls back to the slower init-job path | Purity analysis only allows the function's own params, locals, and a fixed safe-globals set — a free identifier makes it impure | Inline the constant, or accept the init-job path knowingly. See [pure functions](https://docs.kici.dev/user/dynamic-values/#pure-functions-inline-evaluation)   |
-| Fan-out job identities shift between re-evaluations                                                                            | `ctx.event` / `ctx.needs` are frozen and replayed, but `Date.now()` / `Math.random()` are not                                   | Derive job identity only from the frozen event/needs snapshot                                                                            |
-| A rule-skipped job still spawned an agent and cloned                                                                           | Job-level rules evaluate agent-side, after dispatch and clone — not on the orchestrator                                         | This is by design: rules can read true runtime context (`$`, `changedFiles`, `env`). See [step-level rules](https://docs.kici.dev/user/hooks/#step-level-rules) |
+| Symptom                                                                   | Why                                                                                                                            | Fix                                                                                                                                      |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| A top-level `let seen = 0` (or a cache filled in job A) is empty in job B | Each job loads the workflow module fresh in its own agent process after its own clone — there is no shared memory between jobs | Pass data through step/job **outputs** (`OutputProxy` / `needs`), not module variables                                                   |
+| Fan-out job identities shift between re-evaluations                       | `ctx.event` / `ctx.needs` are frozen and replayed, but `Date.now()` / `Math.random()` are not                                  | Derive job identity only from the frozen event/needs snapshot                                                                            |
+| A rule-skipped job still spawned an agent and cloned                      | Job-level rules evaluate agent-side, after dispatch and clone — not on the orchestrator                                        | This is by design: rules can read true runtime context (`$`, `changedFiles`, `env`). See [step-level rules](https://docs.kici.dev/user/hooks/#step-level-rules) |
 
 ## See also
 
@@ -149,6 +164,124 @@ Outputs are typed across the job boundary too: reading `jobRef.result.…` or `c
 
 ---
 
+## Getting help
+
+Source: https://docs.kici.dev/user/getting-help/
+
+When something goes wrong, the fastest path to a fix is a report that already
+carries the context. This page covers what to try first, what to send, and how
+to send it privately.
+
+## Diagnose it yourself first
+
+Two commands answer most problems without anyone else involved:
+
+```bash
+# Check your own setup: login, org, lock file, orchestrator, agent labels
+kici doctor
+
+# Look at the org's infrastructure: orchestrators, scalers, agents
+kici diagnostics
+```
+
+`kici doctor` prints the next command to run for each problem it finds. Work
+down its output before reporting — a stale lock file or an expired login is a
+one-command fix.
+
+If your workflow ran and failed, read its logs:
+
+```bash
+kici runs show <run-id>
+kici runs logs <run-id>
+```
+
+[Common failures](https://docs.kici.dev/user/common-failures/) covers the errors people hit most.
+
+## Report a problem
+
+When you cannot resolve it yourself, gather a diagnostic bundle:
+
+```bash
+kici report --run <run-id> --message "what you expected, and what happened"
+```
+
+The command writes a ZIP and prints its path and `sha256`. It sends nothing.
+The bundle holds:
+
+- your CLI, Node, and orchestrator versions,
+- your redacted KiCI configuration,
+- your project's workflow list and lock-file state,
+- the failing run's detail and logs, when you pass `--run`,
+- a collection report saying which of those the command could and could not
+  read.
+
+Open the file and read it. It is yours until you decide to share it.
+
+### What gets redacted
+
+KiCI removes known secret shapes before anything enters the bundle:
+
+- API keys and access tokens (AWS, GitHub, Slack, KiCI agent tokens),
+- `Authorization` headers and JSON web tokens,
+- passwords inside connection URLs,
+- private keys and encrypted-value blocks,
+- values assigned to a secret-named key, such as `api_key=` or `password=`.
+
+Configuration is redacted twice: an allowlist keeps only known-safe fields, and
+the free-text scrubber runs over what remains.
+
+**Redaction is best effort.** A secret in a format KiCI does not recognize can
+survive it. Review the bundle before you share it. `--no-redact` turns
+redaction off and prints a warning — use it only for a bundle you keep.
+
+## Send it privately
+
+Reports contain your data, so there is no public tracker for them. Add
+`--upload` to send the bundle to KiCI directly:
+
+```bash
+kici report --run <run-id> --upload --message "matrix job hangs on macOS"
+```
+
+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.
+
+Add `--email` if you want a reply address attached to the report.
+
+## Manage what you have sent
+
+An upload is not permanent, and it is yours to revoke:
+
+```bash
+# See the reports you have uploaded
+kici report list
+
+# Delete an uploaded bundle
+kici report withdraw <ref>
+```
+
+Uploaded bundles expire automatically after 90 days.
+
+Anyone in your organization can upload a report. By default you see and
+withdraw your own. A member with the `support:admin` permission can manage
+every report in the organization, which is how an owner cleans up on behalf of
+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)
+instead.
+
+## See also
+
+- [Common failures](https://docs.kici.dev/user/common-failures/) — the errors people hit most, and their fixes
+- [CLI reference](https://docs.kici.dev/user/cli-reference/) — every `kici` command
+- [Dashboard](https://docs.kici.dev/user/dashboard/) — inspecting runs in the browser
+
+---
+
 ## Getting started with workflows
 
 Source: https://docs.kici.dev/user/getting-started/
@@ -171,11 +304,11 @@ npx kici init
 
 This will:
 
-1. Create `.kici/` directory with `workflows/`, `tests/`, `types/`, `package.json`, and `tsconfig.json`
+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
 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/`
+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)
 6. Optionally install a pre-commit hook to auto-compile workflows
 
 The package manager is detected from your repo's `packageManager` field, lockfile, or the manager that invoked `kici`, defaulting to npm. Pass `--package-manager <npm|pnpm|yarn>` to override it.
@@ -496,7 +629,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 `llms-full.txt` bundle to stdout, offline, straight from the installed `@kici-dev/compiler` package. Add `--index` to print the curated `llms.txt` index instead. 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`, `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.

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

@@ -304,12 +304,16 @@ export default workflow('ci', {
 
 Rule check functions receive a `RuleContext` with:
 
-| Property       | Type                                | Description                         |
-| -------------- | ----------------------------------- | ----------------------------------- |
-| `event`        | `EventPayload`                      | The triggering event data           |
-| `changedFiles` | `string[]`                          | Files changed in this event         |
-| `env`          | `Record<string, string\|undefined>` | Environment variables               |
-| `$`            | zx shell                            | Shell executor for running commands |
+| Property       | Type                                | Description                                                                                    |
+| -------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `event`        | `EventPayload`                      | The triggering event data                                                                      |
+| `changedFiles` | `string[]`                          | Files changed in this event                                                                    |
+| `sourceRepo`   | `RepoInfo \| undefined`             | The repo whose event triggered the run, when the evaluation has a checkout                     |
+| `workflowRepo` | `RepoInfo \| undefined`             | The repo that registered the workflow. The same repo as `sourceRepo` outside a global workflow |
+| `env`          | `Record<string, string\|undefined>` | Environment variables                                                                          |
+| `$`            | zx shell                            | Shell executor for running commands                                                            |
+
+`RepoInfo` carries `path` — an absolute path to that repo's checkout — plus optional `ref` and `sha`. In a [global workflow](https://docs.kici.dev/user/global-workflows/) the two are different repos, which is what lets one rule read the source repo's tree while the workflow lives elsewhere. Read _through_ `path`: its contents are stable, but the path itself differs between the evaluation and the later run.
 
 ### Marker rules
 
@@ -573,6 +577,181 @@ This workflow:
 
 ---
 
+## Git credentials
+
+Source: https://docs.kici.dev/user/patterns/git-credentials/
+
+Two facts drive everything on this page, and neither is guessable:
+
+- **Cloning your own repository needs no credential.** The framework checks it
+  out for you, and the app KiCI installs already holds read access.
+- **Pushing always needs a credential you supply.** The KiCI app holds read
+  access only, so every push — including to the job's own repository — needs one.
+
+## Declare credentials once, by name
+
+Credentials are declared on the job as a named map. **Every value is the name of
+a secret**, in `<context>:<secret-name>` form — never the credential itself:
+
+```typescript
+job('release', {
+  runsOn: 'linux',
+  gitCredentials: {
+    // `default` is used whenever a call names no credential
+    default: {
+      kind: 'app',
+      appIdSecret: 'ci:ACME_APP_ID',
+      installationIdSecret: 'ci:ACME_INSTALL_ID',
+      privateKeySecret: 'ci:ACME_APP_KEY',
+    },
+    forge: { kind: 'token', tokenSecret: 'ci:FORGE_PAT' },
+    vendor: { kind: 'ssh', privateKeySecret: 'ci:VENDOR_DEPLOY_KEY' },
+  },
+  steps: [build, tagAndPush],
+});
+```
+
+Store the secrets first with `kici-admin secret set`. Pasting a private key
+straight into the workflow is rejected when the workflow is defined, naming the
+field — a key written into `.kici/` would be committed to your repository.
+
+## Push
+
+Your checkout is read-only by default. Opening a write window is explicit:
+
+```typescript
+step('tag', async ({ $, repo }) => {
+  await $`git tag v${version}`;
+  await repo.withWrite({ permissions: { contents: 'write' } }, async () => {
+    await $`git push origin v${version}`;
+  });
+});
+```
+
+Inside the callback, git operations on that repository use a write credential.
+Outside it they do not, so an accidental push elsewhere in the job fails.
+
+Pass `credential: 'forge'` to use a named entry instead of `default`.
+
+**KiCI never guesses the permission set.** What a push needs depends on what is
+being pushed — changing anything under `.github/workflows/` additionally requires
+`workflows`:
+
+```typescript
+await repo.withWrite({ permissions: { contents: 'write', workflows: 'write' } }, async () => {
+  await $`git push origin HEAD`;
+});
+```
+
+If the app was not granted a permission you request, the forge refuses to issue
+the credential at all. The error names the repository and the permissions you
+asked for, **before any git command runs** — not at the end of a long build.
+
+## Clone more than one repository
+
+A workflow often needs several repositories, not just its own. Mint one token
+that covers all of them, then clone each with it:
+
+```typescript
+const { token } = await kici.git.github.getToken({
+  repositories: ['acme/app', 'acme/shared-lib'],
+  permissions: { contents: 'read' },
+});
+
+for (const repo of ['acme/app', 'acme/shared-lib']) {
+  await $`git clone https://x-access-token:${token}@github.com/${repo}.git`;
+}
+```
+
+A GitHub App token is issued per installation, so one call covers every
+repository you name. Each repository must be inside the app's installation. If
+one is not, the forge refuses the whole request and the error names it.
+
+The credential helper is installed on your own checkout only, so a repository
+you clone yourself does not inherit it. That is why this case mints a token
+rather than relying on the helper.
+
+## Call the forge API
+
+`gh` does not read git credential helpers, so this is the one case that wants the
+token as a value:
+
+```typescript
+const { token } = await kici.git.github.getToken({
+  repositories: ['acme/app'],
+  permissions: { contents: 'write' },
+});
+await $({ env: { ...process.env, GH_TOKEN: token } })`gh release create v${version}`;
+```
+
+The token is masked in step logs. Prefer `withWrite` for git itself, which never
+places a credential in the step environment.
+
+## Credentials that only exist at run time
+
+A credential fetched during the run — from a vault, or a cloud secret store via
+the job's OIDC identity — cannot be named ahead of time. Use the `*Value` half of
+the pair, which says "this is the credential, not a name for one":
+
+```typescript
+gitCredentials: { default: { kind: 'token', tokenValue: fetchedAtRuntime } }
+```
+
+To pass a derived credential to a **later** job, publish it with
+`ctx.setSecretOutput()` and name it with the reserved `needs:` context — that
+path is encrypted, scoped to the run, and deleted when the run ends:
+
+```typescript
+const mint = job('mint', {
+  runsOn: 'linux',
+  run: async (ctx) => {
+    const token = (await ctx.$`vault write -f auth/token/create`).stdout.trim();
+    ctx.setSecretOutput('FORGE_TOKEN', token);
+  },
+});
+
+const build = job('build', {
+  runsOn: 'linux',
+  needs: [mint],
+  gitCredentials: { default: { kind: 'token', tokenSecret: 'needs:FORGE_TOKEN' } },
+  steps: [cloneAndPush],
+});
+```
+
+Never put a credential in a regular job output: regular outputs are not masked,
+are stored, and are shown in the dashboard.
+
+For a **minted app token**, prefer re-deriving over transporting — those expire
+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.
+
+## How it works, and why long jobs still push
+
+An app token expires an hour after it is issued, and cannot be renewed. Rather
+than capture one at checkout time, the agent installs a git credential helper on
+the checkout: git asks it on every network operation, and it obtains a fresh
+credential each time. A push at the end of a three-hour build works exactly as it
+does at the start, and no credential is ever written into `.git/config`, into
+`git remote -v`, or into the step's environment.
+
+## Limits worth knowing
+
+- **Container jobs cannot use this yet.** A container job runs git inside the
+  container, which has no route to the credential service. Bare-metal jobs are
+  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 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.
+- **A credential you supply yourself cannot be narrowed.** A personal access
+  token or SSH key grants whatever it was created with, so a requested permission
+  set is reported as unscoped rather than pretended to be enforced.
+- **Being allowed to push is not the same as the push succeeding.** A branch
+  protection rule or repository ruleset can still reject it.
+
+---
+
 ## Host restart & wait-for-alive
 
 Source: https://docs.kici.dev/user/patterns/host-restart/
@@ -935,7 +1114,7 @@ export default workflow('on-forgejo-push', {
 **Caveat — cloning:** generic webhook sources deliver only the payload; they do not carry a clone token, and KiCI's automatic pre-step clone (`packages/agent/src/checkout/git-clone.ts`) is GitHub-only today (HTTPS + `http.extraHeader` Basic auth with a GitHub installation token). Three practical patterns:
 
 - **Mirror to GitHub and fan out.** Keep the repo on GitHub, register the workflow via a GitHub default-branch push, and have Gogs/Forgejo webhooks fan out via [cross-source delivery](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#cross-source-delivery). The clone runs against the GitHub mirror using the GitHub App's token.
-- **Clone yourself using a secret.** Set `checkout: false` on the job to skip the framework clone, store an SSH private key or forge personal access token as a secret, and run `git clone` explicitly in the first step. This works for any forge the agent can reach, no mirror needed. You still need a way to **register** the workflow — either keep a one-file GitHub repo whose only job is to own the registration, or bootstrap the registration manually against the orchestrator DB.
+- **Clone yourself using a declared credential.** Set `checkout: false` on the job to skip the framework clone, declare the forge credential on the job as a named `gitCredentials` entry (values are **secret names**, never the credential), and run `git clone` in the first step — the agent authenticates it for you, and the credential never appears in workflow source. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/). This works for any forge the agent can reach, no mirror needed. You still need a way to **register** the workflow — either keep a one-file GitHub repo whose only job is to own the registration, or bootstrap the registration manually against the orchestrator DB.
 - **Self-contained workflow.** No clone at all. The step reads whatever it needs from `rawPayload` (e.g., `rawPayload.after`, `rawPayload.repository.clone_url`) and drives external systems — notifications, deploys, third-party CI triggers.
 
 Manual-clone example (pattern 2) using an SSH deploy key:

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

@@ -144,38 +144,22 @@ the manifest flow — follow these steps.
 
 5. **Pick permissions.** Minimum required:
 
-   | Scope                       | Access       | Why                                                                                                                                                       |
-   | --------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | Repository -> Contents      | Read         | Clone the repo to read the lock file                                                                                                                      |
-   | Repository -> Metadata      | Read (auto)  | Default for every App; also lets KiCI look up a pull-request author's repository access level for CI trust                                                |
-   | Repository -> Pull requests | Read         | Match `pull_request` triggers                                                                                                                             |
-   | Repository -> Checks        | Read & write | Post KiCI's enriched Check runs                                                                                                                           |
-   | Organization -> Members     | Read         | (optional, org installs) Receive `organization` / `membership` / `team` events so KiCI's CI-trust permission cache invalidates promptly on access changes |
-
-   The first four rows cover the core flow (clone, trigger matching,
-   Check runs). The **Organization -> Members** row is only relevant if
-   you use [CI trust tiers](https://docs.kici.dev/architecture/security/ci-security/)
-   on an org-level install — see the event note below.
+   | Scope                       | Access       | Why                                  |
+   | --------------------------- | ------------ | ------------------------------------ |
+   | Repository -> Contents      | Read         | Clone the repo to read the lock file |
+   | Repository -> Metadata      | Read (auto)  | Default for every App                |
+   | Repository -> Pull requests | Read         | Match `pull_request` triggers        |
+   | Repository -> Checks        | Read & write | Post KiCI's enriched Check runs      |
+
+   Those four cover the whole flow: clone, trigger matching, Check runs.
+   [CI trust](https://docs.kici.dev/architecture/security/ci-security/) needs no
+   permission of its own — it reads the fork relationship straight out of
+   the webhook payload and calls no GitHub API.
 
 6. **Subscribe to events.** At minimum: `push`, `pull_request`,
    `check_run`, `check_suite`. Add others (`issues`, `release`, ...) if
    your workflows use those triggers.
 
-   **For CI trust (optional but recommended on org installs):** also
-   subscribe to `member`, `organization`, `membership`, and `team`.
-   KiCI caches each pull-request author's repository access level (used
-   to decide whether workflow changes take effect immediately or are
-   held for approval — see
-   [CI security](https://docs.kici.dev/architecture/security/ci-security/)). These
-   events let the orchestrator drop stale cache entries the moment a
-   contributor's access changes. They are not required for correctness:
-   without them the cache simply ages out on its own 15-minute TTL, so a
-   permission change can take up to 15 minutes to take effect. The
-   `organization` / `membership` / `team` events require the
-   **Organization -> Members** read permission and an org-level
-   installation; `member` is a repository event covered by the default
-   Metadata permission.
-
 7. **Generate a private key.** Scroll to the bottom of the App settings
    and click _Generate a private key_. A `.pem` file downloads —
    store it safely; you cannot redownload it.
@@ -312,9 +296,8 @@ when you want a list entry pinned to this specific App rather than
 applying to any source in the org:
 
 ```bash
-# Enable global workflows for the org
-kici-admin org-settings global-workflows set-enabled true \
-  --customer-id <orgId>
+# Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator)
+kici-admin cluster-settings set --global-workflows-enabled true
 
 # Allow the listed repo as an author for any source in the org
 kici-admin org-settings global-workflows allow-add 'my-org/ci-workflows/*' \
@@ -749,9 +732,8 @@ org-scoped (one row per `customer_id`); each list entry can optionally
 pin to a specific source via `--source <routingKey>`:
 
 ```bash
-# Enable global workflows for the org
-kici-admin org-settings global-workflows set-enabled true \
-  --customer-id <orgId>
+# Enable global workflows cluster-wide (the master switch is fleet-wide, held by the operator)
+kici-admin cluster-settings set --global-workflows-enabled true
 
 # Allow authors from any source in the org
 kici-admin org-settings global-workflows allow-add \