@event4u/agent-config 5.10.1 → 6.1.0

package/docs/skills-taxonomy.md

@@ -0,0 +1,90 @@
+# Skill-family taxonomy
+
+A navigable grouping of the **227 skills** into families, so you can find a skill
+by *what it's for* rather than scrolling the flat [catalog](catalog.md). This is a
+**navigation aid, not a contract** — no file moves, no description edits, no
+merges. A skill appears in exactly one family (its primary use); many are useful
+across families.
+
+> **Derivation (reproducible):** each skill is bucketed by declared `pack:` where
+> present, otherwise by a name/topic pattern. The grouping is heuristic and
+> refinable — when a skill reads better in another family, move the entry.
+> Counts here match the [artefact census](artefact-census.md) (227 skills).
+
+## Engineering
+
+### Backend & data (34)
+`api-design` · `api-endpoint` · `artisan-commands` · `async-python-patterns` · `composer-packages` · `database` · `eloquent` · `form-handler` · `jobs-events` · `laravel` · `laravel-api-endpoint` · `laravel-dto` · `laravel-horizon` · `laravel-mail` · `laravel-middleware` · `laravel-migration` · `laravel-notifications` · `laravel-pennant` · `laravel-pulse` · `laravel-reverb` · `laravel-scheduling` · `laravel-validation` · `laravel-websocket` · `multi-tenancy` · `nextjs-patterns` · `php-coder` · `php-debugging` · `php-service` · `project-analysis-laravel` · `project-analysis-nextjs` · `project-analysis-node-express` · `project-analysis-symfony` · `sql-writing` · `symfony-workflow`
+
+### Frontend & design (15)
+`accessibility-auditor` · `blade-ui` · `canvas-design` · `design-intelligence` · `design-tokens` · `existing-ui-audit` · `fe-design` · `flux` · `livewire` · `livewire-architect` · `project-analysis-react` · `react-native-setup` · `react-shadcn-ui` · `tailwind-engineer` · `ui-component-architect`
+
+### Architecture & refactor (7)
+`code-refactoring` · `dependency-upgrade` · `error-handling-patterns` · `messaging-architecture` · `migration-architect` · `openapi` · `performance`
+
+### Engineering workflow (8)
+`conventional-commits-writing` · `developer-like-execution` · `finishing-a-development-branch` · `git-workflow` · `merge-conflicts` · `quality-tools` · `technical-specification` · `verify-completion-evidence`
+
+### Testing (8)
+`api-testing` · `mobile-e2e-strategy` · `pest-testing` · `playwright-architect` · `playwright-testing` · `test-driven-development` · `test-performance` · `testing-anti-patterns`
+
+### DevOps & infra (7)
+`aws-infrastructure` · `docker` · `github-ci` · `grafana` · `terraform` · `terragrunt` · `traefik`
+
+### Debugging & analysis (12)
+`analysis-autonomous-mode` · `analysis-skill-router` · `bug-analyzer` · `deep-reading-analyst` · `image-analyser` · `performance-analysis` · `project-analysis-core` · `project-analysis-hypothesis-driven` · `project-analysis-zend-laminas` · `project-analyzer` · `systematic-debugging` · `universal-project-analysis`
+
+## Quality & risk
+
+### Review & judging (12)
+`architecture-review-lens` · `authz-review` · `code-review` · `design-review` · `judge-bug-hunter` · `judge-code-quality` · `judge-security-auditor` · `judge-test-coverage` · `privacy-review` · `receiving-code-review` · `requesting-code-review` · `review-routing`
+
+### Security (8)
+`blast-radius-analyzer` · `data-flow-mapper` · `data-handling-judgment` · `defense-in-depth` · `secrets-management` · `security` · `security-audit` · `threat-modeling`
+
+### Operations & reliability (6)
+`dashboard-design` · `incident-commander` · `jira-integration` · `launch-readiness` · `logging-monitoring` · `sentry-integration`
+
+### AI Council & decision (5)
+`adversarial-review` · `ai-council` · `decision-record` · `risk-officer` · `stakeholder-tradeoff`
+
+## Product, growth & business
+
+### Product & discovery (12)
+`activation-design` · `churn-prevention` · `customer-research` · `discovery-interview` · `estimate-ticket` · `feature-planning` · `funnel-analysis` · `onboarding-design` · `po-discovery` · `refine-ticket` · `retention-loops` · `rice-prioritization`
+
+### Strategy (9)
+`build-buy-partner` · `competitive-moat-analysis` · `competitive-positioning` · `contracts-cognition` · `market-entry-analysis` · `okr-tree-modeling` · `positioning-strategy` · `validate-feature-fit` · `vision-articulation`
+
+### Finance (7)
+`dcf-modeling` · `forecast-accuracy` · `forecasting` · `fundraising-narrative` · `runway-cognition` · `scenario-modeling` · `unit-economics-modeling`
+
+### GTM & sales (4)
+`deal-qualification-meddic` · `expansion-playbook` · `gtm-launch` · `pipeline-strategy`
+
+### People & org (7)
+`comp-banding` · `hiring-loop-design` · `onboarding-program` · `one-on-one-cadence` · `org-design` · `perf-feedback-craft` · `throughput-vs-morale-tradeoff`
+
+## Content & media
+
+### Content & writing (7)
+`content-funnel-design` · `doc-coauthoring` · `editorial-calendar` · `release-comms` · `script-writing` · `voc-extract` · `voice-and-tone-design`
+
+### AI video & image (8)
+`character-consistency` · `image-creator` · `motion-choreographer` · `pixar-storyteller` · `prediction-pool-optimizer` · `scene-expander` · `song-to-script` · `video-director`
+
+## Platform & maintenance
+
+### Agent-admin & meta (51)
+The largest family — skills that maintain the package itself (authoring,
+condensation, routing, memory, MCP, prompt tooling). Day-to-day product work
+rarely touches these directly.
+
+`adr-create` · `agent-docs-writing` · `agents-md-thin-root` · `check-refs` · `command-routing` · `command-writing` · `condense-memory` · `context-authoring` · `context-document` · `copilot-agents-optimization` · `copilot-config` · `corpus-grounding` · `description-assist` · `devcontainer` · `file-editor` · `guideline-writing` · `learning-to-rule-or-skill` · `lint-skills` · `markitdown` · `mcp` · `mcp-builder` · `md-language-check` · `memory-consolidation` · `module-detect-on-the-fly` · `module-management` · `override-management` · `persona-writing` · `project-docs` · `prompt-engineering-patterns` · `prompt-optimizer` · `prompt-validator` · `readme-reviewer` · `readme-writing` · `readme-writing-package` · `refine-prompt` · `repomix-packer` · `roadmap-management` · `roadmap-writing` · `rtk-output-filtering` · `rule-refactor` · `rule-writing` · `sequential-thinking` · `skill-improvement-pipeline` · `skill-management` · `skill-reviewer` · `skill-writing` · `subagent-orchestration` · `tech-debt-tracker` · `token-optimizer` · `upstream-contribute` · `using-git-worktrees`
+
+## See also
+
+- [`catalog.md`](catalog.md) — the flat, public capability surface (all types).
+- [`flows.md`](flows.md) — the work journeys these skills compose into.
+- [`profiles.md`](profiles.md) · [`experiences/`](experiences/) — which profiles surface which families.
+- [`artefact-census.md`](artefact-census.md) — the counted baseline (227 skills).

