@kici-dev/compiler 0.7.0 → 0.9.0

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

@@ -44,9 +44,7 @@ behalf). The token is printed once — save it now; it cannot be retrieved later
 
 **Option B — an agent org API key.** Create one from the dashboard's
 **Settings → API keys** tab: set the key's kind to **Agent** and give it an
-agent name (the agent label). The same key can also be minted with
-`kici-platform-admin user api-key create --org <id> --agent --agent-label <label>`.
-Reach for an org agent key when the agent should act as a shared service account
+agent name (the agent label). Reach for an org agent key when the agent should act as a shared service account
 rather than as a single user — for example, a long-lived CI bot that outlives any
 individual's membership.
 
@@ -761,7 +759,7 @@ In interactive mode (TTY), `kici init` prompts you to:
 
 **Standalone vs workspace integration:** by default `kici init` scaffolds a self-contained `.kici/` with its own `package.json`. When run inside a pnpm, npm, or yarn workspace, it offers an **integrate** option (or pass `--workspace`): `.kici/` joins the workspace, `@kici-dev/sdk` is added to your workspace-root `package.json`, and your workflows can `import` your other workspace packages (e.g. shared build or deploy utilities). In this mode there is no `.kici/package.json` — the workspace root manages dependencies, and the root install resolves the SDK. Your workflows resolve sibling packages through the workspace-root `node_modules`: under npm and yarn every workspace member is hoisted there automatically, while pnpm links only your root's declared dependencies, so under pnpm add the package you want to import to your workspace-root `dependencies` (this is how KiCI's own repository imports its packages from workflows). Pass `--standalone` to force the self-contained layout even inside a workspace. In CI / non-interactive runs the default is standalone; use `--workspace` to opt in explicitly. `--workspace` and `--standalone` are mutually exclusive, and `--workspace` errors if no workspace is found at or above the current directory.
 
-**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` uses prerelease-compatible version ranges (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds.
+**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` pins `@kici-dev/sdk` to the `latest` dist-tag so npm resolves Verdaccio's newest prerelease build.
 
 ### kici org
 
@@ -1198,10 +1196,11 @@ kici verify-attestation --bundle ./app.tgz.kici.json \
 token was minted relative to the build. A normal attestation prints no marker
 (the token was minted live). A **deferred** attestation prints an `ATTESTATION:
 deferred` line — the build facts were sealed at build time and the token was
-minted later, after a transient platform outage, bound to the frozen statement
-by its hash. An **offline-backfill** attestation prints an `ATTESTATION:
-offline-backfill` line — the run was ingested while the platform was down, so its
-run/job rows were backfilled before the token was minted. Both still verify
+minted later, once the orchestrator's signing key was available again, bound to
+the frozen statement by its hash. An **offline-backfill** attestation prints an
+`ATTESTATION: offline-backfill` line — the run was ingested while the platform
+was down, so its run/job records were replayed to the platform before the token
+was minted. Both still verify
 (PASS); the marker discloses the temporal gap, and the organization id remains
 the authoritative anchor.
 
@@ -1360,6 +1359,9 @@ kici feedback --open
 
 # Read the same contract as structured data
 kici feedback --json
