@kici-dev/compiler 0.1.26 → 0.2.0

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

@@ -1,86 +1,151 @@
 # KiCI Getting started
 
-This bundle covers: Install the SDK, write your first workflow, compile and test locally.
+This bundle covers: Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow.
 
 ## User guide
 
 Source: https://docs.kici.dev/user/
 
-Documentation for workflow authors -- people writing CI/CD pipelines in TypeScript using the KiCI SDK and compiler. If you are defining workflows, running local tests, or learning the SDK API, start here.
+KiCI runs your CI/CD on infrastructure you control -- your own orchestrator and agents clone the code and run every job, while the hosted platform relays webhooks and renders the dashboard without ever seeing your source or secrets. You author workflows in real, typed TypeScript and run them locally before you push, so the pipeline you test on your laptop is the pipeline that runs in production. This section is for the people writing those workflows.
 
-## Pages
+## Start here
 
-### [Getting started with KiCI](https://docs.kici.dev/user/getting-started/)
+1. **[Green run in ~5 minutes](https://docs.kici.dev/user/quickstart/)** -- stand up an orchestrator and agent (Docker / Podman or bare metal) and watch your first workflow go green.
+2. **[Getting started](https://docs.kici.dev/user/getting-started/)** -- install the SDK and compiler, write your first workflow, compile it to a lock file, and test it locally with simulated events.
+3. **[Why KiCI](https://docs.kici.dev/user/why-kici/)** -- the case for running CI on your own infrastructure with typed TypeScript workflows.
+4. **[GitHub App provider](https://docs.kici.dev/user/providers/github/)** -- connect your first source and route real pull-request and push events.
 
-Install the SDK and compiler, write your first workflow, compile it to a lock file, and test it locally with simulated events. Covers prerequisites (Node.js 24+, pnpm), the `kici init` command for scaffolding, and the relationship between workflows, the lock file, and the three-tier runtime.
+## What's in the user guide
 
-### [SDK reference](https://docs.kici.dev/user/sdk-reference/)
+- **Authoring** -- the [SDK reference](https://docs.kici.dev/user/sdk-reference/) covers every factory function, trigger, rule, and matrix option; [workflow patterns](https://docs.kici.dev/user/workflow-patterns/) show monorepo builds, conditional jobs, dynamic matrices, and scheduling; [how your workflow code executes](https://docs.kici.dev/user/execution-model/) maps compile, orchestrator, and agent time.
+- **Running and testing** -- the [CLI reference](https://docs.kici.dev/user/cli-reference/) documents every command; the [testing guide](https://docs.kici.dev/user/testing-guide/) covers `kici run remote`, fixtures, and overlay mode; the [dashboard](https://docs.kici.dev/user/dashboard/) is the web UI for watching runs.
+- **Wiring sources** -- the [GitHub App](https://docs.kici.dev/user/providers/github/) and [universal-git](https://docs.kici.dev/user/providers/universal-git/) providers connect your forge; [global workflows](https://docs.kici.dev/user/global-workflows/) run cross-repo.
+- **Configuration and secrets** -- [contexts](https://docs.kici.dev/user/contexts/), [secrets](https://docs.kici.dev/user/secrets/), [dynamic values](https://docs.kici.dev/user/dynamic-values/), [concurrency groups](https://docs.kici.dev/user/concurrency/), [lifecycle hooks](https://docs.kici.dev/user/hooks/), and [environment variables](https://docs.kici.dev/user/env-vars/).
 
-Complete API reference for `@kici-dev/sdk`. Covers all factory functions (`workflow()`, `job()`, `step()`), trigger builders (`pr()`, `push()`), rule functions (`rule()`, `skip()`), matrix configuration (static arrays, static objects, dynamic functions, include/exclude), and the `StepContext` interface that steps receive at runtime.
+The left sidebar is the full index for the user guide -- every page in curated reading order.
 
-### [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/)
+---
+
+## How your workflow code executes
 
-Why the lock file must stay in sync with workflow source, how to commit both together, using pre-commit and CI to catch drift early, and the agent-side hash verification when compiling from source.
+Source: https://docs.kici.dev/user/execution-model/
 
-### [CLI reference](https://docs.kici.dev/user/cli-reference/)
+Your workflow is plain TypeScript, but different parts of it run at three distinct moments, on three different machines. Knowing which part runs where is the difference between a workflow that behaves and one that surprises you. This page is the map.
 
-All CLI commands provided by `@kici-dev/compiler`: `kici compile` (with watch mode and check mode), `kici run` (local and remote execution), `kici preview` (event simulation with dry-run, filtering, debug output, and custom payloads), `kici login`/`logout`/`org` (authentication and org management), `kici diagnostics` (infrastructure tree) and `kici runs` (`list`/`show`/`logs`/`rerun`/`cancel` — run management), `kici secrets` (secret listing), `kici types` (type generation), `kici fixture` (generate test payloads), `kici init` (interactive project scaffolding), `kici hook` (pre-commit hook installation), `kici endpoints` (webhook entrypoints), and `kici workflows` (workflow listing). Includes environment variables and exit codes.
+## The three phases
 
-### [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)
+| Phase            | Where it runs                            | What runs                                                                                                                                                     | When                      |
+| ---------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| **Compile**      | Your dev machine or CI (`kici compile`)  | Load your workflow modules, validate the DAG, assign step IDs, analyze dynamic-value purity, emit `kici.lock.json`                                            | Before anything is pushed |
+| **Orchestrator** | Your orchestrator (no repo clone)        | Match triggers against the lock, evaluate **pure** inline dynamic values in a sandboxed JavaScript VM, dispatch jobs                                          | On each incoming event    |
+| **Agent**        | An ephemeral agent (fresh clone per job) | Load the workflow module, evaluate job and step rules, run step bodies and hooks, run impure dynamic-value init jobs and `dynamicJob` generators (both forms) | After dispatch            |
 
-Common patterns for building real-world CI/CD workflows. Includes examples for basic CI pipelines with job dependencies, monorepo path-based triggering, conditional jobs with rules, matrix builds across Node versions, dynamic jobs generated at runtime, Docker-based step execution, and parallel test splitting.
+The lock file is the seam. Everything left of it is decided once at compile time and frozen into JSON; everything right of it reads that JSON. See [the lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/) and [the three-tier architecture](https://docs.kici.dev/architecture/overview/) for the wider picture.
 
-### [Dashboard](https://docs.kici.dev/user/dashboard/)
+## Compile time
 
-Guide to the KiCI web dashboard. Covers navigation (sidebar, org switcher, mobile bottom tabs), run list (table columns, filters, pagination, empty states), run detail (resizable two-panel layout, job tree, step selection, metadata tabs), log viewer (ANSI color rendering, search, permalink, copy), settings page (tabbed layout), theme toggle, keyboard shortcuts, and error pages.
+`kici compile` loads your `.kici/workflows/*.ts`, validates dependencies (no cycles, no missing `needs`), assigns compile-time step IDs (unnamed steps become `step-1`, `step-2`, …), runs purity analysis over every dynamic-value function, and writes `kici.lock.json`.
 
-### [Testing guide](https://docs.kici.dev/user/testing-guide/)
+The compiler runs your module's **top-level code** to build the workflow object — but that execution's side effects and in-memory state do not travel. Only the resulting workflow structure (plus the serialized source of pure dynamic-value functions) lands in the lock. Anything your top-level code computes that isn't part of the returned workflow object simply doesn't exist past this point.
 
-How to run and write tests for KiCI workflows, including remote test execution with `kici run remote`, fixture-based testing, and overlay mode for uncommitted changes.
+See [compile the workflow](https://docs.kici.dev/user/getting-started/#compile-the-workflow) for the command in context.
 
-### [Environments](https://docs.kici.dev/user/environments/)
+## What serializes into the lock file
 
-Configure deployment environments (staging, production, review/\*) with variables, scoped secrets, and protection rules. Covers the SDK API (`environment`, `env`, `concurrencyGroup` on jobs), the 8-layer variable merge precedence, protection rules (branch restrictions, required reviewers, wait timers, concurrency), dashboard management, type generation, and migration from the legacy contexts system.
+The lock is portable JSON. It carries:
 
-### [Environment variables](https://docs.kici.dev/user/env-vars/)
+- Workflow and trigger metadata.
+- The job and step DAG, with compile-time step IDs.
+- Static values, verbatim.
+- The **source text** of pure dynamic-value functions, as inline expressions.
 
-Reference for all `KICI_*` environment variables supported by the CLI. Covers authentication overrides (OIDC issuer, client ID, project ID), browser behavior (custom browser command, fixed callback port), development mode, and usage examples for CI/CD, alternate environments, and headless setups.
+It does **not** carry:
 
-### [CLI authentication](https://docs.kici.dev/user/cli-auth/)
+- Your module's runtime state or module-level variables.
+- Closures over those variables.
+- Live instances of modules you imported.
+- Anything computed at top level that isn't part of the returned workflow object.
 
-Authenticate the KiCI CLI with browser-based OAuth (default), device authorization flow (for headless environments), or API key paste (for CI/CD pipelines). Covers org management and PATs.
+The consequence is blunt: if a value isn't in the lock, the orchestrator can't see it — it has no copy of your repository.
 
-### [Event system](https://docs.kici.dev/user/events/)
+## Orchestrator time
 
-Event model concepts: event types, the registration model, event matching, and circuit breaker protection. Understanding this distinction is key to working with non-git triggers like schedules, custom events, and generic webhooks.
+On each event the orchestrator matches triggers using only the lock — it never clones your repository. Pure dynamic `context`, `env`, and `concurrencyGroup` functions are evaluated here, as inline expressions in a sandboxed JavaScript VM (~0ms overhead), instead of dispatching a separate job to resolve them.
 
-### [Lifecycle hooks](https://docs.kici.dev/user/hooks/)
+A runtime error in an inline expression fails the job immediately — there is no automatic fallback to the clone-and-evaluate path. The orchestrator does **not** run `dynamicJob` generator bodies itself: for the event-only (function) form it dispatches a dedicated dynamic-evaluation job to an agent at event time; the generator function then runs agent-side (see below).
 
-SDK hook API for cancel, cleanup, success, failure, and step-level callbacks. Hooks run at specific points in the execution lifecycle to react to outcomes and perform cleanup.
+See [dynamic values](https://docs.kici.dev/user/dynamic-values/) for the exact rules that make a function pure or impure.
 
-### [Concurrency groups](https://docs.kici.dev/user/concurrency/)
+## Agent time
 
-Control parallel execution with auto-cancel and queue modes. Prevent multiple workflow runs from executing in parallel when they target the same resource.
+After dispatch, each job runs in its own ephemeral agent sandbox: a shallow clone at the dispatch ref (or a source-tarball extract for non-build jobs), then the workflow module is loaded fresh — TypeScript is transformed on import. On the agent, in order:
 
-### [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
+1. **Job-level rules** are evaluated. By this point the agent has already spawned and the source has already been restored, so a job that its rules skip has **still** paid for that spawn and clone; only its steps are avoided.
+2. **Step-level rules**, then each step's `run()` body and its hooks.
+3. **Impure** dynamic values are resolved here too, via an init job that clones and evaluates the function (~5–10s) before the real job runs.
+4. **`dynamicJob` generators run here — both forms.** The event-only (function) form runs in a dedicated evaluation job dispatched at event time; the result-aware (options) form is deferred until its declared `needs` complete, then run with the upstream outputs frozen as `ctx.needs`.
 
-Compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event payload. Instead of hardcoding static strings, pass a function that receives the webhook event and returns the resolved value.
+See [job execution](https://docs.kici.dev/architecture/execution/job-execution/) and [hooks and rules](https://docs.kici.dev/user/hooks/) for the details.
 
-### [Secrets](https://docs.kici.dev/user/secrets/)
+## What re-evaluates where
 
-Access encrypted secrets in workflow steps via the explicit secrets API. Secrets are never auto-injected into `process.env` -- you must explicitly request each secret by name.
+| Construct                    | Runs on          | When                            |
+| ---------------------------- | ---------------- | ------------------------------- |
+| Static value                 | Compile → lock   | Never re-evaluated              |
+| Pure dynamic value           | Orchestrator VM  | Per event                       |
+| Impure dynamic value         | Agent init job   | Per event                       |
+| Job-level rules              | Agent            | After clone                     |
+| Step-level rules             | Agent            | Per step                        |
+| `dynamicJob` (function form) | Agent (eval job) | Dispatched at event time        |
+| `dynamicJob` (options form)  | Agent            | Deferred until `needs` complete |
+| Step / job body + hooks      | Agent            | Per job                         |
 
-### [GitHub App provider](https://docs.kici.dev/user/providers/github/)
+**Determinism note.** `ctx.event` and `ctx.needs` are frozen snapshots — captured once and replayed unchanged on any re-evaluation. A generator that derives its output from them is stable across re-evaluations; one that reads the wall clock (`Date.now()`) or a random source (`Math.random()`) is not.
 
-The flagship source. Covers creating the GitHub App on GitHub's side (permissions, webhook URL, private key), registering it with the orchestrator via `kici-admin source add github`, routing keys (`github:<appId>`), global-workflow policy, enriched Check runs on pull requests, private-key and webhook-secret rotation, and troubleshooting.
+## OutputProxy: how outputs flow
 
-### [Universal-git provider](https://docs.kici.dev/user/providers/universal-git/)
+`step(...).result` and `job(...).result` return an `OutputProxy` — a lazy proxy that, at the type level, mirrors the shape of the step or job's declared outputs so that reading `result.foo` is type-checked, and at runtime defers each property read to a shared outputs map populated as the run progresses.
+
+```typescript
+import { workflow, job, step, z } from '@kici-dev/sdk';
+
+const build = job('build', {
+  runsOn: 'default',
+  steps: [
+    step('compile', {
+      outputs: { artifact: z.string() },
+      run: async () => ({ artifact: 'app.tar.gz' }),
+    }),
+    step('publish', {
+      // `compile.result.artifact` is typed from the `outputs` schema above.
+      run: async ({ steps }) => {
+        await Promise.resolve(steps.compile.result.artifact);
+      },
+    }),
+  ],
+});
+
+export default workflow('build-and-publish', { jobs: [build] });
+```
 
-Connect a non-GitHub-App forge (Forgejo, Gitea, Gogs, GitLab, plain GitHub) to KiCI via its webhook. Covers preset selection, PAT and SSH credential wiring, credential rotation, global workflow policy against `generic:<orgId>:<sourceId>` routing keys, and troubleshooting.
+Outputs are typed across the job boundary too: reading `jobRef.result.…` or `ctx.jobOutputs(jobRef)` on a **job reference** threads the upstream job's inferred output shape through — from any job, in a step body or a `run:` shorthand — so a typo on an output field or a renamed step is a compile error. Typed `ctx.needs.jobRef.result.…` additionally works in a `run:` shorthand job (where the run function's `ctx` derives from the enclosing job's `needs` tuple). Name your steps and use the options form (`step('name', { run })`) to give a job a typed output shape, and pass references rather than string names — string-form `needs` stay loosely typed. See [output chaining](https://docs.kici.dev/user/sdk/core/#output-chaining) for the authoring rules.
 
-### [Global workflows](https://docs.kici.dev/user/global-workflows/)
+## Common footguns
 
-Cross-repo workflows that let a single workflow repo define jobs which run on events from many source repos in the same org. Covers the mental model (workflow repo vs. source repo, authoring axis vs. source axis), SDK syntax for declaring globals via `repos:` patterns, the dashboard opt-in flow and per-setting semantics (master toggle, author allow-list, source deny-list, elevated-access list), the security model, and troubleshooting skipped dispatches.
+| Symptom                                                                                                                        | Why                                                                                                                             | Fix                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| A top-level `let seen = 0` (or a cache filled in job A) is empty in job B                                                      | Each job loads the workflow module fresh in its own agent process after its own clone — there is no shared memory between jobs  | Pass data through step/job **outputs** (`OutputProxy` / `needs`), not module variables                                                   |
+| `context: (event) => event.ref + SUFFIX`, where `SUFFIX` is a module constant, silently falls back to the slower init-job path | Purity analysis only allows the function's own params, locals, and a fixed safe-globals set — a free identifier makes it impure | Inline the constant, or accept the init-job path knowingly. See [pure functions](https://docs.kici.dev/user/dynamic-values/#pure-functions-inline-evaluation)   |
+| Fan-out job identities shift between re-evaluations                                                                            | `ctx.event` / `ctx.needs` are frozen and replayed, but `Date.now()` / `Math.random()` are not                                   | Derive job identity only from the frozen event/needs snapshot                                                                            |
+| A rule-skipped job still spawned an agent and cloned                                                                           | Job-level rules evaluate agent-side, after dispatch and clone — not on the orchestrator                                         | This is by design: rules can read true runtime context (`$`, `changedFiles`, `env`). See [step-level rules](https://docs.kici.dev/user/hooks/#step-level-rules) |
+
+## See also
+
+- [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
+- [Hooks and rules](https://docs.kici.dev/user/hooks/)
+- [Lock file and drift](https://docs.kici.dev/user/lock-file-and-drift/)
+- [Job execution (architecture)](https://docs.kici.dev/architecture/execution/job-execution/)
+- [SDK: rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/)
 
 ---
 
@@ -123,6 +188,12 @@ The package manager is detected from your repo's `packageManager` field, lockfil
 | `--skip-install`                      | Create files without installing dependencies                 |
 | `--package-manager <npm\|pnpm\|yarn>` | Force a package manager for the install step (default: auto) |
 | `--mjs`                               | JavaScript-only mode (no TypeScript, no deps)                |
+| `--workspace`                         | Integrate `.kici/` into the surrounding workspace            |
+| `--standalone`                        | Force a self-contained `.kici/` even inside a workspace      |
+
+### Workspace integration
+
+If you run `kici init` inside a pnpm, npm, or yarn workspace, it offers to **integrate** `.kici/` into that workspace instead of scaffolding a self-contained folder. In integrate mode there is no `.kici/package.json`: `@kici-dev/sdk` is added to your workspace-root `package.json`, and your workflows can `import` your other workspace packages directly — for example shared build or deploy utilities. Pass `--workspace` to opt in non-interactively, or `--standalone` to keep the self-contained layout. In CI the default is standalone. See the [`kici init` reference](https://docs.kici.dev/user/cli/account-and-org/#kici-init) for details.
 
 ### MJS mode
 
@@ -177,7 +248,7 @@ Create `.kici/workflows/ci.ts`:
 import { workflow, job, step, pr } from '@kici-dev/sdk';
 
 const lint = job('lint', {
-  runsOn: 'linux',
+  runsOn: 'kici:os:linux',
   steps: [
     step('install', async ({ $ }) => {
       await $`pnpm install --frozen-lockfile`;
@@ -189,7 +260,7 @@ const lint = job('lint', {
 });
 
 const test = job('test', {
-  runsOn: 'linux',
+  runsOn: 'kici:os:linux',
   needs: [lint],
   steps: [
     step('install', async ({ $ }) => {
@@ -213,7 +284,7 @@ This workflow:
 - Runs a `lint` job first
 - Runs a `test` job after lint succeeds (`needs: [lint]`)
 
-`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration — `kici init` scaffolds workflows with exactly that. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms) reference for the full label model.
+`runsOn` selects which agents may run a job. Every agent self-reports `kici:os:<platform>`, `kici:arch:<cpu>`, and `kici:host:<hostname>`, so `runsOn: 'kici:os:linux'` targets any connected Linux agent with zero configuration. `kici init` scaffolds workflows targeting your own host's OS label (`kici:os:linux`, `kici:os:macos`, or `kici:os:windows`) so your first local run dispatches on this machine. Use a custom label such as `'linux'` or `'gpu'` (defined in your scaler's `labelSet`) to target a specific pool instead. See the [runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms) reference for the full label model.
 
 **Single-step shortcut.** If a job only has one step, pass `run` directly to `job()` instead of building a `steps: [step(...)]` array:
 
@@ -277,21 +348,15 @@ Decision Summary:
 
 ## Run locally
 
-Execute matched workflows locally with `kici run local`:
+Execute matched workflows locally with `kici run <event> --local`:
 
 ```bash
-npx kici run local pr:open
+npx kici run pr:open --local
 ```
 
-This compiles, matches triggers, and runs all matched jobs with DAG-based parallel scheduling.
-
-If you do not want to remember the event arg, pass `--pick` (or `-p`) and pick from a list of workflows instead:
+This compiles, matches triggers, and runs all matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based parallel scheduling.
 
-```bash
-npx kici run local --pick
-```
-
-The picker lists each workflow with a summary of its declared triggers, derives the event arg for the one you choose, and runs it through the same pipeline.
+If a run never appears or a webhook seems ignored, run `kici doctor` — it walks your login, organization, orchestrator connection, and compiled lock file, and tells you the exact command to fix the first broken step.
 
 ## Workflow dependencies
 
@@ -416,14 +481,14 @@ Or add the flag to your root `package.json`:
 
 ## Authoring KiCI workflows with LLM coding agents
 
-KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
+KiCI is LLM-ready by design. Because workflows are real, typed TypeScript, coding agents reason over the SDK's `.d.ts` signatures instead of guessing a bespoke YAML DSL — and they verify their own pipelines with the same `kici preview` and `kici run <event> --local` loop you use, so there's no push-to-find-out round-trip. First-class agent context ships in the box, so an agent is briefed the moment it opens the project.
 
 KiCI ships first-class context for LLM coding agents (Claude Code, Cursor, Aider, etc.). When you scaffold a project with `kici init`, the CLI writes `.kici/AGENTS.md`, a one-page briefing that tells the agent:
 
 - where the SDK type declarations live (`node_modules/@kici-dev/sdk/dist/index.d.ts`)
 - the five canonical authoring patterns with runnable examples
 - the anti-patterns that catch agents off-guard (no YAML, no `/dist/...` imports, no top-level `await`)
-- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run local`, `kici docs llm`)
+- the local commands the agent should drive (`kici compile --check`, `kici preview`, `kici run <event> --local`, `kici docs llm`)
 
 If you don't want the file, pass `--no-agents-md` to `kici init`, or delete the file afterwards — KiCI never reads it at runtime.
 
@@ -449,6 +514,7 @@ The compiler watches `.kici/workflows/*.ts` and recompiles on every save.
 ## Next steps
 
 - **[5-minute quickstart](https://docs.kici.dev/user/quickstart/)** -- ready to run your workflow on real infrastructure? Stand up an orchestrator + agent (Docker / Podman or bare metal)
+- **[How your workflow code executes](https://docs.kici.dev/user/execution-model/)** -- the mental model: which parts of your workflow run at compile time, on the orchestrator, and on the agent
 - **[SDK reference](https://docs.kici.dev/user/sdk-reference/)** -- complete API for workflows, jobs, steps, triggers, rules, and matrix
 - **[CLI reference](https://docs.kici.dev/user/cli-reference/)** -- all CLI commands with options and examples
 - **[Workflow patterns](https://docs.kici.dev/user/workflow-patterns/)** -- common patterns for real-world CI/CD workflows
@@ -480,6 +546,158 @@ The lock file approach means the orchestrator stays git-agnostic -- it only need
 
 ---
 
+## Migrating from GitHub Actions
+
+Source: https://docs.kici.dev/user/migrating-from-github-actions/
+
+## Before you start
+
+KiCI workflows are real, typed TypeScript in `.kici/workflows/*.ts` instead of YAML in `.github/workflows/*.yml`. The compiler validates them ahead of time, and at run time the agent clones your repository and executes them on your own infrastructure. This guide maps the GitHub Actions concepts you already know to their KiCI equivalents, translates one realistic workflow side-by-side, and lists honestly what has no equivalent yet.
+
+Follow [getting started](https://docs.kici.dev/user/getting-started/) for the full setup. The mapping below assumes you have `@kici-dev/sdk` installed.
+
+## Concept mapping
+
+| GitHub Actions                                               | KiCI                                                                                                                     | Notes                                                                                                                                                              |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Workflow file `.github/workflows/ci.yml`                     | TypeScript module `.kici/workflows/ci.ts` that default-exports `workflow('ci', {...})`                                   | Workflows are modules built from `workflow()`, `job()`, and `step()` factories.                                                                                    |
+| `on: pull_request:`                                          | `on: pr({ target: 'main' })`                                                                                             | `pr()` is a trigger factory; `on` takes one trigger or an array of triggers.                                                                                       |
+| `on: push: branches: [main]`                                 | `on: push({ branches: ['main'] })`                                                                                       | `push()` matches by branch pattern.                                                                                                                                |
+| `on: schedule: - cron:`                                      | `on: schedule({ cron: '0 2 * * *', timezone: 'UTC' })`                                                                   | `cron` is required; `timezone` defaults to `UTC`. In a cluster only the leader evaluates schedules.                                                                |
+| `on: workflow_dispatch: inputs:`                             | `on: dispatch({ inputs: defineDispatchInputs({...}) })`, read typed via `inputs.from(ctx)`                               | Dispatch inputs are declared with Zod schemas and read back fully typed.                                                                                           |
+| `jobs:` map keyed by name                                    | `jobs: [job('lint', {...}), job('test', {...})]`                                                                         | Jobs are an array of `job()` results.                                                                                                                              |
+| `needs: [build]` (string references)                         | `needs: [buildJob]` (object references)                                                                                  | You reference the `job()` value directly; the compiler validates the dependency graph for cycles and missing references.                                           |
+| `runs-on: <hosted runner>`                                   | `runsOn: 'kici:os:linux'` or a custom scaler label                                                                       | Every agent self-reports labels such as `kici:os:linux`, `kici:arch:x64`, and `kici:host:<hostname>`. A GitHub-hosted runner label matches no KiCI agent.          |
+| `steps: - run: npm test`                                     | `steps: [step('test', async ({ $ }) => { await $\`npm test\` })]`                                                        | The `$` in a step body is a zx shell; a single-step job can use the `run:` function shorthand instead of `steps:`.                                                 |
+| `steps: - uses: actions/checkout@v4`                         | (nothing)                                                                                                                | The agent clones the repository automatically before steps run, so there is no explicit checkout step.                                                             |
+| `steps: - uses: actions/setup-node@v4`                       | Provision the toolchain in a step or from the agent image                                                                | KiCI has no `uses:`-style setup actions; the toolchain comes from the agent environment or an explicit step.                                                       |
+| `${{ secrets.NPM_TOKEN }}`                                   | `await ctx.secrets.get('NPM_TOKEN')`, or `ctx.secrets.expose('NPM_TOKEN')` to place it in the environment                | Secrets are never auto-injected into `process.env`; access is always explicit.                                                                                     |
+| `environment: production` (+ protection rules)               | `context: 'production'` (or `contexts: ['staging', 'prod']`)                                                             | A context carries variables, bound secrets, and protection rules (branch restrictions, required reviewers, wait timers, concurrency limits, minimum trust).        |
+| `env:` (job or step level)                                   | `env: { KEY: 'val' }` on a job                                                                                           | Job-level `env` accepts a static object or a `(event) => ({...})` function for dynamic values.                                                                     |
+| `strategy: matrix: node: [18, 20, 22]`                       | `matrix: ['18', '20', '22']` or `{ node: [...], os: [...] }`                                                             | A single-dimension array exposes `matrix.value`; an object expands all combinations and exposes each dimension by name. A dynamic function form is also supported. |
+| `if: github.ref == 'refs/heads/main'`                        | Native TypeScript conditionals plus `rule()` / `skip()` and dynamic values                                               | Conditions are real TypeScript branching; dynamic values are pure functions of the normalized event.                                                               |
+| `concurrency: group: ...`                                    | `concurrencyGroup: 'production-api'` (static) or a dynamic function                                                      | Set at the job level; a workflow-level concurrency group also exists.                                                                                              |
+| `jobs.<id>.outputs`                                          | Structured job and step outputs consumed downstream via `needs`; `ctx.setSecretOutput(key, value)` for encrypted outputs | Outputs pass values between jobs; secret outputs are encrypted.                                                                                                    |
+| `- uses: actions/cache@v4`                                   | `cache` field on a job or step (declarative) or `ctx.cache.restore` / `ctx.cache.save` (imperative)                      | A keyed cache, immutable once written, org- and ref-scoped, backed by the orchestrator's object storage.                                                           |
+| Reusable workflows / composite actions / marketplace `uses:` | `@kici-dev/action-*` building blocks or any npm package you `import`                                                     | Reusable logic is imported as functions, not referenced by `uses:`.                                                                                                |
+
+### Secrets are explicit
+
+KiCI never copies secrets into `process.env` for you. A step reads a value with `ctx.secrets.get('KEY')` or injects it into the environment with `ctx.secrets.expose('KEY')`, and can mount a secret as a file with `ctx.secrets.mountFile(...)`. Every access is tracked. See [secrets](https://docs.kici.dev/user/secrets/).
+
+### Environments become contexts
+
+A GitHub environment maps to a KiCI context bound at the job level with `context:` (or `contexts:` for several). A context carries variables, bound secrets, and protection rules — branch restrictions, required reviewers, wait timers, concurrency limits, and a minimum-trust gate. See [contexts](https://docs.kici.dev/user/contexts/).
+
+### `if:` becomes real TypeScript
+
+There is no expression mini-language. Conditions are ordinary TypeScript, and values that depend on the event are pure functions of the normalized event object. See [dynamic values](https://docs.kici.dev/user/dynamic-values/).
+
+### Matrix
+
+A single-dimension matrix is an array (`matrix: ['18', '20', '22']`) and exposes the current value as `matrix.value` in the step context. A multi-dimension matrix is an object and exposes each dimension by name. See [conditionals and matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/).
+
+### Caching
+
+Declare a `cache` on a job or step, or drive it imperatively with `ctx.cache.restore(spec)` and `ctx.cache.save(spec)`. Cache entries are keyed and immutable once written. See [caching](https://docs.kici.dev/user/sdk/caching/).
+
+## A real workflow, translated
+
+Here is a pull-request CI workflow that runs tests across a Node version matrix and uploads coverage using a secret.
+
+The GitHub Actions version:
+
+```yaml
+name: ci
+on:
+  pull_request:
+    branches: [main]
+jobs:
+  test:
+    # kici-lint-allow-github-runner: GitHub-hosted runner shown for contrast
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['18', '20', '22']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
+      - run: npx codecov
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+```
+
+The KiCI translation:
+
+```typescript
+import { workflow, job, step, pr } from '@kici-dev/sdk';
+
+const test = job('test', {
+  runsOn: 'kici:os:linux',
+  matrix: ['18', '20', '22'],
+  context: 'ci',
+  steps: [
+    step('install', async ({ $ }) => {
+      // The agent already cloned the repo — no checkout step needed.
+      await $`npm ci`;
+    }),
+    step('test', async ({ $, matrix }) => {
+      // matrix.value is the Node version for this cell ('18' | '20' | '22').
+      // Select it however your agent provisions toolchains, e.g. a version manager.
+      await $`nvm use ${matrix!.value}`;
+      await $`npm test`;
+    }),
+    step('coverage', async (ctx) => {
+      await ctx.secrets.expose('CODECOV_TOKEN');
+      await ctx.$`npx codecov`;
+    }),
+  ],
+});
+
+export default workflow('ci', {
+  on: pr({ target: 'main' }),
+  jobs: [test],
+});
+```
+
+What changed and why:
+
+- `on: pull_request` → `on: pr({ target: 'main' })`.
+
+<!-- kici-lint-allow-github-runner: contrasts GitHub's ubuntu-latest with the KiCI auto-label -->
+
+- `runs-on: ubuntu-latest` → `runsOn: 'kici:os:linux'`, an auto-label every Linux agent reports; a GitHub hosted-runner label would match no agent. See [runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms).
+- `actions/checkout` → removed; the agent clones the repository before steps run.
+- `actions/setup-node` with `matrix.node` → `matrix: ['18', '20', '22']`, with the current value available as `matrix.value` in the step context. KiCI has no built-in setup-node, so toolchain selection is a step or agent-image concern. See [conditionals and matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/).
+- `${{ secrets.CODECOV_TOKEN }}` → `ctx.secrets.expose('CODECOV_TOKEN')`, explicit and never auto-injected. See [secrets](https://docs.kici.dev/user/secrets/).
+- `environment` → `context: 'ci'`. See [contexts](https://docs.kici.dev/user/contexts/).
+
+The `nvm use` line is illustrative — KiCI does not install a Node version for you; use whatever your agent image or step provides.
+
+## What has no equivalent yet
+
+**File artifacts between jobs.** KiCI has no first-class store for uploading a build directory as a named artifact and downloading it in a later job or from the run UI. It does have structured job and step outputs (and secret outputs) for passing _values_, and a keyed [cache](https://docs.kici.dev/user/sdk/caching/) for reusing files across runs. For build outputs you need to hand between jobs, use the cache or an external object store.
+
+**A community action marketplace.** GitHub Actions has thousands of third-party marketplace actions addressable by `uses: owner/repo@ref`. KiCI's reusable blocks are the published `@kici-dev/action-*` packages plus any npm package you import — there is no marketplace of community-contributed actions.
+
+**`uses:`-style step references.** KiCI steps are TypeScript functions, so you call reusable logic as imported library functions rather than referencing a composite or container action. This is a model shift rather than a missing feature, but a drop-in `uses:` translation does not exist.
+
+**Provider breadth.** KiCI is GitHub-first. Other git hosts are reachable through the universal-git and local-file providers, but the richest event coverage is for GitHub. See [the GitHub provider](https://docs.kici.dev/user/providers/github/).
+
+## Next steps
+
+- [Getting started](https://docs.kici.dev/user/getting-started/)
+- [SDK reference — runsOn forms](https://docs.kici.dev/user/sdk/core/#runson-forms)
+- [Conditionals and matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/)
+- [Secrets](https://docs.kici.dev/user/secrets/) and [contexts](https://docs.kici.dev/user/contexts/)
+- [CLI reference](https://docs.kici.dev/user/cli-reference/)
+
+---
+
 ## 5-minute quickstart
 
 Source: https://docs.kici.dev/user/quickstart/
@@ -514,6 +732,44 @@ If you're not sure, pick Docker / Podman.
 
 ## Looking for the laptop-only path?
 
-Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici preview` and `kici run local` instead.
+Both quickstarts deploy a real orchestrator + agent. If you only want to write a workflow and dry-run it on your laptop with no infrastructure, [Getting started](https://docs.kici.dev/user/getting-started/) covers `kici preview` and `kici run <event> --local` instead.
+
+---
+
+## Why KiCI
+
+Source: https://docs.kici.dev/user/why-kici/
+
+Most CI platforms ask you to hand your source, your secrets, and your build machines to someone else. KiCI is built the other way around: your code runs on infrastructure you control, and you describe the pipeline in real TypeScript you can run before you push. This page is the short argument for that trade -- what it buys you, and what it costs.
+
+## Your infrastructure runs the code
+
+KiCI is a three-tier relay. The hosted platform is a thin webhook router: it verifies the incoming webhook signature and relays the event to your orchestrator over a WebSocket. Your **orchestrator** decides what to run and dispatches jobs to your **agents**, which clone the repository, execute the steps, and stream logs back. The orchestrator and agents run on machines you own.
+
+Because of that split, the hosted platform sees only the envelope, never the payload:
+
+- **What it receives:** the webhook event, run metadata (workflow and job names, statuses, timings), aggregate operational metrics, and log lines while you are streaming them to the dashboard.
+- **What it never sees:** your source, your secrets, your artifacts, or your signing material. Those stay on your orchestrator and agents. Log content is relayed only in transit for the live dashboard view -- the platform never stores it.
+
+The hosted platform is operated by KiCI; you do not run your own. What you run is the orchestrator and the agents, and that is where every byte of your code and every secret lives. For the field-level breakdown of what does and does not leave your infrastructure, see [Data residency](https://docs.kici.dev/operator/data-residency/), and for the honest security posture of self-hosting the agents, see [Is self-hosting the agents a security risk?](https://docs.kici.dev/operator/security/self-hosting-security/).
+
+## Workflows are TypeScript
+
+A KiCI workflow is a TypeScript program, not a YAML document. Jobs, steps, triggers, and matrices are typed values you compose with the full language -- loops, conditionals, functions, `async`/`await`, and your editor's autocompletion and type checking. Invalid pipelines fail at compile time, in your editor, instead of failing on the tenth push.
+
+The same TypeScript runs everywhere. `kici run --local` executes your workflow on your own machine against a simulated event, and that is the same execution model the agents use in production. Your local run is the production pipeline, so you debug a green run before it ever reaches a source event. This also makes workflows something an AI coding agent can author, type-check, and run before it opens a pull request.
+
+## The honest trade
+
+Running your own infrastructure is not free. You operate the orchestrator: a Docker / Podman or bare-metal service you stand up (in minutes for the quickstart topology), keep patched, back up, and upgrade. In exchange, you own your data, your egress, and your isolation model -- no third party executes your code or holds your secrets. KiCI is pre-1.0, so pin versions for production. See [Deploying the orchestrator](https://docs.kici.dev/operator/orchestrator/getting-started/) for what running it involves.
+
+## Compared to specific tools
+
+If you are weighing KiCI against a specific incumbent -- GitHub Actions, GitLab CI, CircleCI, Jenkins, Buildkite, and others -- the point-by-point comparisons live on the marketing site, kept current with sourced references. Start with the [GitHub Actions comparison](https://kici.dev/compare/github-actions), or browse [all comparisons](https://kici.dev/compare).
+
+## Next steps
+
+- **[Green run in ~5 minutes](https://docs.kici.dev/user/quickstart/)** -- stand up an orchestrator and agent and watch a workflow go green.
+- **[Getting started](https://docs.kici.dev/user/getting-started/)** -- write your first workflow and test it locally.
 
 ---