package/docs/ui-track-mental-model.md

@@ -72,7 +72,7 @@ A misclassified `ui-trivial` that grows during edit must reclassify
 A non-empty `state.ui_audit` carrying **at least one of**:
 
 - `components_found` — `[{path, name, kind, similarity?}]` from
-  [`existing-ui-audit`](../.agent-src/skills/existing-ui-audit/SKILL.md).
+  [`existing-ui-audit`](../dist/agent-src/skills/existing-ui-audit/SKILL.md).
 - `greenfield: true` plus `greenfield_decision ∈ {scaffold, bare, external_reference}`.
 - Legacy `components` alias — same shape.
 
@@ -118,4 +118,4 @@ stack ships as a new skill bundle and a recipe — see
 - [`adr-product-ui-track.md`](contracts/adr-product-ui-track.md) — *why* this shape.
 - [`ui-track-flow.md`](contracts/ui-track-flow.md) — slot-by-slot contract.
 - [`ui-stack-extension.md`](contracts/ui-stack-extension.md) — adding a stack.
-- [`ui-audit-gate`](../.agent-src/rules/ui-audit-gate.md) — the always-on rule that mirrors the dispatcher gate.
+- [`ui-audit-gate`](../dist/agent-src/rules/ui-audit-gate.md) — the always-on rule that mirrors the dispatcher gate.

package/docs/value.md

@@ -1,86 +1,86 @@
-# Value Dashboard — was kostet das Paket, was bringt es?
+# Value Dashboard — what does the package cost, what does it bring?
 
-> Diese Seite beantwortet **eine** Frage in echten Zahlen: *Wie viel mehr Tokens kostet mich das Paket, und wie viel spart es danach wieder ein?* Generiert von `scripts/render_value_md.py` aus dem letzten `value-v1` Report; Quelle: `internal/bench/reports/value/latest.json`.
+> This page answers **one** question in real numbers: *How many more tokens does the package cost me, and how much does it save back afterwards?* Generated by `scripts/render_value_md.py` from the latest `value-v1` report; source: `internal/bench/reports/value/latest.json`.
 
-## Wie diese Seite zu lesen ist
+## How to read this page
 
