@event4u/agent-config 1.41.1 → 2.0.0

package/docs/migration/v1-to-v2.md

@@ -0,0 +1,98 @@
+# Migration — v1 → v2 (npx-only runtime)
+
+> **Status:** skeleton. The one-shot `npx @event4u/agent-config migrate`
+> is implemented in P3.5 of
+> [`road-to-portable-runtime-and-update-check`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md);
+> this document tracks the user-facing cutover contract so consumers can
+> rehearse the change before the command lands.
+
+## Why this change
+
+v2 retires the local-install scheme (Composer dependency, npm
+`postinstall`, `--global` symlink namespace under `~/.claude/`,
+`~/.cursor/`, `~/.codeium/windsurf/`, `~/.config/agent-config/`) in
+favour of an **npx-only runtime**. The trade-off and the council's Q1
+rejection + the user's override are recorded in
+[`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance).
+
+## TL;DR
+
+```bash
+npx @event4u/agent-config migrate
+```
+
+One command, idempotent. Re-runs on an already-migrated repo do nothing.
+
+## What disappears from the consumer
+
+| Path / entry                                          | Reason                                  |
+|-------------------------------------------------------|-----------------------------------------|
+| `composer.json` → `require-dev.event4u/agent-config`  | No Composer dependency under v2.        |
+| `composer.lock` line for `event4u/agent-config`       | Same; lockfile updated by Composer.     |
+| `package.json` → `devDependencies.@event4u/agent-config` | No npm dependency under v2.          |
+| `package-lock.json` / `pnpm-lock.yaml` entries        | Same.                                   |
+| `node_modules/@event4u/agent-config/`                 | Removed by the package manager once the `package.json` entry is gone. |
+| `vendor/event4u/agent-config/`                        | Removed by Composer once the require entry is gone. |
+| `~/.claude/{rules,skills}/event4u/`                   | Retired `--global` namespace dir.       |
+| `~/.cursor/rules/imported/event4u/`                   | Same.                                   |
+| `~/.codeium/windsurf/global_workflows/event4u/`       | Same.                                   |
+| `~/.config/agent-config/{rules,skills}/event4u/`      | Same (fallback path).                   |
+| Legacy `.gitignore` block lines marked `event4u/agent-config (legacy local install)` | Replaced by the v2 block written by `sync-gitignore`. |
+
+The retired `templates/global-install-manifest.yml` shipped inside the
+package and is gone in v2; consumers never carried it directly.
+
+## What appears in the consumer
+
+| Path / entry                                          | Owner / shape                           |
+|-------------------------------------------------------|-----------------------------------------|
+| `.agent-settings.yml` → `agent_config_version: "<pin>"` | Project version pin, reviewed in PRs. |
+| `.agent-settings.yml` → `update_check:` block         | Defaults shipped by `init`; opt-out per knob. |
+| Updated `.gitignore` block                            | v2 entries written by `sync-gitignore`. |
+
+The per-tool glue (`.claude/`, `.cursor/`, `.clinerules/`,
+`.windsurfrules`, `GEMINI.md`, `.github/copilot-instructions.md`,
+`.augment/`, `.vscode/settings.json`) keeps the same shape as v1 — only
+the source that writes them changed (from `vendor/` /
+`node_modules/` scripts to the npx-resolved runtime).
+
+## The `migrate` command — contract sketch
+
+```bash
+npx @event4u/agent-config migrate              # interactive, default
+npx @event4u/agent-config migrate --dry-run    # plan only, no writes
+npx @event4u/agent-config migrate --yes        # non-interactive
+```
+
+Order of operations (locked once P3.5 lands):
+
+1. Detect pre-v2 markers: `composer.json` require entry,
+   `package.json` devDependency, `vendor/event4u/agent-config/`,
+   `node_modules/@event4u/agent-config/`, legacy `.gitignore` lines,
+   `~/.claude/{rules,skills}/event4u/` and siblings.
+2. Print the planned change set (file removals, file writes, pin
+   value). Stop here under `--dry-run`.
+3. Remove dependency entries via the appropriate package manager
+   (`composer remove`, `npm uninstall` / `pnpm remove` / `yarn remove`).
+4. Wipe the retired user-scope `event4u/` namespace dirs.
+5. Write / update `.agent-settings.yml` with the new shape +
+   `agent_config_version` pin.
+6. Re-run `sync-gitignore` to refresh the project `.gitignore` block.
+7. Print a one-screen post-migration verification list.
+
+Idempotency: each step is a no-op when the v1 marker is absent. Re-runs
+print *"already on v2 — nothing to do"* and exit 0.
+
+## Verification after migration
+
+```bash
+npx @event4u/agent-config doctor    # P3 — runtime sanity check
+```
+
+Expected: pin resolved, no v1 markers detected, `update_check` reachable.
+
+## See also
+
+- [`docs/architecture.md` § Distribution model](../architecture.md#distribution-model--npx-only--version-pin-governance) — Q1 council rejection + override + pin substitution.
+- [`agents/roadmaps/road-to-portable-runtime-and-update-check.md`](../../agents/roadmaps/road-to-portable-runtime-and-update-check.md) — full delivery plan and acceptance criteria.
+- [`docs/installation.md`](../installation.md) — v2 install reference.

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

@@ -29,23 +29,6 @@ Either form populates:
 - `CLAUDE.md`               — agent root pointer (auto-loaded by Claude Code)
 - `.agent-settings.yml`     — your per-project knobs (kept out of git)
 
-## Global install (cross-project skills)
-
-```bash
-npx @event4u/agent-config global --tools=claude-code
-```
-
-Seeds `~/.claude/skills/` with the curated top-N skills from
-[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
-Available across every project on the machine; project-level files
-always take precedence.
-
-Uninstall:
-
-```bash
-npx @event4u/agent-config global --uninstall
-```
-
 ## Plugin marketplace (Claude Code 2026+)
 
 Claude Code 2026 supports plugin marketplaces via

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

@@ -3,56 +3,46 @@
 The fastest path to running our skills, rules, and (optionally) the MCP
 server inside Claude Desktop. macOS / Windows / Linux. ~5 minutes.
 
-> **TL;DR** — install the package globally with `--global` so the
-> kernel rules and the curated top-N skills land in `~/.claude/`,
-> then restart Claude Desktop. The slash-command menu picks them up
-> automatically.
+> **TL;DR** — run `npx @event4u/agent-config init --tools=claude-code`
+> inside each project that should expose the skills/rules to Claude
+> Desktop. The package now ships as an npx-resolved runtime; the
+> retired `--global` symlink scheme has been removed.
 
 ## Prerequisites
 
 - Claude Desktop installed (free or paid plan — same install path).
-- Node ≥ 18 *or* a clone of the `event4u/agent-config` repo
-  (either route can run `--global`).
+- Node ≥ 18 (`npx` resolves the package per-project).
 - 5 minutes.
 
-## Step 1 — global install
+## Step 1 — project-local install
 
-Pick whichever entrypoint matches your environment. Both seed the same
-files under `~/.claude/`.
+Run inside each project that should be visible to Claude Desktop:
 
 ```bash
-# Node — no clone needed.
-npx @event4u/create-agent-config --global --tools=claude-code
-
-# Or via curl (no Node).
-curl -fsSL https://raw.githubusercontent.com/event4u/agent-config/main/setup.sh \
-  | bash -s -- --global --tools=claude-code
-
-# Or from a local clone.
-bash scripts/install --global --tools=claude-code
+npx @event4u/agent-config init --tools=claude-code
 ```
 
 > `--tools=claude-code` covers both Claude Code **and** Claude
-> Desktop — the two surfaces share `~/.claude/`. Pass
-> `--tools=claude-code,cursor,windsurf` if you want Cursor / Windsurf
-> globally seeded in the same run.
+> Desktop — the two surfaces share the project's `.claude/`
+> directory. Pass `--tools=claude-code,cursor,windsurf` to seed
+> additional surfaces in the same run.
 
-After the install you'll have:
+The init writes:
 
 ```
-~/.claude/
-├── rules/event4u/      # 9 kernel rules (Iron-Law set)
-└── skills/event4u/     # 15 curated top-N skills
+.claude/
+├── rules/      # active rules for the project
+├── skills/     # active skills for the project
+└── commands/   # slash commands
 ```
 
-Curation lives in
-[`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml).
-Edit and re-run `--global` to grow or shrink the set.
+`.agent-settings.yml` carries the `agent_config_version` pin so every
+`npx` invocation resolves the same runtime.
 
 ## Step 2 — verify
 
 1. Restart Claude Desktop (full quit, not just window close).
