@event4u/agent-config 3.1.1 → 3.3.0

package/docs/contracts/caveman-telemetry.md

@@ -13,7 +13,7 @@ keep-beta-until: 2026-08-15
 
 | Key | Value | Provenance |
 |---|---|---|
-| `caveman_multiplier_version` | `v1` | Tied to `bench/reports/caveman-v1.{json,md}` |
+| `caveman_multiplier_version` | `v1` | Tied to `internal/bench/reports/caveman-v1.{json,md}` |
 | `caveman_multiplier_value` | `0.9155` | `median(terse_control_tokens / compressed_tokens)` over the 10-prompt v1 corpus |
 | `caveman_multiplier_p10` | `0.4506` | 10th percentile (worst-case carve-out-tax prompts) |
 | `caveman_multiplier_p90` | `2.3664` | 90th percentile (pure-prose prompts where caveman wins) |
@@ -40,7 +40,7 @@ where `M = caveman_multiplier_value`.
 
 ## Why suspended after v1
 
-The `caveman-v1` bench (`bench/reports/caveman-v1.md`, 30 calls,
+The `caveman-v1` bench (`internal/bench/reports/caveman-v1.md`, 30 calls,
 2026-05-16) found:
 
 - Median savings vs raw uncompressed: **+23.51 %** (inflated by the
@@ -78,6 +78,6 @@ Until a v2 bench (broader corpus or a re-tuned dialect) lifts the
 ## See also
 
 - [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) — the rule-default-flip gate; this multiplier is gated on the same `vs_terse` arm.
-- [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) — provenance for the `v1` value.
-- [`bench/reports/caveman-v2.md`](../../bench/reports/caveman-v2.md) — input-side (orthogonal); does NOT feed this multiplier (this multiplier is output-side).
+- [`internal/bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) — provenance for the `v1` value.
+- [`internal/bench/reports/caveman-v2.md`](../../bench/reports/caveman-v2.md) — input-side (orthogonal); does NOT feed this multiplier (this multiplier is output-side).
 - [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md) — runtime rule the multiplier measures.

package/docs/contracts/compression-default-kill-criterion.md

@@ -6,7 +6,7 @@ keep-beta-until: 2026-08-14
 # Compression default — kill-criterion
 
 > **Status:** v1-measured · criterion not met · default stays `off` · **Owner:** `step-16-caveman-substance.md`
-> Phase 1 closeout · **Sources:** [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) ·
+> Phase 1 closeout · **Sources:** [`internal/bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) ·
 > [`council-synthesis.md` § 7](../../agents/evidence/audits/2026-05-14-north-star/council-synthesis.md) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict --> ·
 > [`caveman-v1-kc-verdict.json`](../../agents/runtime/council/responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 
@@ -23,14 +23,14 @@ DECISION OWNED BY THE NEXT BENCH CLOSEOUT, NOT BY THIS DOC.
    [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md)
    but the feature is non-promoted: no skill recommends turning it on,
    no preset enables it, no profile depends on it.
-2. **Baselines.** Every published `bench/reports/caveman-v<N>.{json,md}`
+2. **Baselines.** Every published `internal/bench/reports/caveman-v<N>.{json,md}`
    measures three arms (`compressed` · `terse-control` ·
    `uncompressed`) and reports two savings columns:
    - `vs_raw` — median savings against the uncompressed arm.
    - `vs_terse` — **load-bearing** median savings against the
      `Answer concisely.` terse-control arm. `vs_raw` is inflated by the
      carve-out-tax-free pure-prose case and is **not** the gate metric.
-3. **Decision table.** Read the latest `bench/reports/caveman-v<N>.md`
+3. **Decision table.** Read the latest `internal/bench/reports/caveman-v<N>.md`
    and apply exactly one of:
 
    | Measured `vs_terse` median | Quality regression on corpus | Verdict |
@@ -50,7 +50,7 @@ DECISION OWNED BY THE NEXT BENCH CLOSEOUT, NOT BY THIS DOC.
 
 ## v1 verdict (2026-05-16)
 
-[`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
+[`internal/bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
 landed 30 calls · $0.0805 · 0 errors · `claude-sonnet-4-5`:
 
 | Metric | Median | p10 | p90 |
@@ -100,7 +100,7 @@ re-litigating compression on every PR.
 
 ## Cross-references
 
-- [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
+- [`internal/bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
   — v1 measurement; canonical baseline this doc cites.
 - [`docs/benchmarks.md`](../benchmarks.md)
   — cadence + when the next bench run is mandatory.

package/docs/contracts/cost-enforcement.md

@@ -131,4 +131,4 @@ suite is wired to `task test-cost-budget` per `step-11` Phase 2 Step 5.
 - `step-11-ruflo-parity` — Measurement & Governance Parity roadmap.
 - `docs/contracts/cost-dashboard.md` — companion dashboard contract.
 - `scripts/cost/budget.mjs` — evaluator implementation.
-- `bench/pricing.yaml` — per-model USD pricing table.
+- `internal/bench/pricing.yaml` — per-model USD pricing table.

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).