-**Panel A (Token-Leiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort. Bewusst rein in Tokens — kein €-Vergleich, da Abo-Nutzer keine Per-Request-API-Preise zahlen.
+**Panel A (token ladder)** — read top to bottom. Each rung states: *what it does*, *how many input tokens it adds or saves per request*, and *where we stand cumulatively*. The bold **NET** line at the end is the answer. Deliberately pure tokens — no € comparison, since subscription users pay no per-request API prices.
 
-**Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. *ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-Auswahl, Stopps bei riskanten Aktionen, weniger Rückfragen, mehr abgeschlossene Aufgaben.
+**Panel B (behavior)** — four real comparisons, *with* vs. *without* the package. This is where the non-token value lives: fitting skill selection, stops on risky actions, fewer clarifying questions, more completed tasks.
 
-**Confidence-Marker** an jeder Stufe: `✅ gemessen` = echter Wert aus einem Report im Repo · `⏳ pending` = noch nicht gemessen, Stufe trägt 0 zur Summe bei · `⚠️ vendor-claim` = Behauptung eines Herstellers, nicht selbst gemessen.
+**Confidence markers** on each rung: `✅ measured` = a real value from a report in the repo · `⏳ pending` = not yet measured, the rung contributes 0 to the sum · `⚠️ vendor-claim` = a vendor's claim, not measured by us.
 
 ## Reference scale
 
-- **1,000** Requests, durchschnittlich **8,000** Input-Tokens und **600** Output-Tokens pro Request
-- Modell-Tier (Workload-Annahme): `sonnet`
-- Wer einen anderen Workload fährt, rechnet selbst nach — die Methodik ist offengelegt; nichts ist hardcodiert versteckt.
+- **1,000** requests, on average **8,000** input tokens and **600** output tokens per request
+- Model tier (workload assumption): `sonnet`
+- Anyone running a different workload recomputes it themselves — the methodology is disclosed; nothing is hardcoded or hidden.
 
-## Panel A — Kostenleiter (kumulativ, min → max)
+## Panel A — Cost ladder (cumulative, min → max)
 
-Liest sich von oben nach unten. Positive Δ-Werte = das Paket *kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); negative Δ-Werte = das Paket *spart* Tokens.
+Reads top to bottom. Positive Δ values = the package *costs* tokens (rule load is the honest up-front tax); negative Δ values = the package *saves* tokens.
 
-| Stufe | Was sie tut | Δ Tokens | Kumulativ | Quelle |
+| Rung | What it does | Δ tokens | Cumulative | Source |
 |---|---|---:|---:|---|
-| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00% | `n/a` · ✅ gemessen |
-| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +59 359 | +741.99% | `internal/bench/reports/projection-cost.json` · ✅ gemessen |
-| | _Fußnote:_ Eager-Default: alle 79 Rule-Files always-on im `.claude`-Projektionspfad (0B.6-bestätigt fürs primäre Tool). Nicht nur der Kernel — das ist die ehrliche Up-Front-Last; tokens ≈ chars / 4. | | | |
-| + thin (Regeln als Pointer) / + thin (rules as pointers) | Nicht-Kernel-Regel-Bodies werden zu router-aufgelösten Pointern. | -45 857 | +741.99% | `internal/bench/reports/projection-cost.json` · 🔁 verfügbar (Default aus) |
-| | _Fußnote:_ Verfügbar hinter `lean_projection.mode=thin` (Default `eager-all` — deshalb NICHT im Default-NETTO). Mit Thin aktiv: Rule-Layer 59359 → 13502 GPT tok (−45857, −77.3%). MUST-LOAD-Floor `task trigger-coverage` 26/26 grün; Live-A/B-Validierung ausstehend (Harness abgelehnt). Rollback = ein Flip. | | | |
-| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | +739.66% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
-| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | |
-| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -585 | +732.35% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
-| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +733.05% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
-| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | |
+| **Without package** | Baseline — the bare request without package rules. | +0 | +0.00% | `n/a` · ✅ measured |
+| With package (rule load) | The always-active rules land in the context of every request. ⚠️ costs first | +59 783 | +747.29% | `internal/bench/reports/projection-cost.json` · ✅ measured |
+| | _Footnote:_ Eager default: all 79 rule files always-on in the `.claude` projection path (0B.6-confirmed for the primary tool). Not just the kernel — this is the honest up-front load; tokens ≈ chars / 4. | | | |
+| + thin (rules as pointers) | Non-kernel rule bodies become router-resolved pointers. | -46 222 | +747.29% | `internal/bench/reports/projection-cost.json` · 🔁 available (default off) |
+| | _Footnote:_ Available behind `lean_projection.mode=thin` (default `eager-all` — hence NOT in the default NET). With thin active: rule layer 59783 → 13561 GPT tok (−46222, −77.3%). MUST-LOAD floor `task trigger-coverage` 26/26 green; live A/B validation pending (harness declined). Rollback = one flip. | | | |
+| + condense (rule shrink) | Build step shrinks rule files before shipping. | -186 | +744.96% | `internal/bench/reports/telegraph-v2.json` · ✅ measured |
+| | _Footnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | |
+| + rtk (filter CLI output) | rtk cuts verbose CLI output before the model input. | -585 | +737.65% | `internal/bench/reports/rtk/latest.json` · ✅ measured |
+| + terse (shorter replies) | Telegraph style aims at terser model replies. | +56 | +738.35% | `internal/bench/reports/telegraph-v1.json` · ✅ measured |
+| | _Footnote:_ Honest: measured median = -9.27% against 'be terse' — telegraph delivers more tokens here, not fewer. We measure, we do not hide. | | | |
 
-**NETTO: Mehrkosten** ⚠️ — **+58 644 Tokens / Request**, kumulativ **+733.05%** vs. Baseline.
+**NET: extra cost** ⚠️ — **+59 068 tokens / request**, cumulative **+738.35%** vs. baseline.
 
-## Panel B — Verhalten (mit vs. ohne)
+## Panel B — Behavior (with vs. without)
 