+
+# Turn a JSON draft (keys: draftFields from --json) into the prefilled form URL
+kici feedback --draft draft.json --open
 ```
 
 `--json` exists for coding agents: KiCI is built to be driven by an LLM, and
@@ -1410,10 +1412,11 @@ Synopsis: `kici feedback [options]`
 
 **Options**
 
-| Option   | Default | Description                                          |
-| -------- | ------- | ---------------------------------------------------- |
-| `--open` |         | Open the prefilled issue form in the default browser |
-| `--json` |         | Emit the reporting contract as JSON                  |
+| Option           | Default | Description                                                                                   |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `--open`         |         | Open the prefilled issue form in the default browser                                          |
+| `--json`         |         | Emit the reporting contract as JSON                                                           |
+| `--draft <file>` |         | Build the prefilled issue-form URL from a JSON draft keyed by field id (with --open, open it) |
 
 ### `kici notifications`
 
@@ -1707,6 +1710,18 @@ Secrets are always sourced from your real `.kici/` directory, not from the isola
 
 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.
 
+**If the trigger times out:**
+
+The command waits up to 60 seconds for the local dev plane to create the run. If nothing appears in that window it stops and names the cause it read back from the plane:
+
+| Message                                                                   | What it means                                                                                                                                                     |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plane is not leader yet (election grace period)`                         | The plane had not finished electing itself. A single-machine plane elects within seconds; if it does not, read the plane log (`kici local logs`).                 |
+| `no kici.lock.json at <commit> in <path>`                                 | The plane resolved no lock file for the commit the run packed, so nothing matched. Commit `.kici/kici.lock.json`, or make sure it is present in the working tree. |
+| `the plane recorded delivery <id> as "<status>"`                          | The plane processed the trigger and wrote down a terminal status for it without creating a run. The status names the stage that stopped.                          |
+| `no run appeared for delivery <id> — see <log>`                           | Neither the plane's cluster state nor its delivery record explained the timeout. The named log is the next place to look.                                         |
+| `no run appeared for this trigger — the plane never accepted the webhook` | Every webhook POST came back without a delivery id, so the plane never queued the trigger. Check the plane is up (`kici local status`), then read the named log.  |
+
 **Examples:**
 
 ```bash

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

@@ -1365,7 +1365,7 @@ Manage the **local dev plane** — the warm, per-user orchestrator (plus its own
 kici local up [--offline | --connected]   # Start, or reuse an already-running plane
 kici local status [--json]                 # Port, pid, PostgreSQL backend, attachment mode, readiness
 kici local down                            # Stop the orchestrator and its PostgreSQL, verifying the port is freed
-kici local logs                            # Print the orchestrator log file path
+kici local logs                            # Print the plane log paths and rotation policy
 kici local attach                          # Attach to the Platform (hybrid mode)
 kici local detach                          # Return the plane to offline (independent) mode
 kici local trust-root <file>               # Export the dev-signed trust root for offline verification
@@ -1374,7 +1374,7 @@ kici local trust-root <file>               # Export the dev-signed trust root fo
 The plane runs in one of two modes:
 
 - **Independent (offline)** — the default for a plane that has never been attached. Identity tokens and attestations are signed by a local dev key under the clearly non-production issuer `kici-local`.
-- **Hybrid (attached)** — `kici local attach` mints an org-scoped key with your logged-in credentials and reboots the plane connected to the Platform, so local runs get real Platform-minted identity and attestation. `kici local up` honors a durable attachment record: an attached plane comes back up hybrid, and falls back to offline with a warning when the Platform is unreachable.
+- **Hybrid (attached)** — `kici local attach` mints an org-scoped key with your logged-in credentials and reboots the plane connected to the Platform, so local runs get identity and attestation signed by the plane's own key under its own issuer, as a deployed orchestrator would. `kici local up` honors a durable attachment record: an attached plane comes back up hybrid, and falls back to offline with a warning when the Platform is unreachable.
 
 `--offline` forces an independent boot without clearing the attachment record (only `detach` clears it); `--connected` requires an attached, reachable Platform and fails otherwise.
 
@@ -1382,6 +1382,8 @@ The plane runs in one of two modes:
 
 `kici local status` reports a plane whose process is alive but whose readiness probe fails — for example when its PostgreSQL has stopped — as running but not ready, together with its readiness checks, rather than as not running. When the holder is a KiCI plane orchestrator that this config directory did not start — a plane belonging to another `KICI_CONFIG_DIR`, or one whose record here was lost — status names it as such rather than as not ready, since its readiness is never probed, and points at `kici local down`, which does reclaim it. When the port is held by a process that is not a KiCI plane orchestrator, `kici local status` names that holder instead and points at `KICI_LOCAL_ORCH_PORT`, because `kici local down` will not stop it.
 
+The plane writes its orchestrator log to `orchestrator.log` in its state directory and, when it runs embedded PostgreSQL, the PostgreSQL log to `orchestrator.log.pg` beside it. `kici local logs` prints their location. Each is rotated to a `.1` sibling when it reaches 50 MB, at the next plane start — the plane keeps the current log and one previous generation, so neither can grow without bound.
+
 Pass `--json` for machine-readable output. It prints one object and exits 0 for
 every state, including when the plane is stopped — the state is in the payload,
 not the exit code:
@@ -1540,7 +1542,7 @@ If multiple tools are detected, you are prompted to choose.
 Open the KiCI documentation site in the default browser. With the `llm` subcommand, print the LLM-friendly documentation bundle that ships with `@kici-dev/compiler` — pipe it into a coding agent's context buffer to brief the agent on authoring conventions without an internet round-trip.
 
 ```bash
