@kici-dev/compiler 0.6.1 → 0.8.0

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

@@ -29,7 +29,7 @@ interface LocalConfig {
 
 ### SharedConfig
 
-Shared settings stored in the PostgreSQL `config_versions` table. Defined once, shared across all instances:
+Settings stored in the PostgreSQL `config_versions` table, written and read by the `/admin/config` routes and their `kici-admin config` commands:
 
 ```typescript
 interface SharedConfig {
@@ -73,11 +73,13 @@ interface AppConfig {
 
 ### How they merge
 
+`resolveFullConfig()` takes a `LocalConfig` and an optional `SharedConfig` and merges them:
+
 ```
 defaults (getDefaults())
     |
     v
-SharedConfig (from DB)        ──deepMerge──>  merged layer 1+2
+SharedConfig (argument)        ──deepMerge──>  merged layer 1+2
     |
     v
 LocalConfig (from YAML)       ──deepMerge──>  merged layer 1+2+3
@@ -94,29 +96,48 @@ appConfigSchema.safeParse()    ──validate──>   typed AppConfig
 
 The `deepMerge` function merges objects recursively, replaces arrays (does not merge item-by-item), and skips `undefined`/`null` source values (they do not override existing values).
 
+**The `SharedConfig` argument is `null` in the shipped wiring.** `ConfigReloader` is the only non-test caller of `resolveFullConfig()`, and it is constructed with `sharedStore: null`. So the DB layer is skipped and the effective chain is defaults → YAML → env. The `config_versions` table is read by the `/admin/config` write and inspection routes, by `kici-admin rotate-key`, and by the cluster join flow — never by a running orchestrator's own config.
+
 ## Resolution chain
 
-### Two-phase design
+### Startup
+
+`server.ts` and `standalone.ts` both call `loadConfig()`, which parses `KICI_*` environment variables against the flat schema in `config.ts`. No YAML file and no database row participates:
 
 ```
-Phase 1 (local-only):
-  YAML file + KICI_ env vars
-      |
-      v
-  resolveLocalConfig() -> { databaseUrl, instanceId, port, mode }
-      |
-      v
-  Connect to PostgreSQL
-      |
-      v
-Phase 2 (full merge):
-  defaults -> DB -> YAML -> env
-      |
-      v
-  resolveFullConfig() -> AppConfig
+Process start
+    |
+    v
+loadConfig() -> envDef.parse(process.env) -> AppConfig
+    |
+    v
+Connect to PostgreSQL, run migrations
+    |
+    v
+Start server (HTTP, WS, scaler, cluster)
 ```
 
-**Why two phases?** The database URL must come from local config (YAML or env var) because we need it to connect to PostgreSQL. But the shared config is stored in PostgreSQL. This circular dependency is broken by resolving local config first (Phase 1), connecting to the DB, then doing the full merge (Phase 2).
+The database URL therefore has to be an environment variable: the orchestrator needs it to reach PostgreSQL, and the shared config lives in PostgreSQL.
+
+### Reload
+
+`resolveLocalConfig()` and `resolveFullConfig()` run on the reload path, not at startup:
+
+```
+SIGHUP / POST /admin/config/reload / kici-admin config reload
+    |
+    v
+resolveLocalConfig()  -> YAML file + KICI_ env overlay
+    |
+    v
+resolveFullConfig(local, null)  -> defaults -> YAML -> env -> AppConfig
+    |
+    v
+Hold databaseUrl, port, instanceId and storage at their startup values
+    |
+    v
+Atomic swap into ConfigReloader.currentConfig
+```
 
 ### Env var processing
 
@@ -128,43 +149,6 @@ Environment variables are processed in two stages:
 
 Type coercion is applied based on known field types: numeric fields are parsed as numbers, boolean fields are compared against `"true"`, all others remain strings.
 
-## Two-phase bootstrap
-
-```
-┌─────────────────┐
-│  Process Start   │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Load YAML +    │  resolveLocalConfig()
-│  Env Overrides  │  -> databaseUrl, instanceId, port, mode
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Connect to     │  PostgreSQL
-│  Database       │  Run migrations
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Load Shared    │  SharedConfigStore.getLatest()
-│  Config from DB │  -> decrypt -> SharedConfig
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Full Merge     │  resolveFullConfig(local, db, env)
-│  + Validate     │  -> AppConfig
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  Start Server   │  HTTP, WS, scaler, cluster
-└─────────────────┘
-```
-
 ## DB schema
 
 ### config_versions table
@@ -264,7 +248,7 @@ flowchart TD
     trigger --> execute["executeReload()<br/>boolean mutex"]
 
     execute --> resolveLocal["resolveLocalConfig()"]
-    execute --> getLatest["getLatest (DB)"]
+    execute --> getLatest["getLatest (DB)<br/>skipped: sharedStore is null"]
     execute --> resolveFull["resolveFullConfig()<br/>(merge + validate)"]
 
     resolveLocal --> check["Check restart-required fields"]
@@ -283,26 +267,26 @@ flowchart TD
 - **Mutex:** Boolean flag prevents concurrent reloads. Second reload returns `{ success: false, errors: ["Reload already in progress"] }`.
 - **Debounce:** Rapid triggers (e.g., multiple SIGHUP signals) are collapsed into a single reload with a 500ms window.
 - **Validation before swap:** The new config must pass full schema validation. On failure, the old config is preserved and an error is logged.
-- **Restart-required detection:** Fields like `databaseUrl`, `port`, `instanceId` are compared. If changed, the old values are preserved in the applied config and a warning is logged.
+- **Restart-required detection:** `databaseUrl`, `port`, `instanceId` and `storage` are compared. If changed, the old values are preserved in the applied config and a warning is logged.
 - **No crash on failure:** The orchestrator always keeps running with the old config if anything goes wrong during reload.
 
 ### Subsystem callbacks
 
 The `ConfigReloader` uses a dependency injection pattern with callbacks for subsystem re-initialization:
 
-| Callback              | When Called                   | Purpose                                                                                      |
-| --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
-| `onProviderChange`    | Provider config changed       | Reserved callback (providers are now DB-managed via sources table; currently always a no-op) |
-| `onScalerReload`      | Always on successful reload   | Reload scaler YAML config                                                                    |
-| `onPlatformReconnect` | Platform URL or token changed | Reconnect WS to Platform relay                                                               |
-| `onConfigApplied`     | Always on successful reload   | Atomic config reference swap, increment local config version                                 |
+| Callback              | When Called                   | Purpose                                                                                                                        |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `onProviderChange`    | Provider config changed       | Reserved callback. Providers are DB-managed via the sources table, so the change detector always reports no change             |
+| `onScalerReload`      | Always on successful reload   | Reload scaler YAML config, from the path the process started with                                                              |
+| `onPlatformReconnect` | Platform URL or token changed | Logs that the Platform connection settings changed. The connection is not re-established; `standalone.ts` registers no handler |
+| `onConfigApplied`     | Always on successful reload   | Atomic config reference swap, increment local config version                                                                   |
 
 ### Prometheus metrics
 
-| Metric                          | Type    | Labels                                                                  | Description                           |
-| ------------------------------- | ------- | ----------------------------------------------------------------------- | ------------------------------------- |
-| `kici_orch_config_reload_total` | Counter | `result` (attempted/success/failed), `source` (sighup/http/cluster/cli) | Config reload attempts and outcomes   |
-| `kici_orch_config_version`      | Gauge   | --                                                                      | Current shared config version from DB |
+| Metric                          | Type    | Labels                                                                  | Description                                                                                                    |
+| ------------------------------- | ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `kici_orch_config_reload_total` | Counter | `result` (attempted/success/failed), `source` (sighup/http/cluster/cli) | Config reload attempts and outcomes                                                                            |
+| `kici_orch_config_version`      | Gauge   | --                                                                      | Shared config version from the DB. Set only when the reload path reads a version, so it carries no value today |
 
 ## Multi-Provider
 
@@ -334,40 +318,42 @@ Each source record contains its own `appId` and `privateKey` (stored as scoped s
 
 ### Heartbeat config version
 
-In clustered deployments, each orchestrator includes its current config version in Raft heartbeat metadata via the `configVersion` optional field on the `peerHeartbeatSchema`.
+In clustered deployments, each orchestrator includes its config version in Raft heartbeat metadata via the `configVersion` optional field on the `peerHeartbeatSchema`.
+
+**That number is a local reload counter, not a shared config version.** `onConfigApplied` increments it on every successful reload and publishes the new value to the peer registry. It counts how many times this instance has reloaded.
 
 When the `PeerRegistry` processes a heartbeat:
 
 1. Compare `localConfigVersion` with `peer.configVersion`
 2. If `peer.configVersion > localConfigVersion` AND both are > 0:
    - Invoke the `onConfigVersionBehind` callback
-   - This triggers a config reload from the database
+   - This triggers a config reload, which re-reads the environment and the local YAML file
 
 ### Auto-remediation flow
 
 ```
-Orchestrator A (version 5)          Orchestrator B (version 3)
+Orchestrator A (reloaded 5x)        Orchestrator B (reloaded 3x)
          │                                     │
          │──── heartbeat(configVersion=5) ────>│
          │                                     │
          │                           compare: 5 > 3
-         │                           trigger reload from DB
+         │                           trigger reload
          │                                     │
-         │                           resolveFullConfig()
-         │                           -> version 5
+         │                           resolveFullConfig(local, null)
+         │                           -> counter becomes 4
          │                                     │
-         │<── heartbeat(configVersion=5) ──────│
+         │<── heartbeat(configVersion=4) ──────│
          │                                     │
-         │   both at version 5 ✓               │
 ```
 
+B converges on A's count only after it has reloaded as many times as A has. Each instance reads its own environment and its own YAML file, so the two agree on content only when those inputs agree.
+
 ### Guard conditions
 
 - Version comparison only triggers when **both** local and peer versions are > 0
 - This prevents false triggers from:
-  - Legacy orchestrators that do not report `configVersion` (field is optional, defaults to 0)
-  - Newly started orchestrators before their first config load
-- The `localConfigVersion` is a monotonically incrementing local counter (incremented on each successful reload)
+  - Orchestrators that do not report `configVersion` (field is optional, defaults to 0)
+  - Newly started orchestrators before their first reload
 
 ## See also
 
@@ -398,7 +384,7 @@ GitHub  -->  Platform Relay  -->  Orchestrator  -->  Agent
 
 1. **Provider sends webhook** to the Platform relay endpoint.
 2. **Platform routes the webhook** to the right orchestrator over WebSocket and forwards the body bytes verbatim. Platform never sees customer HMAC secrets — signature verification happens entirely on the orchestrator after reassembly.
-3. **Orchestrator verifies signature** (HMAC-SHA256 against per-source webhook secret, with dual-secret rotation support).
+3. **Orchestrator admits the delivery**, then **verifies the signature** (HMAC-SHA256 against per-source webhook secret, with dual-secret rotation support). Admission runs first, on the routing key alone: when the ingest admission controller sheds, the orchestrator records an `event_log` breadcrumb with status `shed` and ACKs `shed_retry_later`, which the Platform answers as **429** with `Retry-After`. See [ingest admission shed](https://docs.kici.dev/architecture/webhooks/webhook-delivery/#ingest-admission-shed-step-3).
 4. **Orchestrator dedup check** against dual-layer `DedupCache` (in-memory set + `dedup_cache` DB table).
 5. **Orchestrator resolves provider** by looking up the provider bundle from the `ProviderRegistry` using `getByRoutingKey()` (exact match first, falls back to provider type prefix for backward compatibility). Skips processing if the provider is unknown.
 6. **Orchestrator normalizes** the webhook via the provider's `WebhookNormalizer` (extracts branch, event type, action, sender).
@@ -525,7 +511,7 @@ Build Job Dispatch --> Build Agent (kici:role:builder + matching kici:os:/kici:a
   |                      |-- npm ci in .kici/
   |                      |-- Pack .kici/ source (portable tar.gz, excludes node_modules)
   |                      |-- Pack .kici/node_modules (portable tar.gz)
-  |                      |-- Upload source tarball to cache (source/{contentHash}.tar.gz)
+  |                      |-- Upload source tarball to cache (source/v2/{orgId}/{sourceTarDigest}.tar.gz)
   |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{depsHash}.tar.gz)
   |                      |-- Upload deps companion .hash file
   |                      |-- Report success (cache.upload.complete × 2)
@@ -600,7 +586,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 39.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 41.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -639,7 +625,7 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
-- **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
+- **Source:** `source/v2/{orgId}/{sourceTarDigest}.tar.gz`, with a `source/v2/{orgId}/{contentHash}.hash` pointer — platform-agnostic, and scoped to the owning organization so two repositories with matching `.kici/` trees never share one object. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 7` and line endings are normalized to LF so the hash agrees across platforms).
 - **Deps:** `deps/{platform}-{arch}/{depsHash}.tar.gz`, with a
   `deps/{platform}-{arch}/{lockfileHash}.hash` pointer holding that hash — the
   tarball is addressed by its own content, so two builds sharing a lock file
@@ -1370,14 +1356,14 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
 - Host inventory (the canonical queryable host-roster schema shared by the orchestrator's roster store, the agent-facing inventory API, and the SDK's `ctx.kici.inventory`)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
-- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
+- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`; the orchestrator config rejects `kubernetes`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
 - Job resource vocabulary (the requests/limits shape the SDK accepts, the compiler validates and emits, the orchestrator uses for capacity math and kernel-side enforcement, and the dashboard displays)
 - Registration trigger type enum (registerable trigger discriminator)
 - Sandbox capability set (the Linux capability names a container sandbox may add or drop, shared by the SDK validator, the compiler, and the dispatch resolver)
 - Plan tier vocabulary (the hosted plan tiers and the purchasable subset, shared by the Platform and the browser dashboard)
 - Infrastructure alert vocabulary (the diagnostics alert types and severities the Platform mints and the dashboard and `kici` CLI render)
 - Metric catalog (the generated Prometheus metric inventory, its naming policy, and metric-kind compatibility checks)
-- Bundler config (shared bundler configuration consumed by `e2e/helpers/service-deploy.ts`; the agent runtime uses the `@kici-dev/core/ts-loader-hook` to transform TypeScript on import, with no runtime bundler step)
+- Bundler config (the shared workflow-bundle configuration factory on the barrel; the agent runtime uses the `@kici-dev/core/ts-loader-hook` to transform TypeScript on import, so no runtime path bundles a workflow)
 
 > Source: `packages/engine/src/`
 
@@ -1397,7 +1383,7 @@ It also runs the **local dev plane** -- an on-demand, fully local execution stac
 
 ### `@kici-dev/core`
 
-Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
+Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). One further subpath holds the `.kici/` source digest: the single content-hash definition the compiler writes into the lock file and the agent recomputes as its drift gate. Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
 
 > Source: `packages/core/src/`
 
@@ -1479,7 +1465,7 @@ KiCI uses three WebSocket layers for real-time communication.
 
 ### Platform ↔ Orchestrator
 
-The orchestrator connects outbound to the Platform WebSocket endpoint. After authentication (API key validated via SHA-256 hash lookup), the connection is used for webhook relay, execution telemetry (events, status, logs), source registration, and peer discovery. The Platform can also relay `job.reroute` messages between orchestrators that cannot reach each other directly.
+The orchestrator connects outbound to the Platform WebSocket endpoint. After authentication (API key validated via SHA-256 hash lookup), the connection is used for webhook relay, execution telemetry (events, status, logs), source registration, and peer discovery. Peer discovery is matchmaking only: the Platform pushes a `peer.update` membership list to every orchestrator sharing a routing key, and the orchestrators then connect to each other directly. Inter-orchestrator traffic such as `job.reroute` never transits the Platform.
 
 ### Orchestrator ↔ Orchestrator (P2P)
 

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

@@ -126,6 +126,12 @@ If you belong to a single organization, the org is resolved automatically. If
 you belong to several, pass an `orgId` argument to any tool (use `list_orgs` to
 find it).
 
+Only an **active** membership counts: an organization you have been suspended
+in, one that has been disabled, and one that has been deleted are all skipped.
+So a single active membership alongside a disabled one still resolves
+automatically, and a tool call against an organization you are suspended in is
+refused with the same message the dashboard gives.
+
 ### Limits and pagination
 
 The MCP server applies a few bounds so an agent loop can't overwhelm the shared
@@ -215,7 +221,7 @@ you hold, so an agent cannot escalate beyond its creator.
 
 **Repository scope comes along too.** If your role is restricted to a set of
 repositories, an agent token you mint is restricted to the same set. Runs
-outside it are simply not there: they are filtered out of `list_runs`,
+outside it are not there: they are filtered out of `list_runs`,
 `cancel_runs_by_branch` skips them, and naming one directly answers "not found"
 — the same answer a run id that does not exist gets, so an agent cannot use the
 tools to discover which repositories it is missing. Your organization's audit
@@ -458,14 +464,18 @@ Tokens authenticate; RBAC authorizes. Every org-scoped route runs `orgContextMid
 
 ### Configurable surfaces
 
-The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so anything you can configure in the dashboard you can configure over HTTP. The mounted route groups include:
+The dashboard is a browser SPA on top of the same `/api/v1/*` surface, so nearly everything you can configure in the dashboard you can configure over HTTP. The exception is a short list of routes that only a **browser session** may call, marked † below. The mounted route groups include:
 
-- **Auth & identity:** `/cli/exchange-token`, `/pats`, `/user`, `/identity-links`, `/github-oauth`, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`
-- **Org & membership:** `/orgs`, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
+- **Auth & identity:** `/cli/exchange-token`†, `/pats`, `/user`, `/identity-links`, `/identity-links/:id` (DELETE)†, `/github-oauth`, `/auth/github/link`†, `/invites`, `/invites/pending`, `/invites/:inviteId/{accept,decline}`†
+- **Org & membership:** `/orgs` (POST)†, `/orgs/:customerId`, `/orgs/:customerId/{members,roles,api-keys,orchestrator-keys,service-accounts,billing,trust-policies}`
 - **Workflows & runs:** `/orgs/:customerId/{runs,registrations,workflows,held-runs,contexts,secrets,global-workflows}`
 - **Webhooks & event log:** `/orgs/:customerId/{sources,webhook-endpoints,event-log}`
 - **Diagnostics & activity:** `/orgs/:customerId/{diagnostics,activity,access-log}`
 
+**† Browser session only.** These routes answer **403** with `This endpoint requires an interactive login` to a `kici_pat_`, `kici_sk_` or `kici_sa_` token. They are the routes that create an organization, join or decline one, unlink a provider identity, start a GitHub account link, and exchange your session for a personal access token. Each mints a credential wider than the credential presenting it, or changes which organizations and provider identities your account reaches. A `kici_sk_` or `kici_sa_` token is bound to one organization and one permission set, so letting it take those actions would hand it access it was never granted. Do them in the dashboard, or with `kici login`, which runs the browser flow for you.
+
+`POST /pats` is the one route in between: it accepts a browser session **or** an existing `kici_pat_` (so `kici pat create` keeps working), and refuses `kici_sk_` and `kici_sa_`. A token minted from another token can never be wider than that token. The new token is capped by your own permissions **and** by the scopes of the token you called with, whether or not you pass `permissions` explicitly. Mint from an unscoped session when you need a broader token.
+
 The full route tree is the source of truth — every method, request schema, and response schema is enumerated server-side. There is currently no auto-generated OpenAPI spec; the typed `DashboardApiType` export is the canonical contract for TypeScript clients.
 
 ### Calling the API
@@ -484,11 +494,16 @@ curl -sS \
 
 **Browser console (after dashboard login):**
 
+Mint a personal access token and pass it explicitly. Do not script against the
+dashboard's own session token. That token is short-lived and tied to your
+identity-provider session, so anything built on it stops working at the next
+renewal or sign-out.
+
 ```js
-const ns = Object.keys(localStorage).find((k) => k.startsWith('oidc.user:'));
-const { access_token } = JSON.parse(localStorage.getItem(ns));
+// kici pat create --name console --expires-in-days 1   → prints the token
+const token = 'kici_pat_...';
 const res = await fetch('/<deployment-slug>/api/v1/orgs/<your-org-id>/runs?limit=5', {
-  headers: { Authorization: `Bearer ${access_token}` },
+  headers: { Authorization: `Bearer ${token}` },
 });
 console.log(await res.json());
 ```
@@ -513,6 +528,12 @@ The CLI stores authentication data in `~/.kici/config` with `0600` permissions (
 - Routing key for webhook source identification
 - API key, when you logged in with `--token`
 
+The web dashboard holds none of these. It keeps only the tokens of your current
+sign-in, in browser storage for the tab's origin. It does not request offline
+access, so those tokens die with your identity-provider session instead of
+staying valid for weeks. Its origin also serves a Content-Security-Policy that
+restricts which scripts run and which hosts the page may contact.
+
 ## Troubleshooting
 
 ### Browser doesn't open
@@ -717,10 +738,14 @@ kici init --private-registry https://npm.pkg.github.com/ \
   types/              # Directory for generated type declarations (kici types)
   package.json        # Dependencies (@kici-dev/sdk)
   tsconfig.json       # TypeScript configuration (includes types/**/*.d.ts)
+  .gitignore          # Keeps the generated types/ declarations untracked
+  .kiciignore         # Paths the workflow content hash does not cover
   AGENTS.md           # LLM authoring context (skip with --no-agents-md)
 .kiciignore           # Default exclusion patterns for test uploads
 ```
 
+The two `.kiciignore` files are unrelated. The one inside `.kici/` declares which paths the per-workflow content hash skips — see [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/#files-the-content-hash-skips-kicikiciignore). The one at the repo root selects which working-tree files a remote run uploads. Neither is overwritten when it already exists.
+
 `AGENTS.md` is written by default (the interactive prompt defaults to yes, and CI / non-interactive runs write it). An existing `.kici/AGENTS.md` is never overwritten, so hand edits survive a re-run.
 
 In interactive mode (TTY), `kici init` prompts you to:
@@ -736,7 +761,7 @@ In interactive mode (TTY), `kici init` prompts you to:
 
 **Standalone vs workspace integration:** by default `kici init` scaffolds a self-contained `.kici/` with its own `package.json`. When run inside a pnpm, npm, or yarn workspace, it offers an **integrate** option (or pass `--workspace`): `.kici/` joins the workspace, `@kici-dev/sdk` is added to your workspace-root `package.json`, and your workflows can `import` your other workspace packages (e.g. shared build or deploy utilities). In this mode there is no `.kici/package.json` — the workspace root manages dependencies, and the root install resolves the SDK. Your workflows resolve sibling packages through the workspace-root `node_modules`: under npm and yarn every workspace member is hoisted there automatically, while pnpm links only your root's declared dependencies, so under pnpm add the package you want to import to your workspace-root `dependencies` (this is how KiCI's own repository imports its packages from workflows). Pass `--standalone` to force the self-contained layout even inside a workspace. In CI / non-interactive runs the default is standalone; use `--workspace` to opt in explicitly. `--workspace` and `--standalone` are mutually exclusive, and `--workspace` errors if no workspace is found at or above the current directory.
 
-**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` uses prerelease-compatible version ranges (`>=0.0.1-0`) so npm resolves Verdaccio's prerelease builds.
+**Development mode:** When `KICI_DEV=true` or `package.json` has `"kici": { "development": true }`, the generated `package.json` pins `@kici-dev/sdk` to the `latest` dist-tag so npm resolves Verdaccio's newest prerelease build.
 
 ### kici org
 
@@ -1261,6 +1286,14 @@ to see it. The bundle holds your CLI, Node and orchestrator versions, your
 redacted configuration, and your project's workflow and lock-file state. With
 `--run` it also holds the failing run's detail and logs.
 
+For every orchestrator the probe returned the bundle also records where that
+orchestrator's own config files live — the paths only, never the contents. An
+orchestrator that is offline is still listed, with no paths: the CLI reads them
+from the live connection, so a disconnected one has none to report.
+Each path is a host path as that orchestrator sees it. A container deployment
+names a file on the container host, which is not a file you can open from the
+machine that read the bundle.
+
 ```bash
 kici report [options]
 ```
@@ -1674,6 +1707,18 @@ Secrets are always sourced from your real `.kici/` directory, not from the isola
 
 Pass `--in-place` to run against the real working directory instead — useful when you explicitly want in-tree execution. `--in-place` requires no git repository; the default isolated mode does, and fails with an actionable error pointing at `--in-place` when the directory is not a git repository.
 
+**If the trigger times out:**
+
+The command waits up to 60 seconds for the local dev plane to create the run. If nothing appears in that window it stops and names the cause it read back from the plane:
+
+| Message                                                                   | What it means                                                                                                                                                     |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plane is not leader yet (election grace period)`                         | The plane had not finished electing itself. A single-machine plane elects within seconds; if it does not, read the plane log (`kici local logs`).                 |
+| `no kici.lock.json at <commit> in <path>`                                 | The plane resolved no lock file for the commit the run packed, so nothing matched. Commit `.kici/kici.lock.json`, or make sure it is present in the working tree. |
+| `the plane recorded delivery <id> as "<status>"`                          | The plane processed the trigger and wrote down a terminal status for it without creating a run. The status names the stage that stopped.                          |
+| `no run appeared for delivery <id> — see <log>`                           | Neither the plane's cluster state nor its delivery record explained the timeout. The named log is the next place to look.                                         |
+| `no run appeared for this trigger — the plane never accepted the webhook` | Every webhook POST came back without a delivery id, so the plane never queued the trigger. Check the plane is up (`kici local status`), then read the named log.  |
+
 **Examples:**
 
 ```bash