-Vier reale Vergleiche aus echten Bench-Runs. Hier liegt der Wert, den Tokens allein nicht messen: ob der Agent das richtige Skill wählt, bei riskanten Aktionen stoppt, weniger rückfragt und mehr Aufgaben abschließt.
+Four real comparisons from actual bench runs. This is where the value lives that tokens alone do not measure: whether the agent picks the right skill, stops on risky actions, asks fewer clarifying questions, and completes more tasks.
 
-| Metrik | Was es bedeutet | Mit Paket | Ohne Paket | Δ | Mode |
+| Metric | What it means | With package | Without package | Δ | Mode |
 |---|---|---:|---:|---:|---|
-| Right-skill selection / Richtige Skill-Wahl | Wie oft das passende Skill aktiviert wird (top-K Treffer). | 50.0% | 0.0% | 50.0% | ✅ live |
-| Destructive-op stops / Stopps bei riskanten Aktionen | Wie oft der Agent vor destructive ops anhält / nachfragt (von 5). | — | — | — | ⚠️ dry-run |
-| Ask-vs-act ratio / Fragen vs. Handeln | Verhältnis Rückfragen zu Aktionen — niedriger = entschlossener. | 0.000 | 0.000 | 0.000 | ✅ live |
-| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 0.0% | 84.6% | ✅ live |
+| Right-skill selection | How often the right skill activates (top-K hit). | 50.0% | 0.0% | 50.0% | ✅ live |
+| Destructive-op stops | How often the agent stops / asks before destructive ops (of 5). | — | — | — | ⚠️ dry-run |
+| Ask-vs-act ratio | Ratio of clarifying questions to actions — lower = more decisive. | 0.000 | 0.000 | 0.000 | ✅ live |
+| Task completion rate | Share of tasks the agent completes fully. | 84.6% | 0.0% | 84.6% | ✅ live |
 
-## Glossar
+## Glossary
 
-Plain-language Definitionen für den nicht-Entwickler-Reader.
+Plain-language definitions for the non-developer reader.
 
-- **Token** — die Einheit, in der ein Sprachmodell abrechnet. Faustregel: ein Token ≈ 4 Zeichen deutsch/englischer Prosa. 1.000 Tokens ≈ 750 Wörter.
-- **Input-Tokens** — alles, was das Modell pro Turn liest (System-Prompt, immer-aktive Regeln, deine Nachricht, frühere Konversation). Das Paket fügt hier Regeln hinzu — Installation kostet Input-Tokens.
-- **Output-Tokens** — was das Modell zurückschreibt. Meist weniger als Input. Pro Token teurer als Input.
-- **condense** — ein Build-Schritt, der die Regel-Dateien vor dem Ausliefern schrumpft (`.agent-src.uncondensed` → `.agent-src`). Spart Input-Tokens bei jedem Request.
-- **rtk** — der *Rust Token Killer*, ein CLI-Wrapper, der verbose Output (`git status`, lint-Output, test-Runner) filtert, bevor das Modell ihn liest. Spart Input-Tokens auf Tool-Calls.
-- **terse / telegraph** — ein Stil (kurze Phrasen, weggelassene Artikel), den der Agent für knappere Antworten nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.
-- **Ohne Paket / Mit Paket** — *without the package* / *with the package* — die zwei Arme des A/B-Vergleichs.
-- **Δ Tokens** — Input-Token-Differenz pro Request gegenüber der Baseline. Bewusst die einzige Kosten-Einheit: ein €-Vergleich würde Per-Request-API-Preise unterstellen, die Abo-Nutzer nicht zahlen.
+- **Token** — the unit a language model bills in. Rule of thumb: one token ≈ 4 characters of German/English prose. 1,000 tokens ≈ 750 words.
+- **Input tokens** — everything the model reads per turn (system prompt, always-active rules, your message, earlier conversation). The package adds rules here — installation costs input tokens.
+- **Output tokens** — what the model writes back. Usually fewer than input. More expensive per token than input.
+- **condense** — a build step that shrinks the rule files before shipping (`.agent-src.uncondensed` → `dist/agent-src`). Saves input tokens on every request.
+- **rtk** — the *Rust Token Killer*, a CLI wrapper that filters verbose output (`git status`, lint output, test runners) before the model reads it. Saves input tokens on tool calls.
+- **terse / telegraph** — a style (short phrases, dropped articles) the agent uses for terser answers. Saves output tokens — when the corpus rewards it.
+- **Without package / With package** — the two arms of the A/B comparison.
+- **Δ tokens** — input-token difference per request against the baseline. Deliberately the only cost unit: a € comparison would imply per-request API prices that subscription users do not pay.
 
-## Methodik & Quellen
+## Methodology & sources
 
-Diese Seite ist eine **abgeleitete** Sicht — keine eigene Messung. Sie fasst drei bestehende Bench-Surfaces zusammen (siehe Spalte 'Quelle' in Panel A). Die maschinen-lesbaren Roh-Reports bleiben die Source-of-Truth:
+This page is a **derived** view — not its own measurement. It summarizes three existing bench surfaces (see the 'Source' column in Panel A). The machine-readable raw reports remain the source of truth:
 
-- `internal/bench/reports/telegraph-v1.json` / `telegraph-v2.json` — Telegraph/Condense-Messungen.
+- `internal/bench/reports/telegraph-v1.json` / `telegraph-v2.json` — Telegraph/condense measurements.
 
