@event4u/agent-config 8.2.0 → 8.4.0

package/src/scripts/condense.ts

@@ -39,6 +39,7 @@ import {
     resolve_logical as _agent_src_resolve_logical,
     strip_source_prefix,
 } from './_lib/agent_src.js';
+import { build_claude_hook_matrix } from './_lib/claude_settings_hooks.js';
 import { project_settings_path, load_agent_settings } from './_lib/agent_settings.js';
 import { info, success, flush_summary, resolve_level } from './_lib/script_output.js';
 import {
@@ -1809,65 +1810,96 @@ export function generate_subagent_host_contexts(): number {
     return count;
 }
 
+// Bootstrap shim (road-to-install-path-convergence): the Claude Code plugin
+// ships ZERO content skills. It carries only hooks/hooks.json (byte-identical
+// to the managed settings block, so Claude Code dedupes) plus this single
+// pointer skill whose description names the canonical install command.
+export const PLUGIN_POINTER_SLUG = 'install-agent-config';
+export const PLUGIN_POINTER_SKILL_BODY = `---
+name: install-agent-config
+description: >-
+  Install or upgrade the event4u agent-config suite. This marketplace plugin
+  is a bootstrap shim — it ships hooks plus this pointer only; ALL skills,
+  rules, and commands are installed via \`npx -y @event4u/agent-config init\`.
+  Use when the user asks to install, set up, or upgrade agent-config, or
+  wonders why this plugin contains no other skills.
+---
+
+# Install agent-config
+
+This plugin is a **bootstrap shim**. It exists so the marketplace listing
+stays discoverable and existing plugin installs keep working hooks — the
+content surface (skills, rules, commands, personas) is distributed as a
+file projection, not through this plugin.
+
+## Install (canonical, one command)
+
+\`\`\`bash
+npx -y @event4u/agent-config init
+\`\`\`
+
+The installer writes the full content projection, registers the dispatcher
+hooks as a managed block in \`~/.claude/settings.json\` (byte-identical to
+this plugin's hooks, so nothing double-fires), and keeps everything
+upgradeable via \`agent-config upgrade\`.
+
+## Already installed both?
+
+Run \`agent-config doctor\` to check for duplicate surfaces, and
+\`agent-config converge\` to clean up consented duplicates.
+`;
+
 export function generate_plugin_command_skills(): number {
     if (!_isDir(path.join(MODULE_STATE.PROJECT_ROOT, 'src', 'domains'))) {
         return 0;
     }
     _mkdirp(MODULE_STATE.PLUGIN_SKILLS_DIR);
 
-    let skill_names = new Set<string>();
-    if (_exists(MODULE_STATE.SKILLS_SOURCE)) {
-        skill_names = new Set(
-            _iterdirSorted(MODULE_STATE.SKILLS_SOURCE)
-                .filter((p) => _isDir(p))
-                .map((p) => path.basename(p)),
-        );
+    // 1. Materialize the pointer skill (idempotent overwrite-on-drift).
+    const pointer_dir = path.join(MODULE_STATE.PLUGIN_SKILLS_DIR, PLUGIN_POINTER_SLUG);
+    _mkdirp(pointer_dir);
+    const pointer_file = path.join(pointer_dir, 'SKILL.md');
+    if (_isSymlink(pointer_file)) {
+        fs.unlinkSync(pointer_file);
     }
-
-    const current_slugs = new Set<string>();
-    let count = 0;
-    for (const [source_file, slug] of iterCommands()) {
-        if (skill_names.has(slug)) {
-            continue;
-        }
-        current_slugs.add(slug);
-        const skill_dir = path.join(MODULE_STATE.PLUGIN_SKILLS_DIR, slug);
-        _mkdirp(skill_dir);
-        const skill_file = path.join(skill_dir, 'SKILL.md');
-        if (_existsOrSymlink(skill_file)) {
-            fs.unlinkSync(skill_file);
-        }
-        const rel_path = _relativeToPosix(source_file, MODULE_STATE.PROJECT_ROOT);
-        const rel_target = path.join('../../..', rel_path);
-        fs.symlinkSync(rel_target, skill_file);
-        count += 1;
+    if (!_isFile(pointer_file) || fs.readFileSync(pointer_file, 'utf-8') !== PLUGIN_POINTER_SKILL_BODY) {
+        fs.writeFileSync(pointer_file, PLUGIN_POINTER_SKILL_BODY);
     }
 
+    // 2. Prune every other skill dir so the tree converges to shim shape
+    //    from any prior state. Removable = every entry is a symlink (the
+    //    generated projection shape — SKILL.md and optional evals links into
+    //    src/), or the dir holds only a single SKILL.md file (the old sweep's
+    //    rule). Dirs with real extra files are never touched.
     let removed_dirs = 0;
     for (const item of _iterdirSorted(MODULE_STATE.PLUGIN_SKILLS_DIR)) {
         if (!_isDirNoFollow(item) || _isSymlink(item)) {
             continue;
         }
-        if (current_slugs.has(path.basename(item))) {
+        if (path.basename(item) === PLUGIN_POINTER_SLUG) {
             continue;
         }
-        const skill_md = path.join(item, 'SKILL.md');
-        if (_isSymlink(skill_md) || _isFile(skill_md)) {
-            const entries = _iterdirSorted(item);
-            if (entries.length === 1 && path.basename(entries[0] as string) === 'SKILL.md') {
-                fs.unlinkSync(skill_md);
-                fs.rmdirSync(item);
-                removed_dirs += 1;
+        const entries = _iterdirSorted(item);
+        const all_symlinks = entries.length > 0 && entries.every((e) => _isSymlink(e));
+        const single_skill_md =
+            entries.length === 1 &&
+            path.basename(entries[0] as string) === 'SKILL.md' &&
+            _isFile(entries[0] as string);
+        if (all_symlinks || single_skill_md) {
+            for (const e of entries) {
+                fs.unlinkSync(e);
             }
+            fs.rmdirSync(item);
+            removed_dirs += 1;
         }
     }
 
-    let msg = `  ✅  Created ${count} command entries in .claude-plugin/skills/`;
+    let msg = '  ✅  Plugin skills: bootstrap shim (1 pointer skill) in .claude-plugin/skills/';
     if (removed_dirs) {
-        msg += ` (${removed_dirs} stale dirs removed)`;
+        msg += ` (${removed_dirs} content entries pruned)`;
     }
     info(msg);
-    return count;
+    return 1;
 }
 
 export function generate_persona_symlinks(): number {
@@ -1963,36 +1995,13 @@ export function generate_plugin_hooks(): number {
         return 0;
     }
 
-    // Python: `manifest = yaml.safe_load(...) or {}`.
-    let manifest = _yamlParse(_readText(manifest_path)) as Record<string, unknown> | null;
-    if (manifest === null || manifest === undefined) {
-        manifest = {};
-    }
-    const hook_spec = (manifest['schema_version'] as unknown) ?? 1;
-    const platforms = (manifest['platforms'] ?? {}) as Record<string, unknown>;
-    const claude_events = ((platforms['claude'] ?? {}) as Record<string, unknown>) || {};
-    const nativeAliasesAll = (manifest['native_event_aliases'] ?? {}) as Record<string, unknown>;
-    const aliases = ((nativeAliasesAll['claude'] ?? {}) as Record<string, unknown>) || {};
-    // Reverse the native→agent-config map.
-    const ac_to_native: Record<string, string> = {};
-    for (const [native, ac] of Object.entries(aliases)) {
-        ac_to_native[String(ac)] = native;
-    }
-
+    // Single source of truth: the SAME matrix derivation the installer uses
+    // for the managed settings.json block (road-to-claude-code-single-surface
+    // Phase 4) — plugin hooks.json and settings hooks cannot drift by
+    // construction. Backstop: tests/install/claude_hook_matrix_parity.test.ts.
+    const matrix = build_claude_hook_matrix(manifest_path);
     const hooks: Record<string, unknown[]> = {};
-    for (const [ac_event, concerns] of Object.entries(claude_events)) {
-        if (!concerns || (Array.isArray(concerns) && concerns.length === 0)) {
-            continue;
-        }
-        const native = ac_to_native[ac_event];
-        if (native === undefined) {
-            continue;
-        }
-        const command =
-            'BIN="$CLAUDE_PROJECT_DIR/agent-config"; [ -x "$BIN" ] || BIN=agent-config; ' +
-            `"$BIN" dispatch:hook --platform claude --event ${ac_event} ` +
-            `--native-event ${native} --project-dir "$CLAUDE_PROJECT_DIR" ` +
-            `--min-version ${String(hook_spec)}`;
+    for (const [native, command] of Object.entries(matrix)) {
         hooks[native] = [{ hooks: [{ type: 'command', command }] }];
     }
 

package/src/scripts/hook_manifest.yaml

@@ -125,17 +125,26 @@ concerns:
     script: src/scripts/wrapper_freshness_hook.ts
     args: []
     fail_closed: false
+  # road-to-install-path-convergence Phase 4 — duplicate-surface probe.
+  # Reads src/config/surface-matrix.yml, existence-checks declared duplicate
+  # classes, nudges ONCE per day (state: agents/runtime/state/
+  # surface-probe.json). Fail-open, never blocking; silent when clean or
+  # when install.auto_converge is already set.
+  surface-probe:
+    script: src/scripts/surface_probe_hook.ts
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]
 
   claude:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -157,7 +166,7 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
-    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
     stop:             [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -172,7 +181,7 @@ platforms:
   # IDE-only — CLI-only users fall back to /checkpoint per
   # agents/settings/contexts/chat-history-platform-hooks.md.
   cursor:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -187,7 +196,7 @@ platforms:
   # both map to session_start. TaskCancel maps to stop because the
   # session is interrupted with partial state (mirrors Augment Stop).
   cline:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
@@ -206,7 +215,7 @@ platforms:
   # surface to record verification commands; documented limitation).
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness, surface-probe]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete]
 
@@ -221,7 +230,7 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
-    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness]
+    session_start:      [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:        [chat-history]
     stop:               [chat-history, hot-context, verify-before-complete]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]

package/src/scripts/install

@@ -27,6 +27,9 @@
 #                     the comma-separated values are unioned.
 #   --list-tools      Print supported tool IDs with descriptions, then exit
 #   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
+#   --no-ui           Unattended install: never launch the browser setup
+#                     wizard and skip the terminal tool picker (tools default
+#                     to all). Used by `agent-config upgrade`.
 #   --force           Overwrite existing bridge files
 #   --dry-run         Show what payload sync would do (does not run bridges)
 #   --verbose         Detailed payload sync output
@@ -95,12 +98,13 @@ MINIMAL=false
 VALIDATE_ONLY=false
 FLEET_CONFIG=""
 USER_TYPE=""
+NO_UI=false
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,61p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -167,6 +171,7 @@ while [[ $# -gt 0 ]]; do
         --ai=*)          TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --list-tools)    LIST_TOOLS=true; shift ;;
         --yes|-y)        YES=true; shift ;;
+        --no-ui)         NO_UI=true; shift ;;
         --force)         FORCE=true; shift ;;
         --dry-run)       DRY_RUN=true; shift ;;
         --verbose)       VERBOSE=true; shift ;;
