@event4u/agent-config 9.8.0 → 9.9.0

package/docs/deploy/connector-setup.md

@@ -1,129 +0,0 @@
-# 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/old/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/old/council-question-connector-scope.md).
-- Quickstart: [`quickstart.md`](quickstart.md).
-- Policy cookbook: [`policy-cookbook.md`](policy-cookbook.md).

package/docs/deploy/env-vars.md

@@ -1,70 +0,0 @@
-# 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)

package/docs/deploy/policy-cookbook.md

@@ -1,130 +0,0 @@
-# Policy cookbook — internal AI OS
-
-> **Status**: 🚧 **skeleton**. Phase 3 of
-> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
-> is **not yet implemented**. This file documents the **shape** that
-> central org policy will take so operators can review the contract
-> before code lands. Every section below is normative-once-shipped.
->
-> Open design questions live in
-> [`agents/tmp/council-question-central-policy.md`](../../agents/old/council-question-central-policy.md).
-
-## Audience
-
-An admin at a deploying organization who needs to set org-wide floors
-(and ceilings) that individual users cannot escape.
-
-## File location (planned)
-
-```text
-/etc/event4u/policy.yaml          # inside the container
-${POLICY_PATH:-./policy.yaml}      # bind-mounted from the host
-```
-
-The file is the source of truth. A future admin UI generates this
-file, never the other way around.
-
-## Inheritance model (planned)
-
-```text
-default → org policy → user settings
-                   ↑           ↑
-                   |           └── user-only knobs (preferred name,
-                   |               IDE, bot icon)
-                   └── shared knobs (autonomy ceiling, redaction
-                       allowlist, provider allowlist, cost cap) —
-                       org wins; user cannot escape upward.
-```
-
-## Schema sketch (planned)
-
-```yaml
-# /etc/event4u/policy.yaml — example, not yet enforced.
-version: 1
-
-autonomy:
-  ceiling: review                   # never | review | apply-low | apply-medium
-  user_can_lower: true
-
-redaction:
-  allowlist_paths: []               # paths users are allowed to disable redaction for
-  block_paths:                      # paths where redaction is mandatory
-    - "**/secrets/**"
-    - "**/credentials/**"
-
-providers:
-  allowlist:
-    - openai
-    - anthropic
-  cost_cap_usd_per_day_per_user: 25
-  cost_cap_usd_per_day_total: 500
-
-audit:
-  retention_days: 90
-  include_read_actions: false       # only state-changing requests by default
-```
-
-## Recipes (planned)
-
-### Lock autonomy at "review" for all users
-
-```yaml
-autonomy:
-  ceiling: review
-  user_can_lower: false
-```
-
-### Cap monthly spend per user
-
-```yaml
-providers:
-  cost_cap_usd_per_day_per_user: 5      # ≈ $150/mo at max
-```
-
-### Restrict providers to those with EU data residency
-
-```yaml
-providers:
-  allowlist:
-    - anthropic-eu
-    - mistral
-```
-
-### Mandate redaction for `infrastructure/`
-
-```yaml
-redaction:
-  block_paths:
-    - "infrastructure/**"
-```
-
-## Hot reload (planned)
-
-The server will watch `POLICY_PATH` and apply changes within ~2 s
-without a restart. Sessions are not invalidated; only new
-permissions checks see the new policy. A `policy_reloaded` audit
-event lands on each successful reload.
-
-## Versioning (planned)
-
-Operators are expected to check `policy.yaml` into their **own** git
-repo (separate from this project) and mount it read-only into the
-container. `version: 1` is the only currently-defined schema version;
-breaking changes will bump the version + ship a migrator.
-
-## What's not yet here
-
-- Schema is not validated by the running server.
-- Hot-reload is not wired.
-- Admin UI does not exist.
-- Audit log table does not exist.
-
-All of the above land in Phase 3. Until then, per-user
-`.agent-settings.yml` is the only enforcement surface.
-
-## Cross-references
-
-- 🚧 Reserved ADR slot: `docs/decisions/ADR-023-central-policy.md`.
-- Council question: [`agents/tmp/council-question-central-policy.md`](../../agents/old/council-question-central-policy.md).
-- Env contract: [`env-vars.md`](env-vars.md) (`POLICY_PATH`).
-- Quickstart: [`quickstart.md`](quickstart.md).

package/docs/deploy/quickstart.md