-kici docs               # open https://kici.dev/docs/
+kici docs               # open https://docs.kici.dev/
 kici docs --no-open     # print the URL instead of opening a browser
 kici docs llm           # print the llms.txt index (a router over the task bundles)
 kici docs llm sdk       # print the SDK task bundle
@@ -1674,7 +1676,7 @@ Synopsis: `kici local down`
 
 ### `kici local logs`
 
-Print the local dev plane orchestrator log path
+Print the local dev plane log paths and rotation policy
 
 Synopsis: `kici local logs`
 

package/dist/llm-context/llms-features-execution.txt

@@ -607,7 +607,7 @@ The KiCI CLI reads the following environment variables to customize its behavior
 
 | Variable            | Description                                                                                                                                                                | Default |
 | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`          | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
+| `KICI_DEV`          | Enable development mode. When `true`, pins `@kici-dev/sdk` to the `latest` dist-tag (so a dev registry's prerelease build resolves) and skips npm version resolution.      | unset   |
 | `KICI_DEV_REGISTRY` | npm registry the `@kici-dev` scope points at when `KICI_DEV` is set. `kici init` writes it into `.npmrc`; with no value it writes no `.npmrc`.                             | unset   |
 | `KICI_DEBUG`        | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
 
@@ -977,7 +977,7 @@ The first two treat "no tier" as untrusted. The last two treat it as "no opinion
 
 A subscriber that inherits a tier below `trusted` loses its install secrets. A job that installs from a private registry then fails at install time.
 
-A `minimumTrust` context holds an `unknown` subscriber for security review, whatever value the context declares. Trust is a ref-based judgement with two answers, so `minimumTrust: 'trusted'` and the deprecated `minimumTrust: 'known'` block the same thing. The declared value still decides the wording of the hold reason. A subscriber that inherited the legacy `known` tier from a run row written by an earlier build passes both.
+A `minimumTrust: 'trusted'` context holds an `unknown` subscriber for security review. Trust is a ref-based judgement with two answers, so that is the only floor a context can declare.
 
 Both symptoms appear far from their cause. The tier belongs to the **emitting** run, so read that run's tier first.
 
@@ -1439,9 +1439,8 @@ Global workflows are gated by a **fleet-wide master switch** held by the orchest
 | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | Allowed author repos | Restricts which repos can **author** (register) global workflows. Globs matched against the authoring repo identifier. When OFF, any repo in the org may author globals.                             | Lock authoring to `myorg/ci-*` so random product repos can't ship org-wide automation. |
 | Blocked source repos | Blocks dispatch for events emitted from these **source** repos, regardless of authoring. Globs matched against the event source repo identifier. When OFF, events from any repo may trigger globals. | Protect against fork spam — e.g. `!myorg/*` via `myorg/fork-*`.                        |
-| Elevated access      | **Deprecated and not enforced.** Stored and echoed back, but nothing reads it — a global workflow's job receives no secrets, so there is no access for it to grant. See _Secrets are not available_. | None. Clear the list so it does not imply a grant that is not in force.                |
 
-All three lists accept globs. Leading `!` inside a single pattern is not supported here; negation is via the list-is-implicit-deny semantics, so keep it simple (`myorg/ci-*`, `myorg/platform-*`).
+Both lists accept globs. Leading `!` inside a single pattern is not supported here; negation is via the list-is-implicit-deny semantics, so keep it simple (`myorg/ci-*`, `myorg/platform-*`).
 
 Patterns match repo identifiers by the same rule as `repos:` on a trigger: an identifier is an owner/name pair, not a file path, so a leading dot carries no meaning of its own and a wildcard segment matches one. `myorg/*` covers `myorg/.github`, and `**` covers every repo in the org. Review any existing entry that relies on a wildcard to reach — or to spare — a dot-prefixed repo name.
 
@@ -1476,8 +1475,6 @@ This is about your **stored secrets**, not about repository access: the job is s
 
 To run something that needs secrets on a source repo's event, put those jobs in a per-repository workflow in that repo, where the workflow's `contexts:` resolve normally.
 
-The **Elevated access** setting reads as the way to lift this, and it is not: it is **deprecated and never consulted**. Nothing in the dispatch path reads the list, and adding a repo to it does not make any secret readable. It is kept only so an existing value stays visible and clearable, and is removed at the next major version — see [Deprecations](https://docs.kici.dev/user/deprecations/).
-
 ## When does it fire?
 
 Same-repo globals (a workflow in `myorg/app` with `repos: ['myorg/app']`) fire on pushes to `myorg/app`. Cross-repo globals fire on pushes to any source repo whose identifier matches a glob on the authoring workflow's trigger. The orchestrator de-duplicates between the per-repo and cross-repo matching passes, so a single event produces at most one run per (workflow, source-repo, trigger) triple.
@@ -1530,7 +1527,7 @@ A `filter` reads the source tree, so the evaluation must be able to obtain one.
 | Global workflow registered but never runs                                                       | Master toggle OFF, or allow-list blocks the authoring repo, or deny-list blocks the source repo                                                                                                                        | Orchestrator log: `Skipping global workflow dispatch` (dispatch time) / `Global workflows excluded from registration` (registration time)                                                                                                                                                                                                    |
 | A global workflow is never registered at all — it is absent from `kici-admin registration list` | The fleet-wide master switch is off, or the authoring repo does not match a populated _Allowed author repos_ list.                                                                                                     | Orchestrator log: `Global workflows excluded from registration`, naming the organization it decided against. Check the switch first (`kici-admin cluster-settings show`), then that org's allow-list in the dashboard. An `"orgId": "__default__"` in the line is not itself the fault — that anchor carries no lists and restricts nothing. |
 | `repos:` has no effect — workflow only fires on its own repo                                    | The fleet-wide master switch is off. Without it, the orchestrator treats the workflow as per-repo-only.                                                                                                                | Check the fleet-wide switch with `kici-admin cluster-settings show`. The dashboard → Settings → Global workflows tab shows it as a read-only badge.                                                                                                                                                                                          |
-| Secrets unavailable in a global job                                                             | Expected — a global workflow's job receives no secrets at all, and the _Elevated access_ list is not enforced.                                                                                                         | Move the jobs that need credentials into a per-repository workflow in the repo that owns the secrets                                                                                                                                                                                                                                         |
+| Secrets unavailable in a global job                                                             | Expected — a global workflow's job receives no secrets at all.                                                                                                                                                         | Move the jobs that need credentials into a per-repository workflow in the repo that owns the secrets                                                                                                                                                                                                                                         |
 | Dashboard shows workflow twice after registering                                                | Both a generic webhook source and a provider source (github, generic) re-registered the same repo.                                                                                                                     | Check `workflow_registrations` via `kici-admin workflow list` and confirm the right routing key owns the workflow.                                                                                                                                                                                                                           |
 | Global workflow registered, enabled, allowed — and still no run appears                         | Its `filter` returned `false`. A global filter runs before the run is created, so a suppressed workflow leaves nothing behind at all.                                                                                  | [Reading a global workflow's filter output](https://docs.kici.dev/user/global-workflows/#reading-a-global-workflows-filter-output) — the evaluation round's own log. The orchestrator also logs `Global workflow skipped by eval round`, naming the workflow and the reason.                                                                                                             |
 | Global workflow never fires for one particular source repo                                      | Its `repos:` patterns do not match that repo's identifier.                                                                                                                                                             | Orchestrator log: `Global workflows dropped by their repos filter` — one line per delivery, naming each dropped workflow, its repo and its patterns.                                                                                                                                                                                         |
@@ -1870,7 +1867,7 @@ Bind provisioning and teardown workflows to a context that carries the cloud cre
 
 ## The cloud-init that starts the agent
 
-`buildAgentCloudInit(creds, options)` renders the `#cloud-config` that boots the KiCI agent. In the claim-code form it writes the single-use claim code — never a token — into a root-only env file (`0600`, owned by root). The agent exchanges that code for its own token inside the instance, so the token never transits cloud-init, the instance metadata, or any other provisioning channel. The env file holds:
+`buildAgentCloudInit(creds, options)` renders the `#cloud-config` that boots the KiCI agent. It writes the single-use claim code — never a token — into a root-only env file (`0600`, owned by root). The agent exchanges that code for its own token inside the instance, so the token never transits cloud-init, the instance metadata, or any other provisioning channel. The env file holds:
 
 - `KICI_ORCHESTRATOR_URL` — from `creds.orchestratorUrl`.
 - `KICI_SCALER_CLAIM_CODE` — from `creds.claimCode`. The agent exchanges it for its own token in-instance.
@@ -1886,11 +1883,14 @@ The `0600` env file still protects the non-secret env from other users on the in
 
 Pass any of these options to shape the boot:
 
+- `agentImage` — the agent image `deliveryMode: 'container'` runs. Defaults to `quay.io/kici-dev/kici-agent:latest`.
+- `startCommand` — an escape hatch that replaces the whole agent-start command. It ignores `deliveryMode` and `agentImage`.
 - `packages` — extra apt/yum packages, merged into the cloud-init `packages:` list.
 - `writeFiles` — extra `write_files` entries (path, content, permissions, owner). The reserved env-file path is rejected, so a custom file cannot overwrite the credentials.
 - `runcmdBefore` / `runcmdAfter` — shell lines that run before or after the agent starts.
 - `agentEnv` — extra variables appended to the agent env file. Keys must be valid env names, and a value with a newline is rejected.
 - `baseCloudConfig` — a raw cloud-config document to merge everything into (users, ssh keys, apt mirrors, mounts, bootcmd). The builder unions its `packages`, `runcmd`, and `write_files` with yours.
+- `userDataEncoding` — `'raw'` (the default) returns the plain `#cloud-config` text that Hetzner `user_data` expects; `'base64'` returns it base64-encoded, the form AWS EC2 `UserData` and Azure `customData` expect.
 
 ## The teardown workflow
 
@@ -2061,7 +2061,7 @@ scalers:
 
 On `kici.scaler.scale-up`, the provisioning workflow dispatches a `kici-agent.yml` workflow run in a GitHub repo. It passes the claim code, orchestrator URL, agent id, and labels as dispatch inputs. The token never appears in those inputs — only the single-use claim code, which the agent exchanges for its own token in-instance.
 
-The `kici-agent.yml` run starts the agent on the runner itself with `KICI_SCALER_CLAIM_CODE` set. `KICI_SCALER_MANAGED=1` and a zero idle timeout make the agent register, run one job, and exit. The GitHub Actions run then completes on its own. By default the run installs the published agent from npm; set `agent_bundle_release` to a release tag holding a `kici-admin agent package` tarball to pin an exact build or to serve runners that cannot reach npm.
+The `kici-agent.yml` run starts the agent on the runner itself with `KICI_SCALER_CLAIM_CODE` set. `KICI_SCALER_MANAGED=1` and a zero idle timeout make the agent register, run one job, and exit. The GitHub Actions run then completes on its own. The job carries `timeout-minutes: 15`. A wedged run (an agent the orchestrator refused, a job that never dispatched) then releases the runner instead of holding it for the six-hour default. Raise the limit if your jobs run longer. By default the run installs the published agent from npm; set `agent_bundle_release` to a release tag holding a `kici-admin agent package` tarball to pin an exact build or to serve runners that cannot reach npm.
 
 Teardown is largely automatic. A GitHub Actions run self-completes when its agent exits. So the `kici.scaler.scale-down` workflow only cancels a run GitHub has not yet marked finished, and only for reasons where the agent will never do useful work (`spawn-timeout`, `heartbeat-timeout`).