@event4u/agent-config 3.0.0 → 3.1.0

package/docs/maintainers/dev-mode.md

@@ -0,0 +1,105 @@
+# Maintainer Dev Mode (`AGENT_CONFIG_DEV_MODE=1`)
+
+**Audience.** Maintainers of `@event4u/agent-config` working **inside**
+the package repo. Consumers never see this flag; consumer installs
+land in `~/.event4u/agent-config/` per [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md).
+
+**Status.** Forward-looking — the gate ships in Phase 3 of the
+`road-to-global-only-install` roadmap. This document is the
+canonical reference once Phase 3 lands.
+
+## Why the flag exists
+
+Phase 3 of `road-to-global-only-install` flips `SCOPE_SUPPORT` so that
+**every** consumer scope on `scripts/install.py` is global. The
+package repo itself is structurally identical to a consumer repo
+(same `.augment/`, `.claude/`, `.cursor/` projection layout) which
+means maintainer dev-installs would otherwise be blocked by the same
+gate.
+
+`AGENT_CONFIG_DEV_MODE=1` is the explicit, audit-visible opt-out.
+With the flag set, the installer:
+
+1. Allows project-scope writes back into the repo tree (so a
+   maintainer can run `task dev:install-global` and iterate on the
+   working copy).
+2. **Skips** writing `agents/.event4u-bridge.yml` into the package
+   repo (per `consumer-bridge § Writer contract`). The repo is the
+   source, not a consumer of itself.
+3. Treats `~/.event4u/agent-config/` as a peer install — touches are
+   limited to the working-copy projection.
+
+Without the flag, `scripts/install.py` refuses to write anywhere
+under the repo tree and points at this document.
+
+## When to set it
+
+Set the flag for these workflows, and **only** these:
+
+- `task dev:install-global` — refresh the user-scope projection from the working tree.
+- `task dev:install:gui` — iterate the unified Setup-Wizard / Installer-GUI before merge.
+- `task dev:setup` / `task dev:setup:dry-run` — exercise the onboarding wizard.
+- `task release` rehearsal — verify the published shape matches the dev shape.
+
+Do **not** set it for:
+
+- Consumer project work (the flag is undefined behaviour outside this repo).
+- CI runs on the package itself (CI uses the flag transparently via the dev tasks above; bare runs MUST NOT export it).
+- Production maintainer machines that also consume the package as a user (set per-shell, not in `~/.zshrc`).
+
+## How to set it
+
+Per-command (preferred):
+
+```bash
+AGENT_CONFIG_DEV_MODE=1 task dev:install-global
+```
+
+Per-shell session:
+
+```bash
+export AGENT_CONFIG_DEV_MODE=1
+task dev:install:gui
+unset AGENT_CONFIG_DEV_MODE
+```
+
+The `unset` discipline matters: a stale `=1` in your shell environment
+is the most common way a project-scope write sneaks into a consumer
+repo. Future work (`agent-config doctor`, Phase 5.4) will warn when
+the flag is set outside the package repo.
+
+## Safety properties
+
+- **Audit-visible.** Every install run logs whether the flag was set
+  at the top of the transaction log.
+- **No silent fallback.** If `scripts/install.py` detects the
+  package repo signature (presence of `.agent-src.uncompressed/` plus
+  `dist/router.json`) and the flag is **not** set, the install
+  refuses with a one-line error pointing here.
+- **Not for consumers.** Setting the flag in a consumer project is
+  defined as undefined behaviour. The installer will not actively
+  refuse (because it cannot distinguish a misconfigured shell from a
+  legitimate vendored maintainer install), but it will print a single
+  warning line on every run.
+
+## Interaction with the bridge marker
+
+Per [`consumer-bridge`](../contracts/consumer-bridge.md), the bridge
+marker is the in-repo pointer to the global root. Under
+`AGENT_CONFIG_DEV_MODE=1`:
+
+- The marker is **not** written into the package repo — the repo's
+  `agents/` directory is the project surface, not a consumer surface.
+- A pre-existing marker in the package repo is treated as stale and
+  removed on the next dev install (with an audit log line).
+- Consumer adapters reading the marker from inside the package repo
+  during local development should expand `global_root` against the
+  current user's `$HOME` per the reader contract — same as in a
+  consumer repo.
+
+## References
+
+- [ADR-020](../decisions/ADR-020-global-only-consumer-scope.md) — the global-only decision.
+- [`consumer-bridge`](../contracts/consumer-bridge.md) — bridge marker schema.
+- [`road-to-global-only-install`](../../agents/roadmaps/road-to-global-only-install.md) — Phase 3 SCOPE_SUPPORT flip + Phase 5 migration order.
+- [`taskfiles/dev.yml`](../../taskfiles/dev.yml) — `dev:install-global`, `dev:install:gui`, `dev:setup` task entries.