@@ -194,6 +199,15 @@ if $LIST_TOOLS; then
     exit 0
 fi
 
+# --no-ui = unattended install (the `agent-config upgrade` path). Export the
+# suppression env so every downstream stage (install.ts honors both the flag
+# and AGENT_CONFIG_NO_UI) skips the browser setup wizard — the wizard is an
+# onboarding surface whose foreground server used to block `upgrade` until
+# Ctrl-C.
+if $NO_UI; then
+    export AGENT_CONFIG_NO_UI=1
+fi
+
 # road-to-global-only-install § Phase 3.3 — consumer-floor gate.
 #
 # Consumer installs are global-only (ADR-020). Explicit --scope=project
@@ -282,8 +296,8 @@ prompt_tools() {
 # When an interactive global install will hand off to the browser wizard,
 # the wizard is the single tool-selection surface — skip the terminal
 # picker so it does not pre-empt (and, via TOOLS_EXPLICIT, suppress) the
-# GUI. Mirrors install.py::_wizard_should_launch minus the --no-ui flag,
-# which the bash orchestrator never receives (it errors on unknown args).
+# GUI. Mirrors install.py::_wizard_should_launch (the --no-ui flag is
+# handled here too — it suppresses both the wizard and the picker).
 # Headless paths (no TTY / CI / AGENT_CONFIG_NO_UI) still get the picker.
 wizard_will_handle_tools=false
 if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
@@ -291,8 +305,12 @@ if $GLOBAL && [[ -t 0 && -t 1 && -z "${CI:-}" ]] \
     wizard_will_handle_tools=true
 fi
 
+# --no-ui also skips the terminal picker: the flag means "fully unattended"
+# (its only caller today is `agent-config upgrade`, where a mid-upgrade
+# prompt reads as a hang). Tools fall through to the "all" default below —
+# the same effective selection the wizard-handoff path used.
 if ! $MINIMAL && ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS \
-   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools; then
+   && [[ -t 0 && -t 1 ]] && ! $wizard_will_handle_tools && ! $NO_UI; then
     prompt_tools
     TOOLS_EXPLICIT=true
 fi
@@ -416,6 +434,7 @@ run_bridges() {
     [[ -n "$CUSTOM_PATH" ]] && args+=(--custom-path="$CUSTOM_PATH")
     $OFFLINE && args+=(--offline)
     $MINIMAL && args+=(--minimal)
+    $NO_UI && args+=(--no-ui)
     args+=(--tools="$TOOLS")
     "${runner[@]}" "${args[@]}"
 }

package/src/scripts/install.ts

@@ -78,6 +78,7 @@ import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
+import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
 import { detect_module_roots } from './_lib/module_detection.js';
 import {
@@ -2914,6 +2915,35 @@ function _deploy_global_content(
         }
         _emit_progress({ type: 'reaped', tool: tool_id, count: reaped.length });
         results[tool_id] = [written_total, skipped_total, 'deployed', written_paths];
+
+        // Single-surface model (road-to-claude-code-single-surface): the
+        // deterministic hook matrix registers directly in the user-scope
+        // settings file — the marketplace plugin is no longer required for
+        // hooks. Failure here must not sink the content deploy (hooks can
+        // be re-wired via `agent-config refresh --global` / doctor).
+        if (tool_id === 'claude-code') {
+            try {
+                const manifest = path.join(package_root, 'src', 'scripts', 'hook_manifest.yaml');
+                const matrix = claude_settings_hooks.build_claude_hook_matrix(manifest);
+                const res = claude_settings_hooks.ensure_managed_hooks(
+                    path.join(anchor, 'settings.json'),
+                    matrix,
+                );
+                if (!state.QUIET) {
+                    if (res.changed) {
+                        success(
+                            `claude-code: managed hooks registered in ~/.claude/settings.json ` +
+                                `(${res.events.length} event(s))`,
+                        );
+                    } else {
+                        skip('claude-code: managed hooks already registered');
+                    }
+                }
+            } catch (e) {
+                warn(`claude-code: managed-hook registration failed — ${String(e)}`);
+                _emit_progress({ type: 'hooks_failed', tool: tool_id, error: String(e) });
+            }
+        }
     }
     return results;
 }

