@event4u/agent-config 3.1.1 → 3.3.0

package/docs/decisions/ADR-028-root-layout.md

@@ -0,0 +1,147 @@
+---
+adr: 028
+status: accepted
+date: 2026-05-25
+decision: root-layout
+supersedes: —
+superseded_by: —
+phase: v3.x · root-layout-cleanup Phase 1
+type: structural
+review_date: 2027-05-25
+---
+
+# ADR-028 — Root layout — targeted prune now, multi-workspace deferred behind four audits
+
+## Status
+
+**Accepted** · 2026-05-25. Encodes the AI Council verdict from
+[`root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md)
+and opens
+[`road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) (archived; complete).
+Time-boxed: review on **2027-05-25** or earlier if any trigger below fires.
+
+## Context
+
+A request to move "everything not needed at root into `./src/`" failed
+the reality check on three counts:
+
+1. **`./src/` is occupied** — the TypeScript application (CLI · Server · UI · shared) per
+   [`ADR-012`](ADR-012-typescript-cli-shell.md) / [`ADR-016`](ADR-016-installer-architecture.md).
+   Moving general tooling into `./src/` collides with the app boundary.
+2. **`router.json` is not at root** — lives under `./dist/`, governed by
+   [`ADR-019`](ADR-019-router-json-dist-location.md). Out of scope.
+3. **`setup.sh` is the curl entry point** — referenced by external installers
+   (`bash <(curl …setup.sh)`). Discovery surface, immovable.
+
+A council session (2 members, $0.13 actual) reframed the problem:
+
+> "Root noise" is not a *discoverability* problem (GitHub paginates
+> anyway, npm consumers never see it). It is a *maintainability*
+> problem — "where do new internal tools belong?"
+
+With that reframe, the cheap-and-safe move (Option 1 — targeted prune)
+becomes obvious, and the deep restructure (multi-workspace) drops to a
+conditional follow-up gated by evidence the package does not yet have.
+
+### Consumer-contract surface check (Phase 1 scope)
+
+Re-audit of `bench/`, `evals/`, `workers/`, `user-types/` against the
+installer / projector / CI:
+
+| Dir | `scripts/install.py` | `scripts/compress.py` projection | `.github/workflows/*` | Verdict |
+|---|---|---|---|---|
+| `bench/` | — | — | `bench-drift.yml` (path filter) | **movable** |
+| `evals/` | — | — | — | **movable** |
+| `workers/` | — | — | `deploy-mcp-worker.yml` (working-dir, 6+ refs) | **movable** (CI updates only) |
+| `user-types/` | `USER_TYPES_DIR = "user-types"` (line 52) | `AUGMENT_SYMLINK_DIRS` includes `"user-types"` | — | **immovable — public contract** |
+
+`user-types/` is dropped from Phase 1 — installer + projector reference
+it as a stable root path. Surfaced during execution, not in the
+council's original scope (the council recommended all four; the audit
+narrowed it).
+
+## Decision
+
+**Two-phase strategy.** Phase 1 ships now; Phases 2–3 are conditional.
+
+### Phase 1 — Targeted Prune (immediate, ≤ 1 day, no version bump)
+
+Move into a new `./internal/` umbrella:
+
+- `bench/` → `internal/bench/`
+- `evals/` → `internal/evals/`
+- `workers/` → `internal/workers/`
+
+Update:
+
+- `.github/workflows/bench-drift.yml` — path filter.
+- `.github/workflows/deploy-mcp-worker.yml` — `working-directory` + `cache-dependency-path`.
+- `taskfiles/engine.yml`, `taskfiles/mcp.yml` — `dir:` references.
+- `AGENTS.md` — placement rule pointer.
+
+Outcome: 3 fewer root entries; zero consumer risk; precedent for
+"maintainer-internal → `./internal/`".
+
+### Phase 2 — Pre-audits (gates Phase 3, no time-box)
+
+Four audits must complete and pass before Phase 3 opens:
+
+1. **Consumer-contract audit** — GitHub code search +
+   `node_modules/@event4u/agent-config/` path probing for
+   `scripts/`, `templates/`, `config/`, `schemas/` references.
+2. **Symlink-mobility test** — verify Cursor / Claude / Windsurf
+   honor symlinked projections (`.cursor/` → `./projections/.cursor/`).
+3. **Hash-sequencing audit** — confirm `.compression-hashes.json`
+   uses paths that survive `.agent-src/` relocation (or document the
+   regeneration migration).
+4. **CI-path audit** — every hardcoded path in
+   `.github/workflows/*.yml` and `taskfiles/*.yml`.
+
+Each audit produces a verdict file under
+`agents/evidence/audits/2026-XX-root-layout-phaseN/`.
+
+### Phase 3 — Conditional multi-workspace (deferred, gated)
+
+Only if **all four audits pass**: restructure to npm-workspaces with
+`tooling/` (Python maintainer scripts), `runtime/` (TS app), and
+optionally `projections/` (host-agent configs). If any audit fails,
+Phase 3 closes as "not feasible" and a successor ADR documents the
+blocker.
+
+## Consequences
+
+- New top-level `./internal/` directory becomes the home for
+  maintainer-only tooling. `AGENTS.md` documents this with one line.
+- `.gitignore` and `eslint`/`pyproject` ignore rules updated as
+  needed.
+- The four Phase 2 audits are pre-requirements, not work. They are
+  *not* sprint tasks — they run on demand when someone wants to
+  re-open multi-workspace.
+- Review on **2027-05-25** or earlier if any trigger fires:
+  1. A new maintainer-only dir is added at root (signal: `./internal/`
+     convention is breaking down).
+  2. Phase 2 audits all return clean (signal: Phase 3 is ready).
+  3. A consumer reports breakage from a Phase 1 path change (signal:
+     audit missed a contract).
+  4. Council session re-opens the question with new evidence.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Move everything into `./src/` (original request) | `./src/` is the TS app per ADR-012/016. Collision. |
+| Option 2 — `./tooling/` umbrella with `templates/` / `config/` / `schemas/` | Council: cost underestimated (duplicate-then-deprecate + 2-month window + major bump); installer paths in those dirs are unaudited. |
+| Option 3 — full category-coded migration | Council hard-reject: projection mobility unproven; compression-hash sequencing risk; unshippable without symlink test. |
+| Option 4 — `MAP.md` documentation | Council: adds 51st entry; documentation-as-apology; AGENTS.md already serves this role. |
+| Skip Phase 1, jump to multi-workspace prototype | Loses the cheap visible win; Phase 2 audits unfunded; risks scope creep into Phase 3. |
+
+## References
+
+- [`agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md`](../../agents/runtime/council/questions/root-cleanup-organizing-principle-2026-05-25.md) — council brief.
+- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) — full synthesis.
+- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) — execution roadmap (archived; Phase 1 ✅, Phase 2 ✅, Phase 3 closed).
+- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) — Phase 2 audit verdict bundle.
+- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — Phase 3 close-out (multi-workspace deferred indefinitely).
+- [`ADR-012`](ADR-012-typescript-cli-shell.md), [`ADR-016`](ADR-016-installer-architecture.md) — `./src/` is the TS app.
+- [`ADR-019`](ADR-019-router-json-dist-location.md) — `router.json` lives in `./dist/`.
+- `scripts/install.py:52` (`USER_TYPES_DIR`), `scripts/compress.py:1106` (`AUGMENT_SYMLINK_DIRS`) — evidence pinning `user-types/` to root.