-2. Open a new conversation.
+2. Open the project folder in a new conversation.
 3. Type `/` — the curated skills (`/work`, `/commit`, `/create-pr`,
    `/quality-fix`, `/review-changes`, `/agent-handoff`,
    `/project-analyze`, …) appear in the slash-command menu.
@@ -61,7 +51,8 @@ Edit and re-run `--global` to grow or shrink the set.
 
 If the menu is empty:
 
-- Check `ls ~/.claude/skills/event4u/` — should list 15 directories.
+- Check `ls .claude/skills/` inside the project — should list the
+  curated skills.
 - Quit Claude Desktop (`Cmd+Q` on macOS, **not** just close the
   window — the menubar process keeps the old skills cached).
 - Re-open and try `/` again.
@@ -123,22 +114,23 @@ native HTTP) and per-client Bearer-auth snippets live in
 
 ## Claude Desktop ↔ Claude Code config sharing
 
-Both surfaces read **the same `~/.claude/` directory**. Anything you
-install for one is automatically available in the other:
+Both surfaces read **the same project `.claude/` directory**. Anything
+the `npx … init` writes for one is automatically picked up by the
+other when the project folder is opened:
 
 | File / dir                       | Shared by Desktop & Code? |
 | -------------------------------- | ------------------------- |