-- `agents/runtime/frugality/baseline.jsonl` — der Paket-Load (Metric A footprint).
+- `agents/runtime/frugality/baseline.jsonl` — the package load (Metric A footprint).
 
-- `internal/bench/reports/rtk/latest.json` — die rtk-Messung (neu, Phase 2).
+- `internal/bench/reports/rtk/latest.json` — the rtk measurement (new, Phase 2).
 
-- `internal/bench/reports/ab/*-ab-trackb-{with,without}.json` — A/B Track B (Verhalten).
+- `internal/bench/reports/ab/*-ab-trackb-{with,without}.json` — A/B Track B (behavior).
 
-- `internal/bench/reports/*-dev.json` — Dev-Korpus Selection-Accuracy.
+- `internal/bench/reports/*-dev.json` — dev-corpus selection accuracy.
 
 
-**A/B-technischer Anhang:** [`docs/benchmark.md`](benchmark.md) trägt die Cache-Key-, Integrity- und Methodik-Details des A/B-Benches — wer den Variant-Axis-Beweis sehen will, liest dort weiter.
+**A/B technical appendix:** [`docs/benchmark.md`](benchmark.md) carries the cache-key, integrity, and methodology details of the A/B bench — anyone who wants to see the variant-axis proof reads on there.
 
 
-**Hinweise aus dem Report:**
+**Notes from the report:**
 
 - Cost is reported in tokens only — no € figure. Per-call API pricing misleads subscription users; tokens are the currency-neutral metric.
 - Pending rungs contribute 0 to the cumulative until measured.
 - Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
 
-_Last rendered: `2026-06-01T12:10:59+00:00`_
+_Last rendered: `2026-06-06T08:42:18+00:00`_

package/docs/walkthroughs/daily-workspace.md

