@event4u/agent-config 4.3.0 → 4.6.0

package/docs/contracts/gui-wizard.md

@@ -90,7 +90,12 @@ Versioned under `/api/v1/`. Selected routes:
 | POST   | `/api/v1/wizard/state`        | Persist state between steps                                             |
 | GET    | `/api/v1/wizard/manifest`     | Locked discovery-manifest (extended mode)                               |
 | GET    | `/api/v1/wizard/auto-detect`  | Project-signal evidence for the `ai-tools` step (extended mode)         |
+| GET    | `/api/v1/wizard/detect-tools` | Native AI-tool presence (home/app/`$PATH`) for Step-1 pre-select + badge |
+| GET    | `/api/v1/wizard/detect-rtk`   | rtk presence + per-OS install hint (Editor-and-tooling step)            |
+| GET    | `/api/v1/wizard/ai-council`   | AI-council scalar subset + provider key presence (extended mode)        |
+| POST   | `/api/v1/wizard/ai-council`   | Comment-preserving scalar merge into `.ai-council.yml`                  |
 | POST   | `/api/v1/wizard/finish`       | 2PC commit of settings + user-identity                                  |
+| POST   | `/api/v1/shutdown`            | Browser-close shutdown beacon (`navigator.sendBeacon` target; real-serve only) |
 | POST   | `/api/v1/wizard/apply`        | **Single real-apply route.** `dry_run:true` → buffered plan preview; otherwise SSE-streams `scripts/install.py --apply-payload` |
 | GET    | `/api/v1/install/detect`      | Scope + project shape + tool presence                                   |
 | POST   | `/api/v1/install/plan`        | Plan preview (per-tool file counts + conflicts) for the Review step     |
@@ -107,6 +112,36 @@ an `Origin` allow-list (browser-issued requests), and a per-server bearer
 token (`Authorization: Bearer <token>`, minted at boot, surfaced in the
 `?token=` URL). A bad token / Host / Origin returns `403`.
 
+### Browser-lifecycle shutdown
+
+In real-serve (`runUiServe`), the server stops itself when the browser that
+drives it goes away — the local process should not outlive its only client:
+
+- The SPA ([`src/ui/serverLifecycle.ts`](../../src/ui/serverLifecycle.ts))
+  heartbeats `GET /api/v1/ping` every 30s while the tab is visible and the
+  user has interacted within the last 30 min. On `pagehide` (window/tab
+  close) it fires `navigator.sendBeacon('/api/v1/shutdown?token=…')` (the
+  token rides as a query param because `sendBeacon` cannot set headers); and
+  once the user has been idle for 30 min it fires the same beacon instead of
+  a ping, so the server stops even with the tab still open.
+- The server (`createApp` `idleShutdown` option, passed only by `runUiServe`)
+  exits on that beacon, and — as a backstop for crashes where neither beacon
+  is delivered — via an idle timer that **arms only after the first authed
+  request** (so headless / `--allow-headless` manual-connect servers are
+  never killed before the operator attaches) and fires after 30 min of
+  silence.
+
+On boot, `runUiServe` records `{pid, port, url}` to
+`~/.event4u/agent-config/local-server.json`
+([`src/server/serverInfo.ts`](../../src/server/serverInfo.ts)) and removes it
+on graceful exit. A fresh `agent-config init` (via `scripts/install.py`
+`_kill_stale_wizard_server`) reads that record, terminates a still-running
+prior instance, and starts a new server — so init always lands on step 1.
+
+`createApp` is inert (no watchdog, no `/api/v1/shutdown` route) unless
+`idleShutdown` is supplied, so the in-process test harness
+([`tests/server/helpers.ts`](../../tests/server/helpers.ts)) is unaffected.
+
 ## Real apply — single source of truth
 
 `POST /api/v1/wizard/apply` is the only write path:
@@ -185,16 +220,76 @@ effect):
 
 | `extendedSteps` | Steps | Layout |
 |---|---|---|
