@event4u/agent-config 9.7.0 → 9.9.0

package/docs/contracts/cost-profile-defaults.md

@@ -1,110 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# Cost-Profile Defaults — Contract
-
-> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-14
->
-> Normative contract for the **default `rule_loading_tier`** new installs receive.
-> Profile semantics themselves are documented in
-> [`docs/customization.md` § rule_loading_tier](../customization.md) and
-> [`docs/contracts/rule-router.md`](rule-router.md); this file owns only the
-> **default-selection decision** and the rationale behind it.
-
-## Decision
-
-```
-DEFAULT_PROFILE = "balanced"
-```
-
-`scripts/install.py` and `npx @event4u/agent-config init` write
-`rule_loading_tier: balanced` into `.agent-settings.yml` for fresh installs
-unless the user passes `--profile=minimal` or `--profile=full`.
-
-## Profile table
-
-| Profile | Contents | Token footprint | Use when |
-|---|---|---|---|
-| `minimal` | Kernel only (9 always-loaded Iron-Law rules, ≤ 26 k chars) | Lowest | Token-constrained agents (small context windows, free-tier models) or projects that opt out of routing |
-| **`balanced`** *(default)* | Kernel + tier-1 auto-rules (workflow + safety floor) | Medium | Every productized install — the documented "current behaviour superset" |
-| `full` | Kernel + tier-1 + tier-2 (every rule, every guideline-cited skill) | Highest | Teams running large-context models (Opus 4, GPT-5) that want maximum guardrail coverage |
-| `custom` | Ignore profile; every matrix value set explicitly | Variable | Power users tuning per-rule load decisions |
-
-## Why `balanced`, not `minimal`
-
-The kernel-only `minimal` profile predates the tier-1 router. It was the
-correct default while tier-1 was experimental, but four signals now point
-at `balanced`:
-
-1. **Documented intent already says so.** Both
-   `src/config/agent-settings.template.yml` (the source the installer projects
-   from) and `docs/customization.md` describe `balanced` as
-   "default — current behaviour superset". The code default of `minimal`
-   was a drift artifact, not a deliberate stance.
-2. **Productization (Level-6) demands sensible-default-out-of-the-box.**
-   A fresh `npx init` followed immediately by `/work` should engage the
-   full workflow guardrail set — `developer-like-execution`,
-   `verify-before-complete`, `minimal-safe-diff`, `scope-control`.
-   These live in tier-1, not the kernel. With `minimal`, the
-   work-engine runs unanchored against most quality guardrails.
-3. **Decision-engine gates assume tier-1 is present.** The P2.x gates
-   (`min_confidence`, `block_on_risk`, `require_memory_hits`) are
-   harmless under `minimal` but only reach their documented behaviour
-   under `balanced` and above — because the confidence model and
-   risk-classification rules they read live in tier-1.
-4. **Opt-out is cheap, opt-in is invisible.** A team that wants the
-   `minimal` floor flips one YAML value. A team that doesn't know
-   tier-1 exists never finds it. The default should err toward
-   guardrail coverage.
-
-## Opt-out path
-
-Token-budget pressure → flip in `.agent-settings.yml`:
-
-```yaml
-rule_loading_tier: minimal
-```
-
-…or pass `--profile=minimal` to `npx @event4u/agent-config init`.
-No migration is required: removing tier-1 rules from a session has no
-state-machine impact because the kernel carries the Iron-Law floor.
-
-## Drift detection
-
-CI must keep three surfaces in sync:
-
-- `scripts/install.py` — `DEFAULT_PROFILE` constant.
-- `src/config/agent-settings.template.yml` — comment block on the
-  `rule_loading_tier:` key.
-- `docs/customization.md` — cost-profile table default column.
-
-Reviewer guidance: a PR that changes any one of these must touch the
-other two **plus** this file's `Last reviewed:` field. The
-`docs-sync` rule enforces the cross-reference check; a missing update
-trips it.
-
-## Re-review schedule
-
-`re-review: 2026-11-14` (six months out). Triggers for earlier
-re-review:
-
-- Tier-1 rule count drops below 5 (the router would carry too little
-  to justify the load cost).
-- Median `npx init` token cost grows past 40 k for a fresh agent
-  session (then re-evaluate `minimal` as the default).
-- A consumer-project tally shows ≥ 80 % of installs override the
-  default within seven days (the default is wrong for the population).
-
-## Non-goals
-
-- This contract does **not** dictate what tier-1 contains. That belongs
-  to [`rule-router.md`](rule-router.md) and the `kernel-membership.md`
-  contract.
-- It does **not** add a fourth profile. `custom` covers the
-  per-tenant-tuning case; no new tier needed.
-- It does **not** auto-migrate existing installs. Projects already
-  pinned to `minimal` keep `minimal` until a developer edits the file
-  or runs `npx @event4u/agent-config migrate` (which preserves
-  user-set values per [`migration/v1-to-v2.md`](../migration/v1-to-v2.md)).

package/docs/contracts/cost-summary-schema.md

@@ -1,107 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-15
----
-
-# cost-summary schema (`cost-summary/v1`)
-
-Stable JSON contract for inter-tool consumption of cost-tracking data
-emitted by [`scripts/cost_summary.py`](../../src/scripts/cost_summary.py).
-Schema-versioned so downstream consumers can pin and migrate explicitly.
-
-Design reference: the external runtime `scripts/summary.mjs` (upstream cite). Our shape
-diverges to align with the local `agents/cost-tracking/sessions.jsonl`
-fields and the telegraph-suspended-multiplier contract.
-
-## Envelope
-
-```json
-{
-  "schema_version": "cost-summary/v1",
-  "generated_at": "2026-05-16T23:45:00Z",
-  "totals": { ... },
-  "by_session": [ ... ],
-  "by_conversation": [ ... ],
-  "by_model": [ ... ]
-}
-```
-
-| Field | Type | Notes |
-|---|---|---|
-| `schema_version` | string | Pinned to `cost-summary/v1`. Downstream consumers MUST refuse unknown versions. |
-| `generated_at` | string (ISO-8601 UTC, `Z` suffix) | Emit time. |
-| `totals` | object | Lifetime aggregates — see `totals` below. |
-| `by_session` | array | Per `sessionId` row; ordered by `sessionId` ascending. |
-| `by_conversation` | array | Per `conversation_id` row; ordered by `conversation_id` ascending. |
-| `by_model` | array | Per `model` row; ordered by `model` ascending. |
-
-## `totals` shape
-
-```json
-{
-  "sessions": 123,
-  "total_cost_usd": 1.2345,
-  "input_tokens": 100000,
-  "output_tokens": 50000,
-  "telegraph_delta_tokens": 0,
-  "telegraph_multiplier_version": "v1",
-  "telegraph_multiplier_active": false
-}
-```
-
-`telegraph_delta_tokens` is always `0` while
-`telegraph_multiplier_active == false` — see
-[`telegraph-telemetry.md`](telegraph-telemetry.md) for the suspension contract.
-
-## `by_session` / `by_conversation` row shape
-
-```json
-{
-  "key": "<sessionId or conversation_id>",
-  "sessions": 12,
-  "total_cost_usd": 0.4567,
-  "input_tokens": 8000,
-  "output_tokens": 4500,
-  "telegraph_delta_tokens": 0
-}
-```
-
-The `key` field is the grouping identifier; consumers identify the
-group by inspecting which array the row lives in.
-
-## `by_model` row shape
-
-```json
-{
-  "model": "claude-3-5-sonnet-20241022",
-  "sessions": 12,
-  "total_cost_usd": 0.4567,
-  "input_tokens": 8000,
-  "output_tokens": 4500
-}
-```
-
-`by_model` omits telegraph fields — the multiplier is dialect-scoped, not
-model-scoped.
-
-## Stability guarantees
-
-- **Field additions** are **non-breaking**: consumers MUST ignore unknown fields.
-- **Field removals or renames** bump the `schema_version` minor (`v1` → `v2`).
-- **Type changes** bump the major (`v1.*` → `v2.0`).
-- Downstream consumers SHOULD pin to a specific `schema_version` and
-  refuse unknown ones; the pin is the migration boundary.
-
-## Downstream consumers
-
-- `agent-status` skill — surfaces lifetime / current-conversation slice.
-- Future `cost-export-to-monitoring` scripts (deferred; trigger:
-  consumer request) would wrap this JSON to push to Prometheus / OTLP.
-
-## See also
-
-- [`telegraph-telemetry.md`](telegraph-telemetry.md) — defines the
-  `telegraph_*` fields and the suspended-multiplier contract.
-- [`scripts/cost_summary.py`](../../src/scripts/cost_summary.py) — implementation.
-- [`scripts/cost_by_conversation.py`](../../src/scripts/cost_by_conversation.py) — narrower per-conversation lens with the same JSONL source.
-- [`scripts/telegraph_stats.py`](../../src/scripts/telegraph_stats.py) — telegraph-only delta lens with the same JSONL source.

package/docs/contracts/creative-pack-boundary.md

@@ -1,63 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# Creative Pack boundary — video is an optional pack, not core identity
-
-The `ai-video` (Creative) pack is a **bounded, optional** capability: a first-class
-part of the **content creator** experience, never the package's core identity.
-This contract draws the boundary so omitting the pack degrades nothing in the
-engineering / strategy / finance experiences. (`ai-video` ships
-`trust_level_default: experimental`, 10 artefacts.)
-
-## (a) User-facing video artefacts
-
-Surfaced only when the pack is active (the `content_creator` profile, or an
-explicit enable):
-
-- **Commands:** `/video:from-script` · `/video:storyboard` · `/video:scene` ·
-  `/video:stitch` · `/video:from-song` · `/image:create` · `/image:analyse` · `/image:verify`.
-- **Skills:** `video-director` · `character-consistency` · `motion-choreographer` ·
-  `scene-expander` · `song-to-script` · `pixar-storyteller` · `image-creator` ·
-  `image-analyser` (+ `prediction-pool-optimizer`).
-
-## (b) Internal / provider-specific artefacts
-
-Not user-facing; they implement the pipeline and stay inside the pack boundary:
-
-- Provider adapters under `src/scripts/ai-video/adapters/` (openai-images,
-  gemini-veo, kling, higgsfield, sora) + the adapter contract.
-- `provider-lifecycle-discipline` rule + `agents/templates/.ai-video.xml.example`
-  (provider tiers, `<default-video-provider>`).
-- `AIV_DRYRUN=true` cost-safety default; the media-governance policy layer
-  (`agents/settings/policies/media/`) and the `media-sync-ground-truth` /
-  `media-governance-routing` rules.
-
-## (c) Compatibility matrix — what works without the Creative Pack
-
-| Profile | Creative Pack | Without it |
-|---|---|---|
-| `content_creator` | **active** | full video surface |
-| `developer` · `agency` · `ops` · `finance` · `founder` | not included | **no change** — video was never projected |
-
-| Flow | Depends on Creative Pack? |
-|---|---|
-| discovery · implementation · review · delivery | **No** — the four work-flows are engineering journeys; none reference a video command or skill |
-
-**What breaks without it:** nothing in the core surface. The `/video:*` and
-`/image:*` commands are simply absent (graceful — projection-time filtering never
-writes them); no rule, flow, or non-creator profile depends on an `ai-video`
-artefact. The media-governance policy layer is referenced by routing rules that
-stay inert unless a media surface fires, so it does not break either.
-
-**Conclusion:** the Creative Pack is cleanly severable. It enriches the
-`content_creator` experience and is invisible everywhere else — keeping video a
-bounded Creator capability, not the package's identity.
-
-## See also
-
-- [`src/domains/ai-video/pack.yaml`](../../src/domains/ai-video/pack.yaml) — the generated pack manifest (span + trust level).
-- [`profiles.md`](../profiles.md) · [`experiences/content_creator.md`](../experiences/content_creator.md) — where the pack surfaces.
-- [`provider-lifecycle-discipline`](../../src/rules/provider-lifecycle-discipline.md) — the provider-tier rule inside the boundary.
-- ADR-040 — projection-time filtering (the mechanism that makes a pack optional).

package/docs/contracts/cross-repo-retrieval.md

@@ -1,64 +0,0 @@
----
-stability: experimental
----
-
-# Cross-Repo Retrieval Contract
-
-> **Status** · v0 / design · 2026-05-30. Phase 4 of `road-to-leaner-core-and-discovery`.
-> Extends [ADR-032](../decisions/ADR-032-linked-projects-scope.md) **Option A** (passive,
-> read-only, opt-in-per-sibling, no bulk inclusion). Does **not** advance to Option B (auto-scan)
-> or Option C (implicit inclusion).
-
-## Problem
-
-The ADR-032 detector finds IDE-attached sibling repos but today only produces a passive *awareness
-note* — the agent knows a sibling exists but cannot pull context from it. This contract makes opted-in
-siblings a **read-only, targeted retrieval source**: the agent can fetch a shared type, an API contract
-the frontend consumes, or a config the sibling owns, **without bulk-including** its files.
-
-## Scope guards (Option A, non-negotiable)
-
-```
-READ-ONLY. OPT-IN-PER-SIBLING. TARGETED QUERY, NEVER A FULL-TREE SWEEP.
-```
-
-- **Read-only.** No writes to any sibling. Out-of-root writes still pass the host permission gate;
-  this surface never writes.
-- **Opt-in only.** Only siblings with `include: true` in `agents/settings/.agent-settings.local.yml`
-  → `linked_projects[]` are read. A sibling not opted in is never touched.
-- **Targeted query only.** Every retrieval is a bounded path-glob + content grep — never a blind walk.
-  A `large`-flagged sibling (per the detector) **requires a path scope** and rejects an unscoped query.
-- **Bounded.** ≤ `max_chunks` results per query (default 8). One concept per query.
-
-## Retrieval envelope
-
-Each match is returned as:
-
-```json
-{ "source_repo": "<sibling dir name>", "path": "<rel path in sibling>",
-  "chunk": "<≤ 2 KB redacted excerpt>", "freshness": "<git last-commit date or mtime>",
-  "match_reason": "<why this matched: path-glob or content term>" }
-```
-
-`chunk` passes the same redaction floor as `knowledge_ingest.py` — secrets and PII are scrubbed before
-any cross-repo text is surfaced. Cross-repo text never leaks a secret.
-
-## Memory integration — tagged + discounted
-
-Cross-repo matches projected into `memory_retrieve` carry `source: cross-repo` and are scored **below**
-local curated knowledge — the same 0.85× discount the `knowledge:` namespace already applies — so
-cross-repo context never outranks the project's own truth.
-
-## Surfaces
-
-- CLI: `agent-config linked-projects:list` — prints opted-in siblings (`path · detected_via · large`).
-  Closes the ADR-032 follow-up "expose the detector as a CLI subcommand for consumer reach."
-- CLI / agent: `/knowledge:cross-repo <query>` — renders matches as `source_repo · path · freshness · why`.
-  Honours opt-out (a sibling not `include: true` is never read); inert with a clear message when no
-  siblings are opted in.
-
-## Implementation
-
-`scripts/cross_repo_retrieve.py` (≤ 300 LOC). Pure-local, read-only, no network. Reuses the chunking +
-redaction floor from `knowledge_ingest.py`. Coverage: `tests/test_cross_repo_retrieve.py` against
-fixture sibling repos under `tests/fixtures/cross-repo/`.

package/docs/contracts/cross-wing-handoff.md

@@ -1,134 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-
-# Cross-Wing Handoff Contract
-
-> **Status:** active · **Stability:** beta · **Owner:** suite-closure Phase 3
-> · **Lint gate:** `task lint-handoffs` (CI)
-
-The four wings (Engineering, Product+Foundation, GTM+Growth,
-Money+Strategy+Ops) compose by handing off **typed artifacts** between
-senior-tier skills, not by sharing a runtime. This contract locks the
-shape of those handoffs so cognition clusters do not collide and the
-linter can detect drift mechanically.
-
-## § 1 — Purpose
-
-Typed composition across wings prevents three failure modes:
-
-1. **Cognition-cluster collision** — a Wing-3 skill silently re-implements
-   Wing-4 reasoning (e.g. funnel-analysis ad-hoc forecasting); the
-   handoff makes the dependency explicit.
-2. **Tier mismatch** — a senior skill delegates to a non-senior peer,
-   weakening the per-wing authoring floor; the linter blocks this.
-3. **Untyped artifact drift** — caller and callee disagree on the input
-   shape; the contract requires the delegated skill to declare its
-   `## Input` block so the linter can verify call-site compatibility.
-
-## § 2 — Anatomy
-
-A handoff has three named parts:
-
-```
-initiator-skill  →  delegated-skill(input-shape)  →  output-artifact
-   senior-tier         senior-tier                    declared in
-   in wing X           in wing Y (may = X)            delegated-skill's
-                                                      `## Output` block
-```
-
-- **initiator-skill** — the senior-tier skill that triggers the handoff;
-  declares the target in its `## Related Skills` § *WHEN NOT to use this*
-  routing list **or** as a `Composes` line in the procedure.
-- **delegated-skill** — the senior-tier skill that owns the cognition
-  step being handed off; MUST declare a `## Input` block listing the
-  shape the initiator must pass (named fields + 1-line type hint).
-- **output-artifact** — the named artifact from the delegated skill's
-  `## Output` block (e.g. `opportunity-tree.md`, `forecast-band.json`).
-
-A handoff that omits any of the three parts is incomplete and the
-linter rejects it.
-
-## § 3 — Worktree boundary
-
-Each handoff MAY run in a fresh git worktree when invoked through
-[`subagent-orchestration`](../../.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md)
-mode 6 (`do-in-worktrees`). Mode 6 is the state-machine layer — it
-declares when worktree isolation is mandatory (multi-step cross-wing
-chain, each step ≥30 min, branch state would otherwise leak between
-steps) and what handoff shape each step emits / consumes. The
-executor lives in
-[`using-git-worktrees`](../../.agent-src.uncondensed/skills/using-git-worktrees/SKILL.md)
-and
-[`finishing-a-development-branch`](../../.agent-src.uncondensed/skills/finishing-a-development-branch/SKILL.md);
-this contract does not duplicate that runtime.
-
-The boundary is **advisory** for chains that do not opt into mode 6:
-the handoff contract does not force isolation, but every handoff
-MUST not assume shared in-process state with the initiator. Write
-artifacts to disk; never pass live Python objects. Chains that opt
-into mode 6 promote the boundary from advisory to mandatory for the
-duration of the chain.
-
-## § 4 — Lint rules
-
-`scripts/lint_handoffs.py` enforces three rules over the handoff graph
-built from senior-tier skills. The graph is built from the
-`**WHEN to use this**` sub-block of each skill's `## Related Skills`
-section — those links are **composition (delegation) edges**. Links
-under `**WHEN NOT to use this**` are **alternative pointers** (peer
-cognition the user picks instead) and are NOT composition edges:
-mutual `A ↔ B` "use the other instead" pointers are intentional and
-MUST NOT be flagged.
-
-| Rule | Failure code | Description | Sub-block scope |
-|---|---|---|---|
-| **No cycles** | `handoff_cycle` | Composition graph must be a DAG. A→B→A or longer cycles fail. | WHEN-to-use only |
-| **No dangling references** | `handoff_dangling` | Every link must resolve to an existing skill file. | WHEN-to-use **and** WHEN-NOT |
-| **No tier mismatch** | `handoff_tier_mismatch` | A senior skill MAY only reference other senior skills (delegate to OR offer as alternative). | WHEN-to-use **and** WHEN-NOT |
-
-Optional rule (warning only, locked in Phase 6):
-
-| Rule | Code | Description |
-|---|---|---|
-| Input shape declared | `handoff_missing_input` | Delegated skill SHOULD declare `## Input`. Warning today; error after Phase 6. |
-
-Lint runs in CI between `task lint-skills` and `task test`. Output
-mirrors `lint_skills` (`file:line:reason`).
-
-## § 5 — Reference chains
-
-Three shipped chains across the suite illustrate the contract:
-
-### W3 launch chain — `positioning-strategy` → `messaging-architecture` → `gtm-launch`
-
-- `positioning-strategy` (H1) owns category framing.
-- `messaging-architecture` (H2) **composes** `positioning-strategy` — primary
-  message + supporting proofs derive from H1's point-of-view output.
-- `gtm-launch` (H3) **composes** `messaging-architecture` plus
-  `release-comms` (unified-senior-roles Block L) — launch sequencing
-  reuses the messaging stack.
-
-### W4 / W3 forecasting chain — `forecasting` → `forecast-accuracy`
-
-- `forecasting` (Wing-4 O2) owns construction cognition (top-down vs
-  bottom-up, confidence-band, retro-loop).
-- O2 ships an interface-first stub (`forecast-construction-shape` ADR)
-  before full implementation — locks the call shape early.
-- `forecast-accuracy` (Wing-3 H10) **composes** O2's interface for the
-  forecast-call loop. Contract drift = O2's break, not H10's.
-
-### W4 build-buy → org-design chain — `build-buy-partner` → `org-design`
-
-- `build-buy-partner` (P1) owns insource-vs-outsource reasoning.
-- `org-design` (Q1) **composes** `build-buy-partner` for insource-vs-
-  outsource shape — team-design follows the build-buy verdict.
-
-## See also
-
-- `.agent-src.uncondensed/rules/skill-quality.md` § Senior-Tier
-  Required Structure — defines the `## Related Skills` and `## Output`
-  blocks the contract reads.
-- `scripts/lint_handoffs.py` — mechanical enforcement.

