@kici-dev/compiler 0.8.0 → 0.9.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { realpathSync } from "node:fs";
 import { Argument, Command } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.8.0";
+const version = "0.9.0";
 /**
 * Top-level commands that were removed, mapped to their current equivalent.
 * Consulted when the CLI hits an unknown command so the user gets a precise
@@ -492,11 +492,12 @@ Environment variables:
 		});
 		process.exit(success ? 0 : 1);
 	});
-	program.command("feedback").description("Print how to report a discrepancy between what KiCI advertises and what it does. Files nothing.").option("--open", "Open the prefilled issue form in the default browser").option("--json", "Emit the reporting contract as JSON").action(async (options) => {
+	program.command("feedback").description("Print how to report a discrepancy between what KiCI advertises and what it does. Files nothing.").option("--open", "Open the prefilled issue form in the default browser").option("--json", "Emit the reporting contract as JSON").option("--draft <file>", "Build the prefilled issue-form URL from a JSON draft keyed by field id (with --open, open it)").action(async (options) => {
 		const { feedbackCommand } = await import("./commands/index.js");
 		const success = await feedbackCommand({
 			open: options.open,
-			json: options.json
+			json: options.json,
+			draft: options.draft
 		});
 		process.exit(success ? 0 : 1);
 	});

package/dist/commands/docs.js

@@ -3,11 +3,11 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 import pc from "picocolors";
 import { readFile, readdir, writeFile } from "node:fs/promises";
-import { logger, toErrorMessage } from "@kici-dev/core";
+import { docsUrl, logger, toErrorMessage } from "@kici-dev/core";
 import open from "open";
 //#region src/commands/docs.ts
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const DOCS_HOME_URL = "https://kici.dev/docs/";
+const DOCS_HOME_URL = docsUrl("");
 function bundleFilenameForTopic(topic) {
 	if (!topic) return "llms.txt";
 	if (topic === "full") return "llms-full.txt";

package/dist/commands/feedback.d.ts

@@ -5,6 +5,12 @@ export declare const FEEDBACK_TEMPLATE = "agent_report.yml";
 export declare const FEEDBACK_NEW_ISSUE_URL = "https://github.com/kici-dev/kici-public/issues/new?template=agent_report.yml";
 /** Suspected vulnerabilities go here instead, privately. */
 export declare const FEEDBACK_SECURITY_ADVISORY_URL = "https://github.com/kici-dev/kici-public/security/advisories/new";