package/src/scripts/lint_glama_drift.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against `internal/glama/README.md` drifting from the committed
+ * `internal/glama/build` / `internal/glama/run` scripts it documents.
+ *
+ * Extracts the single canonical command line each script actually runs
+ * (the last non-comment, non-`set -euo pipefail` line — `exec ` stripped)
+ * and asserts that literal string appears verbatim somewhere in the README.
+ * Catches the exact failure mode fixed in road-to-mcp-full-power.md Phase 1:
+ * the README described a Python/uv build long after the scripts moved to
+ * Node/tsx.
+ *
+ * Exit codes: 0 no drift, 1 one or more scripts' canonical command is not
+ * documented verbatim in the README.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const GLAMA_DIR = path.join(REPO, 'internal', 'glama');
+
+interface ScriptSpec {
+    file: string;
+    /** Strip this exact prefix from the extracted command line before comparing. */
+    stripPrefix?: string;
+}
+
+const SCRIPTS: readonly ScriptSpec[] = [
+    { file: 'build' },
+    { file: 'run', stripPrefix: 'exec ' },
+];
+
+function _canonicalCommand(scriptPath: string, stripPrefix?: string): string {
+    const lines = fs.readFileSync(scriptPath, 'utf8').split('\n');
+    const candidates = lines
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.startsWith('#') && l !== 'set -euo pipefail');
+    const last = candidates[candidates.length - 1] ?? '';
+    return stripPrefix && last.startsWith(stripPrefix) ? last.slice(stripPrefix.length) : last;
+}
+
+function main(): number {
+    const readmePath = path.join(GLAMA_DIR, 'README.md');
+    const readme = fs.readFileSync(readmePath, 'utf8');
+
+    let failed = false;
+    for (const spec of SCRIPTS) {
+        const scriptPath = path.join(GLAMA_DIR, spec.file);
+        const cmd = _canonicalCommand(scriptPath, spec.stripPrefix);
+        if (!cmd) {
+            console.error(`❌  internal/glama/${spec.file}: could not extract a canonical command line`);
+            failed = true;
+            continue;
+        }
+        if (!readme.includes(cmd)) {
+            console.error(
+                `❌  drift: internal/glama/${spec.file} runs \`${cmd}\` — not found verbatim in internal/glama/README.md`,
+            );
+            failed = true;
+        }
+    }
+
+    if (failed) {
+        console.error('\nUpdate internal/glama/README.md to match the committed build/run scripts.');
+        return 1;
+    }
+
+    process.stdout.write('✅  internal/glama/README.md matches build/run scripts — no drift.\n');
+    return 0;
+}
+
+process.exit(main());