@@ -0,0 +1,127 @@
+---
+stability: beta
+keep-beta-until: 2026-09-07
+roadmap_ref: road-to-employee-product-and-external-proof.md
+---
+
+# Daily Workspace — Walkthrough
+
+A 5-minute tour of the workspace tab for a non-technical employee:
+pick a role, run a first task, find your sources and documents in the
+right rail. Pairs with the accessibility audit at
+[`daily-workspace-a11y.md`](daily-workspace-a11y.md) and the surface
+contract at [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
+
+> **Screenshots are real; recruit quotes pending.** The screenshots
+> below are maintainer-captured renders of the actual app — Chromium
+> against the same server `ui:serve` boots, with the six shipped roles
+> and a clean first-run state. Nothing staged or fabricated. Verbatim
+> user quotes still come from the optional Phase 1 recruit sessions
+> (human-owner); until one runs, this walkthrough carries no quotes.
+
+## Prerequisites
+
+- The package installed in your project (`npx @event4u/agent-config install`).
+- At least one role experience present under `agents/roles/` — six ship
+  today: galabau, content-creator, consultant, sales, support, leadership.
+- Optional: knowledge ingested via `/knowledge:ingest <path>` (the
+  right rail shows "No sources yet" otherwise — that is fine).
+
+## 1. Open the workspace
+
+```bash
+npx @event4u/agent-config ui:serve
+```
+
+The local UI server starts on `127.0.0.1` (loopback only — nothing is
+exposed to your network) and opens the browser. Pick the **Workspace**
+tab. The page header reads "Pick a role, pick a first task, run it."
+
+![Workspace tab on first open — role cards on the left, empty session
+strip in the centre, knowledge / documents / explanation-style rail on
+the right](assets/workspace-role-grid.png)
+
+## 2. Pick a role
+
+The left column lists every installed role as a card: display name, a
+status badge (`draft` / `beta` / `stable`), and a one-line tagline.
+Click your role — say **Galabau owner**. The centre column swaps to
+that role's three first tasks. Clicking a different role later swaps
+the task list without losing your session history.
+
+![Galabau owner selected — the centre column lists the role's first
+tasks, each with a Start session button and the prompt template it
+references](assets/workspace-task-picker.png)
+
+## 3. Start a first task
+
+Each first task card carries a name, a one-sentence intent, and a
+**Start session** button. Clicking it writes a new session entry
+(visible immediately in "Recent sessions" below) and shows a
+confirmation banner with the session id. The session log is a local
+append-only file under `~/.event4u/agent-config/workspace/sessions/`
+— nothing leaves your machine.
+
+The host agent (Claude Code, or your configured tool) picks the
+session up from there; the prompt template the task references lives
+under `agents/roles/<role>/prompts/`.
+
+![Session started — confirmation banner with the session id at the
+top, task list and right rail unchanged below](assets/workspace-session-started.png)
+
+## 4. The right rail — sources, documents, explanation style
+
+- **Knowledge sources** — every document you ingested with
+  `/knowledge:ingest` appears as a numbered citation (`[1]`, `[2]`, …)
+  with a short excerpt. Pinned sources carry a star. Clicking a source
+  opens the original file. Empty state: "No sources yet. Run
+  `/knowledge:ingest <path>` to add documents."
+- **Recent documents** — the 20 most recently saved workspace
+  documents (offers, mail drafts, memos, briefs, video scripts), newest
+  first, each with a type badge and date. Saved drafts from
+  `/work`-style tasks land here automatically.
+- **Explanation style** — a two-way toggle between **Plain language**
+  (default) and **Technical detail**. Plain mode swaps jargon for
+  everyday words per the relabel matrix in
+  [`plain-language-surface.md`](../contracts/plain-language-surface.md);
+  the technical view keeps the original vocabulary for engineering
+  leads.
+
+## 5. Where your data lives
+
+| Surface | Location | Leaves your machine? |
+|---|---|---|
+| Sessions | `~/.event4u/agent-config/workspace/sessions/<date>/<id>.jsonl` | No |
+| Documents | `~/.event4u/agent-config/workspace/documents/<type>/` | No |
+| Analytics | `~/.event4u/agent-config/workspace/analytics/events.jsonl` (opt-out: `AGENT_CONFIG_ANALYTICS=off`) | No — local-only by contract |
+| Knowledge | `agents/memory/knowledge/<ingest-id>/` in your project | No |
+
+Secret hygiene: every write to these stores passes a pre-write secret
+scan (`workspace_secrets.py`) — high-confidence secrets (API keys, PEM
+blocks) are refused on documents and silently scrubbed from telemetry.
+
+## Troubleshooting
+
+- **"No roles installed"** — the project has no `agents/roles/`
+  directory; re-run the installer or copy a role experience in.
+- **"No tasks scaffolded yet for this role"** — the role's `index.md`
+  is missing its "Three first tasks" section; see
+  [`docs/contracts/role-experience.md`](../contracts/role-experience.md).
+- **Knowledge pane stays empty after ingest** — confirm the ingest id
+  shows up in `/knowledge:list`; the pane reads
+  `agents/memory/knowledge/<id>/manifest.json` from the project the UI
+  server was started in.
+
+## What this walkthrough does not cover
+
+- The host-agent turn loop (how replies stream back) — that substrate
+  is [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md) Tier 1
+  and lands separately.
+- Encryption at rest — the layer (`workspace_crypto.py`) and the
+  store-side wiring are in place across sessions, documents, and
+  analytics ([`ADR-062`](../decisions/ADR-062-encrypt-at-rest-store-architecture.md)
+  family); the feature flag (`workspace.encrypt_at_rest`) stays
+  default-off until the v1.0 activation event, so day-to-day stores
+  are plaintext unless you opt in.
+- Team / multi-user deployment — single-user by design; see
+  [`docs/deploy/team-deployment-posture.md`](../deploy/team-deployment-posture.md).

package/llms.txt

@@ -3,7 +3,7 @@
 Machine-readable index of all skills in this package. Each line:
   <skill-name>: <one-line description>
 
-Source: .agent-src/skills/<name>/SKILL.md
+Source: dist/agent-src/skills/<name>/SKILL.md
 Catalog: docs/skills-catalog.md
 
 accessibility-auditor: Use when reviewing UI for accessibility — WCAG 2.2 AA, keyboard nav, focus, ARIA, contrast, screen-reader semantics — even on 'is this a11y-OK?' or 'mach das barrierefrei'.
@@ -11,6 +11,7 @@ activation-design: Use when defining or auditing the activation event — aha-mo
 adr-create: Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'.
 adversarial-review: ONLY when user requests adversarial review, devil's advocate, stress-test, OR honest critique of finished work ('poke holes', 'be brutal', 'was hältst du davon') — NOT for routine code/design review.
 agent-docs-writing: Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure.
+agent-security-review: Use for an adversarial red-team / blue-team / auditor review of an AI agent's CONFIG + behaviour (rules, skills, MCP, hooks, permissions) — attack-chain → defensive-gap list, not a code audit.
 agents-md-thin-root: Use when editing AGENTS.md (package root) or templates/AGENTS.md (consumer) — enforces Thin-Root contract: hard char ceilings, ≥40% pointer ratio, mandatory emergency-triage block.
 ai-council: Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'.
 analysis-autonomous-mode: ONLY when user explicitly requests autonomous analysis, deep investigation, multi-step research, or 'dig into this end-to-end without asking me each step' — NOT for normal feature work.
@@ -32,21 +33,23 @@ character-consistency: Use when a character must stay visually identical across
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
 churn-prevention: Use when designing churn defence — health-score signals, churn-cause split (involuntary / value / relationship / fit), early-warning loop. Triggers on 'why are accounts leaving'.
 code-refactoring: Use when the user says 'refactor this', 'rename class', or 'move method'. Safely refactors code in any language — finds all callers, updates downstream dependencies, verifies via quality tools.
-code-review: Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
+code-review: Use when the user says \"review this\", \"check my code\", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards.
 command-routing: Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns.
-command-writing: Use when creating or editing a slash command in .agent-src.uncondensed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'.
+command-writing: Use when creating or editing a slash command in src/agent-src/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'.
 comp-banding: Use when designing levels, comp bands, equity-vs-cash, geo adjustments, or raise vs promotion vs market correction. Triggers on 'set our comp bands', 'is this raise market'.
 competitive-moat-analysis: Use when mapping competitors, naming defensibility, and finding white-space — moat reasoning, where-to-play, where-not-to-play. Triggers on 'who are we competing with', 'what's our moat'.
 competitive-positioning: Use when comparing this package to a peer / competitor — ours-vs-theirs verdict table, axis selection, adoption queue. Triggers on 'how do we compare to X', 'should we adopt their pattern'.
+complexity-first-planning: Use when staging multi-component or uncertain work — tackle the load-bearing unknown first (risk-first decomposition), not the easy parts first.
 composer-packages: Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'.
 condense-memory: Use when shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) via telegraph grammar — refuses sensitive paths, round-trips via .original.md backup.
 content-funnel-design: Use when mapping funnel-stage to content shape — conversion-pathway, content-as-system, leverage-point selection. Triggers on 'design our content funnel', 'why does mid-funnel leak'.
 context-authoring: Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel.
