@kici-dev/compiler 0.1.3 → 0.1.6

package/dist/cli.js

@@ -22,7 +22,7 @@ import "./commands/index.js";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.3";
+const version = "0.1.6";
 const program = new Command();
 program.name("kici").description("KiCI workflow compiler").version(version);
 program.hook("preAction", () => {
@@ -50,7 +50,7 @@ program.command("fixture").addArgument(fixtureEventArg).description("Generate fi
 	await fixtureCommand(event, options);
 });
 const runCommand = program.command("run").description("Execute workflows locally or remotely");
-runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").action(async (event, options) => {
+runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).action(async (event, options) => {
 	if (options.pick && options.workflow) {
 		console.error("Error: --pick is mutually exclusive with --workflow.");
 		process.exit(2);
@@ -76,7 +76,9 @@ runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open
 		junit: options.junit,
 		files: options.files,
 		debug: options.debug,
-		kiciDir: options.kiciDir
+		kiciDir: options.kiciDir,
+		inPlace: options.inPlace,
+		keep: options.keep
 	});
 	process.exit(success ? 0 : 1);
 });

package/dist/commands/login.js

@@ -48,16 +48,15 @@ async function oauthLogin(options) {
 	const platformUrl = options.platformEndpoint || process.env.KICI_PLATFORM_URL || "";
 	const issuer = process.env.KICI_OIDC_ISSUER || "";
 	const clientId = process.env.KICI_OIDC_CLIENT_ID || "";
-	const projectId = process.env.KICI_OIDC_PROJECT_ID || "";
 	const missing = [];
 	if (!platformUrl) missing.push("KICI_PLATFORM_URL");
 	if (!issuer) missing.push("KICI_OIDC_ISSUER");
 	if (!clientId) missing.push("KICI_OIDC_CLIENT_ID");
 	if (missing.length > 0) {
 		console.error(pc.red(`Error: missing required env var(s) for OAuth login: ${missing.join(", ")}`));
-		console.error(pc.gray("  Set them to your Platform and Zitadel endpoints, for example:"));
+		console.error(pc.gray("  Set them to your Platform and IdP endpoints, for example:"));
 		console.error(pc.gray("    export KICI_PLATFORM_URL=https://your-platform.example.com"));
-		console.error(pc.gray("    export KICI_OIDC_ISSUER=https://your-zitadel.example.com"));
+		console.error(pc.gray("    export KICI_OIDC_ISSUER=https://your-idp.example.com"));
 		console.error(pc.gray("    export KICI_OIDC_CLIENT_ID=<cli-client-id>"));
 		return false;
 	}
@@ -66,12 +65,11 @@ async function oauthLogin(options) {
 	const useDeviceFlow = options.device || !browserCmdSet && isHeadless();
 	const flowName = useDeviceFlow ? "device authorization" : "PKCE (browser)";
 	console.log(pc.gray(`  Using ${flowName} flow`));
-	console.log(pc.cyan(`\n  Step 2/4: Authenticating with ZITADEL (${flowName})...`));
+	console.log(pc.cyan(`\n  Step 2/4: Authenticating with IdP (${flowName})...`));
 	let accessToken;
 	const oauthOpts = {
 		issuer,
-		clientId,
-		projectId: projectId || void 0
+		clientId
 	};
 	if (useDeviceFlow) accessToken = await deviceFlow(oauthOpts);
 	else accessToken = await pkceFlow(oauthOpts);

package/dist/commands/status.js

@@ -15,7 +15,7 @@ import { formatDuration, logger, toErrorMessage } from "@kici-dev/shared";
 * Looks up local history first, then fetches from the orchestrator for
 * up-to-date status and logs.
 */
-const CLI_VERSION = "0.1.3";
+const CLI_VERSION = "0.1.6";
 /**
 * Show status and details of a test run.
 *

package/dist/execution/executor.js

@@ -14,7 +14,7 @@ import { pathToFileURL } from "node:url";
 * in its sandbox process). No Rolldown bundling: host-repo imports and
 * transitive deps with dynamic import() resolve via Node's normal ESM loader
 * against the workspace's node_modules — the same module graph any other
-* `npx tsx` invocation would see. This keeps ops-style workflows (which
+* `pnpm exec tsx` invocation would see. This keeps ops-style workflows (which
 * import repo-local modules like scripts/lib/*) working the same as minimal
 * workflows that only touch @kici-dev/sdk.
 */

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

@@ -449,6 +449,41 @@ The lock file approach means the orchestrator stays git-agnostic -- it only need
 
 ---
 
+## 5-minute quickstart
+
+Source: https://kici.dev/docs/user/quickstart/
+
+KiCI offers two equally-supported quickstart paths. Pick the one that fits your machine — both end with the same working pipeline (orchestrator + agent + your first workflow run visible in the dashboard).
+
+## 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.
+
+[Start with the Docker / Podman quickstart →](./quickstart/compose.md)
+
+## Option B — Bare-metal install
+
+Native systemd services managed by `kici-admin orchestrator install` / `kici-admin agent install` — the orchestrator and agents run as native processes. The backing PostgreSQL runs as a single container by default (one `docker compose up -d`), or you can install it natively if you'd rather not run a container runtime at all. Best for a long-lived Linux host.
+
+[Start with the bare-metal quickstart →](./quickstart/bare-metal.md)
+
+## Which should I pick?
+
+|                   | Docker / Podman                          | Bare metal                                                                            |
+| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
+| Host requirements | `docker` or `podman` with compose v2.20+ | systemd, Node.js 24+, PostgreSQL 18 (container — needs `docker`/`podman` — or native) |
+| Time to first run | ~5 minutes                               | ~10 minutes                                                                           |
+| Upgrades          | `docker compose pull` + restart          | `kici-admin orchestrator restart` after `npm install -g kici-admin@latest`            |
+| Best for          | Quick evaluation, ephemeral hosts        | Long-lived production hosts                                                           |
+
+If you're not sure, pick Docker / Podman.
+
+## Looking for the laptop-only path?
+
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](./getting-started.md) covers `kici test` and `kici run local` instead.
+
+---
+
 # Workflow patterns
 
 ## Basic workflow patterns
@@ -1337,7 +1372,7 @@ export default workflow('on-github-repo-push', {
 - No auto-clone — `packages/agent/src/checkout/git-clone.ts` uses GitHub App installation tokens to fetch the repo; a generic source has none. Either set `checkout: false` and clone yourself with a PAT/Deploy Key secret (same pattern as the Forgejo manual-clone example above), or keep the workflow self-contained.
 - No lock-file fetch — the orchestrator cannot fetch `.kici/kici.lock.json` at the pushed SHA via the GitHub API. The workflow must be pre-registered via the [registration model](../events.md#the-registration-model); ad-hoc per-commit workflow discovery that a GitHub App push gives you is not available.
 - No changed-files enrichment — `event.changedFiles` is empty. Use JSONPath `match` on `rawPayload.commits[*].added/modified/removed` if you need path filters.
-- No check-run integration — KiCI cannot post commit statuses or Check Run results back to GitHub.
+- No check-run integration — KiCI cannot post Check Run results back to GitHub.
 - Workflow authors must use `genericWebhook()`, not `push()` / `pr()` / `webhook()` — the latter three only match events delivered through the native GitHub App provider.
 
 **When to use it anyway:** trigger-only workflows that don't need the cloned repo — posting Slack messages, kicking off external deploys, forwarding to downstream systems, or exposing GitHub repo events as `genericWebhook` for same-org [cross-source fan-out](../../architecture/webhooks/webhook-delivery.md#cross-source-delivery). For anything that compiles, tests, or checks code, install the GitHub App instead.
@@ -1390,7 +1425,7 @@ const build = step('build', {
 
 ## Examples repository
 
-For more runnable examples, see the [examples/](https://github.com/kici-dev/kici/tree/master/examples) directory in the KiCI repository.
+For more runnable examples, see the [examples/](https://github.com/kici-dev/kici-public/tree/main/examples) directory in the KiCI repository.
 
 ## GitHub check run output
 
@@ -3452,7 +3487,7 @@ function genericWebhook(config: GenericWebhookConfigInput): GenericWebhookTrigge
 
 ```typescript
 interface GenericWebhookConfigInput {
-  source: string; // Required: webhook source identifier
+  source: string; // Required: must match `--name` from `kici-admin source add generic`
   events?: string[]; // Filter by event types
   match?: Record<string, unknown>; // JSONPath payload matching
   not?: Record<string, unknown>; // Negative JSONPath filter
@@ -3873,7 +3908,7 @@ The KiCI CLI supports three authentication methods: browser-based OAuth (default
 
 The default `kici login` flow:
 
-1. Opens your default browser to the KiCI identity provider (ZITADEL)
+1. Opens your default browser to the KiCI identity provider
 2. You authenticate in the browser
 3. The CLI receives a token via localhost callback
 4. A personal access token (PAT) is created and stored locally
@@ -4012,20 +4047,20 @@ The Platform exposes a versioned REST API under `/api/v1/*`. The same endpoints
 
 Every request to `/api/v1/*` carries an `Authorization: Bearer <token>` header. The Platform routes on the prefix:
 
-| Prefix      | Token type                       | Created via                             | Scope            |
-| ----------- | -------------------------------- | --------------------------------------- | ---------------- |
-| `kici_pat_` | Personal access token            | `kici login` or dashboard               | User (cross-org) |
-| `kici_sk_`  | User API key                     | Dashboard → Settings → API keys         | Org              |
-| `kici_sa_`  | Service account key              | Dashboard → Settings → Service accounts | Org              |
-| (other)     | ZITADEL JWT or opaque OIDC token | OIDC login (browser SPA)                | User (cross-org) |
+| Prefix      | Token type                    | Created via                             | Scope            |
+| ----------- | ----------------------------- | --------------------------------------- | ---------------- |
+| `kici_pat_` | Personal access token         | `kici login` or dashboard               | User (cross-org) |
+| `kici_sk_`  | User API key                  | Dashboard → Settings → API keys         | Org              |
+| `kici_sa_`  | Service account key           | Dashboard → Settings → Service accounts | Org              |
+| (other)     | OIDC JWT or opaque OIDC token | OIDC login (browser SPA)                | User (cross-org) |
 
-JWT and opaque OIDC tokens are validated against your ZITADEL issuer (JWKS for JWTs, `/oidc/v1/userinfo` for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](../architecture/security/rbac.md#authentication-methods) for the full model.
+JWT and opaque OIDC tokens are validated against the configured OIDC issuer (JWKS for JWTs, the issuer's UserInfo endpoint for opaque ones). All `kici_*` tokens are validated by SHA-256 hash lookup against the Platform DB. See [RBAC: authentication methods](../architecture/security/rbac.md#authentication-methods) for the full model.
 
 > **Note:** `kici_ok_` keys are **not** for the HTTP API — they authenticate orchestrator-to-Platform WebSocket connections only. Use `kici_sk_` (or `kici_pat_`) for HTTP calls.
 
 ### Permissions
 
-Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 13 resources and 5 levels are documented in [RBAC](../architecture/security/rbac.md#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).
+Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMiddleware` (verifies you are a member of the target org) followed by `requirePermission(resource, level)`. The 14 resources and 5 levels are documented in [RBAC](../architecture/security/rbac.md#permission-model). User API keys carry their own permission matrix bounded above by the creator's effective permissions; PATs inherit the user's role permissions (or are capped further by their `scopes` field).
 
 ### Configurable surfaces
 
@@ -4232,6 +4267,8 @@ kici run local [event] [options]
 | `--junit <path>`    | none      | Output JUnit XML result to file                                                                                                                                                                                   |
 | `--debug`           | `false`   | Verbose internals                                                                                                                                                                                                 |
 | `--kici-dir <path>` | `.kici`   | Path to .kici directory                                                                                                                                                                                           |
+| `--in-place`        | `false`   | Run against the real working directory instead of an isolated tmp checkout (see "Execution isolation" below)                                                                                                      |
+| `--keep`            | `false`   | Always retain the isolated tmp checkout (default: keep only on failure)                                                                                                                                           |
 
 **Interactive workflow selection (`--pick` / `-p`):**
 
@@ -4265,6 +4302,26 @@ Coordination is local only — running the same workflow on two different machin
 
 The `SIGTERM`-to-`SIGKILL` grace window defaults to 30 000 ms. Override it with the `KICI_LOCAL_LOCK_KILL_GRACE_MS` environment variable (positive integer, milliseconds) when iterating on workflows that need longer to clean up on cancellation.
 
+**Execution isolation:**
+
+By default, `kici run local` executes steps inside an **isolated tmp checkout** rather than against your real working directory. Any file a step writes, builds, or deletes — and any `git` mutation a step performs — lands in that throwaway copy, so casual local runs never touch your tree.
+
+What gets materialized into the isolated checkout has full parity with what `kici run remote` reconstructs: your current working tree minus gitignored files, with `.kiciignore` applied to local changes, over a real `.git` directory. Concretely, the checkout is built from a clone pinned to your current `HEAD`, with your local overlay (modified, staged, and untracked-but-not-ignored files) copied on top and locally-deleted files removed. Workflows that read git metadata work because the `.git` directory is present and pinned to your `HEAD`.
+
+The path is logged at run start (for example, `running in /tmp/kici-run-ab12cd`) so you can inspect it.
+
+Cleanup policy:
+
+- On a fully successful run, the isolated checkout is removed.
+- On failure, it is retained and its path is logged so you can inspect the failed state.
+- `--keep` always retains it, even on success.
+
+Set the `KICI_RUN_DIR` environment variable to place the isolated checkout under a base directory other than the system temp directory.
+
+Secrets are always sourced from your real `.kici/` directory, not from the isolated checkout. Gitignored secret files (such as `.kici/.env.local` and `.kici/secrets.yaml`) are never copied into the checkout, so a step that reads a secret still gets it from the original location.
+
+Pass `--in-place` to run against the real working directory instead — useful when you explicitly want in-tree execution. `--in-place` requires no git repository; the default isolated mode does, and fails with an actionable error pointing at `--in-place` when the directory is not a git repository.
+
 **Examples:**
 
 ```bash
@@ -4453,7 +4510,7 @@ kici test push --files src/index.ts --files README.md
 
 Authenticate with KiCI via browser-based OAuth (default) or API key (`--token`).
 
-By default, `kici login` opens your browser for ZITADEL authentication using PKCE. In headless environments (SSH, CI, containers), it automatically switches to the RFC 8628 device authorization flow where you visit a URL and enter a code.
+By default, `kici login` opens your browser for OIDC authentication using PKCE. In headless environments (SSH, CI, containers), it automatically switches to the RFC 8628 device authorization flow where you visit a URL and enter a code.
 
 After OAuth, the CLI exchanges the OIDC token for a personal access token (PAT) stored in the config directory (`~/.kici/config` by default, overridable with `KICI_CONFIG_DIR`).
 
@@ -5318,7 +5375,7 @@ The lock file (`kici.lock.json`) is a JSON file with the following top-level fie
 
 | Field           | Description                                                                                                         |
 | --------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `schemaVersion` | Lock file schema version (currently 11). Incremented on breaking format changes.                                    |
+| `schemaVersion` | Lock file schema version (currently 12). Incremented on breaking format changes.                                    |
 | `source`        | Reference to the source file and export (e.g., `{ file: “.kici/workflows/ci.ts”, export: “#default” }`).            |
 | `contentHash`   | SHA-256 of the serialized lock file content (excluding itself). Changes when any workflow, trigger, or job changes. |
 | `lockfileHash`  | SHA-256 of `.kici/package-lock.json`, used as the dependency cache key. Omitted when no package lock file exists.   |
@@ -6068,6 +6125,7 @@ The left sidebar provides persistent navigation across all org-scoped pages:
 - **Secrets** -- secret scope management with environment bindings
 - **Approval queue** -- held runs pending approval (shows a badge with pending count)
 - **Activity** -- federated forensic log merging upstream tenant-plane mutations and orchestrator reads (`access_log`) into one chronological stream
+- **DLQ** -- dead-letter queue of internal events whose dispatch retries were exhausted (shows a badge with the current depth)
 - **Settings** -- organization settings with tabbed sub-pages
 
 The sidebar footer shows the WebSocket connection indicator, your user profile, UTC/local time toggle, theme toggle, and a collapse button.
@@ -6445,7 +6503,7 @@ Each member's linked provider accounts (e.g. GitHub) are also visible here.
 
 <!-- help:settings-roles#settings -->
 
-Roles define granular permissions across 13 resource categories (runs, secrets, members, etc.) with 5 access levels: `none`, `read`, `read_payload`, `write`, `admin`.
+Roles define granular permissions across 14 resource categories (runs, secrets, members, etc.) with 5 access levels: `none`, `read`, `read_payload`, `write`, `admin`.
 
 Create custom roles to restrict what team members can do, or use the built-in **Owner** role for full access.
 
@@ -6521,6 +6579,16 @@ When you hit the cap, new relayed webhooks are rejected with `429 Plan limit rea
 
 <!-- /help:settings-billing-relayed-webhooks -->
 
+<!-- help:settings-billing-currency#settings -->
+
+Switch the prices shown on the tier cards between US dollars and euros. The choice you pick here is also the currency Stripe charges in when you click "Upgrade".
+
+The default is detected from your browser language. EU, EFTA, and UK locales default to euros; everywhere else defaults to dollars.
+
+Your choice persists in a 90-day cookie (`kici_pricing_currency`), so it survives across reloads and applies on every billing page.
+
+<!-- /help:settings-billing-currency -->
+
 <!-- help:billing-payment-failure#settings -->
 
 This banner appears when your organization's latest payment to Stripe has failed. Your subscription remains active during the retry period, but you should update your payment method promptly to avoid service interruption.
@@ -6549,6 +6617,23 @@ Click a row's run target to jump straight to the run detail page.
 
 <!-- /help:activity-filters -->
 
+## DLQ
+
+The DLQ (dead-letter queue) page lists internal events whose dispatch attempts were exhausted (or that hit a non-retryable error). Each row shows when the event landed in the DLQ, the event name, the attempt count, the failure reason, and the last error message.
+
+<!-- help:dlq#dlq -->
+
+The DLQ holds events your org emitted that could not be dispatched within the retry budget. The sidebar badge shows the current depth so you can spot a building backlog without opening the page.
+
+Per-row actions (visible when you have `event_dlq:write`):
+
+- **Retry:** clears the DLQ flag and re-publishes the event. A healthy orchestrator picks it up immediately.
+- **Discard:** permanently deletes the row. Use when the payload is corrupt or the routing target no longer exists.
+
+Members with only `event_dlq:read` see the list but cannot retry or discard. Org owners have both actions by default.
+
+<!-- /help:dlq -->
+
 <!-- help:settings-ci-trust#settings -->
 
 CI trust policy controls how your organization handles PR-triggered runs from different contributor types. Configure the default trust level for unknown contributors and set per-member overrides to control who can run workflows with full secrets access.
@@ -6643,6 +6728,22 @@ For each endpoint you can:
 
 <!-- /help:settings-webhooks -->
 
+<!-- help:settings-security-dashboard-policy#settings -->
+
+Read-only view of the orchestrator's dashboard-write policy.
+
+Each row toggles one mutating dashboard action — setting a secret, approving a held run, retrying a dead-lettered webhook, and so on. The orchestrator operator decides which actions stay on the dashboard and which become **CLI-only**. The dashboard cannot change the policy itself — that's the point: disabled actions stay out of the SaaS Platform's trust path.
+
+Manage the policy with:
+
+- **Show the full policy:** `kici-admin org-settings dashboard-writes show`
+- **Disable an operation:** `kici-admin org-settings dashboard-writes set --op <name>=false`
+- **Reset to permissive defaults:** `kici-admin org-settings dashboard-writes reset`
+
+The summary strip at the top shows total / enabled / disabled counts plus whether your orchestrator is currently connected. A disconnected orchestrator means the page falls back to the cached policy from the most recent connection.
+
+<!-- /help:settings-security-dashboard-policy -->
+
 <!-- help:settings-webhooks-delivery-log#settings -->
 
 The delivery log shows recent webhook deliveries for an endpoint, including the HTTP status code, number of retry attempts, and the event payload.
@@ -6698,6 +6799,7 @@ The settings page (`/orgs/:customerId/settings`) uses a tabbed layout:
 9. **Global workflows** -- org-level security knobs for cross-repo workflows (visible with `org_settings:read` permission)
 10. **Webhooks** -- outbound webhook endpoint management with delivery logs and test ping
 11. **Event log** -- inbound webhook delivery log (visible with `event_log:read` permission)
+12. **Security** -- read-only view of the orchestrator's dashboard-write policy matrix (visible with `org_settings:read` permission)
 
 Audit-log-style entries are no longer a settings tab; they live on the dedicated **Activity** page accessible from the sidebar.
 
@@ -6793,6 +6895,28 @@ Organizations are the top-level container for your CI/CD resources. Each org has
 
 <!-- /help:orgs-list -->
 
+<!-- help:orchestrators-list#orchestrators -->
+
+The Orchestrators page lists every orchestrator currently connected to this org, keyed by **cluster name**. Each row shows:
+
+- **Cluster** — the human-friendly cluster name set on the orch via `kici-admin cluster-name set <name>`, or an auto-generated `cluster-<6hex>` if no operator has renamed it.
+- **Role** — `coordinator` (talks to Platform directly) or `worker` (relays through a coordinator).
+- **Version**, **mode**, **routing keys**, and **last heartbeat**.
+
+Click a cluster to drill into its per-orch surfaces (security policy, environments, secrets, DLQ, registrations, global workflows). Different clusters in the same org can have different settings — this page is the entry point that lets you pick which cluster you're configuring.
+
+<!-- /help:orchestrators-list -->
+
+<!-- help:orchestrators-scope#orchestrators -->
+
+Every panel inside this view scopes to the named cluster. Settings shown here come from that orchestrator's own database — a sibling orchestrator in the same org may have a different security policy, different environments, and different secrets.
+
+When the cluster shows **disconnected**, the orch is offline and its current state can't be queried. Most child pages will return 404 in that state; return to the orchestrator list to find a connected cluster.
+
+To rename a cluster, run `kici-admin cluster-name set <new>` on the orchestrator host and restart the orch service so the new name reaches Platform on the next `source.register`.
+
+<!-- /help:orchestrators-scope -->
+
 ## Workflows
 
 The workflows page (`/orgs/:customerId/workflows`) shows permanently registered workflows listening for events. It displays a filterable table with columns for workflow name, repository, trigger types, last triggered time, next fire time (for scheduled workflows), source repos, and actions.
@@ -6841,6 +6965,22 @@ The secrets page (`/orgs/:customerId/secrets`) provides a scope-centric view of
 
 Permission-gated: `secrets:read` to view scopes, `secrets:write` to add or delete secrets, `environments:write` to modify environment bindings.
 
+### Where secrets live
+
+Secret values are stored in the orchestrator's secret store and authorized through the orchestrator's RBAC. The dashboard surfaces secret **names** and scope membership for every secret regardless of where the value was entered.
+
+Whether secret **values** can be set from the dashboard depends on the orchestrator's [dashboard-write policy](/operator/security/dashboard-write-policy):
+
+- **Permissive (default):** the "Add secret" and "Edit value" controls accept plaintext directly in the dashboard. This is how a typical SaaS CI tool works and is the right default for small teams.
+- **`secrets.set` disabled by policy:** the controls render with a lock icon, grayed out. Hovering shows the exact `kici-admin secret set` invocation needed; a copy button puts it on the clipboard. The control is inert — the dashboard issues no mutating request. Use the CLI to enter values; the dashboard refreshes within ~30 seconds and shows the new secret name.
+
+The policy state is visible at three layers in the UI:
+
+- A **lock-icon prefix** on every disabled control, with a per-control CLI hint.
+- A **per-page banner** on any page containing at least one disabled operation, listing every disabled op on that page and its CLI equivalent.
+
+The Security policy page (Settings → Security → Dashboard policy) renders the full 23-row read-only matrix with the current state and the `kici-admin` command for each row. The policy itself cannot be changed from the dashboard — the orchestrator operator manages it via `kici-admin org-settings dashboard-writes`. See [Dashboard-write policy](/operator/security/dashboard-write-policy) for the operator-side details.
+
 ## Approval queue
 
 The approval queue page (`/orgs/:customerId/approval-queue`) shows held runs that are pending approval. Runs can be held due to environment protection rules (required reviewers, wait timers). The page supports filtering by status (pending, approved, rejected, expired) and provides approve/reject actions for users with `environments:write` permission. Users with `environments:admin` permission can skip wait timers.
@@ -7067,7 +7207,7 @@ kici login --token <<< "$KICI_API_KEY"
 Point the CLI to a self-hosted or testing OIDC provider:
 
 ```bash
-export KICI_OIDC_ISSUER=https://your-zitadel.example.com
+export KICI_OIDC_ISSUER=https://your-idp.example.com
 export KICI_OIDC_CLIENT_ID=your-client-id
 export KICI_OIDC_PROJECT_ID=your-project-id
 export KICI_PLATFORM_URL=https://your-platform.example.com
@@ -7510,7 +7650,7 @@ genericWebhook({
 
 **Config options:** `source` (required), `events`, `match`, `not`, `auth`, `path`, `description`.
 
-Generic webhook sources must be created by an operator via the admin API before events can be received. See [Operator guide: event routing](../operator/event-routing.md) for setup instructions.
+The `source` field MUST match the `--name` that an operator passed to `kici-admin source add generic --name <name>` when the source was created — that string is the source's identifier in the orchestrator. Generic webhook sources must be created by an operator before events can be received; see [Operator guide: event routing](../operator/event-routing.md) for setup instructions.
 
 ### Schedule events
 
@@ -7658,7 +7798,7 @@ KiCI's event router delivers every accepted event with **at-least-once** semanti
   is released on failure) and the event is automatically retried.
 - The retry policy is exponential backoff with full jitter: base 5 s, cap 5 min,
   up to 5 attempts before the event lands in the **DLQ** (dead-letter queue).
-  Operators triage DLQ entries via `kici-admin event-dlq list / retry / discard`.
+  Operators triage DLQ entries via `kici-admin event-dlq list / count / retry / discard`.
 
 **What this means for workflow authors:**
 
@@ -8151,6 +8291,60 @@ Secrets are managed per-environment in the orchestrator (see [operator docs](/op
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
+## Where secret values come from
+
+Secret values are written either through the dashboard or through `kici-admin` running against the orchestrator. The orchestrator operator decides — per organization — which surface accepts secret writes. From the workflow author's perspective, the resolution path at run time is identical either way; the difference is where you (or your ops team) **enter** the value.
+
+### Default — dashboard or CLI
+
+A fresh orchestrator starts in **permissive** mode: both surfaces are available.
+
+- **Dashboard:** Settings → Secrets → pick a scope → enter the secret name and value.
+- **CLI:** `kici-admin secret set --scope <scope> <KEY>` against the orchestrator's HTTP admin API.
+
+Use whichever fits the workflow — most small teams stay on the dashboard; ops engineers and CI scripts use the CLI.
+
+### When the operator has disabled dashboard writes
+
+The orchestrator operator can flip `secrets.set` (and `variables.set`) to **CLI-only** as part of the [dashboard-write policy](/operator/security/dashboard-write-policy). When that flip is on:
+
+- The dashboard's "Add secret" / "Edit value" controls render with a lock icon. Clicking them shows a tooltip with the exact `kici-admin secret set` invocation needed.
+- The dashboard's secrets page still lists secret **names**, scopes, and bindings — only the value-entry path moves to the CLI.
+- `kici-admin secret set` becomes the single entry point for new and updated secret values.
+
+This configuration is common for SOC2-prep and regulated workloads, where the customer requirement is "the SaaS control plane process never receives plaintext customer secret values." The dashboard remains usable for everything else (read paths, name CRUD, environment bindings).
+
+### CLI input modes
+
+`kici-admin secret set` accepts five input modes — pick the one that fits your workflow:
+
+```bash
+# Interactive prompt (default when stdin is a TTY). No echo, no shell history.
+kici-admin secret set --scope production DB_PASSWORD --prompt
+
+# Pipe from another tool (default when stdin is not a TTY).
+pass show prod/db | kici-admin secret set --scope production DB_PASSWORD --from-stdin
+
+# Read from a file (handy after `sops -d` to a tmpfile).
+kici-admin secret set --scope production DB_PASSWORD --from-file ./db.pass
+
+# Read from a named environment variable (CI-friendly).
+KICI_SECRET_VALUE=$(my-secrets-fetcher prod db) \
+  kici-admin secret set --scope production DB_PASSWORD --from-env KICI_SECRET_VALUE
+
+# Direct argv — discouraged. Prints a stderr warning ("visible in shell history").
+kici-admin secret set --scope production DB_PASSWORD --value "<plaintext>"
+```
+
+Two cross-cutting flags help every mode:
+
+- `--confirm-fingerprint <hex>` — pre-compute SHA-256 of the value and pass it. The CLI rejects the call if the value's fingerprint doesn't match. Catches paste corruption.
+- `--dry-run` — parse and validate the value, print `[dry-run] would set <key> in scope <scope> sha256=<hex>`, exit without writing.
+
+`kici-admin variable set` uses the same flags for non-encrypted variables, plus `--locked` to mark a variable as immutable from subsequent dashboard writes.
+
+A full reference of input modes — including the default-mode resolution rules and the security trade-offs of each — lives in [Dashboard-write policy → CLI input modes](/operator/security/dashboard-write-policy#cli-input-modes-for-the-plaintext-path).
+
 ## Accessing secrets
 
 Use `ctx.secrets.get(key)` to retrieve a secret value. The method is async to support process-level step isolation in future versions.
@@ -8399,11 +8593,14 @@ repos where you can't install an App.
    https://<platform-host>/webhook/<orgId>/github
    ```
 
-   For self-hosted independent / hybrid orchestrators the same path
-   serves directly on the orchestrator's public hostname. The `<orgId>`
-   segment is the KiCI organization ID the source belongs to; the
-   `<appId>` is discovered from `X-GitHub-Hook-Installation-Target-ID`
-   at request time and is _not_ part of the URL.
+   GitHub App webhooks are always delivered to this Platform endpoint and
+   relayed to your orchestrator over its outbound connection — platform and
+   hybrid orchestrators both receive GitHub events this way. Independent-mode
+   orchestrators have no Platform connection and therefore no GitHub-App
+   ingress; use a generic webhook source instead. The `<orgId>` segment is
+   the KiCI organization ID the source belongs to; the `<appId>` is
+   discovered from `X-GitHub-Hook-Installation-Target-ID` at request time and
+   is _not_ part of the URL.
 
 4. **Set the webhook secret.** Generate a random hex string (e.g.
    `openssl rand -hex 32`) and save it for step 4 of the orchestrator
@@ -8412,18 +8609,38 @@ repos where you can't install an App.
 
 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                   |
-   | Repository -> Pull requests   | Read         | Match `pull_request` triggers           |
-   | Repository -> Checks          | Read & write | Post KiCI's enriched Check runs         |
-   | Repository -> Commit statuses | Read & write | (optional) Legacy commit-status posting |
+   | 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](../../architecture/security/ci-security.md)
+   on an org-level install — see the event note below.
 
 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](../../architecture/security/ci-security.md)). 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.
@@ -8449,10 +8666,21 @@ kici-admin --url http://<orchestrator-host>:4000 --token $KICI_BOOTSTRAP_ADMIN_T
   --webhook-secret <the-webhook-secret-from-step-4>
 ```
 
-The command returns the routing key (always `github:<appId>`). The
-private key and webhook secret are stored encrypted in the orchestrator
-database under `KICI_SECRET_KEY`; no restart needed — the orchestrator
-accepts webhooks from this App immediately.
+The command prints the routing key (always `github:<appId>`) and the public
+webhook URL to paste into the GitHub App's "Webhook URL" field:
+
+```
+Source added: github:<appId> (my-org)
+Webhook URL:  https://<platform-host>/webhook/<orgId>/github
+  ↳ Paste this into your GitHub App's "Webhook URL" field.
+```
+
+When the orchestrator runs in independent mode (no Platform connection) the
+URL line reads `(unavailable — this orchestrator runs in independent mode)`,
+because GitHub-App ingress is Platform-relayed. The private key and webhook
+secret are stored encrypted in the orchestrator database under
+`KICI_SECRET_KEY`; no restart needed — the orchestrator accepts webhooks from
+this App immediately.
 
 **Secret input modes** (for `--private-key` and `--webhook-secret`):
 
@@ -9529,13 +9757,13 @@ GitHub         Platform                  Orchestrator              Agent
 
 5. **Agent execution:** The agent wraps each `onJobDispatch` callback in `requestContext.run()` with `requestId`, `runId`, and `jobId`. A trace header is printed once at job start. All subsequent log lines carry all trace fields automatically.
 
-6. **Check run summaries:** GitHub Check Run updates include `Trace: <requestId> | Run: <runId>` in the summary text, giving operators a direct link from GitHub UI to ELK queries.
+6. **Check run summaries:** GitHub Check Run updates include `Trace: <requestId> | Run: <runId>` in the summary text, giving operators a direct link from GitHub UI to Loki queries.
 
 ### Implementation
 
-Trace propagation uses Node.js `AsyncLocalStorage` from `@kici-dev/shared`. A logger format (`traceContextFormat`) reads the current context and injects fields into every JSON log line -- no changes needed at individual call sites.
+Trace propagation uses Node.js `AsyncLocalStorage` from `@kici-dev/shared`. A logger format reads the current context and injects fields into every JSON log line -- no changes needed at individual call sites.
 
-Tier identification is handled at the infrastructure level: `kici.service` (populated by Filebeat from the container name) identifies which service produced the log. For agent logs forwarded through the orchestrator's stdout, the `app.service` field (set to `'agent'` by the log forwarder) identifies the originating tier.
+Tier identification is handled at the infrastructure level: the `service` Loki label (set by Grafana Alloy from the systemd unit / log source) identifies which service produced the log (`platform`, `orchestrator`, `agent`, etc.). For agent logs forwarded through the orchestrator's stdout, the parsed JSON also carries an inner `service: 'agent'` field — query both with `{service="orchestrator"} | json | service="agent"` to disambiguate.
 
 ## Output chaining data flow
 
@@ -9633,7 +9861,7 @@ The Platform tier exposes a `/ws/browser` WebSocket endpoint for dashboard clien
 - [State machine](./execution/state-machine.md) -- job execution state transitions
 - [Webhook delivery](./webhooks/webhook-delivery.md) -- detailed webhook processing pipeline
 - [Operator: dependency caching](../operator/dependency-caching.md) -- configuration guide
-- [Operator: monitoring & tracing](../operator/observability/monitoring.md) -- trace fields and ELK queries
+- [Operator: monitoring & tracing](../operator/observability/monitoring.md) -- trace fields and Loki queries
 - [Operator: event routing & generic webhooks](../operator/event-routing.md) -- generic source setup and trust management
 - [SDK reference: output chaining](../user/sdk/core.md#output-chaining) -- user-facing output chaining API
 
@@ -9693,7 +9921,7 @@ Per-source secrets enable multi-tenant Platform with proper isolation. Each cust
 
 **Decision:** Webhooks are routed by provider-scoped routing key (e.g., `github:12345`) derived from the `X-GitHub-Hook-Installation-Target-ID` header. One routing key maps to one orchestrator connection.
 
-App ID routing provides a clean 1:1 mapping between a customer's GitHub App and their orchestrator. The orchestrator extracts the `installation_id` from the webhook payload body for GitHub API calls (fetching lock files, setting commit statuses).
+App ID routing provides a clean 1:1 mapping between a customer's GitHub App and their orchestrator. The orchestrator extracts the `installation_id` from the webhook payload body for GitHub API calls (fetching lock files, posting check runs).
 
 **Alternative:** Route by Installation ID (more granular, one App can have many installations). Rejected because it adds complexity without clear benefit -- most customers use one App with one or a few installations, and the orchestrator can handle multiple installations internally.
 
@@ -9885,7 +10113,7 @@ Shared utilities used across packages. Provides `initZx()` for zx initialization
 
 ### Dashboard
 
-Web UI for KiCI. A browser single-page application that provides the operator dashboard with execution run listing, run detail views, real-time log streaming, settings management, and keyboard shortcut support. Authenticates via OIDC against ZITADEL and communicates with the Platform REST-over-WebSocket API.
+Web UI for KiCI. A browser single-page application that provides the operator dashboard with execution run listing, run detail views, real-time log streaming, settings management, and keyboard shortcut support. Authenticates via OIDC against the identity provider and communicates with the Platform REST-over-WebSocket API.
 
 ### `kici` (wrapper)
 
@@ -9961,7 +10189,7 @@ The agent connects outbound to the orchestrator WebSocket endpoint. After regist
 
 ## Authentication and multi-tenancy
 
-KiCI uses application-level tenant isolation. The Platform dashboard API accepts three authentication methods (PATs, API keys, JWTs) and enforces org membership on every `/api/v1/orgs/:customerId/*` request through `orgContextMiddleware`. Triple-auth wiring, the ZITADEL identity provider integration, and the API key permission matrix are SaaS-Platform specifics covered in the internal docs.
+KiCI uses application-level tenant isolation. The Platform dashboard API accepts three authentication methods (PATs, API keys, JWTs) and enforces org membership on every `/api/v1/orgs/:customerId/*` request.
 
 ## See also