@kici-dev/compiler 0.1.25 → 0.1.27

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

@@ -1,6 +1,6 @@
 # KiCI Workflow features
 
-This bundle covers: Workflow features: concurrency, environments, secrets, approvals, provenance, events.
+This bundle covers: Workflow features: concurrency, contexts, secrets, approvals, provenance, events.
 
 ## Account and sign-in
 
@@ -107,7 +107,7 @@ job('deploy', {
 });
 ```
 
-`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `environments:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
+`approval: true` holds the element until **any** org member who can act on approvals signs off — anyone with the `contexts:write` or `ci_trust:write` permission. Use it when you want a manual gate without restricting who may release it.
 
 ### Approver list (AND)
 
@@ -228,7 +228,7 @@ A `when: 'drift'` gate on a step without a `check` facet, or at job/workflow sco
 
 ## Mandatory vs. explicit gates
 
-`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected environment via required reviewers (see [Environments](https://docs.kici.dev/user/environments/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
+`approval` is the **explicit** gate — a deliberate "pause for a human here" written by the workflow author. It composes with the **mandatory** gate an operator can attach to a protected context via required reviewers (see [Contexts](https://docs.kici.dev/user/contexts/#required-reviewers)). When both apply to the same job, all clauses from both sources must be satisfied before the job is released. The two funnel into one held-element mechanism, so the dashboard queue and `kici approve` work the same way regardless of which source held the element.
 
 ## Approving from the CLI
 
@@ -262,12 +262,14 @@ kici run remote deploy-prod --approve-all
 
 `--approve-all` is **run-scoped** — it only auto-approves holds belonging to the run this invocation dispatched; there is no fleet-wide or account-wide auto-approve. Eligibility is still enforced per hold: if you are not eligible for a gate, that gate still blocks. Each auto-approved gate prints its payload before resolving and is recorded distinctly in the audit trail (`held_run.auto_approve`).
 
-You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/environments-and-secrets/#approval-queue).
+`--approve-all` is honored in non-interactive runs too: with `--json` or `--quiet` (no TTY), the flag still auto-approves each eligible gate as it appears instead of hanging or printing out-of-band instructions. Hold notices are routed to stderr so `--json` stdout stays pure machine-readable output.
+
+You can also approve from the dashboard approval queue. See [Dashboard](https://docs.kici.dev/user/dashboard/contexts-and-secrets/#approval-queue).
 
 ## See also
 
 - [Idempotent steps](https://docs.kici.dev/user/idempotent-steps/) — the check/apply step facet that drift gates build on.
-- [Environments](https://docs.kici.dev/user/environments/) — operator-required reviewers on protected environments.
+- [Contexts](https://docs.kici.dev/user/contexts/) — operator-required reviewers on protected contexts.
 - [Approval gates (operator guide)](https://docs.kici.dev/operator/approvals/) — teams, the approval queue, expiry, and self-approval.
 - [Approval gates (architecture)](https://docs.kici.dev/architecture/approvals/) — the unified hold model and the step-level round-trip.
 
@@ -329,7 +331,7 @@ group: () => 'deploy';
 group: (ctx) => `deploy-${ctx.event.targetBranch ?? 'default'}`;
 ```
 
-The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Environments](https://docs.kici.dev/user/environments/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
+The workflow-level group function is always evaluated **agent-side** at runtime -- the lock file records only that a group function exists (`hasGroup: true`), not the function itself. The agent loads the workflow source, calls the group function with `{ branch, event }`, and reports the evaluated key back to the orchestrator before step execution begins. This differs from job-level `concurrencyGroup` (see [Contexts](https://docs.kici.dev/user/contexts/#concurrency-groups)), where the compiler performs purity analysis and can inline pure functions for orchestrator-side evaluation.
 
 ## cancelInProgress mode
 
@@ -422,7 +424,7 @@ workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'linux',
-      environment: 'staging',
+      context: 'staging',
       steps: [
         /* ... */
       ],
@@ -464,11 +466,11 @@ workflow('deploy', {
 });
 ```
 
-## Interaction with environment protection
+## Interaction with context protection
 
-When a workflow has both `concurrency` and `environment` protection rules:
+When a workflow has both `concurrency` and `context` protection rules:
 
-1. Environment protection gates (required reviewers, wait timer) apply first
+1. Context protection gates (required reviewers, wait timer) apply first
 2. Concurrency group check happens after protection gates pass
 3. If the run is queued by concurrency, it keeps its protection approval
 
@@ -480,17 +482,15 @@ Queued runs can be cancelled before they start executing. The cancel request rem
 
 ## Job-level concurrency groups
 
-In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Environments — concurrency groups](https://docs.kici.dev/user/environments/#concurrency-groups) for details.
+In addition to workflow-level concurrency, individual jobs can define their own concurrency group via the `concurrencyGroup` property. This controls concurrent execution at the job level rather than the workflow level. See [Contexts — concurrency groups](https://docs.kici.dev/user/contexts/#concurrency-groups) for details.
 
 ## Local execution
 
-`kici run local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
+`kici run <event> --local` honors workflow-level `concurrency` per-machine, per-user. The `group` callback is evaluated against the simulated event identically to the remote orchestrator path; `cancelInProgress` carries the same semantics — `true` interrupts the holder via `SIGTERM` (escalating to `SIGKILL` after a grace window) and proceeds with the new run, while `false` queues the new invocation in FIFO order until the holder finishes.
 
 Coordination is local only. Running the same workflow on two different machines does not serialize across them — that requires the orchestrator. For full cross-host enforcement (queueing across agents, dashboard visibility, `max > 1`), use `kici run remote` against a deployed orchestrator.
 
-Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
-
-The `kici run local --concurrency <n>` flag is a separate concept — it caps **job-level** parallelism within a single run (how many jobs from one workflow run at once), not cross-run serialization.
+Lock files live under `$XDG_RUNTIME_DIR/kici-local-locks/` on Linux, falling back to `os.tmpdir()/kici-local-locks-<uid>/`. A workflow whose `group` callback throws aborts the run with a clear error rather than running unprotected. See [`kici run <event> --local` — Concurrency enforcement](https://docs.kici.dev/user/cli-reference/#concurrency-enforcement) for the `KICI_LOCAL_LOCK_KILL_GRACE_MS` override and the diagnostic output emitted while contending on a busy lock.
 
 ---
 
@@ -498,239 +498,19 @@ _Source: `packages/sdk/src/types.ts` (WorkflowOptions.concurrency, JobOptions.co
 
 ---
 
-## Dashboard
-
-Source: https://docs.kici.dev/user/dashboard/
-
-The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
-
-This guide is split across the following pages:
-
-| Page                                                                                  | Covers                                                                  |
-| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
-| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
-| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
-| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
-| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
-| [Environments, secrets, and approvals](https://docs.kici.dev/user/dashboard/environments-and-secrets/)       | Environments, secret scopes, approval queue                             |
-| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
-| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
-
----
-
-## Dynamic values
-
-Source: https://docs.kici.dev/user/dynamic-values/
-
-Dynamic values let you compute `environment`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
-
-```typescript
-job('deploy', {
-  runsOn: ['default'],
-  environment: (event) => event.targetBranch,
-  env: (event) => ({ BRANCH: event.targetBranch }),
-  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
-  steps: [
-    /* ... */
-  ],
-});
-```
-
-```typescript
-job('deploy', {
-  runsOn: 'default',
-  // One shape everywhere: branch on the normalized event type.
-  environment: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
-  steps: [
-    /* ... */
-  ],
-});
-```
-
-## How it works
-
-When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
-
-### Pure functions (inline evaluation)
-
-A pure function is one that:
-
-- Is synchronous (no `async`/`await`)
-- Only references its parameters and local variables
-- Does not import or require external modules
-- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
-- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
-- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
-
-When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
-
-**Examples of pure functions:**
-
-```typescript
-// Simple branch extraction
-environment: (event) => event.targetBranch;
-
-// Object literal with string operations
-env: (event) => ({ BRANCH: event.targetBranch });
-
-// Concatenation with event data
-concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
-
-// Using safe globals
-env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
-
-// Local variables are fine
-environment: (event) => {
-  const parts = event.targetBranch.split('/');
-  return parts[parts.length - 1];
-};
-```
-
-### Impure functions (init-job evaluation)
-
-If the compiler determines a function is impure, it emits a warning during compilation and falls back to the two-phase init model. This means:
-
-1. The orchestrator dispatches a special `__init__` job to a builder agent
-2. The builder agent clones the repository and evaluates the function
-3. The resolved values are sent back to the orchestrator
-4. The orchestrator dispatches the real execution job with the resolved values
-
-This adds approximately 5-10 seconds of overhead for cloning and evaluation.
-
-**Examples of impure functions (will use init job):**
-
-```typescript
-// Async functions cannot be inlined
-environment: async (event) => await lookupEnv(event.targetBranch);
-
-// External module references
-env: (event) => {
-  const config = require('./config');
-  return config.env;
-};
-
-// Process/global access
-environment: (event) => process.env.DEFAULT_ENV || 'staging';
-
-// Dynamic imports
-env: async (event) => {
-  const m = await import('./config.js');
-  return m.default;
-};
-```
-
-## Performance comparison
-
-| Evaluation path                      | Overhead | When used                                                           |
-| ------------------------------------ | -------- | ------------------------------------------------------------------- |
-| Static value (string/object literal) | ~0ms     | `environment: 'staging'`                                            |
-| Inline expression (pure function)    | ~0ms     | `environment: (event) => event.targetBranch`                        |
-| Init job (impure function)           | ~5-10s   | `environment: async (event) => await lookupEnv(event.targetBranch)` |
-
-## Tips
-
-- **Write pure functions whenever possible** to avoid the init-job delay. Most environment and env computations only need the event payload data.
-- **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
-- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
-- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
-
----
-
-## Environment variables
-
-Source: https://docs.kici.dev/user/env-vars/
-
-The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
-
-## Authentication
-
-| Variable              | Description                            | Default                                      |
-| --------------------- | -------------------------------------- | -------------------------------------------- |
-| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
-| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
-| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
-| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
-
-## Browser behavior
-
-| Variable             | Description                                                                                                                                          | Default                                                |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser via the `open` package |
-| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port                                  |
-
-## Development
-
-| Variable     | Description                                                                                                                                                                | Default |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
-| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
-| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
-
-## Usage examples
-
-### CI/CD environment
-
-Authenticate with a pre-existing API key (no browser needed):
-
-```bash
-kici login --token <<< "$KICI_API_KEY"
-```
-
-### Targeting another environment or custom OIDC provider
-
-`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
-
-```bash
-export KICI_OIDC_ISSUER=https://your-idp.example.com
-export KICI_OIDC_CLIENT_ID=your-client-id
-export KICI_PLATFORM_URL=https://your-platform.example.com
-kici login
-```
-
-### Headless SSH session
-
-The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
-
-```bash
-export KICI_BROWSER_CMD=none
-kici login
-```
-
-This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
-
-### Fixed callback port
-
-When behind a firewall or using port forwarding:
-
-```bash
-export KICI_CALLBACK_PORT=19876
-kici login
-```
-
-### Custom config location
-
-Store the KiCI config in a non-default location:
-
-```bash
-export KICI_CONFIG_DIR=/tmp/kici-test
-kici login
-```
-
----
-
-## Environments
+## Contexts
 
-Source: https://docs.kici.dev/user/environments/
+Source: https://docs.kici.dev/user/contexts/
 
-<!-- help:environments-list#overview -->
+<!-- help:contexts-list#overview -->
 
-Environments are named deployment targets (like staging or production) that control where your workflow jobs run. Each environment can have its own variables, secrets, and protection rules to gate deployments.
+Contexts are named deployment targets (like staging or production) that control where your workflow jobs run. Each context can have its own variables, secrets, and protection rules to gate deployments.
 
-<!-- /help:environments-list -->
+<!-- /help:contexts-list -->
 
-<!-- help:environments-protection#protection-rules -->
+<!-- help:contexts-protection#protection-rules -->
 
-Protection rules control when jobs targeting an environment can execute.
+Protection rules control when jobs targeting a context can execute.
 
 Available rules:
 
@@ -739,24 +519,24 @@ Available rules:
 - **Wait timers** — delay execution for a fixed period.
 - **Concurrency limits** — prevent collisions between parallel deployments.
 
-<!-- /help:environments-protection -->
+<!-- /help:contexts-protection -->
 
-Environments represent deployment targets like `staging`, `production`, or `review/PR-*`. Each environment can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that environment can execute.
+Contexts represent deployment targets like `staging`, `production`, or `review/PR-*`. Each context can have its own variables, bound secrets, and protection rules that control when and how jobs targeting that context can execute.
 
 ## Overview
 
-An environment in KiCI provides:
+A context in KiCI provides:
 
 - **Variables** -- non-secret key-value configuration (e.g., `API_URL`, `CLUSTER_NAME`)
-- **Scoped secrets** -- encrypted values bound to the environment via scope bindings
+- **Scoped secrets** -- encrypted values bound to the context via scope bindings
 - **Protection rules** -- branch restrictions, required reviewers, wait timers, and concurrency limits
 - **Per-source overrides** -- repositories can override unlocked variables for their own deployments
 
 ## SDK API
 
-### Job-level environment property
+### Job-level context property
 
-The `environment` property is set on a job, not a workflow or step:
+The `context` property is set on a job, not a workflow or step:
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -766,16 +546,16 @@ export default workflow('deploy', {
   jobs: [
     job('deploy-staging', {
       runsOn: 'default',
-      environment: 'staging',
+      context: 'staging',
       steps: [
         step('deploy', async (ctx) => {
-          // ctx.environment is the resolved environment name
-          console.log(`Deploying to ${ctx.environment}`);
-          // ctx.secrets provides async get/expose/has methods for environment-bound secrets
+          // ctx.context is the resolved context name
+          console.log(`Deploying to ${ctx.context}`);
+          // ctx.secrets provides async get/expose/has methods for context-bound secrets
           const dbPassword = await ctx.secrets.get('DB_PASSWORD');
           // Environment variables are in ctx.env
           const apiUrl = ctx.env.API_URL;
-          await ctx.$`deploy --target ${ctx.environment}`;
+          await ctx.$`deploy --target ${ctx.context}`;
         }),
       ],
     }),
@@ -783,54 +563,54 @@ export default workflow('deploy', {
 });
 ```
 
-### Dynamic environments
+### Dynamic contexts
 
-The environment name can be a string or a function (sync or async) for dynamic environments (e.g., per-PR review environments). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
+The context name can be a string or a function (sync or async) for dynamic contexts (e.g., per-PR review contexts). The function receives the normalized event envelope, with the raw provider body nested at `event.payload`:
 
 ```typescript
 job('deploy-review', {
   runsOn: 'default',
-  environment: (event) => `review/PR-${event.payload.pull_request.number}`,
+  context: (event) => `review/PR-${event.payload.pull_request.number}`,
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.environment is 'review/PR-123' (resolved at runtime)
-      await ctx.$`deploy-preview --env ${ctx.environment}`;
+      // ctx.context is 'review/PR-123' (resolved at runtime)
+      await ctx.$`deploy-preview --env ${ctx.context}`;
     }),
   ],
 });
 ```
 
-A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic environments that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
+A pure function like the one above (see [Dynamic values](https://docs.kici.dev/user/dynamic-values/)) is evaluated inline at dispatch with no init-job overhead. Dynamic contexts that match a glob pattern (e.g., `review/*`) inherit the pattern's configuration, variables, and protection rules.
 
-### Multiple environments per job
+### Multiple contexts per job
 
-A job can bind more than one environment with `environments`, an ordered array. This lets a single job draw secrets and variables from several environments at once — for example a shared `staging` environment plus a `my-testing` environment that carries test-only variables:
+A job can bind more than one context with `contexts`, an ordered array. This lets a single job draw secrets and variables from several contexts at once — for example a shared `staging` context plus a `my-testing` context that carries test-only variables:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environments: ['staging', 'my-testing'],
+  contexts: ['staging', 'my-testing'],
   steps: [
     step('deploy', async (ctx) => {
-      // ctx.secrets and ctx.env carry the merged set from both environments
+      // ctx.secrets and ctx.env carry the merged set from both contexts
       const dbUrl = await ctx.secrets.get('DB_URL');
     }),
   ],
 });
 ```
 
-- `environment` (singular) and `environments` (array) are mutually exclusive — setting both is a compile error. `environment: 'staging'` is exactly equivalent to `environments: ['staging']`.
-- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic environment.
+- `context` (singular) and `contexts` (array) are mutually exclusive — setting both is a compile error. `context: 'staging'` is exactly equivalent to `contexts: ['staging']`.
+- Each array entry is a static name or a function of the event, resolved per element exactly like a single dynamic context.
 
-**Merge order — last wins.** All bound environments are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one environment, the later entry in the array wins. With `environments: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each environment.
+**Merge order — last wins.** All bound contexts are resolved on every dispatch (webhook, scheduled, and test runs alike) and merged in array order. When the same secret or variable key is defined in more than one context, the later entry in the array wins. With `contexts: ['staging', 'my-testing']`, a key defined in both resolves to `my-testing`'s value; keys defined in only one are preserved. The longest-scope-path-wins rule still applies _within_ each context.
 
-**Protection rules combine all-must-pass.** A job must satisfy **every** bound environment's gates — adding an environment can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all environments; the minimum trust tier is the most restrictive across them; required reviewers are the union of all environments' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which environment and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
+**Protection rules combine all-must-pass.** A job must satisfy **every** bound context's gates — adding a context can never loosen access. Branch restrictions, trigger-type filters, and repo patterns must pass for all contexts; the minimum trust tier is the most restrictive across them; required reviewers are the union of all contexts' reviewers; the wait timer is the longest; and the hold expiry is the shortest. If a run is gated out, the rejection names which context and which rule rejected it (visible via `kici runs show <run-id>` and the run's rejection reason), so a mutually-exclusive set of rules surfaces as a clear failure rather than a silent perpetual rejection.
 
-**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run local`), a bound environment never rejects the run. Any bound environment that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped environment(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `environments: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound environment is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
+**Skip-on-test (allow-and-warn).** On a test or local run (`kici run remote`, `kici run <event> --local`), a bound context never rejects the run. Any bound context that disallows local execution (`allowLocalExecution: false`) — or that is not configured — is **skipped**: its variables and secrets are omitted from the merge and its gates are not evaluated. The run proceeds, and a user-visible warning naming the skipped context(s) is shown both on the `kici run remote` CLI output and on the dashboard run view. This makes the test-only-variables pattern work: with `contexts: ['staging', 'my-testing']` where only `my-testing` allows local execution, a test run resolves just `my-testing`'s variables and warns that `staging` was skipped. If every bound context is skipped, the job runs with no environment variables. This is intentionally different from a fixture `secrets:` mapping, which is fail-closed — see the [testing guide](https://docs.kici.dev/user/testing-guide/).
 
-**Unconfigured environments contribute nothing at dispatch.** At dispatch time a bound environment name with no matching configured environment (and no matching glob environment) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic environment resolving to an as-yet-unconfigured name does today.
+**Unconfigured contexts contribute nothing at dispatch.** At dispatch time a bound context name with no matching configured context (and no matching glob context) simply adds no variables, secrets, or protection rules — the job still runs, exactly as a single dynamic context resolving to an as-yet-unconfigured name does today.
 
-**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-environment binding: a bound environment that does not exist, a disabled one, or two environments with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the environments, and the rule — for example `unsatisfiable environment binding: job 'deploy' binds environments [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound environments)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
+**Registration rejects a provably-unsatisfiable binding.** When a workflow is registered, KiCI statically checks every multi-context binding: a bound context that does not exist, a disabled one, or two contexts with mutually-exclusive fixed branch / trigger-type / repository restrictions (no value can satisfy both) makes the binding provably unsatisfiable, and the registration is rejected with a precise message naming the job, the contexts, and the rule — for example `unsatisfiable context binding: job 'deploy' binds contexts [staging, my-testing] with mutually exclusive branch restrictions (no value satisfies all bound contexts)`. Bindings whose restrictions use globs are undecidable at registration and fall through to the dispatch-time gate check instead.
 
 ### Job-level environment variables
 
@@ -839,7 +619,7 @@ The `env` property on a job provides static or dynamic environment variables:
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   env: { DEPLOY_TARGET: 'us-east-1' },
   // Or dynamic:
   // env: (event) => ({ DEPLOY_SHA: event.payload.after?.slice(0, 7) }),
@@ -854,14 +634,14 @@ job('deploy', {
 
 ### Concurrency groups
 
-Jobs can define their own concurrency groups to control concurrent execution within an environment. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
+Jobs can define their own concurrency groups to control concurrent execution within a context. For workflow-level concurrency (which applies to all jobs in a workflow), see [Concurrency groups](https://docs.kici.dev/user/concurrency/).
 
-Control concurrent deployments to the same environment:
+Control concurrent deployments to the same context:
 
 ```typescript
 job('deploy', {
   runsOn: 'default',
-  environment: 'production',
+  context: 'production',
   concurrencyGroup: 'production-api',
   // Or dynamic:
   // concurrencyGroup: (event) => `review-${event.payload.pull_request.number}`,
@@ -871,17 +651,17 @@ job('deploy', {
 });
 ```
 
-If no `concurrencyGroup` is specified, the environment name is used as the default concurrency group. For a job bound to multiple environments, the default is the **first** bound environment's name.
+If no `concurrencyGroup` is specified, the context name is used as the default concurrency group. For a job bound to multiple contexts, the default is the **first** bound context's name.
 
 ### Step context
 
 Inside a step, the `ctx` object provides:
 
-| Property          | Type                                  | Description                                                                               |
-| ----------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `ctx.environment` | `string \| undefined`                 | Resolved environment name (undefined for jobs without environment)                        |
-| `ctx.env`         | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
-| `ctx.secrets`     | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
+| Property      | Type                                  | Description                                                                               |
+| ------------- | ------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `ctx.context` | `string \| undefined`                 | Resolved context name (undefined for jobs without context)                                |
+| `ctx.env`     | `Record<string, string \| undefined>` | Environment variables (merged from system, org, source, and job-level `env`)              |
+| `ctx.secrets` | `StepSecretsTyped`                    | Async accessor for bound secrets (get, expose, has, getMeta, list, mountFile, exposeFile) |
 
 | Method                                       | Returns                   | Description                                                                                                                                                        |
 | -------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -898,25 +678,25 @@ The full secrets API — including `SecretFileOptions`, log masking, and the can
 
 ## Environment variable merge precedence
 
-When a job targets an environment, variables are merged in this order (last wins):
+When a job targets a context, variables are merged in this order (last wins):
 
 1. **Allowed system vars** -- `PATH`, `HOME`, etc. from the agent process
 2. **Sandbox defaults** -- `FORCE_COLOR=1`
 3. **KICI\_\* system vars** -- orchestrator-generated metadata
-4. **Org-level environment vars** -- from the dashboard, managed per-environment
+4. **Org-level context vars** -- from the dashboard, managed per-context
 5. **Source-level overrides** -- per-repository overrides (skips locked vars)
 6. **Job env** -- from the `env` property in the SDK
 7. **`setEnv()` calls** -- runtime modifications within steps
 
-> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/environments/#step-context) section above.
+> **Note:** Secrets are NOT part of the environment variable merge. They are delivered to the step context via IPC and accessed through `ctx.secrets`, not through `process.env`. See the [step context](https://docs.kici.dev/user/contexts/#step-context) section above.
 
 ## Protection rules
 
-Environments can have protection rules that gate job execution:
+Contexts can have protection rules that gate job execution:
 
 ### Branch restrictions
 
-Limit which branches can deploy to an environment:
+Limit which branches can deploy to a context:
 
 ```
 Allowed branches: main, release/*
@@ -973,7 +753,7 @@ See the [CI security architecture docs](https://docs.kici.dev/architecture/secur
 
 ### Security approval queue
 
-When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from environment-level approval queues.
+When a PR is held for security review (unknown contributor, workflow modification, or trust policy violation), it enters the security approval queue. This is separate from context-level approval queues.
 
 Held runs can be approved:
 
@@ -984,7 +764,7 @@ Security holds expire after a configurable timeout (default 1 hour).
 
 ### Concurrency limits
 
-Control how many jobs can run simultaneously in an environment:
+Control how many jobs can run simultaneously in a context:
 
 ```
 Concurrency limit: 1
@@ -996,18 +776,18 @@ Strategy: queue (or cancel-pending)
 
 ## Dashboard management
 
-### Creating environments
+### Creating contexts
 
-Navigate to **Settings > Environments** in the dashboard. Click **New environment** to choose the environment name and type (Fixed or Glob).
+Navigate to **Settings > Contexts** in the dashboard. Click **New context** to choose the context name and type (Fixed or Glob).
 
-- **Fixed** -- applies to jobs that declare exactly this environment name, like `staging` or `production`
-- **Glob** -- applies to any environment name a job declares that matches the pattern, e.g. `review/*` matches a job with `environment: 'review/PR-123'`
+- **Fixed** -- applies to jobs that declare exactly this context name, like `staging` or `production`
+- **Glob** -- applies to any context name a job declares that matches the pattern, e.g. `review/*` matches a job with `context: 'review/PR-123'`
 
-The environments list shows each environment's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
+The contexts list shows each context's type, whether test runs may use it (the `allowLocalExecution` flag -- see the [testing guide](https://docs.kici.dev/user/testing-guide/)), and whether it is enabled.
 
-### Environment detail page
+### Context detail page
 
-Each environment has four tabs:
+Each context has four tabs:
 
 1. **Variables** -- manage key-value pairs with lock toggles. Locked variables cannot be overridden by source-level overrides. Source overrides are managed in a sub-tab.
 
@@ -1015,26 +795,26 @@ Each environment has four tabs:
 
 3. **Protection** -- configure branch restrictions, required reviewers, wait timers, and concurrency limits with enable toggles for each section.
 
-4. **History** -- view filtered runs targeting this environment.
+4. **History** -- view filtered runs targeting this context.
 
-### Bound environments on runs
+### Bound contexts on runs
 
-A job's bound deployment environments are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-environment job the chips read left-to-right in merge order — later environments override earlier ones on key collisions. A `(dynamic)` chip marks an environment whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single environment shows one chip; a job that binds none shows no chip.
+A job's bound deployment contexts are shown as chips on the run detail page (in the job metadata panel) in the order the job declared them, and the distinct set across a run's jobs appears as compact chips on the run list. For a multi-context job the chips read left-to-right in merge order — later contexts override earlier ones on key collisions. A `(dynamic)` chip marks a context whose name is computed at runtime; it resolves to the real name once the run starts. A job that binds a single context shows one chip; a job that binds none shows no chip.
 
-If a multi-environment binding is gated out, the run's failure banner names which environment and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
+If a multi-context binding is gated out, the run's failure banner names which context and which rule rejected it (the same all-must-pass detail surfaced by `kici runs show <run-id>`).
 
 ### Secrets management
 
-Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to environments via bindings:
+Secrets are individual encrypted values organized by scope paths (e.g., `aws/prod`, `databases/postgres`). Scopes are bound to contexts via bindings:
 
-- **Scope-centric view** (Secrets page): tree view of scopes with per-scope environment binding checkboxes
-- **Environment-centric view** (inside environment detail): bound scopes, resolved secrets, add binding
+- **Scope-centric view** (Secrets page): tree view of scopes with per-scope context binding checkboxes
+- **Context-centric view** (inside context detail): bound scopes, resolved secrets, add binding
 
 When scope paths collide on the same key name, the longer (more specific) path wins.
 
 ## Type generation
 
-Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all environments) and `EnvironmentSecrets` (per-environment key unions):
+Running `kici types` generates two augmented interfaces: `KnownSecretKeys` (union of all secret keys across all contexts) and `ContextSecrets` (per-context key unions):
 
 ```typescript
 interface KnownSecretKeys {
@@ -1042,13 +822,233 @@ interface KnownSecretKeys {
   API_KEY: string;
 }
 
-interface EnvironmentSecrets {
+interface ContextSecrets {
   production: 'DB_PASSWORD' | 'API_KEY';
   staging: 'DB_PASSWORD';
 }
 ```
 
-`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `EnvironmentSecrets` maps each environment to its available secret key names as a string union. Dynamic environments fall back to the full `KnownSecretKeys` union.
+`KnownSecretKeys` narrows `ctx.secrets.get()` and `ctx.secrets.expose()` key parameters to valid key names. `ContextSecrets` maps each context to its available secret key names as a string union. Dynamic contexts fall back to the full `KnownSecretKeys` union.
+
+---
+
+## Dashboard
+
+Source: https://docs.kici.dev/user/dashboard/
+
+The KiCI dashboard is the browser interface for monitoring workflow runs, inspecting jobs and logs, and managing your organization. It signs in via OIDC and talks to KiCI over its API.
+
+This guide is split across the following pages:
+
+| Page                                                                                  | Covers                                                                  |
+| ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Getting started](https://docs.kici.dev/user/dashboard/getting-started/)                                     | Onboarding checklist and your organizations list                        |
+| [Navigation and layout](https://docs.kici.dev/user/dashboard/navigation/)                                    | Sidebar, mobile nav, theme, time display, shortcuts, error pages        |
+| [Runs and logs](https://docs.kici.dev/user/dashboard/runs/)                                                  | Run list, run detail, the log viewer                                    |
+| [Settings](https://docs.kici.dev/user/dashboard/settings/)                                                   | Members, roles, teams, keys, sources, billing, security, support access |
+| [Workflows, diagnostics, and orchestrators](https://docs.kici.dev/user/dashboard/workflows-and-diagnostics/) | Registered workflows, infra health, per-cluster views                   |
+| [Contexts, secrets, and approvals](https://docs.kici.dev/user/dashboard/contexts-and-secrets/)               | Contexts, secret scopes, approval queue                                 |
+| [Activity and DLQ](https://docs.kici.dev/user/dashboard/activity-and-dlq/)                                   | Forensic activity log and dead-letter queue                             |
+| [Account](https://docs.kici.dev/user/dashboard/account/)                                                     | Personal account settings                                               |
+
+---
+
+## Dynamic values
+
+Source: https://docs.kici.dev/user/dynamic-values/
+
+Dynamic values let you compute `context`, `env`, and `concurrencyGroup` at runtime based on the incoming event. Instead of hardcoding static strings, you pass a function that receives the normalized event envelope and returns the resolved value.
+
+```typescript
+job('deploy', {
+  runsOn: ['default'],
+  context: (event) => event.targetBranch,
+  env: (event) => ({ BRANCH: event.targetBranch }),
+  concurrencyGroup: (event) => `deploy-${event.targetBranch}`,
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+```typescript
+job('deploy', {
+  runsOn: 'default',
+  // One shape everywhere: branch on the normalized event type.
+  context: (event) => (event.type === 'pull_request' ? 'preview' : 'production'),
+  steps: [
+    /* ... */
+  ],
+});
+```
+
+## How it works
+
+When you define a dynamic value as a function, the compiler analyzes it at compile time to determine whether it is **pure** (can be evaluated without cloning the repo or running an init job).
+
+### Pure functions (inline evaluation)
+
+A pure function is one that:
+
+- Is synchronous (no `async`/`await`)
+- Only references its parameters and local variables
+- Does not import or require external modules
+- Does not access globals like `process`, `fetch`, `console`, `setTimeout`, etc.
+- Uses only safe built-in constructors: `String`, `Number`, `Boolean`, `Array`, `Object`, `JSON`, `Math`, `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
+- Does not use `this`, `new`, `class`, `throw`, `try`/`catch`, `delete`, `var`, `yield`, or mutation operators (`++`, `--`, `+=`, etc.)
+
+When the compiler detects a pure function, it serializes the function source directly into the lock file as an inline expression. At dispatch time, the orchestrator evaluates the expression in a sandboxed VM context (~0ms overhead) instead of dispatching an init job.
+
+**Examples of pure functions:**
+
+```typescript
+// Simple branch extraction
+context: (event) => event.targetBranch;
+
+// Object literal with string operations
+env: (event) => ({ BRANCH: event.targetBranch });
+
+// Concatenation with event data
+concurrencyGroup: (event) => `deploy-${event.targetBranch}`;
+
+// Using safe globals
+env: (event) => ({ UPPER: String(event.targetBranch).toUpperCase() });
+
+// Local variables are fine
+context: (event) => {
+  const parts = event.targetBranch.split('/');
+  return parts[parts.length - 1];
+};
+```
+
+### Impure functions (init-job evaluation)
+
+If the compiler determines a function is impure, it emits a warning during compilation and falls back to the two-phase init model. This means:
+
+1. The orchestrator dispatches a special `__init__` job to a builder agent
+2. The builder agent clones the repository and evaluates the function
+3. The resolved values are sent back to the orchestrator
+4. The orchestrator dispatches the real execution job with the resolved values
+
+This adds approximately 5-10 seconds of overhead for cloning and evaluation.
+
+**Examples of impure functions (will use init job):**
+
+```typescript
+// Async functions cannot be inlined
+context: async (event) => await lookupEnv(event.targetBranch);
+
+// External module references
+env: (event) => {
+  const config = require('./config');
+  return config.env;
+};
+
+// Process/global access
+context: (event) => process.env.DEFAULT_ENV || 'staging';
+
+// Dynamic imports
+env: async (event) => {
+  const m = await import('./config.js');
+  return m.default;
+};
+```
+
+## Performance comparison
+
+| Evaluation path                      | Overhead | When used                                                       |
+| ------------------------------------ | -------- | --------------------------------------------------------------- |
+| Static value (string/object literal) | ~0ms     | `context: 'staging'`                                            |
+| Inline expression (pure function)    | ~0ms     | `context: (event) => event.targetBranch`                        |
+| Init job (impure function)           | ~5-10s   | `context: async (event) => await lookupEnv(event.targetBranch)` |
+
+## Tips
+
+- **Write pure functions whenever possible** to avoid the init-job delay. Most context and env computations only need the event payload data.
+- **Check compiler warnings** -- the compiler tells you when a function is classified as impure and explains why.
+- **Runtime errors in inline expressions cause immediate job failure.** There is no fallback to the init-job path. If your pure function throws at runtime (e.g., accessing a property on `undefined`), the job fails immediately.
+- **The event parameter is the normalized event envelope** — the same shape rules receive as `ctx.event`: `{ type, action, targetBranch, sourceBranch, changedFiles, payload, … }` (see the [event payload reference](https://docs.kici.dev/user/sdk/event-payloads/) for the complete schema). Narrow on `event.type` (`'push'`, `'pull_request'`, `'tag'`, …) to branch per trigger kind. The raw provider webhook body is nested at `event.payload` (for GitHub pushes: `payload.ref`, `payload.after`, `payload.repository`, …).
+
+---
+
+## Environment variables
+
+Source: https://docs.kici.dev/user/env-vars/
+
+The KiCI CLI reads the following environment variables to customize its behavior. OAuth login (`kici login` without `--token`) defaults `KICI_PLATFORM_URL`, `KICI_OIDC_ISSUER`, and `KICI_OIDC_CLIENT_ID` to the hosted KiCI Platform, so `kici login` works with no configuration. Set them only to target another KiCI environment (e.g. a testing instance) or a custom OIDC provider.
+
+## Authentication
+
+| Variable              | Description                            | Default                                      |
+| --------------------- | -------------------------------------- | -------------------------------------------- |
+| `KICI_OIDC_ISSUER`    | OIDC issuer URL for authentication     | `https://auth.kici.dev/realms/kici-internal` |
+| `KICI_OIDC_CLIENT_ID` | OIDC client ID for the CLI application | `kici-cli`                                   |
+| `KICI_PLATFORM_URL`   | Platform API base URL                  | `https://api.kici.dev`                       |
+| `KICI_CONFIG_DIR`     | Override the KiCI config directory     | `~/.kici`                                    |
+
+## Browser behavior
+
+| Variable             | Description                                                                                                                                          | Default                                                |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `KICI_BROWSER_CMD`   | Custom browser command for OAuth login. Supports `{url}` placeholder. Set to `none` to suppress browser opening and print the URL to stdout instead. | Uses the system default browser via the `open` package |
+| `KICI_CALLBACK_PORT` | Fixed port for the OAuth PKCE callback server. Useful when firewall rules require a known port.                                                      | Random available port                                  |
+
+## Development
+
+| Variable     | Description                                                                                                                                                                | Default |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| `KICI_DEV`   | Enable development mode. When `true`, uses prerelease-compatible version ranges (`>=0.0.1-0`) for dev dependencies and skips npm version resolution.                       | unset   |
+| `KICI_DEBUG` | Enable debug logging. When `true`, prints verbose diagnostics (SDK alias resolution, step-level debug logs, stack traces on errors). Equivalent to the `--debug` CLI flag. | unset   |
+
+## Usage examples
+
+### CI/CD environment
+
+Authenticate with a pre-existing API key (no browser needed):
+
+```bash
+kici login --token <<< "$KICI_API_KEY"
+```
+
+### Targeting another environment or custom OIDC provider
+
+`kici login` targets the hosted KiCI Platform by default. To point the CLI at another KiCI environment (e.g. a testing instance) or a custom OIDC provider, override the defaults:
+
+```bash
+export KICI_OIDC_ISSUER=https://your-idp.example.com
+export KICI_OIDC_CLIENT_ID=your-client-id
+export KICI_PLATFORM_URL=https://your-platform.example.com
+kici login
+```
+
+### Headless SSH session
+
+The CLI auto-detects headless environments and uses the device flow. To force PKCE with URL output instead:
+
+```bash
+export KICI_BROWSER_CMD=none
+kici login
+```
+
+This prints the authorization URL to stdout as `KICI_AUTH_URL=<url>`. Open the URL in any browser to complete authentication.
+
+### Fixed callback port
+
+When behind a firewall or using port forwarding:
+
+```bash
+export KICI_CALLBACK_PORT=19876
+kici login
+```
+
+### Custom config location
+
+Store the KiCI config in a non-default location:
+
+```bash
+export KICI_CONFIG_DIR=/tmp/kici-test
+kici login
+```
 
 ---
 
@@ -1643,21 +1643,19 @@ guaranteed side-effect-free.
 
 ## Running in check mode
 
-`--check` and `--fail-on-drift` work on both local and remote runs:
+`--check` and `--fail-on-drift` control drift reporting on `kici run remote`:
 
 ```bash
 # Apply (default): converge the workflow.
-kici run local push
+kici run push --local
 kici run remote my-fixture
 
 # Check: report drift, change nothing. Always exits 0.
-kici run local push --check
 kici run remote my-fixture --check
 
-# Check + fail on drift: exit non-zero (2) locally, or fail the run remotely,
-# when any step reports drift. Use this as a CI gate ("fail the build if prod
-# has drifted").
-kici run local push --check --fail-on-drift
+# Check + fail on drift: fail the run when any step reports drift. Use this as a
+# CI gate ("fail the build if prod has drifted").
+kici run remote my-fixture --check --fail-on-drift
 ```
 
 `--fail-on-drift` only modifies check mode — passing it without `--check` is an
@@ -1696,7 +1694,7 @@ The two channels (Option A and Option C) compose. If you declare both, the agent
 
 ## Option A — `registries:` block
 
-Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<environment>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
+Declare the registry in your workflow file and point its `tokenSecret` at a scoped secret using the qualified `<context>:<secret-name>` syntax. The orchestrator resolves the token at dispatch time and the agent applies it for one `npm install` only.
 
 ```typescript
 import { workflow, job, step, push } from '@kici-dev/sdk';
@@ -1713,7 +1711,7 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('install-and-build', async (ctx) => {
           // .kici/package.json can now reference @my-org/* packages
@@ -1729,7 +1727,7 @@ Per-field rules:
 
 - **`url`** — Must be HTTPS. HTTP is permitted only for `localhost` / `127.0.0.0/8` / `::1` / `*.local` hosts, or when an operator has flipped the org-level `allow_http_npm_registries` toggle (see [`kici-admin org-settings allow-http-npm`](https://docs.kici.dev/operator/kici-admin-cli#allow-http-npm--permit-non-https-private-npm-registries)).
 - **`scope`** — Optional. When present, the registry serves only that scope (`@my-org`). When absent, this entry becomes the **default** registry — at most one entry may omit `scope`.
-- **`tokenSecret`** — Mandatory `<environment>:<secret-name>`. The orchestrator looks up the secret in the named environment via the per-environment secret resolver. The bare name **must not** contain a colon.
+- **`tokenSecret`** — Mandatory `<context>:<secret-name>`. The orchestrator looks up the secret in the named context via the per-context secret resolver. The bare name **must not** contain a colon.
 - **`alwaysAuth`** — Defaults to `true`. Forces npm to send the token on every request (even GETs), which is what most managed-registry providers require.
 
 ### How tokens reach `npm install`
@@ -1759,14 +1757,14 @@ export default workflow('build', {
   jobs: [
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
   ],
 });
 ```
 
-The orchestrator resolves `MY_NPM_TOKEN` from the `production` environment's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
+The orchestrator resolves `MY_NPM_TOKEN` from the `production` context's secret store and seeds it as `MY_NPM_TOKEN` (bare name) in the install subprocess. Your committed `.npmrc` reads it through `${MY_NPM_TOKEN}`.
 
 This path is the right answer when:
 
@@ -1788,7 +1786,7 @@ export default workflow('build', {
   jobs: [
     job('mint-codeartifact-token', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('mint', async (ctx) => {
           const awsKey = await ctx.secrets.get('AWS_ACCESS_KEY_ID');
@@ -1813,7 +1811,7 @@ export default workflow('build', {
     }),
     job('build', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       needs: ['mint-codeartifact-token'],
       steps: [step('build', async (ctx) => ctx.$`npm run build`)],
     }),
@@ -1837,7 +1835,7 @@ registries: [
 ],
 ```
 
-Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` environment.
+Mint the token from a fine-grained PAT with `read:packages` scope, store it as a scoped secret in the `production` context.
 
 ### GitLab Packages
 
@@ -1892,8 +1890,8 @@ registries: [
 
 ## Security model
 
-- **Per-environment scoping.** Every `tokenSecret` and `installEnv` entry is qualified with an environment name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named environment **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install environment **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
-- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured environment lacks an explicit `requiredTrustTier`.
+- **Per-context scoping.** Every `tokenSecret` and `installEnv` entry is qualified with a context name. The orchestrator runs the same protection-rule pipeline (branch / trust / concurrency / reviewer / wait-timer) against each named context **before** resolving any secret, so a workflow that wants a `production` token from a feature branch is rejected exactly like a job that tries to deploy to `production` from a feature branch. A reviewer-gated install context **pauses** the whole workflow dispatch as a workflow-scoped held run instead of resolving the token — see [Reviewer-gated installs](https://docs.kici.dev/user/private-registries/#reviewer-gated-installs) below.
+- **Untrusted contributors get no tokens.** When a fork PR is dispatched and the contributor-trust resolution returns anything other than `trusted`, the orchestrator strips both `npmRegistries` and `installEnvSecrets` out of the dispatch. The install runs without auth and fails naturally on the first private dep — fork PRs cannot ever observe a registry token, even if a misconfigured context lacks an explicit `requiredTrustTier`.
 - **Lifecycle scripts disabled.** Whenever a private registry is in scope, the agent runs the install with `--ignore-scripts` (npm or pnpm alike). A malicious `preinstall` / `postinstall` hook in committed `package.json` cannot read the synthesized token env vars, even though they exist in the install subprocess. For a pnpm workspace, the agent builds your in-repo dependency closure as a separate step **after** the install's auth is torn down, so build scripts never see the tokens either.
 - **Stderr is redacted.** If the install fails, the agent masks every token literal out of the surfaced stderr / stdout chunks before logging.
 - **Job-scoped env-var names.** The synthesized auth env var is `KICI_NPM_TOKEN_<jobIdShort>_<i>` where `jobIdShort` is the first 8 chars of the dispatched job id. The name is unguessable from outside the install subprocess and not reused across jobs.
@@ -1901,12 +1899,12 @@ registries: [
 
 ## Reviewer-gated installs
 
-When the named install environment carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
+When the named install context carries a protection rule that holds — a required reviewer (`hold`) or a wait timer (`wait`) — the install gate **pauses the whole workflow dispatch** instead of rejecting it. The run is created in the `held` state, no jobs are queued, and a workflow-scoped row appears on the held-runs page with a `Workflow` scope badge.
 
 - **Reviewer hold:** the run waits for an approver. On approval the dispatch resumes from the install gate, resolves the token, and dispatches its jobs as a normal run. On rejection the run transitions to `cancelled` — no jobs ever run.
 - **Wait timer:** the run waits out the timer and resumes automatically when it elapses.
 
-A `reject` protection outcome (for example a disabled environment or a branch the environment forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
+A `reject` protection outcome (for example a disabled context or a branch the context forbids) still fails the dispatch loudly with a clear reason, exactly as before — the orchestrator never dispatches a run with an unresolved install token.
 
 ## Limitations
 
@@ -1917,19 +1915,19 @@ A `reject` protection outcome (for example a disabled environment or a branch th
 
 The orchestrator exposes Prometheus counters and a histogram under the `kici_orch_install_secrets_*` prefix on its `/metrics` endpoint. They populate the **Install secrets resolution** Grafana dashboard and let operators graph install-secrets activity without digging through Loki.
 
-| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                       |
-| ------------------------------------------------------------- | --------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install environment. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
-| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                                |
-| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                            |
-| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                      |
+| Metric                                                        | Type      | Labels                         | What it tells you                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------- | --------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_install_secrets_decisions_total`                   | Counter   | `decision`, `reason`           | Pass / reject / hold volume. `decision=hold` (reason `held`) counts dispatches paused at a reviewer-gated install context. Reject reasons enumerate the failure mode: `malformed_ref`, `invalid_url_scheme`, `env_not_found`, `protection_rule_block`, `missing_token`, `missing_install_env`, etc. |
+| `kici_orch_install_secrets_npm_registry_used_total`           | Counter   | `channel`, `provider`, `scope` | Per-channel + per-scope usage. `channel=registries` is Option A, `channel=install_env` is Option C. `scope=default` marks a no-scope default registry; `scope=-` marks Option C entries.                                                                                                            |
+| `kici_orch_install_secrets_contributor_stripped_total`        | Counter   | `trust_tier`                   | Number of dispatches where registry tokens were stripped because the contributor tier wasn't `trusted` (fork PRs from unknown / known contributors). Expected to be 0 in single-tenant orgs.                                                                                                        |
+| `kici_orch_install_secrets_token_resolution_duration_seconds` | Histogram | `environment`                  | Latency of per-environment secret resolution. Pathological tails (>500ms) usually mean a Vault timeout or a slow Postgres replica.                                                                                                                                                                  |
 
 The dashboard JSON lives at `infra/terraform/modules/grafana/dashboards/install-secrets.json`; if you maintain your own monitoring stack, you can import it directly.
 
 ## See also
 
-- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<environment>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
-- [Environments](https://docs.kici.dev/user/environments/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
+- [Secrets](https://docs.kici.dev/user/secrets/) — how to seed the `<context>:<secret-name>` values referenced by `tokenSecret` / `installEnv`.
+- [Contexts](https://docs.kici.dev/user/contexts/) — protection rules (`branch_restrictions`, `requires_review`, `minimum_trust`) that the install gate inherits.
 - [Operator: `kici-admin org-settings`](https://docs.kici.dev/operator/kici-admin-cli#org-settings----org-level-security-policy) — the `allow_http_npm_registries` toggle and other org-scoped knobs.
 
 ---
@@ -2198,11 +2196,11 @@ KiCI provides an explicit secrets API that gives workflow steps controlled acces
 
 ## Overview
 
-Secrets are managed per-environment in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with an `environment` binding, the agent receives the secret keys available for that environment but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
+Secrets are managed per-context in the orchestrator (see [operator docs](https://docs.kici.dev/operator/orchestrator/configuration) for setup). When a job runs with a `context` binding, the agent receives the secret keys available for that context but does **not** inject their values into the step's process environment. Instead, steps access secrets through the `ctx.secrets` API.
 
 This design prevents accidental secret leakage through child processes, log output, or error messages. Only secrets you explicitly request are loaded into memory.
 
-A job can bind several environments with `environments: ['staging', 'my-testing']`; the secret keys from all bound environments are merged in array order, with a later environment's value winning on a key collision. See [Multiple environments per job](https://docs.kici.dev/user/environments/#multiple-environments-per-job).
+A job can bind several contexts with `contexts: ['staging', 'my-testing']`; the secret keys from all bound contexts are merged in array order, with a later context's value winning on a key collision. See [Multiple contexts per job](https://docs.kici.dev/user/contexts/#multiple-contexts-per-job).
 
 ## Where secret values come from
 
@@ -2270,7 +2268,7 @@ export default workflow('deploy', {
   jobs: [
     job('deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('deploy', async (ctx) => {
           const token = await ctx.secrets.get('DEPLOY_TOKEN');
@@ -2394,7 +2392,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt', async (ctx) => {
           const ageKeys = ctx.secrets.list().filter((k) => k.startsWith('AGE_KEY_'));
@@ -2426,7 +2424,7 @@ export default workflow('deploy', {
   jobs: [
     job('decrypt-and-deploy', {
       runsOn: 'default',
-      environment: 'production',
+      context: 'production',
       steps: [
         step('decrypt-to-env', async (ctx) => {
           await ctx.secrets.exposeFile('SOPS_AGE_KEY_FILE', {