@event4u/agent-config 3.1.1 → 3.2.0

package/docs/contracts/role-experience.md

@@ -0,0 +1,121 @@
+---
+stability: beta
+keep-beta-until: 2026-08-24
+---
+
+# Role-experience contract
+
+**Purpose.** Freeze the on-disk shape of a `role-experience` — the artefact that turns a non-developer persona (galabau owner, content creator, consultant, …) into a first-class entry point with three first tasks, a named prompt library, and a curated skill shortlist. Pins the interface **before** the launcher in Phase 4 reads it, so the launcher and the role authors can move independently.
+
+Last refreshed: 2026-05-24. Phase 3 of the employee-product workstream.
+
+## What a role experience is
+
+A folder at `agents/roles/<role>/` that contains:
+
+- One **identity index** (`index.md`) — one-paragraph persona, three concrete first tasks, recommended pack list, install-path hint.
+- A **prompt library** (`prompts/<name>.md`) — 5–10 named prompts, each a single markdown file with structured frontmatter and a parameterised body the launcher can fill.
+- A **skill shortlist** (`skills.yml`) — the existing skills the launcher should surface for this role, in priority order. Cites existing skills only; never duplicates them.
+
+A role experience is **not**:
+
+- A new skill — the shortlist references existing skills under `packages/<pack>/.agent-src.uncompressed/skills/`. The role experience curates; it does not implement.
+- A documentation page — `docs/getting-started-by-role.md` is the prose surface and links **to** the role experience, never duplicates it.
+- A persona file under `personas/` — personas are review voices the AI Council uses; role experiences are end-user entry points.
+
+## Folder shape
+
+```
+agents/roles/<role>/
+├── index.md            # identity + three first tasks + recommended packs
+├── skills.yml          # skill shortlist (priority-ordered)
+└── prompts/
+    ├── <name-1>.md
+    ├── <name-2>.md
+    └── …               # 5–10 prompts
+```
+
+`<role>` is a kebab-case identifier; it doubles as the launcher key and the URL slug. Reserved words: `default`, `_template`, `_archive`.
+
+## `index.md` frontmatter (required)
+
+```yaml
+---
+role: <kebab-case-id>
+display_name: "Galabau owner"
+tagline: "One-sentence description visible in the launcher rail."
+recommended_packs: [core, founder-strategy]   # cites existing packs only
+install_path_hint: "MCP recommended (Claude Desktop) · CLI when …"
+recruit_session_ref: "agents/recruit-sessions/01-galabau-owner.md"  # nullable until session lands
+status: stable | beta | draft
+---
+```
+
+The body of `index.md` then lists, in this order:
+
+1. **Persona paragraph** (≤ 80 words) — who this role is for, in the role's own language.
+2. **Three first tasks** — each a single sentence + the prompt name (`prompts/<name>.md`) that bootstraps it.
+3. **Recommended pack list** — referenced from frontmatter, expanded with one-line rationale per pack.
+
+## Prompt frontmatter (required)
+
+Each `prompts/<name>.md` carries:
+
+```yaml
+---
+name: <kebab-case-id>            # unique within the role's prompts/ folder
+intent: "One sentence: what the user gets out of this prompt."
+inputs:
+  - name: customer_brief
+    required: true
+    shape: "free-text paragraph"
+  - name: tone
+    required: false
+    shape: "one of [neutral, warm, urgent]"
+output_shape: "Markdown — H2 sections, ≤ 600 words, structured offer."
+skill_hint: refine-prompt        # which skill the host should foreground; cites existing skill
+---
+```
+
+The body is the parameterised prompt itself, with `{{input_name}}` placeholders the launcher fills before sending to the host model. Bodies stay ≤ 200 lines; prompts longer than that get split.
+
+## `skills.yml` shape
+
+```yaml
+# Priority-ordered. The launcher surfaces the first 5 in its default view; the rest go behind "more".
+skills:
+  - id: refine-prompt
+    why: "Tightens fuzzy customer briefs before any drafting."
+  - id: voice-and-tone-design
+    why: "Locks the role's voice so emails read consistent across customers."
+  - id: doc-coauthoring
+    why: "Section-by-section drafting flow for longer offers."
+```
+
+Every `id` must resolve to an existing skill under `packages/<pack>/.agent-src.uncompressed/skills/<id>/SKILL.md` — verified by the lint pass in Phase 3 Step 6.
+
+## Versioning + status
+
+- `status: draft` — scaffold only, no recruit-session evidence yet. Launcher hides drafts in the default view.
+- `status: beta` — scaffold + at least one recruit session backs the first-task choice. Launcher surfaces with a `beta` badge.
+- `status: stable` — at least two recruit sessions concurred on the role's first tasks and the friction-inventory landed at ≤ 3 P0 items.
+
+Status promotion is a maintainer decision, captured in the `recruit_session_ref` frontmatter trail. Demotion (stable → beta) happens when a follow-up recruit session contradicts the existing first-task choice.
+
+## Lint pass (deferred to Phase 3 Step 6)
+
+The lint pass (`task lint-role-experiences`, wired into `task ci`) asserts:
+
+1. Every `agents/roles/<role>/index.md` has all required frontmatter keys + at least 3 first tasks.
+2. Every `prompts/<name>.md` has the four required frontmatter keys (`name`, `intent`, `inputs`, `output_shape`) plus `skill_hint`.
+3. Every `skills.yml#skills[].id` resolves to an existing skill.
+4. Every `recommended_packs[]` entry resolves to an existing pack manifest.
+5. Status promotion never happens without a non-null `recruit_session_ref`.
+
+Lint pass code lives at `scripts/lint_role_experiences.py`, ≤ 200 LOC. Until the lint pass ships, the scaffolds in Phase 3 Steps 2–4 are hand-validated against this contract.
+
+## Open questions (Phase 3 optional council pass)
+
+- Per-role default model — should `index.md` carry a `default_model` frontmatter key the launcher honours, or stay at the host's global default? Default in this contract: stay at host default; per-role override is a future ADR.
+- Prompt input typing — should `inputs[].shape` be free-text or constrained to a small enum (`text`, `enum`, `file-path`, `url`)? Default: free-text; constraint enum is a future tightening.
+- Multi-language prompt bodies — German vs English by role? Default: prompt bodies follow the language policy of the package (English); the host translates at runtime per `language-and-tone`.