@@ -1,112 +0,0 @@
-# Quickstart — internal AI OS
-
-> **Status**: skeleton. Phase 6 of
-> [`road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md).
-> The artefacts referenced (Compose, env contract, healthcheck) land in
-> Phase 1; **Phases 2–5 (auth, policy, team context, connectors) are
-> not yet implemented**. Sections flagged `🚧` describe surfaces that
-> only become real after those phases ship.
-
-## Audience
-
-A platform / DevOps engineer at a 5–50-person company who wants to
-host `@event4u/agent-config` once for the team behind their existing
-reverse proxy.
-
-## Prerequisites
-
-- Docker Engine ≥ 24 with Compose v2.
-- Reverse proxy (nginx / Caddy / Traefik / ALB) terminating TLS at
-  a hostname you control.
-- One free TCP port to forward to the container (default 8787).
-- 🚧 **Phase 2+** — your company's SSO / OIDC discovery URL + client
-  credentials.
-
-## Five-minute path
-
-```bash
-# 1. Clone the deployment artefacts.
-git clone https://github.com/event4u-app/agent-config.git
-cd agent-config/packages/core/deploy
-
-# 2. Copy and edit the environment file.
-cp .env.example .env
-${EDITOR:-vi} .env
-# Required: ALLOWED_HOSTS=your.host:443
-# Required: POSTGRES_PASSWORD=<long random>
-
-# 3. Boot.
-docker compose up -d
-
-# 4. Verify.
-curl -fsS http://127.0.0.1:8787/api/v1/health | jq
-# {
-#   "status": "ok",
-#   "version": "x.y.z",
-#   "uptime_seconds": 12,
-#   "storage_mode": "filesystem",
-#   "session_backend": "memory",
-#   ...
-# }
-```
-
-## Environment contract
-
-The full table of variables, their defaults, and validation rules
-lives in [`env-vars.md`](env-vars.md). The minimum a production
-deployment must override:
-
-- `ALLOWED_HOSTS` — comma-separated host\:port allowlist for the
-  `Host` header. Non-loopback bind without this **refuses to boot**.
-- `POSTGRES_PASSWORD` — `agent-config` user's password.
-- `SESSION_SECRET` — 32-byte random; rotates user sessions when
-  changed.
-- 🚧 **Phase 2+** — `AUTH_MODE=oidc` + `OIDC_*` block.
-
-## Reverse-proxy template (Caddy)
-
-```caddyfile
-your.host {
-    reverse_proxy 127.0.0.1:8787
-}
-```
-
-The container ships plain HTTP; TLS is the proxy's job. See ADR-021
-for the rationale.
-
-## Healthcheck
-
-Every 10 s the Compose `agent-config` service hits
-`/api/v1/health` (1-rps rate limit means this lands inside the
-budget). A non-200 response for two consecutive cycles flips the
-service to `unhealthy` and the orchestrator restarts it.
-
-## What's not yet here
-
-| Capability | Phase | Status |
-|---|---|---|
-| SSO / OIDC login | 2 | 🚧 deferred (security-sensitive) |
-| Central org policy | 3 | 🚧 deferred |
-| Team context (shared rules / skills) | 4 | 🚧 deferred |
-| Linear / GitHub / Slack connectors | 5 | 🚧 deferred |
-
-Until those land, the deployed instance is a **single-tenant** AI OS
-shared via the reverse proxy. Lock the proxy down with HTTP basic
-auth or an IP allowlist for v1.
-
-## Troubleshooting
-
-- **Container exits with `BIND_HOST=0.0.0.0 requires ALLOWED_HOSTS`** —
-  add `ALLOWED_HOSTS` to `.env` and `docker compose up -d` again.
-- **`/api/v1/health` returns 503 with `storage_unavailable`** —
-  Postgres has not finished its first-boot init. Wait 15 s and retry.
-- **Wizard 404s on every route** — reverse proxy is stripping the
-  `Host` header; either preserve it (`proxy_set_header Host $host`)
-  or add the proxy hostname to `ALLOWED_HOSTS`.
-
-## Cross-references
-
-- ADR-021 — [deployment shape](../decisions/ADR-021-deployment-shape.md).
-- Env contract — [env-vars.md](env-vars.md).
-- 🚧 Policy guide — [policy-cookbook.md](policy-cookbook.md) (Phase 3).
-- 🚧 Connector setup — [connector-setup.md](connector-setup.md) (Phase 5).

package/docs/deploy/small-team-recipe.md

@@ -1,148 +0,0 @@
-# Small-Team Recipe — 3–10 people, no code change
-
-> **Status** · v0 · 2026-05-24. Phase 9 of
-> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md).
-> The recipe relies entirely on **existing primitives**. No new
-> code, no new server, no shared backend. Each user runs the
-> workspace locally; the team shares the inputs.
-
-## Audience
-
-A team of 3–10 people in one organisation that wants every member
-to use agent-config as their daily AI tool, with **shared prompts**,
-**shared role experiences**, and **shared knowledge sources** —
-but where buying / running a central server is not justified.
-
-Examples this recipe is sized for:
-
-- A 4-person landscape-gardening business (one owner, three foremen).
-- A 6-person content team at a small agency.
-- A 5-person consulting partnership.
-
-## Architecture in one picture
-
-```
-┌─ shared NAS / SharePoint / Dropbox ──────────────────────────┐
-│   knowledge/                                                  │
-│     ├── handbuch.pdf                                          │
-│     ├── offer-templates/                                      │
-│     └── customer-history/                                     │
-└───────────────────────────────────────────────────────────────┘
-                       ▲                          ▲
-                       │ each user mounts         │
-                       │                          │
-┌──────────────────────┴──┐    ┌─────────────────┴─────────┐
-│  Person A laptop        │    │  Person B laptop          │
-│  workspace + local        │   │  workspace + local        │
-│  knowledge index (per-    │   │  knowledge index (per-    │
-│  user, ingested from NAS) │   │  user, ingested from NAS) │
-└─────────────┬─────────────┘   └────────────┬──────────────┘
-              │                              │
-              └──────── git pull / push ─────┘
-                          ▲
-                          │
-              ┌───────────┴────────────────┐
-              │  Shared `agents/overrides/`│
-              │  git repo (private)         │
-              │   ├── prompts/             │
-              │   ├── roles/               │
-              │   └── glossaries/          │
-              └─────────────────────────────┘
-```
-
-## Set up the shared overrides repo
-
-One person does this once:
-
-1. Create a **private** git repo, e.g. `internal-agent-pack`.
-2. Inside, mirror the structure of the package's `agents/overrides/`:
-   `prompts/`, `roles/`, `glossaries/`.
-3. Add the team's role experiences (Phase 3 of the roadmap):
-   one folder per role under `roles/<role>/` with `index.md`,
-   `skills.yml`, `prompts/`, and (Phase 6) `explain-glossary.yml`.
-4. Push to the team's git host. Grant read access to every team
-   member, write access to the maintainers.
-
-Each team member then:
-
-```bash
-git clone <repo> ~/internal-agent-pack
-ln -s ~/internal-agent-pack/prompts   ~/.event4u/agent-config/overrides/prompts
-ln -s ~/internal-agent-pack/roles     ~/.event4u/agent-config/overrides/roles
-ln -s ~/internal-agent-pack/glossaries ~/.event4u/agent-config/overrides/glossaries
-```
-
-`git pull` from anywhere on the team rolls out new prompts /
-glossaries to every laptop without any code change.
-
-## Set up shared knowledge
-
-Pick one shared mount the whole team has read access to: NAS,
-SharePoint mounted via DAV, Dropbox, Google Drive desktop sync.
-Anything that surfaces as a file path.
-
-Each team member runs once:
-
-```bash
-npx @event4u/agent-config knowledge:ingest /Volumes/team-share/knowledge
-```
-
-Per-user index. Same content. When new files land on the share,
-each user re-runs the ingest (Phase 2 will add a watcher later).
-
-## Daily flow per team member
-
-```bash
-npx @event4u/agent-config workspace
-```
-
-Opens the browser tab. Launcher shows the team's role experiences
-(from the shared overrides). Click a task → workspace shells out
-to the user's Tier-1 host (Claude Code / Codex / Gemini) or writes
-to the inbox for Tier-3 hosts. Documents land under
-`~/.event4u/agent-config/workspace/documents/`, **encrypted at
-rest** (Phase 8) with the user's per-machine key.
-
-Output documents are local to each user. The team shares **inputs**
-(prompts, role experiences, knowledge sources). The team does
-**not** share **outputs** (offers, mails, memos) through this
-recipe — those are user-private until manually saved to the team
-share.
-
-## Optional: publish the overrides as an npm pack
-
-Once the shared overrides repo is stable, the maintainer may
-publish it as a thin npm package:
-
-```bash
-# inside the overrides repo
-npm init --scope=@your-org
-# package.json names: "@your-org/agent-config-team"
-npm publish --access restricted
-```
-
-New team members then `npm install --global @your-org/agent-config-team`
-instead of cloning the repo. The package's `postinstall` script
-creates the same symlinks. This is **optional**; the git-clone path
-above works fine.
-
-## What this recipe does not give you
-
-- **No SSO.** Each user authenticates to their host agent (Claude
-  Code, etc.) independently.
-- **No central policy enforcement.** Overrides ship via git; users
-  can locally edit them.
-- **No shared output store.** Customer-facing documents stay on the
-  user's laptop. If the team needs shared output, they save / commit
-  the document file to the team share manually.
-- **No org-mode threat model.** This recipe is single-user-per-machine
-  with team-level input sharing. The org-mode threats (cross-user
-  policy enforcement, audit log centralisation) are explicitly out
-  of scope; see [`team-deployment-posture`](team-deployment-posture.md).
-
-## Cross-references
-
-- Posture: [`team-deployment-posture`](team-deployment-posture.md).
-- Workspace: [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
-- Knowledge ingestion: [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md).
-- Role experiences: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).