-| `~/.claude/CLAUDE.md`            | yes — global system prompt |
-| `~/.claude/rules/event4u/`       | yes — installed by `--global` |
-| `~/.claude/skills/event4u/`      | yes — installed by `--global` |
-| `~/.claude/commands/`            | yes — slash commands      |
-| `~/.claude/hooks/`               | yes — lifecycle hooks     |
+| `<project>/.claude/CLAUDE.md`    | yes — project system prompt |
+| `<project>/.claude/rules/`       | yes — written by `npx … init` |
+| `<project>/.claude/skills/`      | yes — written by `npx … init` |
+| `<project>/.claude/commands/`    | yes — slash commands      |
+| `<project>/.claude/hooks/`       | yes — lifecycle hooks     |
 | `claude_desktop_config.json`     | Desktop only (MCP)        |
 | `~/.claude.json` (CLI config)    | Code only                 |
 
-Translation: run `--global` once, both clients pick the files up.
-Cross-link to [`claude-code.md`](claude-code.md) for the CLI-side
-view.
+Translation: run `npx @event4u/agent-config init` once per project,
+both clients pick the files up. Cross-link to
+[`claude-code.md`](claude-code.md) for the CLI-side view.
 
 ## Claude Cowork
 
@@ -158,16 +150,11 @@ client-side feature set.
 
 ## Uninstall
 
-```bash
-bash scripts/install --global --uninstall --tools=claude-code
-```
-
-Removes only `~/.claude/{rules,skills}/event4u/`. Anything you added
-under sibling paths (custom rules, your own slash commands) stays.
+Remove the project's `.claude/`, `.agent-settings.yml`, and any bridge
+files written by `npx … init`. Nothing lives under `~/.claude/` from
+this package any more.
 
 ## See also
 
 - Project-local install — [`../../installation.md`](../../installation.md)
