@kici-dev/compiler 0.5.0 → 0.6.1

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

@@ -76,6 +76,8 @@ Trigger matching can query the **contents** of individual source files, not just
 
 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
@@ -86,20 +88,33 @@ After dispatch, each job runs in its own ephemeral agent sandbox: a shallow clon
 2. **Step-level rules**, then each step's `run()` body and its hooks.
 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              |
-| 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 |
-| 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.
 
@@ -149,6 +164,128 @@ 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"
+```
+
+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.
+
+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-public/blob/main/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 +308,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 +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 `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`, `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.
@@ -706,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.
@@ -736,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

@@ -577,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/
@@ -939,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.