package/docs/contracts/workspace-documents.md

@@ -0,0 +1,140 @@
+# Workspace Documents Contract
+
+> **Status** · v0 / design · 2026-05-24. Phase 5 of the
+> employee-product workstream.
+> Builds on the [`daily-workspace`](daily-workspace.md) surface and
+> the host-agent protocol from
+> [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md). Documents
+> are the **output shape** of selected launcher prompts.
+
+## When a launcher prompt produces a document
+
+A launcher prompt is **document-shaped** when its frontmatter sets
+`output_shape: document`. Otherwise the prompt is **chat-shaped**
+(default) — the host reply lands in the session JSONL log only.
+
+```yaml
+# agents/roles/galabau/prompts/angebot-erstellen.md
+---
+title: Angebot erstellen
+output_shape: document
+document_type: offer
+slug: from_title
+---
+```
+
+Recognised `document_type` values (v0): `offer`, `mail-draft`,
+`memo`, `brief`, `video-script`. Unknown types are rejected at
+launcher-load time with a banner; the prompt falls back to
+chat-shaped.
+
+## Storage layout
+
+```
+~/.event4u/agent-config/workspace/documents/
+├── offer/
+│   ├── kundeX-angebot-2026-05-24.md          ← body
+│   └── kundeX-angebot-2026-05-24.history.jsonl ← per-save revision log
+├── mail-draft/
+├── memo/
+├── brief/
+└── video-script/
+```
+
+Slug rules: kebab-case ASCII; deduped by appending `-2`, `-3`, …;
+filename never contains PII. Slug default = `slugify(title) + "-" + iso-date`.
+
+## Document frontmatter
+
+```markdown
+---
+type: offer
+title: Angebot Kunde X
+created_at: 2026-05-24T12:08:00Z
+last_edited_at: 2026-05-24T12:14:00Z
+source_prompt: agents/roles/galabau/prompts/angebot-erstellen.md
+source_session: 20260524T120800Z-a1b2c3d4
+role: galabau
+tags: [kunde-x, gartenbau, 2026-q2]
+schema: workspace-document/v0
+---
+
+[document body — Markdown, host-generated, user-edited]
+```
+
+`source_prompt` + `source_session` form the provenance pair: every
+document points back to the prompt that produced it and the session
+that ran it. The session JSONL stays in the session store; only the
+**reference** lives here.
+
+## Revision log
+
+Path: `<slug>.history.jsonl`. Append-only. One entry per save.
+
+```json
+{
+  "ts": "2026-05-24T12:14:00Z",
+  "actor": "user",
+  "kind": "save",
+  "delta": { "added": 12, "removed": 4 },
+  "body_sha256": "ab12…"
+}
+```
+
+Actor `host` marks the initial-creation save (from the host agent's
+reply). Actor `user` marks every subsequent edit. No body in the
+log — only the SHA. The body lives in the `.md` file; rollback walks
+the SHA chain and reconstructs from a tracked-base + delta is
+**deferred** to v1 (v0 keeps only the latest body).
+
+## Export
+
+| Format | How | Notes |
+|---|---|---|
+| Markdown | identity copy of `<slug>.md` | always available |
+| PDF | `markitdown` reverse path (preferred), `pandoc` fallback | requires `pandoc` on PATH for fallback |
+| DOCX | `pandoc <slug>.md -o <slug>.docx` | requires `pandoc` on PATH |
+
+Export target: user picks a folder via the OS picker. No autosave to
+cloud, no upload, no remote backend. Export failures surface as a
+banner; partial files are not left behind.
+
+## Workspace integration
+
+- Phase 4 right-rail "Recent documents" list shows ≤ 20 most-recent
+  entries scoped to the current role; click → opens the body in the
+  user's default Markdown editor.
+- The workspace **centre pane** for a document-shaped session shows
+  the document body live (read-only) plus a "Edit" button that
+  hands off to the OS default `.md` editor.
+- Closing the workspace does not lock the document file — it stays
+  user-editable.
+
+## Failure modes
+
+- Host CLI returns a non-document reply for a document-shaped prompt
+  → workspace stores the raw text under `<slug>.md` with a
+  `quarantine: true` frontmatter flag; UI shows a one-line banner.
+- Disk full → red banner, no silent body loss.
+- Frontmatter parse failure → revision log still appends a
+  `kind: save_failed` record; user's working file is preserved
+  alongside as `<slug>.broken.md`.
+
+## Coverage requirements (Phase 5 Step 6)
+
+- Golden tests on the export rendering: 3 fixture documents × 3
+  export formats (Markdown / PDF / DOCX). Fixtures under
+  `tests/golden/workspace-documents/`.
+- Schema-validation tests on the frontmatter contract using
+  `tests/fixtures/workspace-documents/valid/` and `invalid/`.
+- ≥ 80 % branch on save + history-append paths.
+
+## Cross-references
+
+- [`daily-workspace`](daily-workspace.md) — workspace shell that
+  hosts the document view.
+- [`host-agent-protocol`](host-agent-protocol.md) — how the document
+  body is produced.
+- [`local-knowledge-ingestion`](local-knowledge-ingestion.md) —
+  sources cited inside documents.
+- ADRs: [`023`](../decisions/ADR-023-host-agent-protocol.md), [`024`](../decisions/ADR-024-workspace-v0-feature-floor.md), [`025`](../decisions/ADR-025-workspace-chrome.md).

