@kici-dev/compiler 0.6.0 → 0.6.1

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

@@ -243,6 +243,10 @@ Reports contain your data, so there is no public tracker for them. Add
 kici report --run <run-id> --upload --message "matrix job hangs on macOS"
 ```
 
+A defect in KiCI itself is different: if you can reproduce it without your own
+data — the docs promise something the tool does not do — it belongs in the
+public tracker instead. See [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/).
+
 The command prints a reference id. Quote it in any conversation about the
 problem. The bundle goes straight from your machine to KiCI storage over a
 one-time upload link — it never passes through the dashboard.
@@ -271,7 +275,7 @@ someone who has left.
 ## Reporting a security issue
 
 Do not use `kici report` for a suspected vulnerability. Follow the disclosure
-process in [SECURITY.md](https://github.com/kici-dev/kici/blob/master/SECURITY.md)
+process in [SECURITY.md](https://github.com/kici-dev/kici-public/blob/main/SECURITY.md)
 instead.
 
 ## See also
@@ -629,7 +633,7 @@ For coding agents that want the entire documentation set up front, KiCI follows
 
 - `https://kici.dev/llms.txt` — curated link index grouped by SDK / patterns / CLI / architecture.
 - `https://kici.dev/llms-full.txt` — concatenated markdown of every page indexed above.
-- `kici docs llm` — print the same curated `llms.txt` index to stdout, offline, straight from the installed `@kici-dev/compiler` package. `kici docs llm <topic>` prints one task bundle (`getting-started`, `patterns`, `sdk`, `sdk-runtime`, `cli`, `features`, `features-execution`, `providers`, `architecture`), and `kici docs llm full` prints the whole `llms-full.txt`. Add `--out <path>` to write to a file. The agent can pipe the output into its own context buffer with no network call.
+- `kici docs llm` — print the same curated `llms.txt` index to stdout, offline, straight from the installed `@kici-dev/compiler` package. `kici docs llm <topic>` prints one task bundle (`getting-started`, `patterns`, `sdk`, `sdk-runtime`, `cli`, `cli-remote`, `features`, `features-execution`, `providers`, `architecture`), and `kici docs llm full` prints the whole `llms-full.txt`. Add `--out <path>` to write to a file. The agent can pipe the output into its own context buffer with no network call.
 - `kici docs` — open the docs site in your browser.
 
 The offline bundle is regenerated from `docs/` every time the package is built, so it always matches the version of KiCI you've installed.
@@ -839,6 +843,12 @@ KiCI offers two equally-supported quickstart paths. Pick the one that fits your
 
 Each guide is split into two parts. **Part 1** gets you a green run against your own orchestrator with `kici run remote` — no GitHub App needed, just sign up, bring up the stack, and run. **Part 2** then wires up real GitHub pushes so your team's commits trigger runs automatically. You can stop after Part 1 and come back to Part 2 whenever you're ready.
 