package/docs/decisions/ADR-029-multi-workspace-deferred.md

@@ -0,0 +1,122 @@
+---
+adr: 029
+status: accepted
+date: 2026-05-25
+decision: multi-workspace-deferred
+supersedes: —
+superseded_by: —
+phase: v3.x · root-layout-cleanup Phase 3 close-out
+type: structural
+review_date: 2027-05-25
+---
+
+# ADR-029 — Multi-workspace restructure deferred; Phase 3 closed pending L0 symlink-mobility evidence
+
+## Status
+
+**Accepted** · 2026-05-25. Successor to
+[`ADR-028`](ADR-028-root-layout.md) Phase 3. Closes the multi-workspace
+restructure (Option 5 from the original council session) as **not
+feasible today**, with a re-open path documented below. Time-boxed:
+review on **2027-05-25** or earlier if any re-open trigger fires.
+
+## Context
+
+[`ADR-028`](ADR-028-root-layout.md) defined a three-phase strategy:
+
+1. **Phase 1** — move `bench/`, `evals/`, `workers/` to `internal/`. **Shipped.**
+2. **Phase 2** — run four pre-audits that gate Phase 3.
+3. **Phase 3** — conditional multi-workspace restructure
+   (`tooling/` · `runtime/` · `projections/`), only if all four
+   Phase 2 audits return clean.
+
+Phase 2 ran in the same PR as Phase 1 (under maintainer mandate).
+Verdict bundle:
+[`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/).
+
+| # | Audit | Verdict |
+|---|---|---|
+| 1 | Consumer-contract | ✅ Pass — published surface enumerated |
+| 2 | Symlink-mobility | ⚠️ Partial — subdirectory symlinks proven, top-level untested |
+| 3 | Hash-sequencing | ✅ Pass — source-relative keys, idempotent regeneration |
+| 4 | CI-path inventory | ✅ Pass — ~27 edit points enumerated |
+
+Audit 2 is the blocker. The multi-workspace option requires
+**L0 symlinks** (tool root directory itself becomes a symlink, e.g.
+`.cursor/ → projections/.cursor/`). The package today only proves
+**L1 symlinks** (subdirectory level, e.g. `.augment/skills/ →
+../.agent-src/skills/`). L0 has never been tested against current
+Cursor, Claude Code, or Windsurf builds — and one of those three
+(Augment Code) is already known to refuse symlinked rule files at L1,
+which is the precedent that motivates the audit in the first place.
+
+Without L0 evidence, executing Phase 3 would either ship a broken
+projection for at least one host agent or force a fallback to
+per-directory copies that defeat the "single source of truth" win the
+multi-workspace shape is meant to deliver.
+
+## Decision
+
+**Defer Phase 3 indefinitely.** Close the Phase 3 roadmap step as "not
+feasible today". Keep the audit bundle as the canonical evidence base
+so that a future maintainer can re-open the question without redoing
+the work.
+
+The four root-layout claims survive Phase 1 unchanged:
+
+- `bench/`, `evals/`, `workers/` are gone from root (under `internal/`).
+- `user-types/` stays at root (immovable per Audit 1 + ADR-028).
+- Top-level tool roots (`.augment/`, `.cursor/`, `.claude/`, `.clinerules/`)
+  stay as real directories with L1 symlinks pointing at `.agent-src/`.
+- The "maintainer-internal → `./internal/`" precedent is the new
+  placement rule for new internal dirs (already in `AGENTS.md`).
+
+## Re-open conditions
+
+Phase 3 becomes eligible when **all** of these hold:
+
+1. A maintainer (or community contributor) runs the L0 symlink test
+   documented in
+   [`02-symlink-mobility.md`](../../agents/evidence/audits/2026-05-root-layout-phase2/02-symlink-mobility.md)
+   against current Cursor + Claude Code + Windsurf, captures the
+   result, and amends Audit 2 to ✅ or ❌.
+2. If Audit 2 lands ✅: the ~27 CI-path edit points from Audit 4 are
+   accepted as in-scope for the migration window; no new hardcoded
+   paths added in the interim invalidate the inventory.
+3. A council session synthesizes the updated verdict bundle and
+   produces a fresh recommendation (multi-workspace vs. stay-as-is).
+4. The maintainer accepts the deprecation cycle cost (installer
+   version bump + dual-write window for the projection contract).
+
+## Consequences
+
+- The root layout stabilizes at the Phase 1 shape for ≥ 1 year (the
+  `2027-05-25` review date).
+- New maintainer-internal directories go under `internal/`. New
+  tooling that needs to ship to consumers goes under `scripts/`,
+  `config/`, or a new top-level entry that earns its own ADR.
+- The `projections/` umbrella idea is **not dead** — it is gated on
+  fresh L0 evidence, not on a new design decision.
+- The four audit files are reusable: Audit 1 (consumer surface),
+  Audit 3 (hash portability), and Audit 4 (CI path inventory) remain
+  valid until a structural change invalidates them; only Audit 2
+  needs runtime re-verification.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| Execute Phase 3 anyway with L0 untested | Ships projection breakage to one of three host agents in the worst case; the win (single source of truth) collapses if any agent forces a fallback to copies. |
+| Run the L0 test in CI | The L0 test requires the host agent's runtime (Cursor / Claude Code IDE plugins); CI cannot exercise it. |
+| Defer **all** of Phase 3 to a separate roadmap | Phase 2 already produced the audit bundle; closing Phase 3 with an ADR captures the verdict without leaving a stale roadmap open. |
+| Re-shape Phase 3 as L1-only | The council's recommendation specifically called out the `projections/` umbrella, which requires L0. Re-shaping to L1-only is a different decision the council did not weigh; would need a fresh council session. |
+
+## References
+
+- [`ADR-028`](ADR-028-root-layout.md) — parent decision.
+- [`agents/evidence/audits/2026-05-root-layout-phase2/`](../../agents/evidence/audits/2026-05-root-layout-phase2/) —
+  full audit bundle (4 verdict files + README).
+- [`agents/roadmaps/archive/road-to-root-layout-cleanup.md`](../../agents/roadmaps/archive/road-to-root-layout-cleanup.md) —
+  execution roadmap, archived (Phase 1 ✅, Phase 2 ✅, Phase 3 closed via this ADR).
+- [`agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md`](../../agents/runtime/council/sessions/root-cleanup-organizing-principle-2026-05-25.synthesis.md) —
+  original council synthesis that proposed the multi-workspace shape.

package/docs/decisions/INDEX.md

@@ -25,6 +25,14 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-019](ADR-019-router-json-dist-location.md) | Router Json Dist Location | accepted | 2026-05-23 | — |
 | [ADR-020](ADR-020-global-only-consumer-scope.md) | Global Only Consumer Scope | accepted | 2026-05-23 | — |
 | [ADR-021](ADR-021-deployment-shape.md) | Deployment Shape | accepted | 2026-05-24 | — |
+| [ADR-022](ADR-022-daily-workspace-decomposition.md) | Daily Workspace Decomposition | accepted | 2026-05-24 | — |
+| [ADR-023](ADR-023-host-agent-protocol.md) | Host Agent Protocol | accepted | 2026-05-24 | — |
+| [ADR-024](ADR-024-workspace-v0-feature-floor.md) | Workspace V0 Feature Floor | accepted | 2026-05-24 | — |
+| [ADR-025](ADR-025-workspace-chrome.md) | Workspace Chrome | accepted | 2026-05-24 | — |
+| [ADR-026](ADR-026-explain-mode-translation.md) | Explain Mode Translation | accepted | 2026-05-24 | — |
+| [ADR-027](ADR-027-changelog-machine-vs-manual.md) | Changelog Machine Vs Manual | accepted | 2026-05-25 | — |
+| [ADR-028](ADR-028-root-layout.md) | Root Layout | accepted | 2026-05-25 | — |
+| [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
 
 ## Unnumbered (legacy)
 

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