-| `false` | 7 | `editor → personality → cost → roadmap-quality → memory → user-md → review` |
-| `true`  | 9 | `ai-tools → packs → editor → personality → cost → roadmap-quality → memory → user-md → review` |
+| `false` | 9 | `welcome → editor → personality → cost → roadmap-quality → memory → ai-council → user-md → review` |
+| `true`  | 13 | `welcome → ai-tools → roles → packs → editor → personality → cost → roadmap-quality → memory → ai-council → user-md → modules → review` |
+
+The project-specific `modules` step (writes `.agent-project-settings.yml`, not
+the global `.agent-settings.yml`) sits at the **end** of the extended flow,
+just before `review` — global/user settings come first, the project step
+comes last. Because it is no longer part of the install-only lead,
+`setup` mode now walks it too (the lead it skips is `ai-tools → roles →
+packs`).
+
+The `welcome` step (Step 1, both modes) collects **name + language** up front —
+pulled out of the user-md step so the agent knows who it's talking to before
+anything else. Name pre-fills from the OS account (`GET /api/v1/ping`
+`systemUser`) when empty; language pre-fills from the browser locale
+(`navigator.language`) when no `.agent-user.yml` exists yet. In install mode
+the user-md step hides its name + language fields (collected here); setup mode
+skips the welcome step (it lands on the first settings step) and keeps those
+fields in the user-md form.
+
+The `roles` step presents the discovery **workspaces** as the *area*
+(Engineering, Product, Finance, Founder, GTM, Ops, …; the maintainer workspace
+is hidden) — each tile shows the area label, then advisory `example_roles`
+(e.g. Engineering → "Developer, CTO"; Finance → "CFO") and the description. The
+selected workspace ids become `.agent-user.yml` `role[]` (the example roles are
+UI hints, not the stored value) and recommend each domain's `default_packs` on
+the packs step. In install mode the user-md
+step therefore hides its role field (collected here instead); setup mode keeps
+the role field since it skips the roles step.
+
+The `ai-council` step (road-to-wizard-ux-improvements § Phase 8) configures the
+wizard-controlled scalar subset of `.ai-council.yml` (enable, per-member
+enable + low-impact, global transport mode, debate rounds, cost budget, the
+non-locked `decision_resolution` classes) via `GET`/`POST /api/v1/wizard/ai-council`;
+the file is written with comment-preserving `replaceScalar` edits.
 
 The step shapes themselves are declared in
