@event4u/agent-config 3.1.1 → 3.2.0

package/docs/contracts/daily-workspace.md

@@ -0,0 +1,137 @@
+# Daily Workspace Surface Contract
+
+> **Status** · v0 / design · 2026-05-24. Surface contract for the daily
+> workspace introduced as Phase 4 of the employee-product workstream.
+> Governed by ADRs [`022`](../decisions/ADR-022-daily-workspace-decomposition.md) ·
+> [`023`](../decisions/ADR-023-host-agent-protocol.md) ·
+> [`024`](../decisions/ADR-024-workspace-v0-feature-floor.md) ·
+> [`025`](../decisions/ADR-025-workspace-chrome.md).
+
+## Shape (v0)
+
+Browser tab at `http://127.0.0.1:<gui-port>/workspace`, served by the
+existing installer GUI (`packages/core/installer/src/gui/server.ts`).
+Same CSRF token, same loopback bind, same kill-switch as
+[`gui-wizard`](gui-wizard.md). Launched via
+`npx @event4u/agent-config workspace` (alias for
+`init --gui --route=/workspace` once wired).
+
+```
+┌─ /workspace ─────────────────────────────────────────────────┐
+│  [identity strip — shared with installer GUI shell]         │
+├────────────────────┬─────────────────────────────────────────┤
+│ Role + Task        │  Active session log                     │
+│ launcher           │  (latest JSONL entries, append-only)    │
+│                    │                                         │
+│ - galabau          │  ▸ 12:04 launch  · role=galabau         │
+│ - content-creator  │  ▸ 12:05 host    · claude / tier-1      │
+│ - consultant       │  ▸ 12:08 host    · turn.completed       │
+│                    │                                         │
+│ (Phase 3 roles)    │  Knowledge pane                         │
+│                    │  - source: handbuch.pdf                 │
+│                    │  - source: angebot-template.md          │
+│                    │  (Phase 2 namespace; "no sources yet"   │
+│                    │   when empty)                           │
+└────────────────────┴─────────────────────────────────────────┘
+```
+
+No left / centre / right three-rail layout in v0 (deferred per
+ADR-024). One launcher, one log, one stub pane.
+
+## Endpoints (additions to the GUI server)
+
+All endpoints CSRF-gated, loopback-bound. Existing wizard endpoints
+in [`gui-wizard`](gui-wizard.md) are untouched.
+
+| Method · Path | Purpose |
+|---|---|
+| `GET  /workspace` | HTML shell + initial state (role list, recent sessions). |
+| `GET  /api/v1/workspace/roles` | List available roles from `agents/roles/<role>/`. |
+| `GET  /api/v1/workspace/roles/:role/tasks` | Per-role task list from `skills.yml` + `prompts/`. |
+| `POST /api/v1/workspace/launch` | Body: `{ role, task, host? }`. Resolves host via ADR-023 tier; runs the launch; appends to JSONL log. |
+| `GET  /api/v1/workspace/sessions` | List of recent sessions (≤ 20, ordered by mtime). |
+| `GET  /api/v1/workspace/sessions/:id` | Streams the JSONL log for one session. |
+| `GET  /api/v1/workspace/knowledge` | Snapshot of the current `knowledge:` memory namespace (read-only). |
+
+## Session JSONL schema
+
+Path: `~/.event4u/agent-config/workspace/sessions/<yyyy-mm-dd>/<session-id>.jsonl`
+(one file per session; append-only; UTF-8). Session id = `YYYYMMDDTHHMMSSZ-<8-hex>`.
+
+Each line is one JSON record with the shared envelope:
+
+```json
+{ "ts": "<iso-8601-utc>", "kind": "<event-kind>", "data": { … } }
+```
+
+Event kinds:
+
+- `launcher.input` — `{ role, task, rendered_prompt, host_tier, host_id }`
+- `host.turn` — `{ host_id, turn_id, model, input_tokens, output_tokens, latency_ms }`
+- `host.output` — `{ host_id, turn_id, role: "assistant", text }` *(verbatim host envelope text — Tier 1 only)*
+- `host.tool` — `{ host_id, turn_id, tool_name, input, output_excerpt }` *(when the host envelope surfaces it)*
+- `host.error` — `{ host_id, message, exit_code }`
+- `inbox.handoff` — `{ inbox_path, copied_to_clipboard: bool }` *(Tier 3 only)*
+
+No PII in filenames. No remote sync. Encryption-at-rest deferred to a
+future ADR.
+
+## Inbox handoff (Tier 3)
+
+Path: `~/.event4u/agent-config/workspace/inbox/<yyyy-mm-dd>/<id>.md`.
+
+```markdown
+---
+created_at: 2026-05-24T12:08:00Z
+role: galabau
+task: angebot-erstellen
+host_tier: 3
+host_id: cursor
+---
+
+[rendered prompt body — skill context inlined per ADR-023]
+```
+
+The UI surfaces a one-line banner: "Workspace wrote
+`~/.event4u/.../<id>.md`. Open it in Cursor and paste." Clicking
+the banner copies the path to clipboard.
+
+## Skill resolution
+
+Tier 1 with skill surface (Claude Code only) — workspace passes the
+slash command as part of the prompt body (`/work "<task>"` style)
+and lets the host resolve it from `.claude/commands/`.
+
+Tier 1 without skill surface (Codex, Gemini) and Tier 3 — workspace
+**inlines** the skill body into the rendered prompt. The host gets
+the prompt with skill context as a self-contained block.
+
+## State scope
+
+- Per-user. Local-only. One workspace per OS user.
+- No multi-tenant view in v0. Multi-user deployment (the topology
+  from [`ADR-021`](../decisions/ADR-021-deployment-shape.md)) is
+  out of scope for v0.
+- Closing the browser tab does not kill running host subprocesses.
+  Reopening shows the live JSONL log.
+
+## Failure modes & telemetry
+
+- Host CLI not installed → workspace renders "Host `<id>` not
+  available" banner with install link. No silent fallback.
+- JSON envelope shape change → demote host to Tier 3 per ADR-023.
+- Inbox write failure (disk full, permissions) → red banner; no
+  silent loss.
+
+Telemetry stays off by default (project inertia). When the user
+opts in via `.agent-settings.yml`, the workspace emits
+`workspace.launch`, `workspace.host_turn`, `workspace.inbox_handoff`
+counters only. No prompt bodies, no response bodies.
+
+## Cross-references
+
+- ADRs: [`022`](../decisions/ADR-022-daily-workspace-decomposition.md) · [`023`](../decisions/ADR-023-host-agent-protocol.md) · [`024`](../decisions/ADR-024-workspace-v0-feature-floor.md) · [`025`](../decisions/ADR-025-workspace-chrome.md).
+- Host-agent protocol: [`host-agent-protocol`](host-agent-protocol.md).
+- GUI substrate: [`gui-wizard`](gui-wizard.md).
+- Knowledge ingestion: [`local-knowledge-ingestion`](local-knowledge-ingestion.md).
+- Role experience: [`role-experience`](role-experience.md).