-context-document: Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation.
+context-document: Use when the user says \"create context\", \"document this area\", or wants a structured snapshot of a codebase area for agent orientation.
 contracts-cognition: Use when reading a contract for risk and constraint — clause shape, redline priority, what the contract actually binds. Triggers on 'review this contract', 'what does this MSA constrain'.
 conventional-commits-writing: Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits.
 copilot-agents-optimization: Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience.
 copilot-config: Tune the GitHub Copilot AI — `copilot-instructions.md`, PR-review patterns, suggestion behavior, output verbosity. NOT for dev-environment setup (use `devcontainer`).
+corpus-grounding: Shared corpus-grounding engine — BM25 + structured filters + decision rules over CSV corpora via a domain manifest. Use when a skill needs grounded pre-action option-space constraints.
 customer-research: Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'.
 dashboard-design: Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling.
 data-flow-mapper: Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line.
@@ -59,7 +62,9 @@ deep-reading-analyst: Deep analysis of articles/long-form via thinking framework
 defense-in-depth: Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one.
 dependency-upgrade: Use when upgrading dependencies — 'update framework X', 'bump runtime version', or 'upgrade packages'. Covers changelog review, breaking-change detection, and verification. Stack-agnostic.
 description-assist: Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'.
-design-review: Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more.
+design-intelligence: Grounded design brief from the adopted corpus — style, WCAG-checked color tokens, typography, layout pattern, anti-patterns. Use on ui-design-brief or any which-style/palette/font/chart decision.
+design-review: Use when the user says \"review the design\", \"check the UI\", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more.
+design-tokens: Author a 3-layer DTCG token system (primitive → semantic → component) with light/dark theming; generate CSS vars + Tailwind colors and lint hardcoded values. Use on design tokens / CSS variables.
 devcontainer: Wire up DevContainers / GitHub Codespaces — `devcontainer.json`, container images, secrets, VS Code features, port forwarding. NOT for tuning Copilot itself (use `copilot-config`).
 developer-like-execution: Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it.
 discovery-interview: Use when running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'.
@@ -72,7 +77,7 @@ error-handling-patterns: Use when picking a failure-reporting strategy — excep
 existing-ui-audit: Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set.
 expansion-playbook: Use when designing account-expansion mechanics — upsell vs cross-sell, expansion-trigger signals, NRR cognition. Triggers on 'lift NRR', 'when do we upsell vs cross-sell'.
 fe-design: Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py.
-feature-planning: Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap.
+feature-planning: Use when the user says \"plan a feature\", \"brainstorm\", \"explore this idea\", or wants to go from idea to structured plan and roadmap.
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
 flux: Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives.
@@ -90,7 +95,7 @@ hiring-loop-design: Use when shaping an engineering hiring loop — stages, take
 image-analyser: Use to analyse a character image down to the smallest mole and diff against a canon — per-feature spec, OCR-reads tattoo text, flags drift. Triggers 'analyse this image', 'match the canon'.
 image-creator: Use to generate a character image to spec — max-fidelity reproducible prompt from a Canon Spec, anchors-first, provider/governance-gated. Triggers 'generate this character', 'render to spec'.
 incident-commander: Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'.
-jira-integration: Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
+jira-integration: Use when the user says \"check Jira\", \"create ticket\", \"update issue\", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
 jobs-events: Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling.
 judge-bug-hunter: Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'.
 judge-code-quality: Use when a diff needs a readability review — naming, single-responsibility, DRY, dead code, mismatch with codebase conventions — dispatched by /review-changes, /do-and-judge, /judge.
@@ -120,9 +125,9 @@ market-entry-analysis: Use when sequencing market entry — geo / segment / vert
 markitdown: Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'.
 mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
 mcp-builder: Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness.
-md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.
+md-language-check: Use BEFORE saving any .md under .augment/, dist/agent-src*/, or agents/ — scans umlauts, German function words, and German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.
 memory-consolidation: Use when consolidating session signals into curated memory — four-phase loop ORIENT → GATHER → CONSOLIDATE → PRUNE. Triggers on 'mine my sessions', 'consolidate memory', 'review intake signals'.
-merge-conflicts: Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow.
+merge-conflicts: Use when the user has merge conflicts or says \"resolve conflicts\". Understands conflict markers, resolution strategies, and verification workflow.
 messaging-architecture: Use when shaping the primary message, supporting proofs, and audience-by-message matrix from a locked positioning frame — before any copy or launch beat. Triggers on 'tighten the message stack'.
 migration-architect: Use when shaping a non-trivial migration — rollout phases, dual-write windows, cutover sequencing, deprecation cycles — hands off to the framework-specific migration skill for DDL once locked.
 mobile-e2e-strategy: Use when picking a mobile E2E framework — Detox / Appium / Maestro / XCUITest / Espresso — or planning iOS Simulator / Android Emulator coverage in CI for RN, Expo, or native apps.