package/src/scripts/lint_marketplace.ts

@@ -6,16 +6,20 @@
  * Wave 4b). Mirrors the Python CLI contract exactly: same cwd-relative scan
  * roots, finding messages, stdout output, and exit codes.
  *
- * Validates the Claude Code Plugin Marketplace manifest against the canonical
- * manifest shape:
+ * Validates the Claude Code Plugin Marketplace manifest against the
+ * BOOTSTRAP-SHIM shape (road-to-install-path-convergence): the plugin ships
+ * ONLY hooks plus a single install-pointer skill — content skills are
+ * distributed via the npx file projection, never through this plugin.
  *
  *   - Required top-level fields: name, owner, metadata, plugins
  *   - owner must have name + email
  *   - metadata must have description + version
  *   - metadata.version must match package.json (single source of truth)
- *   - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
- *   - every SKILL.md on disk under the committed skill sources must be listed
- *     in some plugin's skills[] (drift detection)
+ *   - the union of plugins[].skills[] must be EXACTLY the pointer skill
+ *     (./.claude-plugin/skills/install-agent-config) — a repopulated
+ *     content-skill list FAILS by design
+ *   - the pointer entry must exist on disk and carry a SKILL.md
+ *   - .claude-plugin/skills/ on disk must contain ONLY the pointer dir
  *
  * Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
  */