-- Global install reference — [`../../installation.md#global-user-level-install---global`](../../installation.md#global-user-level-install---global)
 - MCP client transports — [`../mcp-client-config.md`](../mcp-client-config.md)
-- Curation manifest — [`../../../templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)

package/docs/setup/per-ide/windsurf.md

@@ -35,17 +35,6 @@ Combine with other surfaces:
 npx @event4u/create-agent-config init --tools=windsurf,claude-code,cursor
 ```
 
-## Global install
-
-```bash
-npx @event4u/agent-config global --tools=windsurf
-```
-
-Seeds `~/.codeium/windsurf/global_workflows/` with the curated
-workflow set (see [`templates/global-install-manifest.yml`](../../../templates/global-install-manifest.yml)).
-Available across every project; per-workspace `.windsurf/workflows/`
-takes precedence on slug collisions.
-
 ## Wave-8 frontmatter
 
 Each rule under `.windsurf/rules/` has the Windsurf-shaped header:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.41.1",
+    "version": "2.0.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,
@@ -16,7 +16,6 @@
         ".agent-src/",
         ".augment-plugin/",
         ".claude-plugin/",
-        "bin/",
         "config/",
         "docs/",
         "scripts/",
@@ -26,15 +25,11 @@
         "CONTRIBUTING.md",
         "LICENSE",
         "README.md",
-        "composer.json",
         "llms.txt"
     ],
     "bin": {
         "agent-config": "scripts/agent-config"
     },
-    "scripts": {
-        "postinstall": "bash scripts/postinstall.sh"
-    },
     "publishConfig": {
         "access": "public",
         "provenance": true

package/scripts/_cli/cmd_migrate.py

@@ -0,0 +1,270 @@
+"""``agent-config migrate`` — one-shot migration off legacy install paths.
+
+P3.5/P3.6 of road-to-portable-runtime-and-update-check.md. Migrates a
+consumer project from the legacy composer / npm install paths onto
+the ``npx``-only runtime described in ``docs/architecture.md``.
+
+Steps performed (idempotent):
+
+1. Detect legacy install signals (composer.json entry, package.json
+   devDependency, in-project symlinks pointing at vendor/ or
+   node_modules/).
+2. Remove the package entry from composer.json / package.json
+   in-place, preserving sibling keys + formatting.
+3. Delete agent-config managed symlinks that point inside the legacy
+   install dirs. User-added links elsewhere are preserved with a
+   warning.
+4. Write a fresh ``.agent-settings.yml`` (only if missing) with
+   ``agent_config_version`` pinned to the running version.
+5. Update the consumer's ``.gitignore`` block (legacy paths out, new
+   project-scope entries in).
+6. Print a summary so the developer can review + commit.
+
+Re-runs on an already-migrated repo emit ``already migrated`` and
+exit 0.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+PACKAGE_NAME_NPM = "@event4u/agent-config"
+PACKAGE_NAME_COMPOSER = "event4u/agent-config"
+LEGACY_DIRS = ("vendor", "node_modules")
+MANAGED_SYMLINKS = (
+    ".augment",
+    ".claude",
+    ".cursor",
+    ".clinerules",
+    ".windsurfrules",
+)
+GITIGNORE_BLOCK_START = "# >>> event4u/agent-config (managed) >>>"
+GITIGNORE_BLOCK_END = "# <<< event4u/agent-config (managed) <<<"
+GITIGNORE_NEW_BODY = (
+    ".agent-settings.yml\n"
+    "agents/sessions/\n"
+    "agents/council-responses/\n"
+    "agents/council-sessions/\n"
+)
+
+
+def _detect_npm(pkg_json: Path) -> bool:
+    if not pkg_json.is_file():
+        return False
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    for key in ("dependencies", "devDependencies"):
+        section = data.get(key) or {}
+        if isinstance(section, dict) and PACKAGE_NAME_NPM in section:
+            return True
+    return False
+
+
+def _detect_composer(composer_json: Path) -> bool:
+    if not composer_json.is_file():
+        return False
+    try:
+        data = json.loads(composer_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    for key in ("require", "require-dev"):
+        section = data.get(key) or {}
+        if isinstance(section, dict) and PACKAGE_NAME_COMPOSER in section:
+            return True
+    return False
+
+
+def _strip_npm_entry(pkg_json: Path) -> bool:
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    changed = False
+    for key in ("dependencies", "devDependencies"):
+        section = data.get(key)
+        if isinstance(section, dict) and PACKAGE_NAME_NPM in section:
+            del section[PACKAGE_NAME_NPM]
+            changed = True
+            if not section:
+                del data[key]
+    if changed:
+        pkg_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return changed
+
+
+def _strip_composer_entry(composer_json: Path) -> bool:
+    try:
+        data = json.loads(composer_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError, json.JSONDecodeError):
+        return False
+    changed = False
+    for key in ("require", "require-dev"):
+        section = data.get(key)
+        if isinstance(section, dict) and PACKAGE_NAME_COMPOSER in section:
+            del section[PACKAGE_NAME_COMPOSER]
+            changed = True
+            if not section:
+                del data[key]
+    if changed:
+        composer_json.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return changed
+
+
+def _classify_symlink(link: Path) -> Optional[str]:
+    """Return 'legacy' if the link points into vendor/ or node_modules/, 'user' otherwise."""
+    if not link.is_symlink():
+        return None
+    try:
+        target = Path(link.readlink()) if hasattr(link, "readlink") else Path(link.resolve())
+    except OSError:
+        return None
+    target_str = str(target)
+    if any(seg in target_str.split("/") for seg in LEGACY_DIRS):
+        return "legacy"
+    return "user"
+
+
+def _purge_legacy_symlinks(project: Path) -> tuple[list[str], list[str]]:
+    removed: list[str] = []
+    preserved: list[str] = []
+    for name in MANAGED_SYMLINKS:
+        link = project / name
+        kind = _classify_symlink(link)
+        if kind == "legacy":
+            try:
+                link.unlink()
+                removed.append(name)
+            except OSError:
+                preserved.append(name)
+        elif kind == "user":
+            preserved.append(name)
+    return removed, preserved
+
+
+def _write_settings(project: Path, version: str) -> bool:
+    settings = project / ".agent-settings.yml"
+    if settings.exists():
+        return False
+    body = (
+        "# .agent-settings.yml — generated by `agent-config migrate`.\n"
+        "# See docs/customization.md for the full key reference.\n"
+        f'agent_config_version: "{version}"\n'
+    )
+    settings.write_text(body, encoding="utf-8")
+    try:
+        settings.chmod(0o644)
+    except OSError:
+        pass
+    return True
+
+
+def _update_gitignore(project: Path) -> bool:
+    gitignore = project / ".gitignore"
+    block = (
+        f"{GITIGNORE_BLOCK_START}\n"
+        f"{GITIGNORE_NEW_BODY}"
+        f"{GITIGNORE_BLOCK_END}\n"
+    )
+    if not gitignore.exists():
+        gitignore.write_text(block, encoding="utf-8")
+        return True
+
+    text = gitignore.read_text(encoding="utf-8")
+    pattern = re.compile(
+        re.escape(GITIGNORE_BLOCK_START) + r".*?" + re.escape(GITIGNORE_BLOCK_END) + r"\n?",
+        re.DOTALL,
+    )
+    if pattern.search(text):
+        new_text = pattern.sub(block, text)
+    else:
+        new_text = text
+        if new_text and not new_text.endswith("\n"):
+            new_text += "\n"
+        new_text += block
+    if new_text == text:
+        return False
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def _detect_already_migrated(project: Path) -> bool:
+    """A repo counts as migrated when no legacy signal remains."""
+    if _detect_npm(project / "package.json"):
+        return False
+    if _detect_composer(project / "composer.json"):
+        return False
+    for name in MANAGED_SYMLINKS:
+        if _classify_symlink(project / name) == "legacy":
+            return False
+    return True
+
+
+def main(
+    argv: Optional[list[str]] = None,
+    *,
+    cwd: Optional[Path] = None,
+    version: Optional[str] = None,
+    out=sys.stdout,
+    err=sys.stderr,  # noqa: ARG001 — reserved for future error paths
+) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config migrate",
+        description="One-shot migration off legacy composer / npm install paths.",
+    )
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Detect only; do not write any files.")
+    args = parser.parse_args(argv)
+
+    project = (cwd or Path.cwd()).resolve()
+    version = version or _detect_installed_version()
+
+    if _detect_already_migrated(project):
+        print("✅  already migrated — nothing to do.", file=out)
+        return 0
+
+    if args.dry_run:
+        print("ℹ️  legacy install detected — re-run without --dry-run to migrate.", file=out)
+        return 0
+
+    summary: list[str] = []
+    if _strip_npm_entry(project / "package.json"):
+        summary.append(f"removed {PACKAGE_NAME_NPM} from package.json")
+    if _strip_composer_entry(project / "composer.json"):
+        summary.append(f"removed {PACKAGE_NAME_COMPOSER} from composer.json")
+    removed_links, preserved_links = _purge_legacy_symlinks(project)
+    for name in removed_links:
+        summary.append(f"removed legacy symlink {name}")
+    for name in preserved_links:
+        summary.append(f"preserved user-managed {name} (review manually)")
+    if _write_settings(project, version):
+        summary.append(f".agent-settings.yml written (pinned to {version})")
+    if _update_gitignore(project):
+        summary.append(".gitignore agent-config block refreshed")
+
+    print("✅  migration complete:", file=out)
+    for line in summary:
+        print(f"    - {line}", file=out)
+    print("\n    Next: review the diff and commit.", file=out)
+    return 0
+
+
+def _detect_installed_version() -> str:
+    pkg_json = Path(__file__).resolve().parents[2] / "package.json"
+    try:
+        data = json.loads(pkg_json.read_text(encoding="utf-8"))
+        version = data.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    except (OSError, ValueError, json.JSONDecodeError):
+        pass
+    return "0.0.0"
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())