-[`src/ui/wizard/steps.ts`](../../src/ui/wizard/steps.ts) — the two
-prepended lead steps (`ai-tools`, `packs`) carry no `paths` and use
-dedicated renderers in `WizardPage.tsx`. `getWizardSteps({ extended })`
-is the single resolver; the UI consumes the active list via
-`getActiveSteps()` / `activeTotalSteps()` so a server toggle takes
-effect on the next reload without a code change.
+[`src/ui/wizard/steps.ts`](../../src/ui/wizard/steps.ts) — the always-first
+`welcome` step plus the four extended-only lead steps (`ai-tools`, `roles`,
+`packs`, `modules`) carry no `paths` and use dedicated renderers in
+`WizardPage.tsx`.
+`getWizardSteps({ extended })` is the single resolver; the UI consumes the
+active list via `getActiveSteps()` / `activeTotalSteps()` so a server toggle
+takes effect on the next reload without a code change.
+
+### AI-tools / roles / packs selection rules (Steps 2-4)
+
+- **AI-tools pre-selection.** `detect-tools` returns `tools` (installed on the
+  machine) and `configured` (the user's prior selection, persisted to
+  `~/.event4u/agent-config/wizard-tools.json` on each real apply). On a repeat
+  run the wizard pre-selects exactly the `configured` tools; only on a genuine
+  first run (no prior selection) does it fall back to pre-selecting every
+  installed tool.
+- **Roles → packs recommendation.** Each selected role contributes its
+  workspace `default_packs`; the union pre-selects packs on Step 3 (plus
+  auto-detected project packs). The recommendation stops clobbering the
+  selection once the user manually edits a pack. Each pack tile also badges
+  the workspace(s) it belongs to (from the pack's `workspaces`), highlighting
+  the badges that match a role the user picked on Step 2.
+- **Step 2 framework persistence.** A language tile (`cluster`, e.g. PHP)
+  gates its framework children in the UI but never destroys their stored
+  selection. Turning a language off disables — but keeps checked — its
+  children, so a PHP off→on round-trip restores the exact Laravel-on /
+  Symfony-off choice. `resolveSelectedPacks()` filters disabled children at
+  submit time, so a remembered-but-gated framework is not installed.
+- **No-autodetect packs.** Some packs are never pre-selected from project
+  signals (`python` — a non-engineer may have python installed but not need
+  it). The pack stays available to tick manually.
+- **Empty-selection gate.** The AI-tools, roles, and packs steps each block
+  Next until at least one effective selection exists (≥ 1 tool, ≥ 1 role, and
+  ≥ 1 installable pack respectively).
 
 ### `GET /api/v1/wizard/state` payload
 

package/docs/decisions/ADR-013-discovery-frontmatter-contract.md

@@ -219,6 +219,33 @@ examples instead. No ADR-014 issued.
 
 Driven by [`agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md`](../../agents/roadmaps/monorepo-phase-1-frontmatter-metadata.md).
 
+### 2026-05-27 — Additive advisory `cluster:` key on packs
+
+Pack entries in [`config/discovery/packs.yml`](../../config/discovery/packs.yml)
+may carry an optional `cluster: <language-id>` field. It groups a framework
+pack under a programming-language tile in the setup wizard's capability-packs
+step (e.g. `laravel: cluster: php`, `react: cluster: typescript`). Like
+`requires_hint`, it is **advisory only** — the installer does not act on it; it
+drives the wizard UI's collapsible language→framework grouping. The value must
+be a known pack id (and not self-referential), enforced by
+[`scripts/lint_discovery_vocabulary.py`](../../scripts/lint_discovery_vocabulary.py)
+and emitted into the discovery manifest. Additive, no vocabulary rename.
+
+Driven by [`agents/roadmaps/road-to-wizard-ux-improvements.md`](../../agents/roadmaps/road-to-wizard-ux-improvements.md) § Phase 4 (AI-council-resolved: reuse `packs.yml` as the single source of truth rather than a second mapping file).
+
+### 2026-05-27 — Additive advisory `example_roles:` key on workspaces
+
+Workspace entries in [`config/discovery/workspaces.yml`](../../config/discovery/workspaces.yml)
+may carry an optional `example_roles: [<title>, …]` list of illustrative job
+titles (e.g. `engineering: [Developer, CTO]`, `finance: [CFO]`). The wizard's
+roles step shows the workspace as the *area* and these titles as examples under
+it. **Advisory and free-form** — NOT a closed vocabulary: the stored
+`.agent-user.yml` `role[]` is the workspace id, never these examples; nothing
+acts on the strings beyond display. Emitted into the discovery manifest;
+allowed by [`discovery-manifest.schema.json`](../contracts/discovery-manifest.schema.json).
+Additive, no vocabulary rename. (Same change cleaned the `finance` label from
+"Finance / CFO" to "Finance".)
+
 ## Cross-references
 
 - [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):

package/docs/decisions/ADR-021-deployment-shape.md

@@ -25,7 +25,7 @@ Companion artefacts:
 - Roadmap: [`agents/roadmaps/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/road-to-internal-ai-os-deployment.md)
 - Artefacts: [`packages/core/deploy/`](../../packages/core/deploy/)
 - Env contract: [`docs/deploy/env-vars.md`](../deploy/env-vars.md)
-- Council question (drafted, not invoked — no keys): [`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/old/council-question-deployment-shape.md)
+- Council question (drafted, not invoked — no keys): [`agents/tmp/council-question-deployment-shape.md`](../../agents/old/council-question-deployment-shape.md)
 - Predecessor ADR: [`ADR-016`](ADR-016-installer-architecture.md) — installer architecture (agent-mode protocol the GUI server wraps).
 
 ## Context
@@ -141,7 +141,7 @@ orchestrator-agnostic.
 ## Open questions (council-deferred)
 
 The accompanying council question file
-[`agents/tmp/council-question-deployment-shape.md`](../../agents/tmp/old/council-question-deployment-shape.md)
+[`agents/tmp/council-question-deployment-shape.md`](../../agents/old/council-question-deployment-shape.md)
 has not yet been run (no provider keys configured). A maintainer with
 keys should run it and either ratify or supersede this ADR.
 

package/docs/deploy/connector-setup.md

@@ -6,7 +6,7 @@
 > and Phase 3 (central policy) shipping first.
 >
 > Open design questions live in
-> [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/old/council-question-connector-scope.md).
+> [`agents/tmp/council-question-connector-scope.md`](../../agents/old/council-question-connector-scope.md).
 
 ## Audience
 
@@ -124,6 +124,6 @@ All of the above land in Phase 5, contingent on Phases 2 + 3.
 ## Cross-references
 
 - 🚧 Reserved ADR slot: `docs/decisions/ADR-025-connector-scope.md`.
-- Council question: [`agents/tmp/council-question-connector-scope.md`](../../agents/tmp/old/council-question-connector-scope.md).
+- Council question: [`agents/tmp/council-question-connector-scope.md`](../../agents/old/council-question-connector-scope.md).
 - Quickstart: [`quickstart.md`](quickstart.md).
 - Policy cookbook: [`policy-cookbook.md`](policy-cookbook.md).

package/docs/deploy/policy-cookbook.md

@@ -7,7 +7,7 @@
 > before code lands. Every section below is normative-once-shipped.
 >
 > Open design questions live in
-> [`agents/tmp/council-question-central-policy.md`](../../agents/tmp/old/council-question-central-policy.md).
+> [`agents/tmp/council-question-central-policy.md`](../../agents/old/council-question-central-policy.md).
 
 ## Audience
 
@@ -125,6 +125,6 @@ All of the above land in Phase 3. Until then, per-user
 ## Cross-references
 
 - 🚧 Reserved ADR slot: `docs/decisions/ADR-023-central-policy.md`.
-- Council question: [`agents/tmp/council-question-central-policy.md`](../../agents/tmp/old/council-question-central-policy.md).
+- Council question: [`agents/tmp/council-question-central-policy.md`](../../agents/old/council-question-central-policy.md).
 - Env contract: [`env-vars.md`](env-vars.md) (`POLICY_PATH`).
 - Quickstart: [`quickstart.md`](quickstart.md).

package/docs/examples/agent-user.example.md

@@ -8,7 +8,6 @@ role:
   - founder
   - engineer
 style:
-  formality: "informal"
   pace: "pragmatic"
 voice_sample: |
   Mach das einfach. Wenn unklar, frag im Council. Tokenverbrauch ist ok,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "4.3.0",
+    "version": "4.6.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/build_discovery_manifest.py

@@ -284,6 +284,7 @@ def _build(strict: bool) -> tuple[dict[str, Any], list[dict[str, Any]]]:
             "description": w["description"],
             "default_packs": list(w.get("default_packs") or []),
             **({"optional_packs": list(w["optional_packs"])} if w.get("optional_packs") else {}),
+            **({"example_roles": list(w["example_roles"])} if w.get("example_roles") else {}),
         }
         for w in workspaces
     ]