+/** How an agent turns its draft into the prefilled form a person reviews and files. */
+export declare const FEEDBACK_DRAFT_COMMAND = "kici feedback --draft <file.json> --open";
+/** GitHub's practical URL ceiling; a longer draft violates "minimal" anyway. */
+export declare const FEEDBACK_URL_WARN_BYTES = 6000;
+/** A draft: the issue title plus one string per contract field, keyed by field id. */
+export type FeedbackDraft = Record<string, string>;
 export interface FeedbackField {
     id: string;
     label: string;
@@ -26,6 +32,10 @@ export interface FeedbackContract {
     requiredFields: FeedbackField[];
     prohibited: string[];
     privateReportCommand: string;
+    /** The command that turns a JSON draft into the prefilled issue-form URL. */
+    draftCommand: string;
+    /** The keys a draft must carry: `title` plus every required field's id. */
+    draftFields: string[];
 }
 /**
  * The single definition of what a reportable discrepancy is and what a report
@@ -34,11 +44,22 @@ export interface FeedbackContract {
  * thing — so the CLI and the doc cannot drift apart.
  */
 export declare const FEEDBACK_CONTRACT: FeedbackContract;
+export declare function parseFeedbackDraft(raw: unknown): {
+    ok: true;
+    draft: FeedbackDraft;
+} | {
+    ok: false;
+    problems: string[];
+};
+/** The form URL with every draft field prefilled — GitHub reads each query param by field id. */
+export declare function draftIssueUrl(draft: FeedbackDraft): string;
 export interface FeedbackOptions {
     /** Open the prefilled issue form in the default browser. */
     open?: boolean;
     /** Emit the contract as JSON on stdout instead of prose. */
     json?: boolean;
+    /** Path to a JSON draft; print (and with --open, open) the prefilled issue-form URL. */
+    draft?: string;
 }
 /**
  * Print the contract for reporting a KiCI discrepancy: what qualifies, what a
@@ -47,7 +68,8 @@ export interface FeedbackOptions {
  *
  * The command reaches no network and files nothing. `--open` opens the
  * prefilled issue form; `--json` emits the same contract for an agent to
- * consume without parsing prose.
+ * consume without parsing prose; `--draft <file>` builds the issue-form URL
+ * with every field of a JSON draft prefilled.
  */
 export declare function feedbackCommand(options?: FeedbackOptions): Promise<boolean>;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -1,6 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import pc from "picocolors";
-import { logger, toErrorMessage } from "@kici-dev/core";
+import { readFile } from "node:fs/promises";
+import { docsUrl, logger, toErrorMessage } from "@kici-dev/core";
 import open from "open";
 //#region src/commands/feedback.ts
 /** The public tracker. Reports about KiCI itself go here — never customer data. */
@@ -10,6 +11,10 @@ const FEEDBACK_TEMPLATE = "agent_report.yml";
 const FEEDBACK_NEW_ISSUE_URL = `${FEEDBACK_TRACKER_URL}/issues/new?template=${FEEDBACK_TEMPLATE}`;
 /** Suspected vulnerabilities go here instead, privately. */
 const FEEDBACK_SECURITY_ADVISORY_URL = `${FEEDBACK_TRACKER_URL}/security/advisories/new`;
+/** How an agent turns its draft into the prefilled form a person reviews and files. */
+const FEEDBACK_DRAFT_COMMAND = "kici feedback --draft <file.json> --open";
+/** GitHub's practical URL ceiling; a longer draft violates "minimal" anyway. */
+const FEEDBACK_URL_WARN_BYTES = 6e3;
 /**
 * The single definition of what a reportable discrepancy is and what a report
 * must carry. `kici feedback` prints it, `--json` emits it verbatim, and
@@ -21,7 +26,7 @@ const FEEDBACK_CONTRACT = {
 	newIssueUrl: FEEDBACK_NEW_ISSUE_URL,
 	template: FEEDBACK_TEMPLATE,
 	securityAdvisoryUrl: FEEDBACK_SECURITY_ADVISORY_URL,
-	guideUrl: "https://kici.dev/docs/user/reporting-discrepancies/",
+	guideUrl: docsUrl("user/reporting-discrepancies/"),
 	searchCommand: "gh issue list --repo kici-dev/kici-public --search \"<terms>\" --state all",
 	approval: {
 		required: true,
@@ -59,8 +64,13 @@ const FEEDBACK_CONTRACT = {
 		},
 		{
 			id: "version",
-			label: "Version and environment",
-			description: "Output of `kici --version`, plus Node version and OS."
+			label: "KiCI version",
+			description: "Output of `kici --version`."
+		},
+		{
+			id: "environment",
+			label: "Environment",
+			description: "Node version and OS."
 		},
 		{
 			id: "justification",
@@ -74,8 +84,48 @@ const FEEDBACK_CONTRACT = {
 		"No log excerpts you have not read line by line.",
 		"Reproduce with a minimal synthetic workflow, never the real one you were working on."
 	],
-	privateReportCommand: "kici report --run <run-id> --upload"
+	privateReportCommand: "kici report --run <run-id> --upload",
+	draftCommand: FEEDBACK_DRAFT_COMMAND,
+	draftFields: [
+		"title",
+		"advertised",
+		"observed",
+		"reproduction",
+		"version",
+		"environment",
+		"justification"
+	]
 };
+function parseFeedbackDraft(raw) {
+	const problems = [];
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		problems: ["draft must be a JSON object keyed by field id"]
+	};
+	const input = raw;
+	const allowed = new Set(FEEDBACK_CONTRACT.draftFields);
+	for (const key of Object.keys(input)) if (!allowed.has(key)) problems.push(`unknown field: ${key}`);
+	const draft = {};
+	for (const id of FEEDBACK_CONTRACT.draftFields) {
+		const value = input[id];
+		if (value === void 0) problems.push(`missing required field: ${id}`);
+		else if (typeof value !== "string" || value.trim() === "") problems.push(`field must be a non-empty string: ${id}`);
+		else draft[id] = value;
+	}
+	return problems.length === 0 ? {
+		ok: true,
+		draft
+	} : {
+		ok: false,
+		problems
+	};
+}
+/** The form URL with every draft field prefilled — GitHub reads each query param by field id. */
+function draftIssueUrl(draft) {
+	const url = new URL(FEEDBACK_NEW_ISSUE_URL);
+	for (const id of FEEDBACK_CONTRACT.draftFields) url.searchParams.set(id, draft[id] ?? "");
+	return url.toString();
+}
 function printContract() {
 	const c = FEEDBACK_CONTRACT;
 	logger.info(pc.bold("Reporting a KiCI discrepancy"));
@@ -108,6 +158,7 @@ function printContract() {
 	logger.info(`  ${c.approval.rule}`);
 	logger.info(`  Form: ${c.newIssueUrl}`);
 	logger.info(pc.gray(`  Or: kici feedback --open`));
+	logger.info(pc.gray(`  From a draft: ${c.draftCommand} (fields: kici feedback --json → draftFields)`));
 	logger.info("");
 	logger.info(pc.gray("Machine-readable: kici feedback --json"));
 }
@@ -118,25 +169,51 @@ function printContract() {
 *
 * The command reaches no network and files nothing. `--open` opens the
 * prefilled issue form; `--json` emits the same contract for an agent to
-* consume without parsing prose.
+* consume without parsing prose; `--draft <file>` builds the issue-form URL
+* with every field of a JSON draft prefilled.
 */
 async function feedbackCommand(options = {}) {
+	if (options.draft) return draftFromFile(options.draft, options.open === true);
 	if (options.json) {
 		process.stdout.write(`${JSON.stringify(FEEDBACK_CONTRACT, null, 2)}\n`);
 		return true;
 	}
 	printContract();
 	if (!options.open) return true;
+	return openOrExplain(FEEDBACK_NEW_ISSUE_URL);
+}
+/** Read a JSON draft, print its prefilled issue-form URL as the last stdout line, open it on request. */
+async function draftFromFile(file, openIt) {
+	let raw;
+	try {
+		raw = JSON.parse(await readFile(file, "utf8"));
+	} catch (error) {
+		logger.error(pc.red(`Could not read the draft at ${file}: ${toErrorMessage(error)}`));
+		return false;
+	}
+	const parsed = parseFeedbackDraft(raw);
+	if (!parsed.ok) {
+		for (const problem of parsed.problems) logger.error(pc.red(problem));
+		logger.info(pc.gray(`Fields: ${FEEDBACK_CONTRACT.draftFields.join(", ")} — see kici feedback --json`));
+		return false;
+	}
+	const url = draftIssueUrl(parsed.draft);
+	if (url.length > 6e3) logger.warn(pc.yellow(`The prefilled URL is ${url.length} bytes; GitHub may truncate it. Shorten the reproduction.`));
+	process.stdout.write(`${url}\n`);
+	if (!openIt) return true;
+	return openOrExplain(url);
+}
+async function openOrExplain(url) {
 	try {
-		await open(FEEDBACK_NEW_ISSUE_URL);
+		await open(url);
 		return true;
 	} catch (error) {
 		logger.error(pc.red(`Could not open a browser: ${toErrorMessage(error)}`));
-		logger.info(pc.gray(`Open ${FEEDBACK_NEW_ISSUE_URL} manually.`));
+		logger.info(pc.gray(`Open ${url} manually.`));
 		return false;
 	}
 }
 //#endregion
-export { FEEDBACK_CONTRACT, FEEDBACK_NEW_ISSUE_URL, FEEDBACK_SECURITY_ADVISORY_URL, FEEDBACK_TEMPLATE, FEEDBACK_TRACKER_URL, feedbackCommand };
+export { FEEDBACK_CONTRACT, FEEDBACK_DRAFT_COMMAND, FEEDBACK_NEW_ISSUE_URL, FEEDBACK_SECURITY_ADVISORY_URL, FEEDBACK_TEMPLATE, FEEDBACK_TRACKER_URL, FEEDBACK_URL_WARN_BYTES, draftIssueUrl, feedbackCommand, parseFeedbackDraft };
 
 //# sourceMappingURL=feedback.js.map

package/dist/commands/index.d.ts

@@ -57,9 +57,9 @@ export type { WorkflowsListOptions } from './workflows.js';
 export { drainWorkerCommand } from './drain-worker.js';
 export type { DrainWorkerOptions } from './drain-worker.js';
 export { docsCommand, docsLlmCommand } from './docs.js';
-export { feedbackCommand, FEEDBACK_CONTRACT } from './feedback.js';
+export { feedbackCommand, FEEDBACK_CONTRACT, parseFeedbackDraft, draftIssueUrl, } from './feedback.js';
 export type { DocsOptions, DocsLlmOptions } from './docs.js';
-export type { FeedbackOptions, FeedbackContract, FeedbackField } from './feedback.js';
+export type { FeedbackOptions, FeedbackContract, FeedbackField, FeedbackDraft, } from './feedback.js';
 export { verifyAttestationCommand } from './verify-attestation.js';
 export type { VerifyAttestationOptions } from './verify-attestation.js';
 export { notificationsChannelsListCommand, notificationsChannelsAddCommand, notificationsChannelsRemoveCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsRemoveCommand, notificationsRosterListCommand, notificationsRosterAddCommand, notificationsRosterRemoveCommand, } from './notifications.js';

package/dist/commands/index.js

@@ -6,7 +6,7 @@ import { docsCommand, docsLlmCommand } from "./docs.js";
 import { doctorCommand } from "./doctor.js";
 import { drainWorkerCommand } from "./drain-worker.js";
 import { endpointsCommand } from "./endpoints.js";
-import { FEEDBACK_CONTRACT, feedbackCommand } from "./feedback.js";
+import { FEEDBACK_CONTRACT, draftIssueUrl, feedbackCommand, parseFeedbackDraft } from "./feedback.js";
 import { fixtureCommand } from "./fixture.js";
 import { hookInstallCommand } from "./hook.js";
 import { watchCommand } from "./watch.js";
@@ -35,4 +35,4 @@ import { rejectCommand } from "./reject.js";
 import { workflowsListCommand } from "./workflows.js";
 import { verifyAttestationCommand } from "./verify-attestation.js";
 import { notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand } from "./notifications.js";
-export { FEEDBACK_CONTRACT, approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, drainWorkerCommand, endpointsCommand, feedbackCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, patCreateCommand, previewCommand, previewEvent, rejectCommand, reportCommand, reportListCommand, reportWithdrawCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };
+export { FEEDBACK_CONTRACT, approveCommand, compileCommand, diagnosticsCommand, docsCommand, docsLlmCommand, doctorCommand, draftIssueUrl, drainWorkerCommand, endpointsCommand, feedbackCommand, fixtureCommand, hookInstallCommand, initCommand, localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localTrustRootCommand, localUpCommand, loginCommand, logoutCommand, notificationsChannelsAddCommand, notificationsChannelsListCommand, notificationsChannelsRemoveCommand, notificationsRosterAddCommand, notificationsRosterListCommand, notificationsRosterRemoveCommand, notificationsSubscriptionsAddCommand, notificationsSubscriptionsListCommand, notificationsSubscriptionsRemoveCommand, orchestratorsListCommand, orchestratorsUseCommand, orgCurrentCommand, orgListCommand, orgUseCommand, parseFeedbackDraft, patCreateCommand, previewCommand, previewEvent, rejectCommand, reportCommand, reportListCommand, reportWithdrawCommand, runRemoteCommand, runRoutedCommand, runsArtifactsDownloadCommand, runsArtifactsListCommand, runsCancelCommand, runsListCommand, runsLogsCommand, runsRerunCommand, runsShowCommand, secretsListCommand, typesCommand, verifyAttestationCommand, watchCommand, workflowsListCommand };

package/dist/commands/local.d.ts

@@ -62,9 +62,10 @@ export declare function localDownCommand(): Promise<boolean>;
  */
 export declare function localLogsCommand(): Promise<boolean>;
 /**
- * Attach the local dev plane to the hosted Platform so `kici run --local` uses
- * real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
- * with the logged-in PAT, then (re)boots the plane hybrid.
+ * Attach the local dev plane to the hosted Platform so `kici run --local` mints
+ * OIDC + attestation with the plane's own signing key under its own issuer, as
+ * a deployed orchestrator does. Mints an org-scoped orchestrator key with the
+ * logged-in PAT, then (re)boots the plane hybrid.
  */
 export declare function localAttachCommand(): Promise<boolean>;
 /** Detach the local dev plane from the Platform and reboot it offline (independent). */

package/dist/commands/local.js

@@ -163,9 +163,10 @@ async function localLogsCommand() {
 	return true;
 }
 /**
-* Attach the local dev plane to the hosted Platform so `kici run --local` uses
-* real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
-* with the logged-in PAT, then (re)boots the plane hybrid.
+* Attach the local dev plane to the hosted Platform so `kici run --local` mints
+* OIDC + attestation with the plane's own signing key under its own issuer, as
+* a deployed orchestrator does. Mints an org-scoped orchestrator key with the
+* logged-in PAT, then (re)boots the plane hybrid.
 */
 async function localAttachCommand() {
 	const config = await loadGlobalConfig();
@@ -190,7 +191,7 @@ async function localAttachCommand() {
 			orgId
 		});
 		console.log(pc.green("✓") + ` Local dev plane attached (hybrid) at ${pc.bold(status.url ?? "")} ` + pc.dim(`(org: ${orgId})`));
-		console.log(pc.dim("`kici run --local` now uses real Platform OIDC + attestation. Detach: ") + pc.cyan("kici local detach"));
+		console.log(pc.dim("`kici run --local` now mints OIDC + attestation with this plane's own key against the real Platform org. Detach: ") + pc.cyan("kici local detach"));
 		return true;
 	} catch (err) {
 		console.error(pc.red(`Attach failed: ${toErrorMessage(err)}`));

package/dist/commands/report/identity.js

@@ -19,7 +19,7 @@ import { PROTOCOL_VERSION } from "@kici-dev/engine";
 */
 function collectIdentity(probe) {
 	const identity = {
-		kiciCliVersion: "0.8.0",
+		kiciCliVersion: "0.9.0",
 		nodeVersion: process.version,
 		platform: process.platform,
 		arch: process.arch,

package/dist/commands/run-banner.d.ts

@@ -6,7 +6,7 @@
  *
  * Three variants:
  * - `offline`  — independent plane, local secrets, dev-signed identity.
- * - `attached` — hybrid plane, real Platform-minted OIDC + attestation.
+ * - `attached` — hybrid plane, OIDC + attestation signed by the plane's own key.
  * - `fallback` — wanted attached but the Platform was unreachable, so the run
  *   fell back to offline; a LOUD first line makes the degradation obvious.
  */

package/dist/commands/run-banner.js

@@ -5,7 +5,7 @@ function renderRunBanner(input) {
 	const title = input.mode === "attached" ? "kici run --local (connected)" : "kici run --local";
 	const rows = [];
 	if (input.mode === "fallback") rows.push(["⚠", `Platform unreachable — fell back to OFFLINE${input.fallbackReason ? ` (${input.fallbackReason})` : ""}`]);
-	if (input.mode === "attached") rows.push(["plane", "local dev orchestrator (hybrid, attached)"], ["agent", "this machine (bare-metal)"], ["secrets", `REAL scoped${input.orgId ? ` (org: ${input.orgId})` : ""}`], ["identity", "real Platform OIDC + attestation"], ["control", `kici local status | logs | detach   (${input.planeUrl})`], ["force", "--offline (local plane) · --in-place (ambient)"]);
+	if (input.mode === "attached") rows.push(["plane", "local dev orchestrator (hybrid, attached)"], ["agent", "this machine (bare-metal)"], ["secrets", `REAL scoped${input.orgId ? ` (org: ${input.orgId})` : ""}`], ["identity", `plane-signed OIDC + attestation (iss=${input.planeUrl})`], ["control", `kici local status | logs | detach   (${input.planeUrl})`], ["force", "--offline (local plane) · --in-place (ambient)"]);
 	else rows.push(["plane", "local dev orchestrator (independent, offline)"], ["agent", "this machine (bare-metal)"], ["secrets", "LOCAL files (.kici/.secrets, .env.local, --env)"], ["identity", "DEV-SIGNED (iss=kici-local — NOT prod)"], ["control", `kici local status | logs | down   (${input.planeUrl})`], ["force", "--connected (attach to Platform) · --in-place (ambient)"]);
 	if (input.trusted) rows.push(["execution", "TRUSTED — host env passthrough (NOT sandboxed)"]);
 	const labelWidth = Math.max(...rows.map(([label]) => label.length));

package/dist/commands/verify-attestation.js

@@ -78,7 +78,7 @@ async function verifyAttestationCommand(artifact, options = {}) {
 			if (c.source_origin === "run-remote") logger.info(pc.bold(pc.yellow("  SOURCE: kici run remote (local working-tree overlay — repository/ref/sha are caller-supplied, not a triggered VCS commit)")));
 			else logger.info(pc.gray(`  source: ${c.source_origin ?? "triggered"}`));
 			const origin = result.attestationOrigin ?? "live";
-			if (origin === "deferred") logger.info(pc.bold(pc.yellow("  ATTESTATION: deferred — the build facts were sealed at build time; the identity token was minted later (after a transient Platform outage), bound to the frozen statement by hash.")));
+			if (origin === "deferred") logger.info(pc.bold(pc.yellow("  ATTESTATION: deferred — the build facts were sealed at build time; the identity token was minted later (once the orchestrator's signing key was available), bound to the frozen statement by hash.")));
 			else if (origin === "offline-backfill") logger.info(pc.bold(pc.yellow("  ATTESTATION: offline-backfill — the run was ingested while the Platform was down; its run/job rows were backfilled and the token minted later. The org id is the authoritative anchor; the temporal gap is disclosed.")));
 			logger.info(pc.gray(`  repository=${c.repository} ref=${c.ref} sha=${c.sha} provider=${c.provider ?? "unknown"} run=${c.kici_run_id} job=${c.kici_job_id}`));
 		} else logger.error(`${pc.red("FAIL")} provenance NOT verified: ${result.failures.join(", ")}`);

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

@@ -411,7 +411,7 @@ Orchestrator                         Agent                    Sandbox (child pro
     |                                  |                          |
     |-- job.dispatch (WS) ------------>|                          |
     |   (jobConfig, sourceTarUrl,      |                          |
-    |    sourceTarHash, depsUrl,       |-- Create sandbox ------->|
+    |    sourceTarDigest, depsUrl,     |-- Create sandbox ------->|
     |    depsHash)                     |   (container/bare-metal/ |
     |                                  |    firecracker)          |
     |                                  |                          |-- Restore .kici/ source (tarball)
@@ -593,6 +593,8 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 When multiple webhooks trigger simultaneously for the same repository state, the `BuildCoordinator` coalesces concurrent build requests using a combined key (`contentHash:lockfileHash`). Only one build job runs; all waiting dispatches share the result.
 
+The coalescing map is per coordinator. The build job itself sits on the cluster-wide dispatch queue, so an agent connected to a sibling coordinator can claim it. That sibling persists the terminal `job.status` to the shared `execution_jobs` row (`precursor_result`), and the dispatching coordinator's `PendingPrecursorDbWatcher` reads the row back and settles the pending build through `settlePendingPrecursor()`. The local agent socket goes through the same function. See [runs that span coordinators](https://docs.kici.dev/operator/orchestrator/clustering/#runs-that-span-coordinators).
+
 ### Graceful degradation
 
 If cache storage is unavailable or a download fails:
@@ -667,7 +669,7 @@ Agent                         Orchestrator                    S3
   |                                |    for deps integrity)    |
 ```
 
-The two-phase metadata approach (`upload via PUT` then `initMeta via CopyObject`) works around the limitation that S3 pre-signed URLs cannot include custom metadata headers. For dependency tarballs, the agent also reports the SHA-256 content hash in `cache.upload.complete`; the orchestrator stores it as a companion `.hash` file alongside the tarball. When dispatching execution jobs, the orchestrator reads this hash and includes it as `depsHash` in `job.dispatch`, enabling agent-side integrity verification on download. Source tarballs do not use a companion `.hash` file — the workflow `contentHash` carried in `sourceTarHash` is used to verify the extracted source against the lock file after extraction, which covers drift end-to-end.
+The two-phase metadata approach (`upload via PUT` then `initMeta via CopyObject`) works around the limitation that S3 pre-signed URLs cannot include custom metadata headers. For dependency tarballs, the agent also reports the SHA-256 content hash in `cache.upload.complete`; the orchestrator stores it as a companion `.hash` file alongside the tarball. When dispatching execution jobs, the orchestrator reads this hash and includes it as `depsHash` in `job.dispatch`, enabling agent-side integrity verification on download. Source tarballs carry their own SHA-256 as `sourceTarDigest` in `job.dispatch`, verified before extraction; the workflow `contentHash` is then re-computed against the extracted source to verify it against the lock file, which covers drift end-to-end.
 
 ### URL delivery (downloads)
 
@@ -1166,7 +1168,7 @@ The compiler processes the workflow definition:
 
 When `kici run <event> --local` runs a workflow:
 
-1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the same `@kici-dev/sdk` module instance that the workflow uses (ensures the proxy reads from the same map)
+1. **SDK module resolution:** The runner resolves `setStepOutputsMap` / `setJobOutputsMap` from the `@kici-dev/sdk/internal` subpath of the same SDK copy that the workflow uses (ensures the proxy reads from the same map)
 2. **Map injection:** Fresh `OutputsMap` and `StepRefMap` are created and injected via `setStepOutputsMap()` / `setStepRefMap()` before each job
 3. **Step execution:** Each step runs sequentially. If the step returns a value, it is stored in the `OutputsMap` keyed by step name
 4. **Bare function normalization:** Bare functions in the steps array are assigned counter names and registered in the `StepRefMap` (maps function reference to step name)
@@ -1301,7 +1303,7 @@ The Platform never processes, stores, or executes customer code, and never sees
 
 The orchestrator is the execution brain. It decides what to run and dispatches work to agents.
 
-- **Trigger matching** -- Evaluates lock file triggers against webhook payloads to determine which jobs to run. Uses branch, path, and event matching via picomatch.
+- **Trigger matching** -- Evaluates lock file triggers against webhook payloads to determine which jobs to run. Uses glob-based branch, path, and event matching.
 - **Lock file caching** -- Fetches `kici.lock.json` via the configured source's fetcher (GitHub API, universal-git clone for generic webhook sources backed by a git URL, or the local filesystem for `file://` sources). An LRU cache wraps the per-provider fetcher, keyed by `{provider}:{repo}:{ref}` so cross-provider fallback resolutions stay isolated.
 - **Agent registry** -- Tracks connected agents with label-based routing for job dispatch.
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
@@ -1333,7 +1335,7 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
 - Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
-- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster), plus the deprecated `ContributorResolver` the pipeline no longer calls
+- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster)
 - Git credential vocabulary (forge names plus the credential reference, grant, request, and result shapes the SDK declares and the orchestrator's broker resolves) and the agent→orchestrator relay protocol its credential helper calls. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)
 - Trigger matching engine (branch, path, event evaluation)
 - Content-requirement matcher (the declarative `requires` filter -- pure data describing a query over the bytes of one source file at the event's ref, interpreted by the orchestrator via the `FileContentsFetcher` so no author code runs there) and the shared text-match vocabulary (`contains` / `notContains` / `matches` / `notMatches`) it shares with the commit-message trigger filter
@@ -1383,7 +1385,7 @@ It also runs the **local dev plane** -- an on-demand, fully local execution stac
 
 ### `@kici-dev/core`
 
-Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). One further subpath holds the `.kici/` source digest: the single content-hash definition the compiler writes into the lock file and the agent recomputes as its drift gate. Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
+Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). One further subpath holds the `.kici/` source digest: the single content-hash definition the compiler writes into the lock file and the agent recomputes as its drift gate. It also owns the published docs host: `docsUrl()` builds every docs link a CLI prints or a template scaffolds from one `DOCS_SITE_URL` constant, so no other package spells the host. Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
 
 > Source: `packages/core/src/`
 

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.
 
@@ -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`
 

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

@@ -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.
 
@@ -1542,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

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

@@ -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`).