package/docs/setup/per-ide/claude-desktop.md

@@ -9,8 +9,9 @@ server inside Claude Desktop. macOS / Windows / Linux. ~10 minutes.
 > ZIP per skill under
 > `~/.event4u/agent-config/claude-desktop/bundles/` so you can drag /
 > drop them into the Customize panel. The v1 npm / composer install
-> scheme is retired; the new global-first scheme is ADR-007 and writes
-> through `~/.event4u/agent-config/installed.lock` (legacy
+> scheme is retired; the current global-only scheme follows ADR-007 +
+> [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md) and
+> writes through `~/.event4u/agent-config/installed.lock` (legacy
 > `~/.config/agent-config/installed.lock` read as fallback).
 
 ## Prerequisites

package/docs/wizard.md

@@ -83,10 +83,30 @@ for the full failure-mode matrix.
 
 ## Auto-launch from `npx … init`
 
-Tracked under
-[`agents/roadmaps/wizard-install-py-wiring.md`](../agents/roadmaps/wizard-install-py-wiring.md)
-(carved out from the parent roadmap). Until that ships, run
-`agent-config ui:serve --open` manually after `npx … init`.
+`scripts/install.py` acts as a supervisor at the tail of a successful
+install: it evaluates a gate (TTY, `CI`, `--no-ui`,
+`AGENT_CONFIG_NO_UI`), then spawns `node <pkg>/.../cli.js gui
+--project-root <root>` and waits for the child's
+`WIZARD_READY url=<http://127.0.0.1:PORT/>` handshake on stdout
+(strict regex
+`^WIZARD_READY url=(http://(?:127\.0\.0\.1|localhost):\d+/)\r?$`).
+On match, the parent prints a banner and blocks on the child until
+the user closes the tab or sends Ctrl-C.
+
+Progressive readiness backoff: `10s → 20s → 40s → 80s` (cumulative
+budget 150s) — generous enough for cold-start `node_modules`
+extraction on slow disks. On timeout the parent kills the child,
+prints the last 20 stderr lines, and exits 0 — the install itself
+is unaffected.
+
+Suppress the auto-launch with `--no-ui`, `AGENT_CONFIG_NO_UI=1`, or
+by running in CI (`CI=1`). Preview the gate verdict without
+installing anything via `python3 scripts/install.py --dry-run`,
+which prints a plan summary and exits 0 with zero filesystem
+writes.
+
+Skill: [`agents/roadmaps/archive/wizard-install-py-wiring.md`](../agents/roadmaps/archive/wizard-install-py-wiring.md)
+(archived after ship).
 
 ## Accessibility
 
@@ -99,6 +119,21 @@ Tracked under
   receives `tabIndex={-1}` and `.focus()` so screen readers
   announce the new heading.
 
+## Headless / CI / no-browser
+
+When the wizard cannot or should not open — CI runs, SSH sessions
+without X forwarding, headless servers, automated provisioning —
+take the flag path instead. Three equivalent ways to suppress the
+GUI: pass `--no-ui` to `npx … init`, export `AGENT_CONFIG_NO_UI=1`
+in the environment, or run inside a `CI=1` context (auto-detected).
+With the GUI suppressed, pass profile + pack on the command line —
+`npx -y @event4u/agent-config init --no-ui --profile=developer
+--pack=engineering-base` — or hand-edit `.agent-settings.yml`
+directly. Preview the gate verdict and the planned writes with
+`python3 scripts/install.py --dry-run` (zero filesystem writes,
+exits 0). Settings can still be hand-edited at any time; the GUI
+is opt-in, not required.
+
 ## Disabling the GUI
 
 Set `AGENT_CONFIG_NO_UI=1` in the environment to skip every

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "3.0.0",
+    "version": "3.1.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,
@@ -13,6 +13,21 @@
         "url": "https://github.com/event4u-app/agent-config/issues"
     },
     "homepage": "https://github.com/event4u-app/agent-config#readme",