@@ -302,6 +303,8 @@ def _build(strict: bool) -> tuple[dict[str, Any], list[dict[str, Any]]]:
         }
         if p.get("requires_hint"):
             item["requires_hint"] = list(p["requires_hint"])
+        if p.get("cluster"):
+            item["cluster"] = p["cluster"]
         pk_out.append(item)
 
     if strict and unassigned:
@@ -546,6 +549,7 @@ def _packs_view(manifest: dict[str, Any]) -> dict[str, Any]:
                 "description": p["description"],
                 "workspaces": list(p.get("workspaces", [])),
                 "requires_hint": list(p.get("requires_hint", [])),
+                "cluster": p.get("cluster"),
                 "trust_level_default": p.get("trust_level_default"),
                 "artefact_count": len(ids),
                 "artefacts": ids,

package/scripts/condense.py

@@ -1060,6 +1060,59 @@ def generate_user_type_symlinks() -> int:
     return total
 
 
+def generate_plugin_hooks() -> int:
+    """Generate ``hooks/hooks.json`` at the plugin root from the hook manifest.
+
+    Claude Code plugins auto-discover hooks at ``<plugin-root>/hooks/hooks.json``
+    (Plugins reference). The agent-config plugin's source is the repo root
+    (``.claude-plugin/marketplace.json``), so the file lands at
+    ``PROJECT_ROOT/hooks/hooks.json``.
+
+    Delivering the Claude lifecycle hooks via **plugin scope** — instead of
+    writing them into the shared ``.claude/settings.json`` ``hooks`` array —
+    means no shared ``hooks`` array in any settings file, so there is no
+    collision with a neighbour tool's hooks or with a developer's
+    ``settings.local.json``. Claude Code merges plugin-scope and
+    settings-scope hooks and dedups by command string.
+
+    The command is rooted at ``$CLAUDE_PROJECT_DIR`` so it resolves from
+    plugin scope regardless of cwd; the universal dispatcher then reads
+    ``scripts/hook_manifest.yaml`` at runtime to fan out to the active
+    concerns (each a no-op when its feature is disabled).
+    """
+    manifest_path = PROJECT_ROOT / "scripts" / "hook_manifest.yaml"
+    if not manifest_path.exists():
+        print("  ⚠️  scripts/hook_manifest.yaml not found — skipping plugin hooks",
+              file=sys.stderr)
+        return 0
+
+    manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) or {}
+    claude_events = manifest.get("platforms", {}).get("claude", {}) or {}
+    aliases = manifest.get("native_event_aliases", {}).get("claude", {}) or {}
+    # Reverse the native→agent-config map so we can emit native event names.
+    ac_to_native = {ac: native for native, ac in aliases.items()}
+
+    hooks: dict[str, list] = {}
+    for ac_event, concerns in claude_events.items():
+        if not concerns:
+            continue
+        native = ac_to_native.get(ac_event)
+        if native is None:
+            continue
+        command = (
+            '"$CLAUDE_PROJECT_DIR"/agent-config dispatch:hook '
+            f"--platform claude --event {ac_event} --native-event {native}"
+        )
+        hooks[native] = [{"hooks": [{"type": "command", "command": command}]}]
+
+    hooks_dir = PROJECT_ROOT / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    out = hooks_dir / "hooks.json"
+    out.write_text(json.dumps({"hooks": hooks}, indent=2) + "\n", encoding="utf-8")
+    info(f"  ✅  Generated hooks/hooks.json ({len(hooks)} Claude plugin hooks)")
+    return len(hooks)
+
+
 def generate_tools() -> None:
     """Generate all tool-specific directories and files.
 
@@ -1074,6 +1127,7 @@ def generate_tools() -> None:
         generate_gemini_md()
     skills = generate_claude_skills() if _tool_active("claude-code") else 0
     commands = generate_claude_commands() if _tool_active("claude-code") else 0
+    plugin_hooks = generate_plugin_hooks() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
     user_types = generate_user_type_symlinks()
     cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
@@ -1082,7 +1136,8 @@ def generate_tools() -> None:
     windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas} user_types={user_types} "
+        f"commands={commands} plugin_hooks={plugin_hooks} "
+        f"personas={personas} user_types={user_types} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
         f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
         f"windsurfrules={windsurfrules}"

package/scripts/condense_memory.py

@@ -37,6 +37,11 @@ RE_NUMBERED = re.compile(r"^>?\s*\d+\.\s")
 RE_STATUS = re.compile(r"^\s*(?:❌|⚠️|✅)")
 RE_IRONLAW = re.compile(r"^[A-Z][A-Z0-9 ,.\-_/']{3,}$")
 RE_BACKTICK_SPAN = re.compile(r"`[^`\n]+`")
+# Spans frozen byte-for-byte inside prose lines. Backtick spans first so a
+# slash-bearing span inside backticks is captured whole; then any non-whitespace
+# run containing `/` or `\` — bare URLs, markdown link/image targets, and file
+# paths whose segments (`is`, `the`, `a`) would otherwise be eaten as drop-tokens.
+RE_PRESERVE_SPAN = re.compile(r"`[^`\n]+`|\S*[/\\]\S*")
 RE_FRONTMATTER = re.compile(r"^---\s*$")
 WORD_RE = re.compile(r"\b[A-Za-z]+\b")
 DROP_TOKENS = {"the", "a", "an", "is", "are", "was", "were", "be", "been",
@@ -50,10 +55,11 @@ def _condense_words(text: str) -> str:
 
 
 def _condense_prose_line(line: str) -> str:
-    """Condense a prose line; preserve backtick-spans byte-for-byte."""
+    """Condense a prose line; preserve backtick spans, URLs, link targets, and
+    slash-bearing paths byte-for-byte (see ``RE_PRESERVE_SPAN``)."""
     parts: list[str] = []
     last = 0
-    for span in RE_BACKTICK_SPAN.finditer(line):
+    for span in RE_PRESERVE_SPAN.finditer(line):
         parts.append(_condense_words(line[last:span.start()]))
         parts.append(span.group(0))
         last = span.end()

package/scripts/install.py

@@ -32,6 +32,7 @@ import os
 import re
 import shlex
 import shutil
+import signal
 import subprocess
 import sys
 import threading
@@ -1082,52 +1083,25 @@ def ensure_augment_user_hooks(package_root: Path, force: bool) -> list[dict[str,
 # concern fires on the same logical surface across platforms — the
 # contract from agents/settings/contexts/hardening-pattern.md § Cross-platform
 # parity.
-CLAUDE_DISPATCHER_BINDINGS = (
-    ("session_start",      "SessionStart"),
-    ("session_end",        "SessionEnd"),
-    ("stop",               "Stop"),
-    ("user_prompt_submit", "UserPromptSubmit"),
-    ("post_tool_use",      "PostToolUse"),
-)
-
-
-def _claude_dispatch_block(ac_event: str, native: str) -> dict:
-    """Single hook entry routing the event through the universal dispatcher."""
-    return {
-        "hooks": [
-            {
-                "type": "command",
-                "command": (
-                    f"./agent-config dispatch:hook "
-                    f"--platform claude --event {ac_event} "
-                    f"--native-event {native}"
-                ),
-            },
-        ],
-    }
-
-
 def ensure_claude_bridge(project_root: Path, force: bool) -> list[dict[str, Any]]:
-    """Deploy .claude/settings.json with plugin enablement and the Phase 7
-    universal dispatcher hooks.
-
-    Each Claude Code lifecycle event is wired to a single
-    `./agent-config dispatch:hook` invocation. The dispatcher reads
-    scripts/hook_manifest.yaml at runtime and runs the resolved concern
-    chain — concerns are no-ops when the relevant feature is disabled
-    in .agent-settings.yml. Idempotent: reruns merge cleanly without
-    duplicating entries (deep_merge replaces hook arrays rather than
-    appending).
+    """Deploy .claude/settings.json with plugin enablement only.
+
+    Claude lifecycle hooks are delivered via **plugin scope**
+    (`hooks/hooks.json`, generated by `condense.generate_plugin_hooks`), not
+    written into the shared `.claude/settings.json` `hooks` array. Writing
+    them here would monopolise that array and collide with any neighbour
+    tool's hooks or a developer's `settings.local.json` — Claude Code merges
+    plugin-scope and settings-scope hooks at runtime and dedups by command
+    string, so plugin delivery needs no `hooks` block here.
+
+    The plugin id matches `.claude-plugin/marketplace.json`
+    (`<plugin>@<marketplace>` = `agent-config@event4u-agent-config`) and the
+    documented install command in docs/installation.md. Idempotent:
+    `enabledPlugins` is a dict-merge, so the key coexists with any other
+    plugin a neighbour tool enabled.
     """