package/docs/contracts/daily-workspace.md

@@ -1,147 +0,0 @@
----
-stability: experimental
----
-
-# 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/`. Each task inlines its prompt's `inputs` (`{name, required, shape}`) + `skill_hint` (ADR-075) so the GUI builds its input form without a second round-trip. |
-| `POST /api/v1/workspace/launch` | Body: `{ role, task, inputs?, host? }`. Writes a session header; resolves host tier (ADR-068). On a **tier-1** host whose task resolves to a prompt, renders (ADR-069) + drives one turn (ADR-070/071), appending `host.turn`/`host.error`. Tier-3 / drive failure degrades to the inbox hand-off (best-effort). Always 200 with `{driven, turn?\|reason?\|error_kind?, handoff?}`. |
-| `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. |
-| `POST /api/v1/workspace/sessions/:id/continue` | Body: `{ prompt }`. Continues the conversation in the same host session (ADR-076) — records the prompt (`launcher.input` `followup:true`, ADR-083), resumes by the `session_id` on the latest `host.turn` (`--resume`), appends another `host.turn`. 409 if no host turn has run yet; **410** if the host session has expired (ADR-080); same kill-switch gate as launch. |
-| `GET  /api/v1/workspace/knowledge` | Snapshot of the current `knowledge:` memory namespace (read-only). |
-| `POST /api/v1/workspace/render` | Body: `{ role, prompt, inputs }`. Fills `{{name}}` placeholders in `prompts/<prompt>.md`; returns `{ rendered, skill_hint }`. Pure — skill body is **not** appended (ADR-069). Missing-required / undeclared-placeholder → 400. |
-| `GET  /api/v1/workspace/drive-health` | `?host=<id>` for one host, omitted for all. Read-only per-host kill-switch cache (ADR-073/074): `{ consecutive_failures, killed, kill_reason, killed_at, trip_count, total_success, total_failure, … }`. Auto-tripped hosts self-recover via a half-open probe after `AGENT_CONFIG_DRIVE_COOLDOWN_SEC` (default 600 s); manual kills are sticky. Fails open (missing cache → empty). |
-| `GET  /api/v1/workspace/hosts` | Tier-1 host availability for the picker (ADR-079): `{ hosts: [{ id, cli_present, effective_tier }] }` (claude-code / codex / gemini). Side-effect-free PATH probe. Fails open (`[]`). |
-| `POST /api/v1/workspace/drive-health/:host/reset` | Clears a host's kill-switch (ADR-081) → `{ host, state }`. Operator escape hatch (and the only path for a sticky manual kill). 400 on an invalid host id. |
-
-## 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 }` (opening); a follow-up turn appends `{ role, task, prompt, followup: true }` (ADR-083)
-- `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
-
-- **Boundary:** [`workspace-boundary`](workspace-boundary.md) — what the workspace owns vs. does **not** own ([`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md)), enforced by the import-edge linter.
-- 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).