@@ -26,14 +30,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const ROOT = ".";
 const MARKETPLACE = path.join(ROOT, ".claude-plugin", "marketplace.json");
 const PACKAGE_JSON = path.join(ROOT, "package.json");
-// Committed marketplace skill sources (git-consumed): real skills resolve to
-// dist/agent-src/skills/<name>; command-as-skill entries to the committed
-// .claude-plugin/skills/<slug> projection. .claude/skills/ is a gitignored
-// local channel and is intentionally NOT a marketplace source.
-const SKILL_SOURCE_DIRS = [
-  path.join(ROOT, "dist/agent-src", "skills"),
-  path.join(ROOT, ".claude-plugin", "skills"),
-];
+// Bootstrap shim: the ONLY skill the plugin may list. Content skills live in
+// the npx file projection (dist/agent-src/skills/ ships in the npm package,
+// not through the marketplace). .claude/skills/ is a gitignored local channel
+// and is intentionally NOT a marketplace source.
+const POINTER_SKILL_ENTRY = "./.claude-plugin/skills/install-agent-config";
+const PLUGIN_SKILLS_DIR = path.join(ROOT, ".claude-plugin", "skills");
+const POINTER_SKILL_DIRNAME = "install-agent-config";
 
 type JsonValue =
   | string
@@ -174,6 +177,18 @@ export function main(): number {
       }
       seen.add(p);
 
+      // Bootstrap-shim invariant: any entry other than the pointer skill is
+      // a repopulated content-skill list and must FAIL.
+      if (p !== POINTER_SKILL_ENTRY) {
+        errors.push(
+          `${entry} violates the bootstrap shim: the plugin must not ship ` +
+            `content skills (only \`${POINTER_SKILL_ENTRY}\` is allowed), ` +
+            `got \`${p}\` — content is distributed via ` +
+            "`npx -y @event4u/agent-config init`",
+        );
+        continue;
+      }
+
       // Resolve path relative to repo root (strip leading "./" only,
       // NOT every "." and "/" character)
       const rel = removePrefix(p, "./");