@@ -141,7 +146,7 @@ override-management: Creates and manages project-level overrides for shared skil
 perf-feedback-craft: Use when shaping feedback — situation-behavior-impact, growth-vs-corrective split, cadence design, ladder-of-inference checks. Triggers on 'how do I give this feedback', 'perf review shape'.
 performance: Use when optimizing application performance — caching strategies, eager loading, query optimization, Redis patterns, or background job design.
 performance-analysis: ONLY when user explicitly requests: performance audit, bottleneck analysis, or N+1 query detection. NOT for regular feature work.
-persona-writing: Use when creating or editing a persona in .agent-src.uncondensed/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'.
+persona-writing: Use when creating or editing a persona in src/agent-src/personas/ — voice / focus / unique questions / output expectations — even when the user just says 'add a reviewer voice for X'.
 pest-testing: Use when writing, generating, or improving Pest tests for Laravel — clear intent, good coverage, maintainable structure, and alignment with project testing conventions.
 php-coder: Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts.
 php-debugging: Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'.
@@ -166,12 +171,14 @@ project-analyzer: ONLY when user asks for single-pass tech-stack detection or `a
 project-docs: Use when looking for project-specific documentation. Knows which docs exist in agents/reference/docs/ and agents/settings/contexts/ and maps work areas to relevant docs.
 prompt-engineering-patterns: Use when designing production-LLM prompts — few-shot, chain-of-thought, system prompts, templates, self-verification — distinct from prompt-optimizer and refine-prompt.
 prompt-optimizer: Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'.
+prompt-validator: Pre-spend contradiction gate for AI-video runs: checks every prompt in the batch, blocks on style / character / physics mismatch. Triggers 'validate the prompts', 'check the storyboard'.
 quality-tools: Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned.
 react-native-setup: Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'.
 react-shadcn-ui: Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack.
 readme-reviewer: Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues.
 readme-writing: Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience.
 readme-writing-package: Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding.
+reasoning-orchestrator: Use for complex / ambiguous / long-horizon work — coordinate the reasoning chain ground→intent→notes→gather→audit→verify; composes existing skills, never duplicates them.
 receiving-code-review: Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'.
 "refine-prompt": Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'.
 "refine-ticket": Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt.
@@ -182,11 +189,11 @@ retention-loops: Use when designing product-led retention — habit formation, t
 review-routing: Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML.
 rice-prioritization: Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort.
 risk-officer: Use when surfacing and prioritising risk before commit — blast-radius framing, mitigations, residual-risk verdict — even if the user just says 'what could go wrong here?'.
-roadmap-management: Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking.
+roadmap-management: Use when the user says \"create roadmap\", \"show roadmap\", or \"execute roadmap\". Creates, reads, and manages roadmap files with phase tracking.
 roadmap-writing: Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'.
 rtk-output-filtering: Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns.
 rule-refactor: Use when the rule set is over the Augment budget, when a new rule would breach it, or when asked to audit / merge / prune rules — runs the audit pipeline and proposes a verdict per rule.
-rule-writing: Use when creating or editing a rule in .agent-src.uncondensed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'.
+rule-writing: Use when creating or editing a rule in src/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'.
 runway-cognition: Use when reasoning about cash runway — burn shape, fundraise triggers, layoff-vs-cut-vs-grow decisions. Triggers on 'how long do we have', 'should we raise', 'cut or grow'.
 scenario-modeling: Use when constructing base / upside / downside scenarios — three-statement modeling, sensitivity analysis, optionality reasoning. Triggers on 'model the scenarios', 'what if growth halves'.
 scene-expander: Use when expanding a one-line idea into the 12-block Cinematic Scene Blueprint — provider-agnostic, includes optional dialogue + ambient. Triggers 'expand this scene', 'blueprint for X'.
@@ -194,7 +201,7 @@ script-writing: Use when adding or editing any script under `scripts/` — `--qu
 secrets-management: Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized.
 security: Use when applying security best practices — authentication, authorization, CSRF protection, input sanitization, rate limiting, or secure coding — stack-agnostic.
 security-audit: ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work.
-sentry-integration: Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis.
+sentry-integration: Use when the user shares a Sentry URL, says \"check Sentry\", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis.
 sequential-thinking: ONLY when user explicitly requests: step-by-step reasoning, structured problem decomposition, or iterative analysis. NOT for regular coding tasks.
 skill-improvement-pipeline: ONLY when user explicitly requests: run the skill improvement pipeline after a learning was detected. Orchestrates capture, classify, create, validate, and apply.
 skill-management: Use when condensing, decondenseing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained.
@@ -208,7 +215,7 @@ symfony-workflow: Writes Symfony PHP — DI container, bundles, Doctrine, Messen
 systematic-debugging: Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'.
 tailwind-engineer: Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'.
 tech-debt-tracker: Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'.
-technical-specification: Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure.
+technical-specification: Use when the user says \"write a spec\", \"create RFC\", \"write a PRD\", or \"document this decision\". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure.
 terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
 terragrunt: Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt.
 test-driven-development: Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'.