@event4u/agent-config 2.26.0 → 3.1.0

package/docs/decisions/ADR-019-router-json-dist-location.md

@@ -0,0 +1,124 @@
+---
+adr: 019
+status: accepted
+date: 2026-05-23
+decision: router-json-dist-location
+supersedes: —
+superseded_by: —
+phase: v2.x · post-monorepo cleanup
+type: retrospective
+---
+
+# ADR-019 — `router.json` relocated to `dist/router.json`
+
+## Status
+
+**Accepted** · 2026-05-23. Moves the compiled router-kernel artefact
+from the repo root to `dist/router.json`, aligning it with the
+existing `dist/discovery/` build-artefact slot established by
+ADR-015.
+
+Companion artefacts:
+- Contract: [`docs/contracts/rule-router.md`](../contracts/rule-router.md)
+- Compiler: [`scripts/compile_router.py`](../../scripts/compile_router.py)
+- ADR-rule-kernel-and-router: [`ADR-rule-kernel-and-router.md`](ADR-rule-kernel-and-router.md)
+- Tier ADR: [`docs/adrs/router/0001-three-tier-routing.md`](../adrs/router/0001-three-tier-routing.md)
+
+## Context
+
+`router.json` was emitted at the repo root by the original
+kernel-and-router shipping (ADR-rule-kernel-and-router, P3.2). The
+root location pre-dated the `dist/` convention; once
+ADR-015 codified `dist/discovery/` as the build-artefact slot and
+ADR-012 introduced `dist/cli/` for the TS shell, the router
+artefact's root location became the outlier — visually equivalent
+to hand-edited project files like `AGENTS.md` or
+`.agent-settings.yml`, even though it is regenerated from rule
+frontmatter on every `task compile-router` / `task sync` run.
+
+The artefact is still a **public contract**: external host agents
+(Claude.ai bundle, Skills API per
+[`package-self-orientation`](../contracts/package-self-orientation.md))
+read it once per session to resolve the always-loaded kernel and the
+tier-1/2 routing tables. Moving it is therefore a one-time breaking
+change for consumers — they update the read path or fail to resolve
+rules at session start.
+
+## Decision
+
+**Compile to `dist/router.json` and ship the file tracked in git
+under a `!/dist/router.json` allowlist exception.** `dist/` remains
+gitignored; only the router artefact is committed.
+
+Rationale:
+
+1. **Slot consistency.** Build outputs live under `dist/`. Two
+   pre-existing slots (`dist/discovery/`, `dist/cli/`) already
+   commit selected artefacts via `.gitignore` allowlists. The
+   router follows the same pattern.
+2. **Thin-Root contract.** `AGENTS.md` and the repo root are
+   pointer-heavy and human-curated; generated artefacts at the root
+   create review noise on every regen.
+3. **Single read path.** Host agents already read
+   `dist/discovery/discovery-manifest.json`; adding the router to
+   the same parent dir collapses the "where does the package emit
+   its public contracts" answer to a single directory.
+
+## Trade-offs accepted
+
+- **Breaking change for consumers.** Pinned external readers (the
+  Claude.ai bundle, any Skills API caller, third-party tooling
+  reading the kernel) must update their read path from
+  `<root>/router.json` to `<root>/dist/router.json`. No deprecation
+  shim — the path is in the artefact body for one
+  release window, surfaced via the changelog, and that is the
+  contract update.
+- **Allowlist drift risk.** A future `dist/` purge that forgets the
+  `!/dist/router.json` line will silently regress the public
+  contract. The `task release-prepare` and `task ci` runs both call
+  `compile_router.py`, which re-creates the file before any
+  packaging step that would notice its absence.
+
+## Implementation footprint
+
+- **Compiler / CLI.** `scripts/compile_router.py`,
+  `scripts/lint_trust_coherence.py`, `scripts/_cli/cmd_explain.py`,
+  `scripts/_cli/explain_last/route.py` — output path constants
+  point at `dist/router.json`.
+- **Smoke.** `scripts/smoke/kernel.sh`, `scripts/smoke/router.sh`
+  read from the new path; `.github/workflows/smoke.yml` path-trigger
+  globs updated via `docs/contracts/smoke-contracts.md`.
+- **Tests.** `tests/test_lint_trust_coherence.py`,
+  `tests/test_cmd_explain.py`, `tests/cli/explain_last/conftest.py`
+  patch the new constants; `tests/test_one_liner_entrypoints.sh`
+  stages `dist/router.json` (not the whole `dist/`, to avoid pulling
+  in the TS-compiled CLI which needs `node_modules`).
+- **`.gitignore`.** `/dist/` stays ignored; `!/dist/router.json`
+  allowlist exception added.
+- **Docs.** `AGENTS.md`, `docs/architecture.md`,
+  `docs/customization.md`, `docs/contracts/{rule-router,
+  namespace, trust-and-safety, smoke-contracts, kernel-membership}.md`,
+  `docs/contracts/explain-trace.schema.json`,
+  `docs/adrs/router/0001-three-tier-routing.md`,
+  `docs/adrs/smoke/0001-per-tier-smoke-scripts.md`.
+- **Source rules.** Uncompressed rule sources referencing the path
+  (`caveman-speak.md`, `git-history-discipline.md`) updated and
+  re-projected.
+
+## Reversal cost
+
+Two-edit revert: move the file back, flip the constants, drop the
+allowlist line. `git mv` history is preserved through the rename,
+so a `git revert` of the commit suffices. The contract update would
+be a second breaking change for any consumer that adopted the new
+path — so reversal is **possible but expensive after first
+external uptake**.
+
+## References
+
+- [`docs/contracts/rule-router.md`](../contracts/rule-router.md) — frontmatter + read-path contract.
+- [`docs/contracts/kernel-membership.md`](../contracts/kernel-membership.md) — kernel cap.
+- [`dist/router.json`](../../dist/router.json) — compiled output.
+- [`scripts/compile_router.py`](../../scripts/compile_router.py) — compiler.
+- [`ADR-015-discovery-manifest-contract.md`](ADR-015-discovery-manifest-contract.md) — precedent for `dist/` allowlist.
+- [`ADR-rule-kernel-and-router.md`](ADR-rule-kernel-and-router.md) — original kernel-and-router decision.