+## Bring a coding agent
+
+Workflows are TypeScript, so a coding agent can write them. KiCI ships its docs in a form an agent reads directly: point yours at [llms.txt](https://kici.dev/docs/llms.txt), or pipe a task bundle straight into its context with `kici docs llm` (`kici docs llm sdk` for the authoring API, `kici docs llm patterns` for recipes). An agent briefed that way can scaffold your first workflow, compile it, and read the failure when it breaks.
+
+If your agent finds that these docs promise something KiCI does not do, that is worth telling us — `kici feedback` prints how to report it, and [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/) is the full guide.
+
 ## Option A — Docker / Podman (recommended)
 
 Two containers brought up with `docker compose up -d` (orchestrator + PostgreSQL), plus one short-lived agent container spawned per job by the container scaler. Minimal host setup, perfect for a laptop, home server, or a tiny VM. No need to install PostgreSQL or any other system service.
@@ -869,6 +879,143 @@ Both quickstarts deploy a real orchestrator + agent. If you only want to write a
 
 ---
 
+## Reporting a discrepancy
+
+Source: https://docs.kici.dev/user/reporting-discrepancies/
+
+This page is addressed to a **coding agent** working with KiCI. KiCI is built to
+be driven by an LLM, so an agent is often the first to notice a mismatch. A
+documented flag does not exist; a command prints something the docs never
+promised. You can report that.
+
+A human reader can use this page too. The rules below exist because the tracker
+is public and you are filing under someone else's GitHub identity.
+
+Run `kici feedback` to print this contract in your terminal, or
+`kici feedback --json` to read it as structured data.
+
+## The rule, in one sentence
+
+You find a checkable mismatch between what the docs or the CLI advertise and
+what KiCI actually does. You draft an issue carrying a reproduction and a
+justification, and show it to the person you are working with. You file it only
+after they say yes.
+
+You never file on your own initiative.
+
+## What qualifies
+
+Report it when you can point at the claim and at the contradicting behaviour:
+
+- A documented flag, command, or option that does not exist in the version you ran.
+- Documented output — a shape, a field, an exit code — that differs from what the command produced.
+- A CLI `--help` description that contradicts the published docs.
+- A documented behaviour that does not happen, or a documented guarantee that does not hold.
+- A documented error or limit that the tool does not actually enforce.
+
+Two conditions apply to all of them. You ran the command and saw the result —
+inference from reading the docs is not a reproduction. And you ran a published
+version: check with `kici --version`.
+
+## What does not qualify
+
+- Usage questions, or behaviour you find surprising but that the docs describe correctly.
+- Feature requests and design preferences.
+- Anything you inferred from reading docs without running the command.
+- Anything reproduced only on a locally built or unreleased version.
+- A failure that is your workflow, your credentials, or your environment.
+
+If you are unsure whether the docs are wrong or you misread them, you are not
+ready to file. Say so to the person you are working with and let them decide.
+
+## Never file these publicly
+
+**A suspected vulnerability is never a public issue.** Do not file it, and do
+not describe it in one. Open a private
+[security advisory](https://github.com/kici-dev/kici-public/security/advisories/new)
+instead, or tell the person you are working with to. This holds even if the
+issue looks minor to you.
+
+**A problem with someone's own runs is not a tracker issue.** That covers a
+failing run, a broken deployment, and anything that needs their logs. Use the
+private path in [Getting help](https://docs.kici.dev/user/getting-help/) instead:
+`kici report --run <run-id> --upload` sends a redacted bundle straight to KiCI.
+
+**Never put customer data in a public issue:**
+
+- No secrets, tokens, or credentials — not even redacted-looking ones.
+- No private repository names, internal hostnames, organization ids, or run ids.
+- No log excerpts you have not read line by line.
+- Reproduce with a minimal synthetic workflow, never the real one you were working on.
+
+Rewriting the reproduction against a throwaway workflow in an empty directory is
+the reliable way to satisfy all four at once.
+
+## Search before you draft
+
+The tracker is small. The same finding arriving once per agent that reads the
+docs is worse than not hearing it at all:
+
+```bash
+gh issue list --repo kici-dev/kici-public --search "<terms>" --state all
+```
+
+Search closed issues too — a closed one may carry the answer, or the decision
+that the behaviour is intended. If a matching issue is open, add your
+reproduction as a comment instead of opening a second one, under the same
+approval rule.
+
+## What the report must carry
+
+Five things. A report missing any of them cannot be acted on:
+
+| Field                                 | What it holds                                                                                                        |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| What the docs or CLI advertise        | The exact claim, quoted, plus its source: a docs URL or the command whose `--help` says it.                          |
+| What actually happened                | The real output or behaviour, quoted, with any error text.                                                           |
+| Minimal reproduction, including setup | Every step from an empty directory: the setup commands, a minimal synthetic workflow, and the exact command you ran. |
+| Version and environment               | Output of `kici --version`, plus Node version and OS.                                                                |
+| Why this is a discrepancy             | One or two sentences ruling out the likely misreads — why the docs cannot be read to match what you observed.        |
+
+The last field is the one agents skip, and it is the one that makes a report
+usable. "The docs say `--foo` exists and it does not" is a claim. "`--foo` is
+documented at <url>, and `kici bar --help` on 0.1.16 lists no such flag" is a
+finding someone can act on in one pass.
+
+Include setup steps whenever your reproduction needed any. A reproduction that
+starts from state a maintainer cannot recreate is not a reproduction.
+
+## Filing it
+
+The tracker is [kici-dev/kici-public](https://github.com/kici-dev/kici-public),
+and the form is **Agent report**:
+
+```bash
+kici feedback --open
+```
+
+Draft the complete body first. Show it to the person you are working with —
+the whole body, not a summary of it. File only after they say yes:
+
+```bash
+gh issue create --repo kici-dev/kici-public --template agent_report.yml
+```
+
+The form asks you to confirm the report was drafted by an agent and reviewed by
+a person before filing. Answer honestly; it is what lets maintainers triage
+agent-filed reports as a group.
+
+If they say no, that is the end of it. Do not re-file the same finding in
+another form, and do not open it as a question instead.
+
+## See also
+
+- [Getting help](https://docs.kici.dev/user/getting-help/) — the private path for a problem with your own runs
+- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/) — the MCP server, and the agent safety model
+- [Common failures](https://docs.kici.dev/user/common-failures/) — check here before concluding the docs are wrong
+
+---
+
 ## Why KiCI
 
 Source: https://docs.kici.dev/user/why-kici/

package/dist/llm-context/llms.txt

@@ -4,17 +4,20 @@
 
 The full markdown bundle of every page indexed here is available at https://docs.kici.dev/llms-full.txt.
 
+Found a mismatch between what these docs advertise and what KiCI does? Read https://docs.kici.dev/user/reporting-discrepancies/ (or run `kici feedback`) before reporting it: a report needs a reproduction, and you draft it but a human decides to file it.
+
 ## Bundles
 
 Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
 
-- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (58 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
+- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (65 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
 - [patterns](https://docs.kici.dev/llms-patterns.txt) (57 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
 - [sdk](https://docs.kici.dev/llms-sdk.txt) (127 KB) — Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs
 - [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (114 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
-- [cli](https://docs.kici.dev/llms-cli.txt) (194 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
+- [cli](https://docs.kici.dev/llms-cli.txt) (90 KB) — Running the CLI locally: compile, test, run local, hooks, lock-file drift, common failures
+- [cli-remote](https://docs.kici.dev/llms-cli-remote.txt) (106 KB) — Auth, org and orchestrator selection, runs, approvals, notifications, diagnostics, and the MCP server a coding agent connects to
 - [features](https://docs.kici.dev/llms-features.txt) (90 KB) — Deployment contexts, scoped secrets, private registries, approvals, provenance, dashboard and account access
-- [features-execution](https://docs.kici.dev/llms-features-execution.txt) (120 KB) — Concurrency, dynamic values, events, container jobs, environment variables, global workflows, idempotent steps
+- [features-execution](https://docs.kici.dev/llms-features-execution.txt) (121 KB) — Concurrency, dynamic values, events, container jobs, environment variables, global workflows, idempotent steps
 - [providers](https://docs.kici.dev/llms-providers.txt) (35 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
 - [architecture](https://docs.kici.dev/llms-architecture.txt) (99 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
@@ -26,6 +29,7 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [Getting started with workflows](https://docs.kici.dev/user/getting-started/): Install the SDK, write your first workflow, compile and test locally
 - [Migrating from GitHub Actions](https://docs.kici.dev/user/migrating-from-github-actions/): Map GitHub Actions concepts to KiCI, translate a real workflow side-by-side, and see what has no equivalent yet
 - [5-minute quickstart](https://docs.kici.dev/user/quickstart/): Stand up a KiCI orchestrator + agent and run your first workflow
+- [Reporting a discrepancy](https://docs.kici.dev/user/reporting-discrepancies/): For coding agents — how to report a mismatch between what KiCI's docs advertise and what the tooling does, with the reproduction and the approval a report needs.
 - [Why KiCI](https://docs.kici.dev/user/why-kici/): The case for running CI on infrastructure you control, with typed TypeScript workflows you test locally
 
 ## Workflow patterns
@@ -58,18 +62,21 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [SDK reference: temp directories](https://docs.kici.dev/user/sdk/temp-directories/): Allocate job-scoped scratch dirs and files with ctx.mktemp() / ctx.mktempFile()
 - [SDK reference: waitFor](https://docs.kici.dev/user/sdk/wait-for/): Polling helpers for steps that pause until an external condition becomes true
 
-## CLI and authoring
+## CLI: authoring on your own machine
 
-- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/): Point a coding agent at KiCI's MCP server and let it trigger, read, and re-run your CI under your own identity.
-- [CLI authentication](https://docs.kici.dev/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
-- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, preview, local, fixture, types, workflows, hook, docs, run, runs, approve, reject, login, logout, init, org, pat, secrets, admin, orchestrators, endpoints, notifications, verify-attestation, diagnostics, doctor, report
+- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, preview, local, fixture, types, workflows, hook, docs, run, runs, approve, reject, login, logout, init, org, pat, secrets, admin, orchestrators, endpoints, notifications, verify-attestation, diagnostics, doctor, report, feedback
 - [Common failures](https://docs.kici.dev/user/common-failures/): Symptom-to-fix reference for the failures workflow authors hit most — no jobs dispatched, lock-file drift, missing webhooks, and agents that won't connect
 - [Lifecycle hooks](https://docs.kici.dev/user/hooks/): SDK hook API for cancel, cleanup, success, failure, and step-level callbacks
 - [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/): Keep the lock file in sync with your workflow source and avoid drift
 - [Testing guide](https://docs.kici.dev/user/testing-guide/): Running remote test fixtures with kici run remote
 - [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/): Common patterns: monorepo builds, conditional jobs, dynamic matrices, generic webhooks, scheduling
-- [kici: account & org](https://docs.kici.dev/user/cli/account-and-org/): Login, org selection, personal access tokens, secrets, and admin
 - [kici: authoring & local dev](https://docs.kici.dev/user/cli/authoring-and-local/): Compile, preview, local execution, fixtures, types, workflows, hooks, and docs
+
+## CLI: driving a deployed orchestrator
+
+- [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/): Point a coding agent at KiCI's MCP server and let it trigger, read, and re-run your CI under your own identity.
+- [CLI authentication](https://docs.kici.dev/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
+- [kici: account & org](https://docs.kici.dev/user/cli/account-and-org/): Login, org selection, personal access tokens, secrets, and admin
 - [kici: notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/): Notification channels, attestation verification, and diagnostics
 - [kici: runs & approvals](https://docs.kici.dev/user/cli/runs-and-approvals/): Run push and inspection plus approval / rejection of held runs
 

package/dist/local-plane/plane-manager.js

@@ -19,8 +19,8 @@ import { generateKeyPairSync, randomBytes } from "node:crypto";
 */
 function currentBuildIdentity() {
 	return {
-		version: "0.6.0",
-		buildCommit: "e4a936029"
+		version: "0.6.1",
+		buildCommit: "d32193b6b"
 	};
 }
 /**

package/dist/templates/package-json.js

@@ -1,6 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.6.0";
+const sdkVersion = "0.6.1";
 /**
 * The npm version range the scaffold pins `@kici-dev/sdk` to.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
     "ci",
@@ -62,17 +62,17 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/agent": "0.6.0",
-    "@kici-dev/core": "0.6.0",
-    "@kici-dev/engine": "0.6.0",
-    "@kici-dev/orchestrator": "0.6.0"
+    "@kici-dev/agent": "0.6.1",
+    "@kici-dev/core": "0.6.1",
+    "@kici-dev/engine": "0.6.1",
+    "@kici-dev/orchestrator": "0.6.1"
   },
   "devDependencies": {
     "@types/archiver": "^8.0.0",
     "jszip": "^3.10.1"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.6.0"
+    "@kici-dev/sdk": "0.6.1"
   },
   "scripts": {
     "build": "node ../../scripts/build-ts.mjs && tsgo --emitDeclarationOnly",