package/docs/decisions/ADR-022-daily-workspace-decomposition.md

@@ -0,0 +1,140 @@
+---
+adr: 022
+status: accepted
+date: 2026-05-24
+decision: daily-workspace-decomposition
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-022 — Daily workspace — decomposition
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 4 Step 1 of
+[`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+Records the council's verdict on the original "workspace shape"
+question — that the question was malformed — and replaces a single
+chrome decision with three sequenced sub-decisions.
+
+The numeric reservation note in
+[`ADR-021`](ADR-021-deployment-shape.md) (ADRs 022–025 held for the
+internal-AI-OS-deployment roadmap) is retired: that roadmap is
+archived ([`agents/roadmaps/archive/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/archive/road-to-internal-ai-os-deployment.md))
+and the active strategy after release `3.1.1` is the
+employee-product / external-proof roadmap. ADR-022 claims the
+number under the new strategy.
+
+Companion artefacts:
+
+- Roadmap: [`agents/roadmaps/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md)
+- Council question: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Council verdict: `agents/runtime/council/responses/daily-workspace-shape.json` (gitignored)
+- Predecessor ADRs: [`ADR-014`](ADR-014-gui-framework-choice.md) (installer chrome), [`ADR-016`](ADR-016-installer-architecture.md) (installer architecture), [`ADR-020`](ADR-020-global-only-consumer-scope.md) (consumer scope).
+
+## Context
+
+Phase 4 of the post-`3.1.1` roadmap proposes a persistent daily
+workspace — left rail (role + task launcher), centre pane (active
+conversation with the host agent), right rail (knowledge sources +
+explain-trace) — as the missing daily-use surface for non-developer
+roles (galabau owner, content creator, consultant).
+
+The original Step 1 framed the decision as a four-way chrome pick:
+extend the GUI installer · separate Electron/Tauri app · browser tab
+· TUI-first. The council was asked to choose one.
+
+## What the council said
+
+Both council members (claude-sonnet-4-5, gpt-4o) **rejected the
+question as malformed** after a two-round debate. The convergent
+verdict, in their own words:
+
+> *"The ADR masquerades as a UI choice when it is actually three
+> entangled, unsequenced decisions: (1) the protocol boundary to
+> host agents, (2) the v0 feature scope that validates 'non-developers
+> prefer this', (3) the chrome that wraps that scope."*
+> — Anthropic
+
+> *"Without a stable, documented protocol between the workspace and
+> host agents, the ADR's proposition lacks substance and could be
+> shelved until a reliable, documented, and tested protocol is
+> defined."* — OpenAI
+
+The load-bearing critique is that the workspace contract requires
+two capabilities the host agents (Claude Code, Augment, Cursor,
+Cline, Windsurf) have not been confirmed to expose:
+
+1. A stable RPC / IPC surface for **launching a conversation with a
+   pre-filled prompt + pre-selected skill** (not just CLI flags that
+   drift per Hyrum's Law).
+2. Structured **explain-trace emission** (not "parse stdout and hope").
+
+Until both are proven for at least one host agent, no chrome option
+can be implemented — each inherits the same fatal coupling risk.
+
+## Decision
+
+Split Phase 4 Step 1 into three sequential sub-decisions, each its
+own ADR:
+
+1. **ADR-023 — Host-agent protocol contract** *(blocking)*. Inventory
+   the surface each named host agent exposes today, name the
+   fallback for missing surfaces, write `docs/contracts/host-agent-protocol.md`.
+   Status today: **drafted, not started**.
+2. **ADR-024 — Workspace v0 feature floor** *(depends on ADR-023)*.
+   Define the minimum viable shell that recruit-session participants
+   can evaluate. Pare back from "left rail + centre pane + right rail"
+   to whatever the protocol from ADR-023 can actually drive end-to-end.
+3. **ADR-025 — Workspace chrome** *(depends on ADR-024)*. The original
+   four-way pick (installer-extension · Electron/Tauri · browser tab ·
+   TUI), narrowed by what ADR-024 needs and what ADR-023 makes
+   feasible.
+
+The roadmap is updated accordingly: Phase 4 grows two new gating
+steps (ADR-023 + ADR-024) ahead of the chrome decision. The
+"≤ 6 weeks for one engineer" budget assumption from the original
+roadmap is preserved as a working figure — both council members
+flagged it as ambitious. ADR-024 will tighten it.
+
+## Consequences
+
+**Positive**
+
+- The blocking risk (host-agent protocol feasibility) is surfaced
+  as its own ADR with its own go/no-go gate, not buried under a
+  chrome debate.
+- Phase 4 cannot accidentally ship a chrome built on an unproven
+  integration substrate.
+- Recruit sessions (Phase 1) get a clearer signal of *what* to
+  validate: "does the v0 feature floor solve the daily-use gap?"
+  rather than "do you prefer this UI?"
+
+**Negative**
+
+- Phase 4 ships two additional ADRs before any code lands. Adds
+  governance overhead; the autonomous-execution rule narrows the
+  ask-tax but doesn't remove it.
+- The chrome decision (ADR-025) is deferred at least one council
+  round behind ADR-023 + ADR-024.
+
+**Reversal cost** — low. If ADR-023 proves the protocol is trivially
+stable, ADR-024 can collapse to a one-line "we re-adopt the
+original v1 scope" decision and ADR-025 proceeds against the
+original four-way pick.
+
+## Open questions (next-ADR-deferred)
+
+- Whether the host-agent protocol investigation should be
+  council-gated again or treated as a research artefact (ADR-023
+  will say).
+- Whether "host agent" remains plural or narrows to one supported
+  host for v0 (ADR-024 will say).
+
+## Cross-references
+
+- Council question file: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Role identity scaffolds (Phase 3 output): [`agents/roles/`](../../agents/roles/)
+- Knowledge-ingestion contract (Phase 2 input): [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md)

package/docs/decisions/ADR-023-host-agent-protocol.md

@@ -0,0 +1,129 @@
+---
+adr: 023
+status: accepted
+date: 2026-05-24
+decision: host-agent-protocol
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-023 — Host-agent protocol — CLI shell-out, three-tier fallback
+
+## Status
+
+**Accepted** · 2026-05-24. First of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md). Locks the
+protocol boundary between the daily workspace and the host agents
+(Claude Code, Codex, Gemini, Augment, Cursor, Cline, Windsurf,
+others). ADR-024 and ADR-025 follow this decision.
+
+Companion artefacts:
+
+- Contract: [`docs/contracts/host-agent-protocol.md`](../contracts/host-agent-protocol.md)
+- Council question: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Predecessor ADR: [`ADR-022`](ADR-022-daily-workspace-decomposition.md)
+
+## Context
+
+The council critique on the original Phase 4 chrome question
+identified the host-agent protocol as the blocking unknown. The
+workspace must (a) launch a conversation in the host with a
+pre-filled prompt and (optionally) a pre-selected skill, and (b)
+read structured tool / model output back without parsing the host's
+UI. Either capability missing forces the workspace into "render a
+banner and ask the user to paste" territory.
+
+The inventory in `host-agent-protocol.md` enumerates what each
+named host agent exposes today. The convergent finding:
+
+- **Claude Code, Codex, Gemini** — first-party CLIs with documented
+  stdin / stdout JSON envelopes. Both surfaces present, with caveats.
+- **Augment, Cursor, Cline, Windsurf** — IDE / extension hosts. Hook
+  trampolines exist for post-event observation but neither surface
+  exists at the protocol layer.
+
+No vendor-stable RPC, MCP-driven agent control, or shared SQLite
+exists across this set. Building against any single non-CLI host
+locks the workspace to one IDE; building against the CLI set covers
+the most users without vendor coordination.
+
+## Decision
+
+Adopt a **CLI shell-out protocol** as the workspace's only
+host-agent integration mechanism in v0, with a **three-tier**
+fallback policy:
+
+### Tier 1 — first-class CLI host
+
+Workspace spawns `claude -p "<prompt>" --output-format json` (or the
+Codex / Gemini equivalent) as a subprocess. The JSON envelope is the
+contract; parsing is by named keys; session id is preserved across
+turns. Claude Code is the only Tier-1 host with a stable
+skill-resolution surface today.
+
+### Tier 2 — degraded CLI host
+
+Reserved for hosts that gain one of the two surfaces but not both
+(e.g. launch with no trace, or trace with no launch). No host
+occupies this tier today; the slot exists so vendor changes don't
+force a binary tier 1 / tier 3 reclassification.
+
+### Tier 3 — observe-only host (inbox handoff)
+
+For hosts without either surface (Augment, Cursor, Cline, Windsurf,
+JetBrains, others), the workspace writes the rendered prompt + skill
+context into `~/.event4u/agent-config/workspace/inbox/<id>.md` and
+surfaces a one-line copy-to-clipboard banner. The user opens the
+host themselves. No tighter integration is attempted in v0. Hook
+trampolines (`scripts/hooks/*-dispatcher.sh`) remain available for
+passive recording but do not initiate conversations.
+
+### Stability & fail-closed
+
+A host-agent CLI release that breaks the JSON envelope demotes the
+host to Tier 3 with a workspace banner until
+[`host-agent-protocol.md`](../contracts/host-agent-protocol.md) is
+updated. No silent stdout reparse, no positional-key fallback.
+
+## Consequences
+
+**Positive**
+
+- The workspace can ship against the existing CLI surface today; no
+  vendor coordination required.
+- Tier-3 hosts get a documented, honest fallback rather than a
+  half-built integration that breaks under the next vendor release.
+- The protocol surface is small enough to test end-to-end in CI
+  (subprocess + JSON parse).
+
+**Negative**
+
+- IDE / extension hosts are second-class until vendors expose a
+  launch / trace surface. The workspace cannot drive Cursor or
+  Augment in v0 except via inbox handoff.
+- Codex and Gemini are Tier 1 but lack skill resolution; the
+  workspace must pre-render skill context into the prompt body.
+  ADR-024 covers this.
+- The session-state model is per-host: closing the workspace mid-turn
+  does not stop the host CLI subprocess.
+
+**Reversal cost** — low at the protocol layer (the contract file is
+single-source); medium at the workspace if features have been built
+against assumed Tier-1 capabilities for hosts that drop a surface.
+
+## Open questions (next-ADR-deferred)
+
+- v0 floor: which features survive in the no-skill-surface case
+  (Codex / Gemini)? ADR-024 will answer.
+- Chrome: does the workspace ship as a browser tab against the
+  installer GUI, an Electron / Tauri app, or a TUI? ADR-025 will
+  answer, informed by what ADR-024 demands.
+
+## Cross-references
+
+- Protocol contract: [`docs/contracts/host-agent-protocol.md`](../contracts/host-agent-protocol.md)
+- Council CLI precedent: [`ai-council` skill](../../.agent-src/skills/ai-council/SKILL.md) — same subprocess + JSON-envelope pattern, in production.
+- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](../contracts/hook-architecture-v1.md) — Tier-3 observe-only surface.
+- Predecessor ADR: [`ADR-022`](ADR-022-daily-workspace-decomposition.md).

package/docs/decisions/ADR-024-workspace-v0-feature-floor.md

@@ -0,0 +1,126 @@
+---
+adr: 024
+status: accepted
+date: 2026-05-24
+decision: workspace-v0-feature-floor
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-024 — Workspace v0 feature floor
+
+## Status
+
+**Accepted** · 2026-05-24. Second of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md), depends on
+[`ADR-023`](ADR-023-host-agent-protocol.md). Locks the minimum
+viable shell that recruit-session participants will evaluate.
+
+## Context
+
+The original Phase 4 roadmap proposed a three-rail workspace (role
+launcher · conversation pane · knowledge-source rail) with persistent
+session history, citations, explain-trace, and per-user document
+store. The council flagged this as unachievable in the stated ≤ 6
+weeks given a single-engineer budget — and observed that the
+recruit-session signal (Phase 1) is not yet collected, so the v0
+scope cannot be over-fitted to assumed user needs.
+
+ADR-023 narrows the host-agent surface to Tier-1 CLI shell-out
+(Claude Code, Codex, Gemini) plus a Tier-3 inbox-handoff fallback.
+The v0 floor must be the smallest surface that exercises both tiers
+end-to-end so the recruit sessions can falsify the workspace
+premise.
+
+## Decision
+
+The v0 ships **three features only**:
+
+### 1. Role-keyed task launcher
+
+- Reads `agents/roles/<role>/skills.yml` + per-role prompts directory.
+- One-click launcher: pick role → pick task → renders the prompt
+  with skill context inlined (so it works on Codex / Gemini too).
+- Routes to the active host:
+  - **Tier 1** → spawns `claude -p` / `codex exec` / `gemini` subprocess
+    per [`ADR-023`](ADR-023-host-agent-protocol.md).
+  - **Tier 3** → writes the rendered prompt into the inbox file and
+    surfaces a copy-to-clipboard banner.
+- No skill execution happens inside the workspace itself.
+
+### 2. Per-user conversation log
+
+- Single append-only JSONL per session at
+  `~/.event4u/agent-config/workspace/sessions/<yyyy-mm-dd>/<session-id>.jsonl`.
+- Captures: launcher input (role, task, rendered prompt), host-agent
+  envelope output (Tier 1) or inbox-handoff marker (Tier 3),
+  timestamps. No PII in filenames. Encryption deferred.
+- No remote sync. No cross-user view. Local-only.
+
+### 3. Knowledge-pane stub
+
+- Reads from the Phase 2 `knowledge:` memory namespace (when
+  populated) and renders source citations *next to* the launcher
+  output. Does **not** parse Tier-1 envelopes for inline citations
+  in v0 — that's a v1 ask.
+- When the knowledge namespace is empty, the pane shows a
+  one-line "no sources yet" message and links to the
+  ingestion contract.
+
+### Hard cuts from the original Phase 4 scope
+
+The following are **deferred** to v1+ and explicitly out of scope
+for v0:
+
+- Inline citations inside the conversation pane.
+- Plain-mode explain-trace (Phase 6 dependency; reads same JSON
+  envelope but is its own surface).
+- Document-store integration (Phase 5; would force a v0 schema
+  decision before recruit sessions inform it).
+- Multi-host concurrency (one host CLI at a time per workspace).
+- Accessibility audit (deferred to post-recruit-session because the
+  chrome decision in ADR-025 changes the surface).
+
+### Budget
+
+- Single engineer, **8 weeks** (revised from the original 6 weeks
+  per the council critique). Stretch goal: 6 weeks if recruit
+  sessions defer the knowledge-pane stub.
+
+## Consequences
+
+**Positive**
+
+- Smallest possible surface that exercises the Tier-1 + Tier-3
+  protocol split. Recruit-session signal is interpretable.
+- Codex / Gemini work end-to-end via inlined skill context — no host
+  is structurally excluded.
+- The three artefacts (launcher, JSONL log, knowledge stub) are
+  testable in isolation and ship-able incrementally.
+
+**Negative**
+
+- Phase 5 (documents) and Phase 6 (plain-mode explain) cannot start
+  until v0 lands. Three months of strict sequencing.
+- "No inline citations" will read as a regression vs the original
+  roadmap pitch; needs to be flagged in recruit-session prep.
+- The inbox-handoff fallback is rough by design; Tier-3 users will
+  feel second-class until v1.
+
+**Reversal cost** — low. The three features are decoupled; any can
+be dropped or expanded without rewriting the others.
+
+## Open questions (next-ADR-deferred)
+
+- The chrome: browser-tab against installer GUI · Electron / Tauri ·
+  TUI-first. ADR-025 answers, informed by what these three features
+  actually need from a UI.
+
+## Cross-references
+
+- Predecessor ADRs: [`ADR-022`](ADR-022-daily-workspace-decomposition.md), [`ADR-023`](ADR-023-host-agent-protocol.md).
+- Knowledge ingestion contract: [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md).
+- Role experience contract: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).
+- Roadmap: [`agents/roadmaps/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md) Phase 4.