@@ -189,9 +204,7 @@ export function main(): number {
     }
   }
 
-  // Reverse-completeness: every SKILL.md on disk under the committed skill
-  // sources (dist/agent-src/skills/ + .claude-plugin/skills/) must appear in
-  // some plugin's skills[].
+  // Shim completeness: the pointer skill must be listed by some plugin.
   const listed = new Set<string>();
   for (const plugin of plugins) {
     if (!isObject(plugin)) {
@@ -201,43 +214,38 @@ export function main(): number {
     if (Array.isArray(skills)) {
       for (const p of skills) {
         if (typeof p === "string") {
-          listed.add(removePrefix(p, "./"));
+          listed.add(p);
         }
       }
     }
   }
+  if (plugins.length > 0 && !listed.has(POINTER_SKILL_ENTRY)) {
+    errors.push(
+      `bootstrap shim: pointer skill \`${POINTER_SKILL_ENTRY}\` is not ` +
+        "listed in any plugin's skills[]",
+    );
+  }
 
-  for (const sourceDir of SKILL_SOURCE_DIRS) {
-    if (!_exists(sourceDir)) {
-      continue;
-    }
-    // source_dir.relative_to(ROOT).as_posix() — ROOT is ".", so this is the
-    // dir spelled relative to cwd with POSIX separators.
-    const prefix = relPosix(sourceDir, ROOT);
-    let entries: fs.Dirent[];
+  // Shim disk shape: .claude-plugin/skills/ must contain ONLY the pointer
+  // dir — a repopulated symlink tree (e.g. from a stale generator) FAILS.
+  if (_exists(PLUGIN_SKILLS_DIR)) {
+    let entries: fs.Dirent[] = [];
     try {
-      entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+      entries = fs.readdirSync(PLUGIN_SKILLS_DIR, { withFileTypes: true });
     } catch {
-      continue;
+      /* unreadable → nothing to assert */
     }
-    // sorted(source_dir.iterdir()) — full-path string sort.
-    const dirs = entries
-      .map((e) => ({ name: e.name, full: path.join(sourceDir, e.name) }))
-      .sort((a, b) => (a.full < b.full ? -1 : a.full > b.full ? 1 : 0));
-    for (const d of dirs) {
-      if (!_isDir(d.full)) {
-        continue;
-      }
-      if (!_exists(path.join(d.full, "SKILL.md"))) {
-        continue;
-      }
-      const rel = `${prefix}/${d.name}`;
-      if (!listed.has(rel)) {
-        errors.push(
-          "skill exists on disk but is not listed in marketplace.json: " +
-            `\`./${rel}\``,
-        );
-      }
+    const extra = entries
+      .filter((e) => _isDir(path.join(PLUGIN_SKILLS_DIR, e.name)))
+      .map((e) => e.name)
+      .filter((name) => name !== POINTER_SKILL_DIRNAME)
+      .sort();
+    for (const name of extra) {
+      errors.push(
+        "bootstrap shim: unexpected skill dir on disk (plugin ships no " +
+          `content skills): \`.claude-plugin/skills/${name}\` — remove it ` +
+          "or re-run the generator",
+      );
     }
   }
 
@@ -246,15 +254,9 @@ export function main(): number {
   }
 
   const pluginCount = plugins.length;
-  let skillCount = 0;
-  for (const p of plugins) {
-    if (isObject(p) && Array.isArray(p["skills"])) {
-      skillCount += p["skills"].length;
-    }
-  }
   process.stdout.write(
     `✅  marketplace.json (${pluginCount} plugin` +
-      `${pluginCount !== 1 ? "s" : ""}, ${skillCount} skills total)\n`,
+      `${pluginCount !== 1 ? "s" : ""}, bootstrap shim: 1 pointer skill)\n`,
   );
   process.stdout.write("  No issues found.\n");
   return 0;
@@ -268,10 +270,6 @@ function _isDir(p: string): boolean {
   }
 }
 
-function relPosix(child: string, base: string): string {
-  return path.relative(base, child).split(path.sep).join("/");
-}
-
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;