package/docs/contracts/explain-modes.md

@@ -0,0 +1,146 @@
+# Explain Modes Contract
+
+> **Status** · v0 / design · 2026-05-24. Phase 6 of the
+> employee-product workstream.
+> Governed by [`ADR-026`](../decisions/ADR-026-explain-mode-translation.md).
+> Translates the existing engineer-shaped `explain-v1` envelope into a
+> role-aware plain surface, without changing the underlying data.
+
+## Two modes over one envelope
+
+The agent-memory MCP already returns an `explain-v1` envelope per
+`memory_explain`. It speaks engineer: `trust_score`, `score_breakdown`,
+`promotion_history`, `contradictions`, `decay`. Phase 6 keeps that
+envelope as the single source of truth and renders **two views**:
+
+| Mode | Default for | Vocabulary |
+|---|---|---|
+| `technical` | engineering-lead, platform-engineer, default for `--debug` flag | trust_score, decay rate, promotion path, contradictions count |
+| `plain` | every other role (galabau, content-creator, consultant, …) | "where this came from", "how confident", "when last reviewed", "what's contested" |
+
+No new MCP call. No new data fetch. The plain renderer is a **pure
+function** over the existing envelope.
+
+## Field mapping
+
+| envelope field | technical label | plain label (default) |
+|---|---|---|
+| `trust_score` (0.0–1.0) | "Trust score" | "Confidence" with 4-band label (Very High ≥ 0.85 · High ≥ 0.65 · Medium ≥ 0.40 · Low < 0.40) |
+| `score_breakdown.validation` | "Validation contribution" | "How well it's been checked" |
+| `score_breakdown.usage` | "Usage contribution" | "How often it's been used" |
+| `score_breakdown.recency` | "Recency contribution" | "How recently it was confirmed" |
+| `score_breakdown.contradictions` | "Contradiction penalty" | "Disagreements found" |
+| `promotion_history[]` | "Promotion timeline" | "When this was confirmed" (most recent first, ≤ 3 entries) |
+| `contradictions[]` | "Unresolved contradictions" | "What disagrees with this" |
+| `decay.applied_factor` | "Decay factor" | "Freshness" with 3-band label (Fresh ≥ 0.80 · Aging ≥ 0.50 · Stale < 0.50) |
+| `evidence.sources[]` | "Sources" | "Where this came from" |
+| `last_reviewed_at` | "Last reviewed" | "When last reviewed" + human-relative ("3 days ago") |
+
+The technical view renders one section per envelope field, terse,
+tabular. The plain view renders four labelled paragraphs:
+
+```
+Where this came from
+  3 sources — handbuch.pdf · offer-template.md · 1 council vote.
+
+How confident
+  High (0.74). Last confirmed 3 days ago.
+
+When last reviewed
+  2026-05-21 — by the maintenance pass.
+
+What's contested
+  No open disagreements.
+```
+
+## Per-role glossary override
+
+Each role may ship an `agents/roles/<role>/explain-glossary.yml`
+that overrides default plain-mode labels and the 4-band threshold
+points. The file is optional; missing → defaults are used.
+
+```yaml
+# agents/roles/galabau/explain-glossary.yml
+schema: explain-glossary/v0
+labels:
+  confidence: "Sicherheit"
+  sources: "Woher das stammt"
+  last_reviewed: "Zuletzt geprüft"
+  contradictions: "Was widerspricht"
+bands:
+  confidence:
+    very_high: 0.85
+    high: 0.65
+    medium: 0.40
+  freshness:
+    fresh: 0.80
+    aging: 0.50
+```
+
+Labels stay in `.md` source English (per `language-and-tone`);
+**glossary YAMLs are the exception** — they hold the localized
+runtime strings for the rendered surface and may be in the role's
+native language. Loader validates `schema:` matches `explain-glossary/v0`.
+
+## `/why` quick command
+
+Any role may invoke `/why` on the last agent reply. Resolution:
+
+1. Look up the last `host.turn` in the active session JSONL.
+2. Extract memory entry IDs referenced in the reply (regex on
+   `mem://<id>` markers the host envelope already emits).
+3. Call `memory_explain` for each id; merge envelopes.
+4. Render in the active mode (plain by default, technical if the
+   role's `explain_default` is `technical`).
+5. Append the rendered output to the session JSONL as
+   `{ kind: "explain.rendered", data: { mode, ids: [...] } }`.
+
+`/why` never makes a network call beyond the existing MCP transport.
+
+## Renderer surface (pure function)
+
+```ts
+function renderExplain(
+  envelope: ExplainV1,
+  options: {
+    mode: "technical" | "plain",
+    glossary?: ExplainGlossaryV0,
+    locale?: string,            // affects relative-date rendering only
+  }
+): { markdown: string, mode: string, ids: string[] }
+```
+
+Implementation lives in `packages/core/src/workspace/explain/`. No I/O,
+no clock dependency beyond the `now` injected for relative-date
+formatting; testable with fixtures.
+
+## Coverage (Phase 6 Step 5)
+
+Fixture-driven golden tests against `tests/golden/explain/` for ≥ 5
+envelope shapes:
+
+1. High-trust validated entry — fresh, no contradictions.
+2. Low-trust quarantined entry — never promoted.
+3. Contradicted entry — 2 open contradictions, one resolved.
+4. Recently promoted entry — last `promotion_history[0]` < 24h old.
+5. Deprecated entry — superseded-by chain, decay factor 0.20.
+
+Each fixture exercised in both `technical` and `plain` modes plus
+one with a glossary override. ≥ 90 % branch on the renderer module.
+
+## Failure modes
+
+- Missing envelope field → render placeholder "(unavailable)" in
+  plain mode; renderer never throws. Technical mode shows the raw
+  null with a warning marker.
+- Unknown `schema:` in glossary → loader logs a warning and falls
+  back to defaults; never blocks rendering.
+- `/why` finds no `mem://` markers → renders "This reply did not
+  cite any stored memory entries." No error.
+
+## Cross-references
+
+- ADR: [`ADR-026`](../decisions/ADR-026-explain-mode-translation.md).
+- Envelope contract: [`agent-memory-contract`](agent-memory-contract.md) (`explain-v1`).
+- Workspace integration: [`daily-workspace`](daily-workspace.md) (right rail).
+- Roles: [`role-experience`](role-experience.md) (`explain_default` field).

package/docs/contracts/host-agent-protocol.md

@@ -0,0 +1,88 @@
+# Host-Agent Protocol Contract
+
+> **Status** · v0 / inventory · 2026-05-24. The daily workspace shells out to
+> a host agent for every model interaction; it never re-implements one. This
+> contract names which surfaces each host agent exposes today, where the
+> workspace can rely on them, and what the fallback is when a surface is
+> missing. Governs ADR-023 / ADR-024 / ADR-025 — see
+> [`ADR-022`](../decisions/ADR-022-daily-workspace-decomposition.md).
+
+## Required capabilities
+
+The workspace v0 requires exactly two surfaces from a host agent:
+
+1. **`launch(prompt, skill?, cwd)`** — start a new conversation in the host
+   agent with `prompt` pre-filled and (optionally) `skill` pre-selected, in
+   the named working directory. Must be invocable from a non-interactive
+   shell. Return shape: success / failure; the conversation runs inside the
+   host's own UI from there.
+2. **`emit_trace(session) → ndjson`** — append-only, structured event stream
+   for the running conversation: model id, tool calls, citations,
+   explain-trace envelope (per
+   [`memory-explain-v1`](memory-explain-v1.md) when memory is involved).
+   Must be readable by tail-style consumers without polling the host's UI.
+
+Both surfaces must be **stable** — documented by the vendor, covered by
+their semver, not derived from unstable stdout parsing.
+
+## Today's inventory (2026-05-24)
+
+| Host agent | `launch` surface | `emit_trace` surface | Effective tier |
+|---|---|---|---|
+| **Claude Code (CLI)** | `claude -p "<prompt>" --output-format json` (subprocess; documented). Slash commands resolved against `.claude/commands/`. | JSON envelope on stdout per turn; session id preserved; no live append stream. | **Tier 1** — only host with both surfaces today. |
+| **OpenAI Codex CLI** | `codex exec --json` consumes stdin; documented. No slash-command surface (skills not first-class). | NDJSON event stream on stdout — `turn.completed`, `item.completed`, tool envelopes. | **Tier 1**, no skill surface — workspace must pre-render the prompt with skill context inlined. |
+| **Gemini CLI** | `gemini --output-format json` consumes stdin; documented. | JSON envelope on stdout per turn. OAuth grant required once. | **Tier 1**, no skill surface (same as Codex). |
+| **Augment (IDE)** | None documented. Hook trampolines exist (`scripts/hooks/augment-dispatcher.sh`) — post-event only, cannot initiate a conversation. | None — hook payloads cover events, not model output. | **Tier 3** — observe-only. |
+| **Cursor (IDE)** | `cursor://` deep links open files / chats but cannot pre-fill a prompt with skill context from a non-Cursor process. Hooks (`.cursor/hooks.json`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
+| **Cline (VS Code ext)** | None. Hooks (`~/Documents/Cline/Hooks/`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
+| **Windsurf (Cascade)** | None. Hooks (`.windsurf/hooks.json`) are post-event. | None at the protocol layer. | **Tier 3** — observe-only. |
+
+## Tier definitions
+
+- **Tier 1 — first-class.** Both `launch` and `emit_trace` are stable.
+  Workspace can build full features against the host.
+- **Tier 2 — degraded.** One of the two surfaces exists; workspace can
+  partially drive but degrades a named feature (e.g. no inline citations).
+  *(No host agent occupies this tier today.)*
+- **Tier 3 — observe-only.** Neither surface exists at the agent boundary.
+  The workspace falls back to (a) user-paste of a generated prompt, or (b)
+  inbox-file handoff (writes `~/.event4u/agent-config/workspace/inbox/<id>.md`,
+  user opens the host themselves). Hook trampolines remain available for
+  passive event recording but do not initiate conversations.
+
+## v0 scope
+
+- The workspace v0 ships against **Claude Code** as the single Tier-1 host.
+  Codex and Gemini are wired but secondary (no skill surface — see ADR-024).
+- Tier-3 hosts get the **inbox handoff** fallback only: workspace writes the
+  rendered prompt + skill body into the inbox file and surfaces a one-line
+  copy-to-clipboard banner. No tighter integration is attempted in v0.
+- The CLI shell-out is the **only** mechanism. No HTTP RPC, no MCP-driven
+  agent control, no shared SQLite — those are deferred to v1+ when at least
+  one Tier-3 host moves up.
+
+## Stability & change policy
+
+- The vendor-published JSON envelope shapes are the contract. Workspace
+  parses by named keys, never by positional fields.
+- A new host-agent CLI release that breaks the envelope **fails closed** —
+  the workspace surfaces a banner and degrades to Tier 3 (inbox handoff)
+  until this contract is updated.
+- This file is the source of truth for host-agent tier. Adding a host or
+  promoting a tier requires (a) a vendor-link in the inventory row,
+  (b) at least one integration test under
+  `tests/integration/host-agent-protocol/`.
+
+## Cross-references
+
+- ADR: [`ADR-022`](../decisions/ADR-022-daily-workspace-decomposition.md) ·
+  [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md) ·
+  [`ADR-024`](../decisions/ADR-024-workspace-v0-feature-floor.md) ·
+  [`ADR-025`](../decisions/ADR-025-workspace-chrome.md).
+- Skill: [`ai-council`](../../.agent-src/skills/ai-council/SKILL.md) — uses
+  the same CLI subprocess shape (claude / codex / gemini) for council
+  members; the workspace inherits the proven invocation paths.
+- Hooks: [`hook-architecture-v1`](hook-architecture-v1.md) — covers the
+  post-event surface for all hosts including Tier-3.
+- Daily workspace surface: [`daily-workspace`](daily-workspace.md) — UI
+  contract that consumes this protocol.

package/docs/contracts/local-analytics.md

@@ -0,0 +1,148 @@
+# Local Analytics Contract
+
+> **Status** · v0 / design · 2026-05-24. Phase 7 of the
+> employee-product workstream.
+> **Local-only.** Does NOT lift the Hard-Floor item from 3.1.0 — no
+> network egress, no remote Worker, no POST. Inertia of the prior
+> telemetry roadmap is preserved.
+
+## Position vs the 3.1.0 telemetry SDK
+
+3.1.0 shipped the telemetry SDK + Cloudflare Worker as **source-only**;
+the kill-switch defaults off and nothing is deployed. Phase 7 builds
+a **separate local-only** analytics path:
+
+| Surface | Lives | Egress | Default |
+|---|---|---|---|
+| 3.1.0 remote telemetry | Worker (undeployed) | ✗ inert | off, Hard-Floor |
+| **Phase 7 local analytics** | `~/.event4u/agent-config/workspace/analytics/` | ✗ never | **on** for local-only |
+
+The two surfaces share **event vocabulary** where it overlaps; they
+never share a transport. Local analytics writes to disk; remote
+telemetry remains undeployed.
+
+## Event vocabulary
+
+Re-uses the `install_stage` schema (3.1.0) where applicable, and
+adds the `workspace_event` schema for launcher / document / explain
+interactions:
+
+| schema | source | example fields |
+|---|---|---|
+| `install_stage/v1` | installer (3.1.0) | `stage`, `outcome`, `duration_ms`, `package_version` |
+| `workspace_event/v0` | Phase 4–6 workspace | `event`, `role`, `task`, `host_tier`, `duration_ms` |
+
+`workspace_event/v0` event names (closed set):
+
+- `launcher.opened` · `launcher.task_picked` · `launcher.task_launched`
+- `session.started` · `session.host_turn` · `session.completed`
+- `document.created` · `document.edited` · `document.exported`
+- `explain.opened` · `explain.mode_toggled` · `why.invoked`
+- `knowledge.queried` · `knowledge.source_clicked`
+
+No prompt bodies. No response bodies. No PII. Only counters, role
+labels, task slugs (already public), and durations.
+
+## Storage
+
+```
+~/.event4u/agent-config/workspace/analytics/
+├── events.jsonl              ← append-only event log
+└── retention.lock            ← prune-pass mutex
+```
+
+One JSON record per line:
+
+```json
+{
+  "ts": "2026-05-24T12:08:00Z",
+  "schema": "workspace_event/v0",
+  "event": "launcher.task_launched",
+  "data": { "role": "galabau", "task": "angebot-erstellen",
+            "host_tier": 1, "duration_ms": 420 }
+}
+```
+
+Rolling retention: **90 days local**. A prune pass on workspace
+launch trims records older than 90 days; the lockfile prevents
+concurrent prune (cheap fs lock, not a real mutex).
+
+## Opt-out
+
+Single env var, single config flag, both checked:
+
+| Surface | Default | Override |
+|---|---|---|
+| Env | `AGENT_CONFIG_NO_LOCAL_ANALYTICS` unset | set to any non-empty value → no writes |
+| Config | `.agent-settings.yml` → `analytics.local: on` | set to `off` → no writes |
+
+Either set to off → emitter short-circuits before opening the file.
+No retention pruning either; the existing log stays until the user
+removes it.
+
+## Emitter API
+
+```python
+# packages/core/src/workspace/analytics/emitter.py
+class LocalAnalytics:
+    def emit(self, event: str, data: dict) -> None: ...
+    def query(self, since: datetime, event: str | None = None) -> list[Event]: ...
+    def prune(self) -> int: ...   # returns number of records dropped
+```
+
+The emitter is a synchronous append-line write. Never blocks the UI
+thread above 5 ms (90th percentile); no async / queue / batch
+machinery in v0.
+
+## `/analytics:show` command
+
+Local-only query. Renders to ASCII / Markdown table; never POSTs.
+
+```
+$ npx @event4u/agent-config analytics:show --window 30d
+
+Top prompts (last 30 days)
+  galabau · angebot-erstellen          47
+  content-creator · video-from-script  31
+  consultant · meeting-memo            24
+
+Launcher → completion rate per role
+  galabau           87% (47 launched · 41 completed)
+  content-creator   71% (31 launched · 22 completed)
+  consultant        92% (24 launched · 22 completed)
+
+Average session length: 4m 12s
+Knowledge sources clicked: 18 (handbuch.pdf · offer-template.md · …)
+```
+
+Flags: `--window <30d|7d|24h>` · `--event <name>` · `--role <slug>` ·
+`--format <markdown|csv|json>`. No `--upload`, no `--share`; the
+command can only read and render.
+
+## Coverage (Phase 7 Step 4)
+
+- pytest against fixture JSONL stores (`tests/fixtures/local-analytics/`):
+  emitter writes, query filters by window + event + role, prune
+  drops correctly at the 90-day boundary.
+- Env-flag short-circuit: emitter is a no-op when
+  `AGENT_CONFIG_NO_LOCAL_ANALYTICS=1`; no file is created.
+- Concurrency: two emitters writing the same file produce
+  well-formed lines (POSIX `O_APPEND` semantics — test on Linux,
+  document Windows caveat).
+
+## Failure modes
+
+- Disk full → emitter logs warning to stderr, drops the event, never
+  raises. UI thread is unaffected.
+- Malformed line in `events.jsonl` → query skips the line, increments
+  a `malformed_lines` counter exposed via `/analytics:show --health`.
+- Schema bump (`workspace_event/v0` → `v1`) → emitter writes the new
+  schema; query reads both. Migration is forward-compatible.
+
+## Cross-references
+
+- Phase 4 shell that produces the events: [`daily-workspace`](daily-workspace.md).
+- Phase 5 document events: [`workspace-documents`](workspace-documents.md).
+- Phase 6 explain events: [`explain-modes`](explain-modes.md).
+- 3.1.0 telemetry inertia: archived `road-to-product-adoption.md` Phase 4.
+- Walkthrough doc (Phase 7 Step 5): `docs/guides/local-analytics.md` (deferred).

package/docs/contracts/local-knowledge-ingestion.md

@@ -0,0 +1,96 @@
+---
+stability: beta
+keep-beta-until: 2026-08-24
+---
+
+# Local knowledge ingestion contract
+
+**Purpose.** Freeze the input shape, bounds, storage target, and redaction defaults for the single-user, local-only knowledge surface (`/knowledge:ingest`, `/knowledge:list`, `/knowledge:forget`) **before** any implementation lands. Closes the "Copy/Paste AI" complaint from feedback A without touching OAuth, multi-tenancy, or Hard-Floor connector territory.
+
+Last refreshed: 2026-05-24. Phase 2 of the employee-product workstream.
+
+## What this doc is **not**
+
+- Not the connector contract for GitHub / Jira / Confluence — those sit behind OAuth and stay cancelled in `road-to-internal-ai-os-deployment.md` Phase 5.
+- Not a remote-fetch surface — every input must resolve to a local path on the same machine the agent runs on.
+- Not a memory replacement — ingested content lives **inside** the existing memory layer under a dedicated namespace, never as a parallel store.
+
+## Input shapes
+
+The ingestion command accepts exactly these input shapes; anything else is rejected at the input validator with a structured error and no partial write.
+
+| Input | Resolution rule | Example |
+|---|---|---|
+| `file://<absolute-path>` | Single file. Path must be absolute and inside the user's home or the project root (no `/etc`, `/var`, `~root/`, `..` escapes). | `file:///Users/maintainer/clients/acme/brief.pdf` |
+| Local folder path | Recursive walk; symlinks not followed; hidden directories skipped (`.git`, `.venv`, `node_modules`). | `/Users/maintainer/clients/acme/` |
+| `.zip` archive | Unpacked to a temp dir inside `$TMPDIR/agent-knowledge-<uuid>`, walked, then the temp dir is removed before the command returns. | `/Users/maintainer/clients/acme.zip` |
+
+**Remote URLs are rejected** — `http://`, `https://`, `s3://`, `gs://`, `azure://`. The error message names `/knowledge:ingest` as local-only by design.
+
+## Supported MIME types
+
+The ingestion module routes each file through the existing `markitdown` adapter when the MIME type is not native markdown.
+
+| MIME | Adapter | Notes |
+|---|---|---|
+| `text/markdown` | passthrough | UTF-8 only; other encodings rejected |
+| `text/plain` | passthrough | UTF-8 only |
+| `application/pdf` | `markitdown` | OCR if scanned; OCR confidence < 0.7 surfaces as `low_confidence` tag |
+| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (`.docx`) | `markitdown` | |
+| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (`.xlsx`) | `markitdown` | One sheet per chunk |
+| `application/epub+zip` (`.epub`) | `markitdown` | Chapter per chunk |
+| `image/png`, `image/jpeg` | `markitdown` OCR | OCR confidence stored same as PDF |
+
+Unsupported MIME → file skipped with a counted `skipped: <mime>` entry in the command summary. No partial-content writes.
+
+## Bounds (non-negotiable, enforced at command entry)
+
+| Bound | Limit | Rationale |
+|---|---|---|
+| Total ingest size | ≤ 100 MB per `/knowledge:ingest` call | Keeps a single ingestion bounded; multi-ingest is fine |
+| Document count | ≤ 1000 per call | Avoids unbounded walks on a misconfigured folder |
+| Per-file size | ≤ 20 MB | One outlier file cannot blow the budget |
+| Total memory footprint | ≤ 500 MB across all ingests | LRU eviction at the namespace level when crossed |
+| Path traversal depth | ≤ 10 directories | Cheap guard against pathological folder trees |
+
+Crossing any bound is a **hard reject** at command entry — not a warning. The command returns a structured error with the bound name and the observed value.
+
+## Storage target
+
+Ingested content lives inside the existing memory namespace as a dedicated prefix:
+
+```
+memory/
+└── knowledge/
+    ├── <ingest-id>/         # uuid7 per ingest call
+    │   ├── manifest.json    # source path, count, timestamps, redactions
+    │   └── chunks/<n>.md    # one markdown chunk per logical unit
+```
+
+- `<ingest-id>` is a uuid7 so timestamps are recoverable from the id; never user-controlled.
+- `manifest.json` is the audit row — used by `/knowledge:list` and by the LRU eviction loop.
+- Chunks are markdown only after the adapter has run; the original binary is never stored.
+
+The MCP tool `memory_retrieve` (existing surface in `agent-memory`) **must** tag retrieved entries from this namespace with `source: knowledge`. The host model decides what to do with user-supplied vs maintainer-curated entries; this contract only requires the tag.
+
+## Redaction defaults
+
+Redaction runs **before** the chunk write, never after.
+
+- **PII allowlist** — only the following identifier classes survive the ingest: project names, document titles, headings, technical terminology. Everything else that pattern-matches a PII regex set (e-mail addresses, phone numbers, IBAN, credit-card-shaped strings, SSN-shaped strings) is replaced with class placeholders (`[EMAIL]`, `[PHONE]`, `[IBAN]`, `[CC]`, `[SSN]`).
+- **Secrets never stored** — anything matching the existing `gitleaks` ruleset (or equivalent) is replaced with `[SECRET]` and the manifest's `secrets_redacted` counter is incremented. A chunk with ≥ 1 secret redaction is tagged `contains_redactions: true`.
+- **The user can opt out per-call** with `--no-redact`, but the manifest captures the flag so the audit trail names exactly which ingests bypassed redaction. The default is always redact.
+
+## Eviction policy
+
+LRU at the namespace level. When the 500 MB cap is crossed, oldest ingests (by `manifest.last_touched`) are dropped whole — never per-chunk. `last_touched` updates on every `memory_retrieve` hit against an entry in the namespace. The user can pin an ingest with `/knowledge:list --pin <ingest-id>`; pinned ingests are never evicted.
+
+## Command surface (deferred to impl PR)
+
+`/knowledge:ingest <path>`, `/knowledge:list`, `/knowledge:forget <prefix>` are defined elsewhere — this contract pins their **inputs, bounds, storage, and redaction**. The Python module that implements the file walk + MIME routing + chunk writing lives at `packages/core/installer/python/knowledge_ingest.py`, ≤ 600 LOC (bumped from the pre-impl ≤ 400 budget once five PII classes, five secret patterns, LRU eviction, manifest persistence, pin/unpin and the multi-verb CLI were all in one file — splitting would have added an import seam without changing the surface), per Phase 2 Step 2.
+
+## Open questions (Phase 2 council pass, optional)
+
+- Chunk size — fixed (e.g. 2 KB markdown) vs adaptive per document? Default: 2 KB until the recruit sessions or eval surface a reason to change.
+- OCR confidence threshold — 0.7 is a guess; first three sessions inform the right number.
+- Pinning UX — `--pin` flag vs a separate `/knowledge:pin` command. Default in this contract: a flag on `/knowledge:list`.