+    "keywords": [
+        "ai-agent",
+        "mcp",
+        "claude-code",
+        "cursor",
+        "windsurf",
+        "copilot",
+        "llm",
+        "agent-governance",
+        "ai-video",
+        "skills",
+        "prompt-engineering",
+        "typescript",
+        "python"
+    ],
     "files": [
         ".agent-src/",
         ".augment-plugin/",
@@ -60,6 +75,8 @@
         }
     },
     "devDependencies": {
+        "@inquirer/prompts": "^7.10.1",
+        "@playwright/test": "^1.60.0",
         "@preact/preset-vite": "^2.10.5",
         "@testing-library/preact": "^3.2.4",
         "@types/js-yaml": "^4.0.9",

package/scripts/_cli/cmd_doctor.py

@@ -17,14 +17,21 @@ Drift categories (manifest ↔ filesystem):
   (P5.2). Hand-edited tags or accidental cross-package writes show up
   here; files without frontmatter are skipped (P5.1 contract).
 
-Health checks (nine categories, see :data:`CHECK_IDS`):
+Health checks (see :data:`CHECK_IDS`):
 scope · manifest-integrity · lockfile-freshness · bridge-drift ·
 mcp-mode · mcp-beta-readiness · offline-readiness · python-runtime ·
-unsupported-combos.
+tier-usage-readiness · council-cli · unsupported-combos ·
+wizard-state.
 Each emits a structured ``{id, status, message, remedy}`` record with
 ``status`` ∈ ``ok`` / ``warn`` / ``fail`` (rendered ``✅`` / ``⚠️`` /
 ``❌``). ``--check <id>`` runs a single check.
 
+Repair affordances: ``--repair wizard-state`` resets a malformed or
+orphaned ``state/wizard-state.json`` under the user-global root (the
+file the unified Setup-Wizard uses for resume continuity). Used as the
+recovery path when ``1.9``'s npm downgrade is not viable
+(road-to-global-only-install § 1.10 / A6).
+
 Exit codes: ``0`` (clean) · ``1`` (drift or any ``fail`` check) · ``2``
 (error such as "manifest missing"). Both human and ``--json`` output
 emit the drift category lists and the structured checks array. Every
@@ -443,8 +450,16 @@ CHECK_IDS = (
     "tier-usage-readiness",
     "council-cli",
     "unsupported-combos",
+    "wizard-state",
 )
 
+#: Repair targets that ``--repair <id>`` accepts. Each id maps to a
+#: function in :func:`_run_repair` that resets the named artefact and
+#: returns an exit code. Additive set: introduce by adding a new id
+#: here, a runner inside :func:`_run_repair`, and (optionally) a
+#: matching health check above.
+REPAIR_IDS = ("wizard-state",)
+
 #: Six gates that govern the MCP `experimental → beta` promotion. The
 #: artefact path under each gate id mirrors `tests/test_mcp_beta_gates.py`
 #: and the contract in `docs/contracts/mcp-beta-criteria.md`.
@@ -983,6 +998,88 @@ def _check_unsupported_combos(manifest: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _wizard_state_path() -> Path:
+    """Return the on-disk location of the unified Setup-Wizard state file.
+
+    Mirrors ``STATE_REL`` in :mod:`src/server/routes/wizard.ts` — the
+    server writes ``<writeRoot>/state/wizard-state.json``. Under the
+    global-only install scope (ADR-020) ``writeRoot`` resolves to
+    :func:`user_global_paths.event4u_root` (typically
+    ``~/.event4u/agent-config/``); the ``EVENT4U_CONFIG_HOME`` override
+    is honoured implicitly so tests stay hermetic.
+    """
+    from scripts._lib.user_global_paths import event4u_root
+    return event4u_root() / "state" / "wizard-state.json"
+
+
+def _check_wizard_state() -> dict[str, Any]:
+    """Health-check the resumable Setup-Wizard state file.
+
+    Returns ``ok`` when the file is absent (no active session) or when
+    its JSON shape matches the contract from
+    :mod:`src/server/routes/wizard.ts` (``step: int``, ``partial: dict``,
+    optional ``totalSteps: int``, ``startedAt: str | null``).
+    Returns ``fail`` when the file exists but is unreadable, not valid
+    JSON, or violates the shape — ``--repair wizard-state`` resets it.
+    """
+    state_pth = _wizard_state_path()
+    if not state_pth.exists():
+        return {
+            "id": "wizard-state", "status": "ok",
+            "message": "no active wizard session",
+            "remedy": "",
+        }
+    try:
+        raw = state_pth.read_text(encoding="utf-8")
+    except OSError as exc:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"unreadable wizard-state at {state_pth}: {exc}",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"malformed JSON in wizard-state ({exc.msg} at line {exc.lineno})",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    if not isinstance(data, dict):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state root is {type(data).__name__}, expected object",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    step = data.get("step")
+    partial = data.get("partial", {})
+    if not isinstance(step, int) or step < 0:
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.step is {step!r}, expected non-negative integer",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    if not isinstance(partial, dict):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.partial is {type(partial).__name__}, expected object",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    total = data.get("totalSteps")
+    if total is not None and (not isinstance(total, int) or total < 1):
+        return {
+            "id": "wizard-state", "status": "fail",
+            "message": f"wizard-state.totalSteps is {total!r}, expected positive integer or omitted",
+            "remedy": "agent-config doctor --repair wizard-state",
+        }
+    suffix = f" of {total}" if isinstance(total, int) else ""
+    return {
+        "id": "wizard-state", "status": "ok",
+        "message": f"resumable wizard session at step {step + 1}{suffix}",
+        "remedy": "",
+    }
+
+
 def _run_checks(
     project_root: Path,
     manifest: dict[str, Any],
@@ -1008,6 +1105,7 @@ def _run_checks(
         "tier-usage-readiness": lambda: _check_tier_usage_readiness(project_root),
         "council-cli": lambda: _check_council_cli(project_root),
         "unsupported-combos": lambda: _check_unsupported_combos(manifest),
+        "wizard-state": _check_wizard_state,
     }
     out: list[dict[str, Any]] = []
     for cid in CHECK_IDS:
@@ -1115,6 +1213,14 @@ def _parse(argv: list[str]) -> argparse.Namespace:
               "layer chain, wrapper, and install-mode; short-circuits "
               "the drift report"),
     )
+    parser.add_argument(
+        "--repair", default=None, metavar="ID",
+        choices=list(REPAIR_IDS),
+        help=("reset a recoverable artefact and exit "
+              f"({' · '.join(REPAIR_IDS)}); short-circuits the drift "
+              "report. Idempotent — absent files report 'nothing to "
+              "repair' and exit 0."),
+    )
     return parser.parse_args(argv)
 
 
@@ -1165,8 +1271,50 @@ def _run_context(opts: argparse.Namespace) -> int:
     return 0
 
 
+def _run_repair(opts: argparse.Namespace) -> int:
+    """Handle ``--repair <id>``: reset the named artefact, no drift report.
+
+    Currently the only target is ``wizard-state`` — unlinks the
+    resumable session file so the next ``agent-config setup`` boots
+    from step 1. Absent files are a no-op (idempotent re-run).
+    """
+    target = opts.repair
+    if target == "wizard-state":
+        state_pth = _wizard_state_path()
+        payload = {
+            "id": "wizard-state",
+            "path": str(state_pth),
+            "action": "remove" if state_pth.exists() else "noop",
+        }
+        if state_pth.exists():
+            try:
+                state_pth.unlink()
+            except OSError as exc:
+                payload["action"] = "error"
+                payload["error"] = str(exc)
+                if opts.json:
+                    print(json.dumps(payload, indent=2))
+                else:
+                    print(f"❌  doctor: could not remove {state_pth}: {exc}",
+                          file=sys.stderr)
+                return 2
+        if opts.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            if payload["action"] == "remove":
+                print(f"✅  doctor: reset wizard-state ({state_pth})")
+            else:
+                print(f"✅  doctor: nothing to repair (no wizard-state at {state_pth})")
+        return 0
+    # argparse `choices=` already constrains target; defensive default.
+    print(f"❌  doctor: unknown repair target {target!r}", file=sys.stderr)
+    return 2
+
+
 def main(argv: list[str] | None = None) -> int:
     opts = _parse(list(argv) if argv is not None else sys.argv[1:])
+    if opts.repair is not None:
+        return _run_repair(opts)
     if opts.trace_root:
         return _run_trace_root(opts)
     if opts.context:

package/scripts/_cli/cmd_explain.py

@@ -42,6 +42,7 @@ from scripts._lib.agent_settings import (
 from scripts.config import presets, profiles
 
 ROUTER_FILENAME = "router.json"
+ROUTER_RELATIVE = Path("dist") / ROUTER_FILENAME
 
 
 def _resolve_root(arg: str | None) -> tuple[Path, str]:
@@ -60,7 +61,7 @@ def _load_user_settings(project_root: Path) -> dict[str, Any]:
 
 
 def _load_router(project_root: Path) -> dict[str, Any]:
-    path = project_root / ROUTER_FILENAME
+    path = project_root / ROUTER_RELATIVE
     if not path.exists():
         return {}
     try: