@kici-dev/compiler 0.5.0 → 0.6.0

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

@@ -340,8 +340,11 @@ kici logout
 This:
 
 1. Revokes the PAT on the server (preventing further use)
-2. Clears auth fields from the local config file
-3. Preserves non-auth settings (active org, default clusters, Platform endpoint)
+2. Detaches the local dev plane if it is attached, so a logged-out user is not left with a hybrid plane holding an orphaned orchestrator key
+3. Clears the auth fields from the local config file — the PAT, its id and expiry, your email, and the active organization
+4. Preserves the connection settings (per-org default clusters, Platform endpoint, orchestrator endpoint, OIDC issuer, routing key)
+
+Server revocation is best-effort: if the network call fails, the local config is still cleared.
 
 ## Organization management
 
@@ -502,11 +505,13 @@ Every `/api/v1/*` mutation that touches tenant-plane data is recorded in the ups
 
 The CLI stores authentication data in `~/.kici/config` with `0600` permissions (owner read/write only). The config file contains:
 
-- PAT token
-- PAT expiry date
+- PAT token, its server-side id, and its expiry date
+- The email address from your OIDC token
 - Active organization ID
 - Per-org default orchestrator clusters
-- Platform endpoint URL
+- Platform endpoint URL, orchestrator endpoint URL, and the OIDC issuer the PAT was minted against
+- Routing key for webhook source identification
+- API key, when you logged in with `--token`
 
 ## Troubleshooting
 
@@ -540,11 +545,11 @@ Two ways forward:
 
 A port below 1024 fails the same way, with a permissions message rather than an "in use" one: those ports need elevated privileges. Pick a port above 1024. A value that is not a port number at all — non-numeric, negative, or above 65535 — is rejected before the login starts, naming the value you set.
 
-### Device flow timeout
+### Device code expired
 
 This is the device flow's own expiry, not the browser flow's callback timeout above.
 
-The device flow has a 5-minute timeout. If it expires:
+The device code is issued by the identity provider, which also sets how long it lives. The CLI prints the lifetime with the code (`Code expires in N minutes`) and polls until you approve or the code expires. On expiry it stops with `Device code expired`. If that happens:
 
 - Run `kici login --device` again to get a new code
 - Ensure you're using the correct URL displayed by the CLI