-    per_event: dict[str, list] = {}
-    for ac_event, native in CLAUDE_DISPATCHER_BINDINGS:
-        per_event.setdefault(native, []).append(
-            _claude_dispatch_block(ac_event, native)
-        )
-
     bridge = {
-        "enabledPlugins": {"agent-conf@event4u": True},
-        "hooks": per_event,
+        "enabledPlugins": {"agent-config@event4u-agent-config": True},
     }
     return merge_json_file(
         project_root / ".claude" / "settings.json", bridge, force, ".claude/settings.json",
@@ -4335,6 +4309,75 @@ def _wizard_cli_dist(project_root: Path) -> Path | None:
     return cli if cli.exists() else None
 
 
+def _server_info_path() -> Path:
+    """Path of the running-server record written by `ui:serve`."""
+    return Path.home() / ".event4u" / "agent-config" / "local-server.json"
+
+
+def _pid_is_agent_config(pid: int) -> bool:
+    """Best-effort check that `pid` is one of our wizard servers.
+
+    Guards against signalling an unrelated process that recycled the pid.
+    Uses `ps` (POSIX); on platforms without it we conservatively return
+    False so we never kill the wrong process.
+    """
+    try:
+        out = subprocess.run(  # noqa: S603,S607 - fixed argv, pid is an int
+            ["ps", "-p", str(pid), "-o", "command="],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return "agent-config" in out.stdout.lower()
+
+
+def _kill_stale_wizard_server() -> None:
+    """Terminate a previously-launched wizard server, if one is recorded.
+
+    `agent-config init` should always start fresh: a stale server (left
+    from an earlier run) is stopped so the new instance owns the port and
+    the wizard re-enters at step 1. Best-effort — every failure is ignored.
+    """
+    path = _server_info_path()
+    try:
+        info = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return
+    pid = info.get("pid")
+    if not isinstance(pid, int):
+        path.unlink(missing_ok=True)
+        return
+    try:
+        os.kill(pid, 0)  # liveness probe
+    except OSError:
+        path.unlink(missing_ok=True)  # already gone
+        return
+    if not _pid_is_agent_config(pid):
+        return  # pid reused by an unrelated process — leave it alone
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        path.unlink(missing_ok=True)
+        return
+    # Wait up to ~3s for a graceful exit, then force-kill.
+    for _ in range(30):
+        try:
+            os.kill(pid, 0)
+        except OSError:
+            break
+        time.sleep(0.1)
+    else:
+        try:
+            os.kill(pid, getattr(signal, "SIGKILL", signal.SIGTERM))
+        except OSError:
+            pass
+    path.unlink(missing_ok=True)
+    print("(Stopped the previous wizard server.)")
+
+
 def _wizard_spawn(project_root: Path) -> int:
     """Spawn the wizard, await readiness, hand off to the child.
 
@@ -4343,6 +4386,9 @@ def _wizard_spawn(project_root: Path) -> int:
     Never raises into the parent — every error surfaces as a printed
     fallback line and a 0 return.
     """
+    # Always start fresh: stop any server left running by a prior init.
+    _kill_stale_wizard_server()
+
     cli = _wizard_cli_dist(project_root)
     if cli is None:
         print(

package/scripts/lint_discovery_vocabulary.py

@@ -101,6 +101,14 @@ def lint(quiet: bool) -> int:
         for hint in pk.get("requires_hint", []) or []:
             if hint not in pack_ids:
                 errors.append(f"packs.yml '{pid}'.requires_hint → unknown pack '{hint}'")
+        # cluster (road-to-wizard-ux-improvements § Phase 4): advisory wizard
+        # grouping; the value must be a known pack id and not self-referential.
+        cluster = pk.get("cluster")
+        if cluster is not None:
+            if cluster not in pack_ids:
+                errors.append(f"packs.yml '{pid}'.cluster → unknown pack '{cluster}'")
+            elif cluster == pid:
+                errors.append(f"packs.yml '{pid}'.cluster → must not reference itself")
 
     # 4. Bidirectional integrity (council HIGH fold-in).
     pack_by_id = {pk.get("id"): pk for pk in packs}