@event4u/agent-config 3.1.1 → 3.2.0

package/docs/decisions/ADR-025-workspace-chrome.md

@@ -0,0 +1,119 @@
+---
+adr: 025
+status: accepted
+date: 2026-05-24
+decision: workspace-chrome
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-025 — Workspace chrome — browser tab against the installer GUI
+
+## Status
+
+**Accepted** · 2026-05-24. Third of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md), depends on
+[`ADR-023`](ADR-023-host-agent-protocol.md) (protocol) and
+[`ADR-024`](ADR-024-workspace-v0-feature-floor.md) (feature floor).
+Picks the UI shape that wraps the v0 feature floor.
+
+## Context
+
+The original Phase 4 question framed chrome as a four-way pick:
+
+| Option | Pitch |
+|---|---|
+| **(a) Extend installer GUI** | Reuse `packages/core/installer/src/gui/`, add workspace routes. Same loopback server, same CSRF gate, same browser. |
+| **(b) Electron / Tauri desktop app** | Native shell, OS integration (tray icon, hotkeys, autostart). |
+| **(c) Browser tab against the installer GUI** | Same as (a) on the runtime side, but framed as a standalone surface (`/workspace`) the user bookmarks. |
+| **(d) TUI-first** | Terminal UI, optional browser companion. Lowest install footprint. |
+
+The council demanded ADRs 023 and 024 land first. With those in
+place: the v0 surface is three small features (launcher, JSONL log,
+knowledge stub) talking to a CLI subprocess. There is no need for
+OS-level integration, no native APIs to call, no real-time low-latency
+rendering. The installer already ships a loopback HTTP + CSRF +
+browser-launch path ([`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md)).
+
+## Decision
+
+Ship workspace v0 as **(c) — a browser tab against the installer
+GUI**.
+
+Concretely:
+
+- New route group `/workspace` inside the existing
+  `packages/core/installer/src/gui/server.ts` Node server (single
+  process, single CSRF token, same loopback bind).
+- `npx @event4u/agent-config workspace` opens the browser at the
+  `/workspace` route — same launch UX as `init --gui`, different
+  default landing page.
+- Per-user state lives under `~/.event4u/agent-config/workspace/`
+  (sessions JSONL + inbox files per ADR-024).
+- The installer GUI and the workspace UI **share the same shell**
+  (header, identity strip, theme) so a user installing for the
+  first time sees the workspace as the natural next surface.
+
+### Why this option
+
+- **(c)** is the only option that reuses the proven loopback +
+  CSRF + browser-launch path. Zero new infrastructure surface.
+- **(a)** is functionally identical at runtime — the only delta is
+  framing. The framing matters: a user-facing "workspace" needs its
+  own URL and bookmark story. (c) gets that for free.
+- **(b)** Electron / Tauri adds a ~150 MB install, a code-signing
+  story, an autoupdate channel, and a native event loop. None of
+  that is needed for the v0 floor; deferred to v1 if recruit
+  sessions surface OS-integration demand.
+- **(d)** TUI-first is intriguing for the developer audience but
+  excludes the non-developer roles (galabau owner, content creator,
+  consultant) named in Phase 1 — the audience this roadmap is for.
+
+### Hard rule: no chrome rewrite without recruit-session signal
+
+The chrome choice does **not** survive the recruit sessions
+silently. If Phase 1 (recruit sessions) surfaces a hard "browser
+tabs are wrong" signal from ≥ 2 of the 3 cohorts, this ADR is
+superseded by a new ADR-027 before any further work on the chrome.
+A maintainer note (not a vendor lock-in) ensures the rewrite can
+happen at v0.5, not v2.
+
+## Consequences
+
+**Positive**
+
+- Zero new infrastructure. Installer GUI is the substrate.
+- Cross-platform for free (browser).
+- One CSRF / port / bind story across installer + workspace —
+  one audit surface, one threat model.
+
+**Negative**
+
+- No native OS hooks (tray icon, global hotkey, autostart). Users
+  must manually run `npx ... workspace` to open the tab.
+- Browser-tab UX has a "where did my workspace go?" failure mode
+  when the tab is closed. Mitigated by a persistent bookmark and a
+  reopen-on-launch flag in `.agent-settings.yml`.
+- Electron / Tauri loyalists will read this as conservative; the
+  v1 ADR can reopen if signal supports it.
+
+**Reversal cost** — medium. Migrating from browser-tab to native
+requires re-implementing the shell and the asset bundling pipeline,
+but the underlying state model (filesystem JSONL + inbox) is shell-
+agnostic.
+
+## Open questions (post-recruit-session)
+
+- Tray-icon / autostart story (Phase 1 + Phase 4 v0.5 — defer).
+- Multi-tenant browser surface for the deployed `agent-config`
+  topology (covered by [`ADR-021`](ADR-021-deployment-shape.md);
+  v0 is single-user local only).
+
+## Cross-references
+
+- Predecessor ADRs: [`ADR-022`](ADR-022-daily-workspace-decomposition.md), [`ADR-023`](ADR-023-host-agent-protocol.md), [`ADR-024`](ADR-024-workspace-v0-feature-floor.md).
+- GUI wizard substrate: [`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md).
+- Installer architecture: [`ADR-016`](ADR-016-installer-architecture.md).
+- Deployment shape: [`ADR-021`](ADR-021-deployment-shape.md).

package/docs/decisions/ADR-026-explain-mode-translation.md

@@ -0,0 +1,117 @@
+---
+adr: 026
+status: accepted
+date: 2026-05-24
+decision: explain-mode-translation
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 6
+type: forward-looking
+---
+
+# ADR-026 — Explain-mode translation — plain as a renderer, not a new pipeline
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 6 design. Depends on the existing
+`explain-v1` envelope shape stabilized in `agent-memory` 3.0 and the
+workspace surface from [`ADR-025`](ADR-025-workspace-chrome.md).
+
+## Context
+
+Feedback A names the technical explain-trace as a non-technical-employee
+barrier. Today the right rail shows `trust_score: 0.74`,
+`promotion_history: [...]`, `contradictions: 0` — vocabulary that
+assumes the reader knows the memory model. For galabau, content-creator,
+and consultant roles, this is opaque.
+
+Two options surveyed:
+
+| Option | Pitch | Cost |
+|---|---|---|
+| **(a) Second MCP surface** | Add `memory_explain_plain` returning a pre-translated envelope. | New endpoint, new schema, drift risk between two surfaces, requires MCP version bump. |
+| **(b) Renderer over existing envelope** | Treat plain mode as a pure rendering function over the existing `explain-v1` envelope. Per-role glossary overrides labels. | Zero MCP change, zero data drift, zero schema bump. Renderer testable with fixtures. |
+
+## Decision
+
+Ship Phase 6 plain mode as **(b) — a pure renderer over the existing
+`explain-v1` envelope**.
+
+Concretely:
+
+- `renderExplain(envelope, { mode, glossary?, locale? })` is a pure
+  function in `packages/core/src/workspace/explain/`.
+- Two modes: `technical` (current surface, verbatim) and `plain`
+  (4 labelled paragraphs: where from, how confident, when reviewed,
+  what's contested).
+- 4-band confidence label (Very High / High / Medium / Low) with
+  default thresholds per [`docs/contracts/explain-modes.md`](../contracts/explain-modes.md);
+  thresholds overridable per role.
+- 3-band freshness label (Fresh / Aging / Stale) from `decay.applied_factor`.
+- Per-role `agents/roles/<role>/explain-glossary.yml` overrides
+  default labels and band thresholds. Glossary YAMLs are the
+  one carve-out from the `.md`-must-be-English rule for role-native
+  rendered strings.
+- `/why` quick command available to every role; resolves `mem://<id>`
+  markers in the last reply and calls `memory_explain` per id, then
+  renders in the active mode.
+
+## Why (b)
+
+- **Zero MCP drift.** One envelope, two views. No risk of plain
+  text saying something the engineer view contradicts.
+- **Testable.** Pure function over fixtures. Golden tests cover
+  high-trust, low-trust, contradicted, recently-promoted, deprecated.
+- **No version bump.** `agent-memory` MCP surface stays at the
+  current contract; consumers running older clients still see the
+  technical envelope unchanged.
+- **Glossary carve-out is bounded.** Only the `explain-glossary.yml`
+  per role holds runtime strings in role-native language; the
+  contract `.md`, the ADR, the renderer code stay English.
+
+## Why not (a)
+
+- A second MCP endpoint duplicates the envelope shape and creates
+  two surfaces that must stay in sync. Drift will land within one
+  release.
+- Schema bump on `agent-memory` cascades to every downstream package
+  consuming the MCP; Phase 6 is not the right time to force that.
+
+## Consequences
+
+**Positive**
+
+- Plain mode lands as a renderer change, no MCP version bump.
+- Per-role glossary opens the door for the recruit-session
+  participants (Phase 1) to localize the plain surface without a
+  code change.
+- Technical mode survives unchanged for engineering-lead role.
+
+**Negative**
+
+- Plain mode is downstream of envelope shape; an `explain-v2`
+  envelope (next major) requires updating the renderer too. Cost
+  is bounded — the renderer is one file.
+- Glossary localization can drift from English defaults if a role
+  ships a partial override. Mitigated by the renderer falling back
+  to defaults for missing keys.
+
+**Reversal cost** — low. Replacing (b) with (a) later if the
+renderer surface grows beyond pure rendering (e.g. needs a different
+data fetch) requires only adding the second MCP endpoint; existing
+glossary YAMLs translate forward.
+
+## Open questions (deferred)
+
+- Localization of the technical view (today: English only). Out of
+  scope for v0; deferred until ≥ 1 recruit-session participant
+  asks for it.
+- Audio / spoken-mode rendering of the plain envelope for the
+  consultant-on-the-road role. Defer to a future ADR.
+
+## Cross-references
+
+- Contract: [`docs/contracts/explain-modes.md`](../contracts/explain-modes.md).
+- Envelope: [`docs/contracts/agent-memory-contract.md`](../contracts/agent-memory-contract.md).
+- Workspace: [`ADR-025`](ADR-025-workspace-chrome.md), [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
+- Roles: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).

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

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

package/docs/deploy/team-deployment-posture.md

@@ -0,0 +1,91 @@
+# Team Deployment Posture
+
+> **Status** · v0 · 2026-05-24. Phase 9 of
+> [`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+> Codifies what is shipped today, what stays cancelled-with-reason,
+> and what is reachable via existing primitives — so feedback rounds
+> 9+ asking "team SSO when?" land on a written answer.
+
+## Where agent-config sits today
+
+| Surface | Status |
+|---|---|
+| Single-user workspace | **Shipped** (Phases 4–7 of this roadmap, single-user / single-machine) |
+| Small-team via shared overrides | **Shipped** (existing primitives — see [`small-team-recipe`](small-team-recipe.md)) |
+| Organization mode (SSO, central policy, OAuth connectors) | **Cancelled-with-reason** — tracked in successor roadmap stubs |
+
+## Shipped — what works today
+
+The phases below this section, once implemented, deliver:
+
+- A daily workspace browser tab (Phase 4) — per-user, local-only.
+- Document workflows (Phase 5) — offer / mail / memo / brief /
+  video-script with local revision history and export.
+- Plain explain mode (Phase 6) — role-aware translation of the
+  memory-trust surface.
+- Local analytics (Phase 7) — top prompts, completion rate,
+  session length; never leaves the machine.
+- At-rest encryption (Phase 8) — AES-256-GCM with OS keyring,
+  default on from workspace v1.0.
+
+All of these run on **one machine, one OS user, one workspace**. No
+remote backend. No shared state. No sign-on screen.
+
+## Reachable via existing primitives — small-team mode
+
+A team of 3–10 people can use the package collaboratively today
+without any code change, by leaning on three existing primitives:
+
+| Primitive | What it gives the team |
+|---|---|
+| `agents/overrides/` repo, shared via git | Shared prompts, role experiences, glossaries, skills overrides |
+| Knowledge ingestion from a shared NAS / SharePoint mount | Each user runs `/knowledge:ingest` against the same mount; per-user index, same content |
+| Manual prompt-pack distribution via npm `@event4u/agent-config-<team>` | Team publishes a thin pack of role experiences as a private npm package |
+
+The recipe lives in [`small-team-recipe`](small-team-recipe.md).
+
+## Cancelled-with-reason — organization mode
+
+The prior archived `road-to-internal-ai-os-deployment.md` Phases 2–5
+were cancelled under Hard-Floor (no real first customer, no audit
+funding, no recruit-session signal). Phase 9 **does not reactivate
+them**. The cancellations stand:
+
+| Cancelled surface | Reason | Successor roadmap (stub) |
+|---|---|---|
+| **SSO / OIDC sign-on** | No customer requires it. Auth surface is auth-adjacent — `engineering-safety-floor` Hard-Floor on adoption without a funded security audit. | `road-to-team-sso.md` |
+| **Central policy enforcement** | Multi-tenant policy without SSO is a half-solution. Wait for SSO. | `road-to-central-policy.md` |
+| **Team-shared overrides server** | Shared-overrides-via-git already works for the small-team case. Server only makes sense once the org-mode threshold is reached. | `road-to-team-context.md` |
+| **OAuth connectors (Google, Slack, M365)** | Per-connector OAuth flow is a permanent footprint we can't ship without an org user agreeing to scope it. | `road-to-internal-connectors.md` |
+
+Each successor roadmap is an empty-named stub today; activation
+requires a recruited team customer plus a human-reviewed security
+audit. Until then, the answer to "team SSO when?" is: **not on this
+package, not on this roadmap**.
+
+## Decision posture going forward
+
+- **Default answer to org-mode requests**: point at this document.
+  Do not re-open the cancellation without a recruited customer +
+  funded audit.
+- **Default answer to small-team requests**: point at
+  [`small-team-recipe`](small-team-recipe.md). The recipe is
+  sufficient for 3–10 people, no code change required.
+- **Default answer to single-user requests**: workspace + Phases
+  4–7 deliver the daily experience.
+
+The Hard-Floor item stays in force. Nothing in Phase 9 lifts it.
+The successor roadmap stubs exist so cross-references resolve and
+so a future maintainer (or external contributor with funding) can
+pick them up without re-deriving the cancellation rationale.
+
+## Cross-references
+
+- Recipe: [`small-team-recipe`](small-team-recipe.md).
+- Archived: `agents/roadmaps/archive/road-to-internal-ai-os-deployment.md`.
+- Stubs (created by Phase 9 Step 4):
+  - `agents/roadmaps/stubs/road-to-team-sso.md`
+  - `agents/roadmaps/stubs/road-to-central-policy.md`
+  - `agents/roadmaps/stubs/road-to-team-context.md`
+  - `agents/roadmaps/stubs/road-to-internal-connectors.md`
+- Engineering safety floor: [`.augment/rules/non-destructive-by-default.md`](../../.augment/rules/non-destructive-by-default.md).

package/docs/getting-started-by-role.md

@@ -8,10 +8,14 @@
 
 > **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates.
 
+> **Deployment posture.** Single-user workspace today (one machine, one user — `npx @event4u/agent-config init`). Small team today (3–10 people) via shared `agents/overrides/` Git repo + shared NAS for knowledge — recipe: [`docs/deploy/small-team-recipe.md`](deploy/small-team-recipe.md). Organization mode (SSO · central policy · team context · internal connectors) is **not started** — tracked under [`agents/roadmaps/stubs/`](../agents/roadmaps/stubs/README.md) with explicit gating (recruited customer + funded audit + maintainer ADR). Rationale: [`docs/deploy/team-deployment-posture.md`](deploy/team-deployment-posture.md).
+
 ---
 
 ## Creator (writer, marketer, indie content shop)
 
+> **Tailored role experience available →** [`agents/roles/content-creator/`](../agents/roles/content-creator/index.md) — three first tasks, priority-ordered skill shortlist, prompt scaffolds. Status `draft` until recruit-session 02 lands.
+
 **You want this if:** you draft blog posts, marketing emails, launch copy, or release announcements and want a writing assistant that holds a defined brand voice across surfaces. You need brand-voice discipline more than code-quality enforcement. You will spend most of your time in Claude Desktop / ChatGPT, not in a terminal.
 
 - [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) — define and audit brand voice (voice attributes, tone-by-context matrix).
@@ -30,6 +34,13 @@ Cinematic-blueprint approach: the agent expands your script into a 12-block scen
 
 `AIV_DRYRUN=true` is the mandatory default — no provider call, no spend until you opt in.
 
+**Worked example — one-line idea to stitched cut, four commands:**
+
+1. `/video:from-script "kurzes Werbevideo für ein Galabau-Projekt"` — agent expands the one-line idea into a 12-block blueprint, locks the character identity, and prints the provider-tuned prompt set.
+2. `/video:storyboard` — review the 12-block scene plan before any provider call; edit blocks inline (camera, lighting, blocking, motion) until the storyboard reads as intended.
+3. `/video:scene` — render one scene at a time against the configured provider adapter; iterate on the motion + audio prompt without paying for the full clip.
+4. `/video:stitch` — assemble the rendered scenes into the final clip via ffmpeg, with the character-lock JSON enforcing identity across cuts.
+
 **Try the first win →** [`pack-ai-video/FIRST_WIN.md`](../packages/pack-ai-video/FIRST_WIN.md) — one-line idea to a provider-tuned motion prompt in ~12 minutes.
 
 > **What this is not:** the package does **not** host a video model. It orchestrates prompts against the provider you select (Veo, Kling, Sora, Runway, …). Trust level is set by the provider's adapter lifecycle tier — see [`provider-lifecycle-discipline`](../.agent-src/rules/provider-lifecycle-discipline.md). You pay the provider directly, the package never sees your API key.
@@ -66,6 +77,8 @@ Cinematic-blueprint approach: the agent expands your script into a 12-block scen
 
 ## Consultant (advisory, freelance, fractional)
 
+> **Tailored role experience available →** [`agents/roles/consultant/`](../agents/roles/consultant/index.md) — three first tasks (client-brief refinement, investor memo, deck outline), priority-ordered skill shortlist. Status `draft` until recruit-session 03 lands.
+
 **You want this if:** you sell discovery, positioning, competitive analysis, or roadmap audits. Output is briefs and slide content for a client, not code. You need defensible methodology behind every deliverable.
 
 - [`discovery-interview`](../.agent-src/skills/discovery-interview/SKILL.md) — switch-event JTBD guides, bias audit, falsifiable hypothesis.
@@ -76,6 +89,20 @@ Cinematic-blueprint approach: the agent expands your script into a 12-block scen
 
 ---
 
+## Galabau owner (Garten- und Landschaftsbau, small-business operator)
+
+> **Tailored role experience available →** [`agents/roles/galabau/`](../agents/roles/galabau/index.md) — three first tasks (offer drafting, customer-email reply, project-brief refinement), priority-ordered skill shortlist. Status `draft` until recruit-session 01 lands.
+
+**You want this if:** you run or co-run a small Garten-und-Landschaftsbau shop and draft customer offers, customer emails, and project briefs every week — usually after the on-site day is done. You want a writing assistant that knows your tone, holds it across customers, and turns a one-paragraph project sketch into a structured document you can send the next morning.
+
+- [`refine-prompt`](../.agent-src/skills/refine-prompt/SKILL.md) — tighten fuzzy customer briefs before any drafting so the agent does not invent scope.
+- [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) — lock the shop tone so offers and emails read consistent across customers.
+- [`doc-coauthoring`](../.agent-src/skills/doc-coauthoring/SKILL.md) — section-by-section drafting for longer offers; never one giant generation.
+
+**Install path:** **MCP recommended.** Claude Desktop opens, the package shows up as a tool, no terminal required. See [`docs/mcp.md`](mcp.md). CLI install is the right path only if you also sit in this repo with code-shaped work.
+
+---
+
 ## Go-To-Market (sales, marketing ops, RevOps)
 
 **You want this if:** you own pipeline shape, forecast accuracy, launch sequencing, or post-launch comms. You need deal-level rigor (MEDDIC, exit criteria) and narrative skills (release comms, messaging) in the same agent.

package/docs/getting-started.md

@@ -146,7 +146,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 129 active commands](../.agent-src/commands/)
+→ [Browse all 136 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guides/local-analytics.md

@@ -0,0 +1,125 @@
+# Local analytics — a 3-minute walkthrough
+
+> Phase 7 of [`road-to-employee-product-and-external-proof`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+> Contract: [`docs/contracts/local-analytics.md`](../contracts/local-analytics.md).
+
+## What this is
+
+A **local-only** event log of your workspace activity. The package never
+POSTs these records anywhere. Storage is a single append-only JSONL file
+under your home directory; pruning is a 90-day rolling window.
+
+If you want to know *"which prompts do I actually run on Tuesday
+mornings?"* — this is the file that knows. If you don't want that
+question answered, flip one flag and the file never opens.
+
+## Where it lives
+
+```
+~/.event4u/agent-config/workspace/analytics/
+├── events.jsonl          # one workspace_event/v0 record per line
+└── retention.lock        # presence = a prune pass is running
+```
+
+One event per line. Schema is `workspace_event/v0` (matches the
+3.1.0 telemetry SDK vocabulary, but the transports never touch each
+other — the SDK is the undeployed Worker surface, this is your disk).
+
+## What's collected
+
+Closed event set (rejected if not on the list):
+
+| Event | When |
+|---|---|
+| `launcher.opened`         | Workspace tab opens. |
+| `launcher.task_picked`    | User clicks a task in the launcher. |
+| `launcher.task_launched`  | Host agent receives the rendered prompt. |
+| `session.started` / `session.host_turn` / `session.completed` | Conversation lifecycle. |
+| `document.created` / `document.edited` / `document.exported` | Phase 5 document workflows. |
+| `explain.opened` / `explain.mode_toggled` / `why.invoked` | Phase 6 explain mode. |
+| `knowledge.queried` / `knowledge.source_clicked` | Phase 2 knowledge pane interactions. |
+
+Each record carries a UTC timestamp, the schema version, and a tiny
+`data` dict (role, task, host_tier, duration_ms — never prompt or
+response bodies).
+
+## How to read it
+
+```bash
+# Render the last 30 days as markdown
+python3 packages/core/installer/python/workspace_analytics.py show
+
+# Last 24 h, JSON
+python3 packages/core/installer/python/workspace_analytics.py show \
+    --window 24h --format json
+
+# Filter to one role
+python3 packages/core/installer/python/workspace_analytics.py show \
+    --role tradesperson --format csv
+```
+
+Output shape (markdown):
+
+```
+# Workspace analytics — last 30d
+
+## Top prompts
+
+- `tradesperson` · `estimate` — 12
+- `content-creator` · `script-video` — 7
+- `consultant` · `weekly-memo` — 4
+
+## Launcher → completion rate per role
+
+- `tradesperson` — 83% (12 launched · 10 completed)
+- `content-creator` — 71% (7 launched · 5 completed)
+
+**Average session length:** 3m 41s
+**Knowledge sources clicked:** 14
+```
+
+## How to opt out
+
+Two equivalent switches — either short-circuits before any file opens.
+
+```bash
+# Env (per-shell)
+export AGENT_CONFIG_NO_LOCAL_ANALYTICS=1
+```
+
+```yaml
+# .agent-settings.yml (per-project)
+analytics:
+  local: off
+```
+
+After either is in effect, `emit()` returns `False` and the JSONL is
+never appended. The `show` command still works against existing data,
+so you can opt out without losing what you already have.
+
+## How to delete it
+
+The file is plain JSONL. Delete it:
+
+```bash
+rm -rf ~/.event4u/agent-config/workspace/analytics/
+```
+
+Or prune the rolling window manually:
+
+```bash
+python3 packages/core/installer/python/workspace_analytics.py prune
+# → pruned 47 event(s)
+```
+
+`prune` drops anything older than 90 days. The lock file prevents two
+concurrent passes from racing each other.
+
+## What this guide does not cover
+
+- **Remote telemetry** — that's the Worker SDK (`packages/telemetry/`).
+  Deployment is out of v0 scope; kill-switch defaults to disabled.
+- **Workspace UI** — Phase 4 builds the browser tab that emits these
+  events. See [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
+- **Encryption at rest** — Phase 8. Until then, the JSONL is plaintext
+  on your local disk.