@@ -605,7 +610,7 @@ The full command reference is split by area:
 - [Authoring & local dev](https://docs.kici.dev/user/cli/authoring-and-local/) — `compile`, `preview`, `local`, `fixture`, `types`, `workflows`, `hook`, `docs`
 - [Runs & approvals](https://docs.kici.dev/user/cli/runs-and-approvals/) — `run`, `runs`, `reject`, `approve`
 - [Account & org](https://docs.kici.dev/user/cli/account-and-org/) — `login`, `logout`, `init`, `org`, `pat`, `secrets`, `admin`, `orchestrators`, `endpoints`
-- [Notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/) — `notifications`, `verify-attestation`, `diagnostics`, `doctor`
+- [Notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/) — `notifications`, `verify-attestation`, `diagnostics`, `doctor`, `report`
 
 Each area page carries a `## Guide` section (worked examples and command-by-command narrative) and a `## Reference` section (the always-current generated signature list for that area's commands).
 
@@ -1166,6 +1171,7 @@ Step entries carry their own capability flags, so the orchestrator can reason ab
 
 | Flag            | Meaning                                                                                                                                              |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hasOutputs`    | The step declares an output schema, so the run has typed outputs to record for it. Present on every step entry.                                      |
 | `hasCheck`      | The step declares an idempotent `check` facet, so a run can be dispatched in check mode. See [idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/). |
 | `hasWhenInSync` | The step declares a `whenInSync` facet that produces its outputs when `check` reports no drift.                                                      |
 | `hasRules`      | The step has conditional rules (evaluated agent-side).                                                                                               |
@@ -1787,7 +1793,7 @@ export const pushMain = fixture('push-main', {
 
 Source: https://docs.kici.dev/user/workflow-patterns/
 
-Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across five pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
+Practical patterns for building real-world KiCI workflows in TypeScript. The patterns are organised across seven pages -- start with [Basic CI](https://docs.kici.dev/user/patterns/basic/) if you're new, or jump to [Integrations](https://docs.kici.dev/user/patterns/integrations/) if you're wiring up a non-GitHub forge or a generic webhook.
 
 | Page                                                       | Covers                                                                                                                                             |
 | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1795,6 +1801,8 @@ Practical patterns for building real-world KiCI workflows in TypeScript. The pat
 | [Conditionals & matrix](https://docs.kici.dev/user/patterns/conditionals-matrix/) | Conditional execution with rules, matrix builds (static + dynamic), and dynamic job generation.                                                    |
 | [Integrations](https://docs.kici.dev/user/patterns/integrations/)                 | Workflow chaining, generic webhooks, Stripe handlers, self-hosted git forges (Forgejo / Gitea / Gogs), plain GitHub repo webhooks (no GitHub App). |
 | [Scheduling & events](https://docs.kici.dev/user/patterns/scheduling-and-events/) | Nightly cron, workflow-complete-triggered deploys, custom event chaining.                                                                          |
+| [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)           | Declaring named git credentials from the secrets backend, and pushing from a job (including to the job's own repository).                          |
+| [Host restart](https://docs.kici.dev/user/patterns/host-restart/)                 | `restartHost()` and `waitForHostAlive()` -- reboot the host a workflow runs on and resume in a second job pinned to the same host.                 |
 | [Pattern reference](https://docs.kici.dev/user/patterns/reference/)               | Step context, the examples repository, and GitHub check run output -- cross-cutting reference shared by every pattern above.                       |
 
 ## See also
@@ -2153,7 +2161,6 @@ Synopsis: `kici init [options]`
 | `--private-registry <url>`         |                        | Scaffold a workflow registries: entry pointing at <url>                                             |
 | `--private-registry-scope <scope>` |                        | Optional npm package scope (e.g. @my-org) for the private registry                                  |
 | `--private-registry-secret <ref>`  | `production:NPM_TOKEN` | Qualified secret reference (env:NAME) the private registry token comes from                         |
-| `--use-verdaccio-local`            | `false`                |                                                                                                     |
 
 ### `kici login`
 
@@ -2428,7 +2435,7 @@ Generate a fixture template for an event type. Useful for creating custom test p
 kici fixture <event> [options]
 ```
 
-**Valid events:** `pr:open`, `pr:sync`, `pr:close`, `pr:reopen`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`, `kici_event`, `workflow_complete`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle` (many support `:action` suffixes, e.g. `comment:edited`, `release:published`, `lifecycle:workflow_complete`). `webhook:<source>` is a shorthand alias for `generic_webhook:<source>`.
+**Valid events:** `pr:open`, `pr:sync`, `pr:close`, `pr:reopen`, `push`, `tag`, `comment`, `review`, `review_comment`, `release`, `dispatch`, `create`, `delete`, `status`, `workflow_run`, `fork`, `star`, `watch`, `kici_event`, `workflow_complete`, `workflows_failed_batch`, `job_complete`, `generic_webhook`, `schedule`, `lifecycle` (many support `:action` suffixes, e.g. `comment:edited`, `release:published`, `lifecycle:workflow_complete`). `webhook:<source>` is a shorthand alias for `generic_webhook:<source>`.
 
 **Examples:**
 
@@ -2458,7 +2465,7 @@ Generate TypeScript declaration files from orchestrator environment metadata. Th
 kici types [options]
 ```
 
-**Prerequisites:** Must be authenticated via `kici login`.
+**Prerequisites:** Authenticate via `kici login` to fetch the real key set. Without it, `kici types` writes an empty stub (see "Offline behavior" below).
 
 **Output:** `.kici/types/secrets.d.ts`
 
@@ -2480,7 +2487,9 @@ kici types --kici-dir packages/app/.kici
 
 After generating types, `ctx.secrets.get('MY_KEY')` and `ctx.secrets.expose('DB_HOST')` gain autocomplete and type checking in your IDE.
 
-**Git workflow:** Commit the generated `.kici/types/secrets.d.ts` so team members get type checking without needing orchestrator access. Run `kici types` to refresh when environments change.
+**Git workflow:** `.kici/types/secrets.d.ts` is a local development aid, not source — its content is a snapshot of one org's secret keys fetched from the Platform. `kici init` gitignores `.kici/types/`, so the file stays out of version control. Each team member runs `kici types` (or an authenticated `kici compile`) to generate their own copy. Do not commit it: a stale committed copy would type-check against secret keys that no longer exist.
+
+**Offline behavior:** When the Platform cannot be reached — not logged in, no active org, or offline — `kici types` never fails. If a `secrets.d.ts` already exists, `kici types` keeps it untouched, so a transient outage does not wipe your real key set. If the file is absent (a fresh clone or unauthenticated CI), `kici types` writes a valid empty stub. Type checking then degrades to "no known keys" (any key name is accepted) rather than breaking with "module has no exported member". Run `kici types` again once authenticated to refresh it.
 
 **Auto-regeneration:** `kici compile` automatically runs `kici types` after successful compilation when authenticated. See the [kici compile](https://docs.kici.dev/user/cli/authoring-and-local/#kici-compile) section for details.
 
@@ -2565,7 +2574,7 @@ kici docs llm sdk | claude -- "Read this and help me author a deploy workflow"
 kici docs llm --out kici-llms-index.txt
 ```
 
-Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `sdk-runtime`, `cli`, `patterns`, `features`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
+Bundles are regenerated from `docs/` every time `@kici-dev/compiler` is built, so they always match your installed CLI version. The index lists each task bundle — `getting-started`, `sdk`, `sdk-runtime`, `cli`, `patterns`, `features`, `features-execution`, `providers`, `architecture` — with its size and a one-line purpose; pass the bundle id as the topic. Every cross-reference link inside a bundle is an absolute `docs.kici.dev` URL. The same files are published online following the [llms.txt convention](https://llmstxt.org/).
 
 ## Reference
 
@@ -2963,9 +2972,9 @@ kici diagnostics --json
 Walk your KiCI setup end to end and print the exact next command for each
 problem found. Where `kici diagnostics` shows the org's infrastructure, `kici
 doctor` checks **your own setup**: it runs six checks in onboarding order —
-login (stored, unexpired credentials), active organization, a live token probe
-against the platform, a connected orchestrator for the org, a present, fresh,
-and committed lock file, and whether every workflow's `runsOn` labels are
+login (stored, unexpired credentials), active organization, a present, fresh,
+and committed lock file, a live token probe against the platform, a connected
+orchestrator for the org, and whether every workflow's `runsOn` labels are
 satisfiable by a connected agent or scaler. Each check reports pass/warn/fail
 with the fix command (e.g. `kici login`, `kici org use <name>`,
 `kici compile`), so the first failing row tells you exactly what to run next.
@@ -2987,6 +2996,60 @@ kici doctor --json
 The command exits `0` when every check passes, `1` when any check warns, and
 `2` when any check fails, so it also works as a CI preflight.
 
+### kici report
+
+Gather a diagnostic bundle to share when you report a problem. `kici doctor`
+tells you what is wrong; `kici report` packages the context somebody else needs
+to see it. The bundle holds your CLI, Node and orchestrator versions, your
+redacted configuration, and your project's workflow and lock-file state. With
+`--run` it also holds the failing run's detail and logs.
+
+```bash
+kici report [options]
+```
+
+The command writes a ZIP and prints its path and `sha256`. It does not send
+anything. Open the file and read it before you share it.
+
+```bash
+# Bundle your setup
+kici report
+
+# Scope it to the run that failed, and say what went wrong
+kici report --run 8f3c1d2e --message "matrix job hangs on macOS"
+
+# Choose the output path and attach your own metadata
+kici report -o /tmp/bug.zip --metadata ticket=1234 --metadata severity=high
+```
+
+**Redaction.** KiCI removes known secret shapes — API keys, tokens, `Authorization`
+headers, private keys, passwords in connection URLs — from configuration and
+from log text. This is best effort. A secret in a format KiCI does not
+recognize can survive, so review the bundle before you share it. `--no-redact`
+turns redaction off and prints a warning; use it only on a bundle you keep.
+
+**Sending it privately.** Add `--upload` to send the bundle to KiCI over a
+one-time upload link. The bundle goes straight to KiCI storage, and the command
+prints a reference id to quote:
+
+```bash
+kici report --run 8f3c1d2e --upload --message "matrix job hangs on macOS"
+```
+
+Uploads are private, are kept for 90 days, and are yours to withdraw:
+
+```bash
+# See what you have sent
+kici report list
+
+# Delete an uploaded bundle
+kici report withdraw <ref>
+```
+
+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.
+
 ## Reference
 
 <!-- BEGIN GENERATED: kici-notifications-and-diagnostics (do not edit; run the doc generator) -->
@@ -3194,6 +3257,49 @@ Synopsis: `kici notifications subscriptions remove <id> [options]`
 | ------------ | ------- | ---------------------------------------------- |
 | `--org <id>` |         | Target organization (overrides the active org) |
 
+### `kici report`
+
+Gather a redacted diagnostic bundle to share when reporting an issue
+
+Synopsis: `kici report [options]`
+
+**Options**
+
+| Option                   | Default | Description                                                  |
+| ------------------------ | ------- | ------------------------------------------------------------ |
+| `--run <id>`             |         | Scope the bundle to a failing run                            |
+| `-o, --output <path>`    |         | Where to write the bundle ZIP                                |
+| `--metadata <key=value>` |         | Attach metadata (repeatable)                                 |
+| `--no-redact`            |         | Do NOT redact secrets (prints a loud warning)                |
+| `--upload`               |         | Upload the bundle privately to KiCI and print a reference id |
+| `--message <text>`       |         | Describe the problem (sent with --upload)                    |
+| `--email <address>`      |         | Contact address for follow-up (sent with --upload)           |
+| `--kici-dir <path>`      | `.kici` | Path to the .kici directory                                  |
+
+### `kici report list`
+
+List the issue reports you have uploaded
+
+Synopsis: `kici report list [options]`
+
+**Options**
+
+| Option   | Default | Description     |
+| -------- | ------- | --------------- |
+| `--json` | `false` | Output raw JSON |
+
+### `kici report withdraw`
+
+Withdraw an uploaded report and delete its bundle
+
+Synopsis: `kici report withdraw <ref>`
+
+**Arguments**
+
+| Argument | Required | Variadic | Description                            |
+| -------- | -------- | -------- | -------------------------------------- |
+| `ref`    | yes      | no       | Reference id of the report to withdraw |
+
 ### `kici verify-attestation`
 
 Verify a KiCI provenance attestation bundle offline
@@ -3509,7 +3615,11 @@ kici runs list --json | jq '.runs[].runId'
 #### kici runs show
 
 Show a run's summary header plus its jobs-and-steps tree (name, status,
-duration, exit code). If the run id is not on the Platform but exists in your
+duration, exit code). A run that never started a step also prints why: the
+run-level failure, and per job the reason it did not run — a job a
+[context](https://docs.kici.dev/user/contexts/#protection-rules) rejected names the context and the
+rule. Any approval hold on the run is listed too, with its context, hold type,
+status and reason. If the run id is not on the Platform but exists in your
 local run history (from `kici run <event> --local`), the local record is shown instead.
 
 ```bash
@@ -3690,10 +3800,12 @@ Synopsis: `kici approve <run-id> [options]`
 
 **Options**
 
-| Option           | Default | Description                                 |
-| ---------------- | ------- | ------------------------------------------- |
-| `--job <name>`   |         | Approve the hold for a specific job         |
-| `--step <index>` |         | Approve a step-scoped hold (requires --job) |
+| Option               | Default | Description                                                                                  |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `--job <name>`       |         | Approve the hold for a specific job                                                          |
+| `--step <index>`     |         | Approve a step-scoped hold (requires --job)                                                  |
+| `--hold-type <type>` |         | Approve the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
+| `--hold <id>`        |         | Approve one hold by its id, as listed when nothing else separates them                       |
 
 ### `kici reject`
 
@@ -3709,11 +3821,13 @@ Synopsis: `kici reject <run-id> [options]`
 
 **Options**
 
-| Option            | Default | Description                                |
-| ----------------- | ------- | ------------------------------------------ |
-| `--job <name>`    |         | Reject the hold for a specific job         |
-| `--step <index>`  |         | Reject a step-scoped hold (requires --job) |
-| `--reason <text>` |         | Reason for the rejection                   |
+| Option               | Default | Description                                                                                 |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `--job <name>`       |         | Reject the hold for a specific job                                                          |
+| `--step <index>`     |         | Reject a step-scoped hold (requires --job)                                                  |
+| `--hold-type <type>` |         | Reject the hold of this type (reviewer, timer, concurrency, security) — a job can carry two |
+| `--hold <id>`        |         | Reject one hold by its id, as listed when nothing else separates them                       |
+| `--reason <text>`    |         | Reason for the rejection                                                                    |
 
 ### `kici run`
 
@@ -3911,7 +4025,7 @@ Synopsis: `kici runs rerun <run-id> [options]`
 
 ### `kici runs show`
 
-Show a run summary with its jobs and steps
+Show a run summary with its jobs and steps, why a job did not run, and any approval hold
 
 Synopsis: `kici runs show <run-id> [options]`