package/docs/decisions/ADR-020-global-only-consumer-scope.md

@@ -0,0 +1,123 @@
+---
+adr: 020
+status: accepted
+date: 2026-05-23
+decision: global-only-consumer-scope
+supersedes: —
+superseded_by: —
+phase: v3.x · global-only install rollout
+type: forward-looking
+---
+
+# ADR-020 — Global-only consumer scope
+
+## Status
+
+**Accepted** · 2026-05-23. Phases 1-5 of
+`road-to-global-only-install` shipped (Setup-Wizard, consumer scope
+gate, surface + bridge, migration tooling). Phase 6 (docs sweep)
+in progress. The ADR locks the decision; the roadmap locks the
+mechanics.
+
+Companion artefacts:
+- Roadmap: [`agents/roadmaps/road-to-global-only-install.md`](../../agents/roadmaps/road-to-global-only-install.md)
+- Bridge contract: [`docs/contracts/consumer-bridge.md`](../contracts/consumer-bridge.md)
+- Wizard contract: [`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md)
+- Predecessor ADR: [`ADR-007`](ADR-007-agent-discovery-scopes.md) — scope precedence, global-default amendment
+- Perms entry-gate: [`scripts/lint_global_paths.py`](../../scripts/lint_global_paths.py)
+- Payload schema: [`schemas/wizard-apply-payload.schema.json`](../../schemas/wizard-apply-payload.schema.json)
+
+## Context
+
+ADR-007 (2025-Q4) established that the agent-config consumer can run
+in two scopes — **project** (`<repo>/.augment/`, `<repo>/.claude/`, …)
+or **global** (`~/.claude/`, `~/.cursor/`, `~/.augment/`, …) — and
+that newly-onboarded consumers default to **global**. Six months of
+field use surfaced three structural problems:
+
+1. **Settings drift.** Per-project `.agent-settings.yml` files
+   accumulate stale `personal.*` keys that disagree with the user's
+   real preferences. Multi-repo developers ship the wrong
+   `personal.autonomy` into PRs.
+2. **Onboarding fragmentation.** New users land in `wizard.md` from
+   one tool, `getting-started-by-role.md` from another, and a
+   project-local `.agent-user.md` from a third. Three near-identical
+   surfaces, each subtly inconsistent.
+3. **Update lag.** Consumer projects pin an installer version in
+   `package.json`. Skill / rule / command edits ship to the package
+   but never reach the consumer until someone manually bumps.
+
+The amendment in ADR-007 (2026-05-13) flipped the **default** to
+global for Augment. This ADR finishes the job: the consumer surface
+becomes **global-only** end-to-end. The project tree retains exactly
+one piece of agent state — `agents/overrides/` plus the bridge marker
+documented in [`consumer-bridge`](../contracts/consumer-bridge.md).
+
+## Decision
+
+Consumer installations of `@event4u/agent-config` write **only** to
+`~/.event4u/agent-config/` (global root) and `agents/.event4u-bridge.yml`
+(in-repo marker). The Setup-Wizard and the legacy Installer-GUI
+converge on a single `/api/apply` endpoint behind a `schema_version`
+discriminator. Per-tool adapters resolve their rules / skills /
+commands by reading the bridge marker, expanding `global_root`, and
+fanning out from there.
+
+The single project-local exception is `agents/overrides/`, which
+remains the canonical place to override or extend a shared skill /
+rule / command per [override-management](../../.agent-src.uncompressed/skills/override-management/SKILL.md).
+
+The maintainer-side dev experience is preserved by the
+`AGENT_CONFIG_DEV_MODE=1` environment gate documented in
+[`docs/maintainers/dev-mode.md`](../maintainers/dev-mode.md). With the
+flag set, `scripts/install.py` treats the package repo as both source
+and project surface (Phase 3 contract).
+
+## Alternatives considered
+
+- **Status quo (project default + global opt-in).** Keeps the drift
+  problem; multi-repo developers continue to ship stale
+  `personal.*` keys. Rejected.
+- **Dual-endpoint `/api/apply` (one per payload shape).** Doubles
+  the CSRF + idle-timer surface with no observability gain. Rejected;
+  see `gui-wizard § D12`.
+- **Per-project bridge YAML pointing to multiple global roots.**
+  Enables team-shared globals via NFS but introduces a tenancy model
+  the rest of the system is not designed for. Deferred to a future
+  ADR; v1 of the bridge marker is single-root.
+
+## Consequences
+
+**Positive.**
+- One source of truth for `personal.*`, `agent_council.*`, and `personas:`.
+- New skills / rules / commands reach every consumer the moment they
+  install or run `task dev:install-global` — no per-repo bump.
+- The onboarding wizard becomes the only authoring surface for
+  `.agent-user.md`. Three duplicate flows collapse into one.
+
+**Negative.**
+- Phase 3 SCOPE_SUPPORT flip is breaking for any tool that still
+  hard-codes a project-local lookup. Migration order is locked in
+  the roadmap (Phase 5) — `agent-config migrate-to-global` runs the
+  perms entry-gate, copies, verifies, then deletes the project
+  shadow.
+- The bridge marker is a new failure mode: a stale `global_root` on
+  disk yields a fail-closed error instead of a silent project-local
+  fallback. The trade-off is intentional; silent fallback is what
+  produced the drift in the first place.
+
+**Operational.**
+- `scripts/lint_global_paths.py` becomes a required precondition for
+  `migrate-to-global`. Wrong perms (e.g. `0755` on the global root
+  when `0700` is expected) abort the migration before any write.
+- The Augment, Claude, and Cursor adapters get free-form-tested by
+  the maintainer dev install every CI run, so a regression in the
+  bridge-resolver surfaces immediately instead of at consumer time.
+
+## References
+
+- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — discovery scope precedence and the 2026-05-13 global-default amendment.
+- [`ADR-018`](ADR-018-trust-and-safety-layer.md) — trust levels and HRR banner; unchanged by this decision.
+- [`road-to-global-only-install`](../../agents/roadmaps/road-to-global-only-install.md) — phased rollout, cross-phase gates A1-A7.
+- [`consumer-bridge`](../contracts/consumer-bridge.md) — bridge marker schema and reader contract.
+- [`gui-wizard § Apply payload`](../contracts/gui-wizard.md#apply-payload--versioning-handshake-road-to-global-only-install-phase-04--d12) — payload discriminator.

package/docs/decisions/ADR-021-deployment-shape.md

@@ -0,0 +1,153 @@
+---
+adr: 021
+status: accepted
+date: 2026-05-24
+decision: deployment-shape
+supersedes: —
+superseded_by: —
+phase: v3.x · internal-AI-OS deployment Phase 1
+type: forward-looking
+---
+
+# ADR-021 — Deployment shape (internal AI OS, Phase 1)
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 1 of
+[`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+ships the container image + Compose topology + host binding +
+healthcheck. Phases 2–5 (identity, central policy, team context,
+connectors) are tracked but **not yet implemented**; their ADRs
+(022–025) are reserved but unwritten.
+
+Companion artefacts:
+
+- Roadmap: [`agents/roadmaps/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+- Artefacts: [`packages/core/deploy/`](../../packages/core/deploy/)
+- Env contract: [`docs/deploy/env-vars.md`](../deploy/env-vars.md)
+- Council question (drafted, not invoked — no keys): [`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/council-question-deployment-shape.md)
+- Predecessor ADR: [`ADR-016`](ADR-016-installer-architecture.md) — installer architecture (agent-mode protocol the GUI server wraps).
+
+## Context
+
+For the first two years `@event4u/agent-config` shipped as a
+developer-local tool: `npx @event4u/agent-config init` writes files
+into the consumer repo, the wizard runs on `127.0.0.1`, no state
+persists beyond the lockfile. Field signal (multiple companies asking
+"can we host this for the team?") motivates a second shape: a
+**single deployed instance per organization**, hosting wizard +
+Council + memory for 5–50 engineers behind their SSO.
+
+Three structural questions had to settle before code:
+
+1. **Topology** — bare Compose vs Helm vs both.
+2. **Process shape** — single Node container vs Node + Python sidecar.
+3. **Boot-time safety** — what happens when the operator inevitably
+   flips `127.0.0.1:8787` to `0.0.0.0:8787` before authentication
+   lands in Phase 2.
+
+## Decision
+
+### 1. Topology — Compose-first, Helm deferred
+
+A single `docker-compose.yml` under `packages/core/deploy/` is the
+shipped artefact. Three services: `agent-config` (the Node image),
+`redis`, `postgres`. Three named volumes for runtime state, Postgres
+data, and the per-user `~/.event4u/agent-config/` mount.
+
+Helm / k8s manifests are **deferred** to a future v2 deployment
+roadmap. Compose covers the 5–50-person band; larger teams author
+their own chart using this Compose as the reference until v2 ships.
+
+### 2. Process shape — single-process Node
+
+The GUI server (`packages/core/installer/src/gui/server.ts`) is the
+only long-running process. The Python install supervisor is spawned
+per-install, not a sidecar. The Compose image stays Node-only to keep
+the budget under 600 MB compressed and the surface area minimal.
+
+If Phase 2+ needs a separate identity-broker process, it lands in a
+separate service in the same Compose; the agent-config container stays
+single-process.
+
+### 3. Host binding — `127.0.0.1` default, `0.0.0.0` opt-in with safety gate
+
+`startGuiServer` accepts `host` + `allowedHosts` options. CLI
+exposes `--host` and `--allowed-hosts`; container defaults
+`BIND_HOST=0.0.0.0` + `ALLOWED_HOSTS=localhost:8787,127.0.0.1:8787`.
+
+**Hard rule**: non-loopback bind without `allowedHosts` refuses to
+boot. Enforced at the CLI surface (`commands/gui.ts`) and at the
+server entry (`gui/server.ts`). This is the structural mitigation
+against operators flipping the host port mapping before Phase 2 SSO
+ships.
+
+### 4. Health endpoint — `/api/v1/health`, read-only, rate-limited
+
+CSRF-exempt, GET-only. Returns `status`, `version`, `pack_version`,
+`uptime_seconds`, `storage_mode`, `session_backend`, and
+`manifest_sha256`. No secrets, no auth state, no PII.
+
+Rate-limited to 1 request per second per remote IP via an in-memory
+token bucket. Wide margin over the docker-default 10 s healthcheck
+cadence; resilient to spoofed probes (the bucket map is bounded at
+1024 entries and self-prunes).
+
+### 5. Redis + Postgres in compose but unwired in Phase 1
+
+Both services ship in the Compose topology with healthchecks and named
+volumes, but the agent-config code does **not** read them in Phase 1:
+
+- `STORAGE_MODE=postgres` is documented but the implementation still
+  uses filesystem.
+- `SESSION_BACKEND=redis` is documented but the implementation still
+  uses in-memory state.
+
+Surfacing both connection strings in `/api/v1/health` lets operators
+verify connectivity *before* Phase 2 wires Postgres and Phase 3 wires
+Redis.
+
+### 6. No TLS in the container
+
+The reverse-proxy (nginx / Caddy / Traefik / ALB) owns TLS
+termination. The container speaks plain HTTP on the bound interface.
+Out-of-scope for this ADR; documented in `packages/core/deploy/README.md`.
+
+## Consequences
+
+**Positive**
+
+- Operators can `docker compose up` and reach a working wizard
+  without writing infrastructure.
+- The shape locks before Phases 2–5 add auth / policy / connectors —
+  those phases extend the topology without rewriting it.
+- `ALLOWED_HOSTS` gate eliminates the DNS-rebinding class of
+  vulnerability at the boot layer.
+
+**Negative**
+
+- Teams already on k8s need to translate Compose to their own
+  charts. Mitigated by the README pointing at the Compose as the
+  reference.
+- Postgres + Redis run unused in Phase 1, adding 60–80 MB RAM idle
+  to the deployment footprint. Mitigated by being able to remove
+  both services from the Compose if Phase 1 is the only phase the
+  operator wants.
+
+**Reversal cost** — low. Compose → Helm migration is mechanical once
+the v2 deployment roadmap kicks off; the agent-config image itself is
+orchestrator-agnostic.
+
+## Open questions (council-deferred)
+
+The accompanying council question file
+[`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/council-question-deployment-shape.md)
+has not yet been run (no provider keys configured). A maintainer with
+keys should run it and either ratify or supersede this ADR.
+
+## Cross-references
+
+- Phase 1 artefacts: [`packages/core/deploy/`](../../packages/core/deploy/)
+- Env contract: [`docs/deploy/env-vars.md`](../deploy/env-vars.md)
+- Installer architecture: [`ADR-016`](ADR-016-installer-architecture.md)
+- Global-only consumer scope: [`ADR-020`](ADR-020-global-only-consumer-scope.md) (orthogonal — local install model)

package/docs/decisions/ADR-rule-kernel-and-router.md

@@ -39,7 +39,7 @@ size budgets.
   tier-1 (default) · `full` = kernel + tier-1 + tier-2.
 - **Budget gates:** `task lint-rule-budget` enforces kernel ≤ 26k chars
   and per-rule ≤ 2.5k (Iron-Law overrides up to 4.0k via ADR-002).
-  Daily snapshots in `agents/.rule-budget-history.jsonl`.
+  Daily snapshots in `agents/runtime/.rule-budget-history.jsonl`.
 - **Compression discipline:** P4.3 brought the auto-bucket from
   ~75k → 59 220 chars (under the 60k target) without behaviour drift.
 
@@ -105,7 +105,7 @@ point.
 
 Kernel-bucket-check: PASS. Per-rule cap: 16 rules over 2.5k target,
 all within 4.0k Iron-Law override per ADR-002. Trend snapshot
-appended to `agents/.rule-budget-history.jsonl`.
+appended to `agents/runtime/.rule-budget-history.jsonl`.
 
 ## Consequences
 

package/docs/decisions/INDEX.md

@@ -15,6 +15,16 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-009](ADR-009-event4u-namespace.md) | Event4U Namespace And Claude Desktop Zip Bundles | accepted | 2026-05-13 | — |
 | [ADR-010](ADR-010-profile-pack-preset-boundary.md) | Profile Pack Preset Boundary | proposed | 2026-05-16 | — |
 | [ADR-011](ADR-011-domain-pack-readiness.md) | Domain Pack Readiness | accepted | 2026-05-17 | — |
+| [ADR-012](ADR-012-typescript-cli-shell.md) | Typescript Cli Shell | accepted | 2026-05-19 | — |
+| [ADR-013](ADR-013-discovery-frontmatter-contract.md) | Discovery Frontmatter Contract | accepted | 2026-05-19 | — |
+| [ADR-014](ADR-014-gui-framework-choice.md) | Gui Framework Choice | accepted | 2026-05-20 | — |
+| [ADR-015](ADR-015-discovery-manifest-contract.md) | Discovery Manifest Contract | accepted | 2026-05-21 | — |
+| [ADR-016](ADR-016-installer-architecture.md) | Installer Architecture | accepted | 2026-05-21 | — |
+| [ADR-017](ADR-017-monorepo-physical-layout.md) | Monorepo Physical Layout | accepted | 2026-05-21 | — |
+| [ADR-018](ADR-018-trust-and-safety-layer.md) | Trust And Safety Layer | accepted | 2026-05-21 | — |
+| [ADR-019](ADR-019-router-json-dist-location.md) | Router Json Dist Location | accepted | 2026-05-23 | — |
+| [ADR-020](ADR-020-global-only-consumer-scope.md) | Global Only Consumer Scope | accepted | 2026-05-23 | — |
+| [ADR-021](ADR-021-deployment-shape.md) | Deployment Shape | accepted | 2026-05-24 | — |
 
 ## Unnumbered (legacy)
 

package/docs/deploy/connector-setup.md

@@ -0,0 +1,129 @@
+# Connector setup — internal AI OS
+
+> **Status**: 🚧 **skeleton**. Phase 5 of
+> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
+> is **not yet implemented**. Phase 5 is contingent on Phase 2 (SSO)
+> and Phase 3 (central policy) shipping first.
+>
+> Open design questions live in
+> [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/council-question-connector-scope.md).
+
+## Audience
+
+An admin at a deploying organization who wants the AI OS to read
+tickets / PRs / Slack threads to ground its plans in the org's actual
+state of work.
+
+## Launch set (planned)
+
+| Connector | Read | Write | OAuth shape |
+|---|---|---|---|
+| Linear | v1 | v2 (gated) | per-org app install |
+| GitHub | v1 | v2 (gated) | GitHub App (per-org) |
+| Jira Cloud | v1 | v2 (gated) | per-user OAuth |
+| Slack | v1 | v2 (gated) | per-org app install |
+| Notion | v1 | — | per-user OAuth |
+
+**v1** = read-only · **v2** = write paths, each behind explicit org
+policy gate (see [`policy-cookbook.md`](policy-cookbook.md) →
+`connectors.write_enabled`).
+
+## OAuth contract (planned)
+
+Each connector lands one of two shapes:
+
+### Per-org app install
+
+Admin installs the app once at the org level. Every authenticated
+user inherits read access. Best for Linear / GitHub / Slack where
+the data is org-shared.
+
+### Per-user OAuth
+
+Each engineer authorizes their own account. The wizard surfaces a
+per-user "Connect Jira" / "Connect Notion" panel. Best where data is
+user-scoped or per-user permission boundaries matter.
+
+## Token storage (planned)
+
+OAuth tokens land in Postgres encrypted with the deployment's
+`SESSION_SECRET` derivative. Rotation happens automatically on
+refresh-token success. A `connector_token_rotated` audit event lands
+on each rotation.
+
+## Rate limits & cost (planned)
+
+| Connector | Cost model | Default cache TTL |
+|---|---|---|
+| Linear | Free, generous quota | 5 min for tickets, 1 min for comments |
+| GitHub | 5,000 / hr per token | 10 min for PRs, 2 min for reviews |
+| Jira Cloud | 10 / sec per app | 5 min |
+| Slack | Tier 2 (~20 / min) | 1 min for threads |
+| Notion | 3 / sec per integration | 10 min |
+
+The wizard surfaces per-connector cost in the admin panel; user-facing
+flows hide it.
+
+## Setup walkthrough (planned)
+
+### Linear
+
+```text
+1. Admin → Linear workspace settings → API → OAuth applications.
+2. Create app, set redirect URI to https://your.host/oauth/linear/callback.
+3. Copy client_id + client_secret into the AI OS admin panel.
+4. Authorize once at the org level.
+```
+
+### GitHub
+
+```text
+1. Admin → org settings → Developer settings → GitHub Apps → New.
+2. Permissions: read on Issues, Pull Requests, Contents, Metadata.
+3. Install on selected repos (or all).
+4. Copy app_id + private_key into the AI OS admin panel.
+```
+
+### Jira Cloud
+
+```text
+🚧 Per-user OAuth flow; each engineer connects on first use.
+```
+
+### Slack
+
+```text
+1. Admin → Slack app directory → Create app → from manifest.
+2. Manifest ships at packages/core/deploy/connectors/slack.manifest.yml
+   (does not yet exist).
+3. Install in workspace, copy bot token + signing secret.
+```
+
+### Notion
+
+```text
+🚧 Per-user OAuth flow.
+```
+
+## Hard-Floor caveats
+
+- OAuth token storage → **security-sensitive**, human-reviewed PR.
+- Write paths (v2) → **explicit org-policy gate** before merge.
+- Third-party data caching → cross-tenant isolation review before
+  merge (a stray cache-key collision exposes org A's data to org B).
+
+## What's not yet here
+
+- No connector code exists in the repo.
+- No OAuth callback routes are registered.
+- No admin panel for connector management.
+- No token-storage schema.
+
+All of the above land in Phase 5, contingent on Phases 2 + 3.
+
+## Cross-references
+
+- 🚧 Reserved ADR slot: `docs/decisions/ADR-025-connector-scope.md`.
+- Council question: [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/council-question-connector-scope.md).
+- Quickstart: [`quickstart.md`](quickstart.md).
+- Policy cookbook: [`policy-cookbook.md`](policy-cookbook.md).

package/docs/deploy/env-vars.md

@@ -0,0 +1,70 @@
+# Environment variable contract — `agent-config` deployment
+
+Phase 1 of [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md).
+Decision shape: [`ADR-021`](../decisions/ADR-021-deployment-shape.md).
+
+This file is the **single source of truth** for environment variables
+read by the deployed container. Every knob below is consumed by either
+the GUI server (TypeScript) or the embedded Python install supervisor.
+
+| Variable | Required | Default | Phase | Meaning |
+|---|---|---|---|---|
+| `BIND_HOST` | no | `127.0.0.1` | 1 | Bind address. Set to `0.0.0.0` for container deployments; non-loopback REQUIRES `ALLOWED_HOSTS`. |
+| `GUI_PORT` | no | `8787` | 1 | TCP port the wizard listens on. CLI override: `--port`. |
+| `ALLOWED_HOSTS` | when host ≠ loopback | derived | 1 | Comma-separated `host:port` allowlist for the Host-header gate. Reverse-proxy hostnames go here. |
+| `STORAGE_MODE` | no | `filesystem` | 1+ | `filesystem` (Phase 1) or `postgres` (Phase 2+). Audit log + memory backend. |
+| `SESSION_BACKEND` | no | `memory` | 1+ | `memory` (Phase 1) or `redis` (Phase 3+). Wizard session + per-user state. |
+| `AGENT_CONFIG_PROJECT_ROOT` | no | `/var/lib/agent-config/runtime` | 1 | Mountpoint the container treats as the consumer "project root". |
+| `AGENT_CONFIG_GUI_NO_OPEN` | no | `1` (in image) | 1 | Set to suppress the browser-launch attempt — required in headless containers. |
+| `AUTH_MODE` | no | `none` | 2 | `none` \| `oidc` \| `saml`. **Not yet read by the server** — placeholder for Phase 2. |
+| `OIDC_ISSUER_URL` | yes when `AUTH_MODE=oidc` | — | 2 | OIDC discovery URL. Not yet consumed. |
+| `OIDC_CLIENT_ID` | yes when `AUTH_MODE=oidc` | — | 2 | Not yet consumed. |
+| `OIDC_CLIENT_SECRET` | yes when `AUTH_MODE=oidc` | — | 2 | Not yet consumed. Read from secret manager only. |
+| `POLICY_PATH` | no | `/etc/event4u/policy.yaml` | 3 | Central org-policy YAML mount path. **Not yet read by the server** — placeholder for Phase 3. |
+| `DATABASE_URL` | yes when `STORAGE_MODE=postgres` | — | 2+ | Postgres connection string. Compose-default points at the bundled service. |
+| `REDIS_URL` | yes when `SESSION_BACKEND=redis` | — | 3+ | Redis connection string. Compose-default points at the bundled service. |
+
+## What ships honoring these vs not
+
+**Honored today (Phase 1):**
+
+- `BIND_HOST` — server respects `--host` flag and `BIND_HOST` env.
+- `GUI_PORT` / `--port` — server listens on this port.
+- `ALLOWED_HOSTS` — `Host:`-header allowlist for the GUI gate.
+- `STORAGE_MODE` / `SESSION_BACKEND` — surfaced in `/api/v1/health`
+  responses but **storage and session implementations still default
+  to filesystem and memory**. Setting them to `postgres` / `redis`
+  in Phase 1 has no effect on storage behavior (and the health
+  response will tell you so).
+- `AGENT_CONFIG_PROJECT_ROOT` — the container's runtime mount.
+- `AGENT_CONFIG_GUI_NO_OPEN` — auto-set to `1` in the shipped image
+  so the wizard does not try to `xdg-open` a browser from inside a
+  container.
+
+**Documented now, wired later:**
+
+- `AUTH_MODE` and its OIDC dependents — Phase 2.
+- `POLICY_PATH` — Phase 3.
+- `DATABASE_URL` / `REDIS_URL` — Phase 2 / Phase 3 respectively.
+
+## Security posture
+
+- **Secrets stay in env or a mounted secret manager.** Never bake
+  `OIDC_CLIENT_SECRET`, `DATABASE_URL` with a password, or
+  `POSTGRES_PASSWORD` into the image. Compose uses host-env or
+  `.env` files; production uses your secrets manager of choice.
+- **`BIND_HOST=0.0.0.0` without `ALLOWED_HOSTS`** — server refuses
+  to start. This is intentional: a non-loopback bind without a
+  Host-header allowlist is an open invitation for DNS rebinding.
+  See [`ADR-021`](../decisions/ADR-021-deployment-shape.md) § Security.
+- **`/api/v1/health`** is the only endpoint exempt from CSRF, but it
+  is rate-limited to 1 request per second per remote IP and exposes
+  no secrets.
+
+## Cross-references
+
+- Image + compose: [`packages/core/deploy/`](../../packages/core/deploy/)
+- ADR: [`ADR-021-deployment-shape.md`](../decisions/ADR-021-deployment-shape.md)
+- Operator quickstart: [`quickstart.md`](quickstart.md)
+- Policy cookbook (Phase 3 preview): [`policy-cookbook.md`](policy-cookbook.md)
+- Connector setup (Phase 5 preview): [`connector-setup.md`](connector-setup.md)