auditor-lambda 0.3.7 → 0.3.8

package/README.md

@@ -22,7 +22,28 @@ The canonical asset for editor and conversation integrations is:
 
 Packaged installs and repository checkouts both ship that prompt asset.
 
-The recommended zero-guess setup path is now:
+The intended user install is one global tool install:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH`. During package install, the package
+also writes user-level command/skill assets for hosts we can seed safely, including
+the Claude command file and Codex skill bundle.
+
+After that, invoke `/audit-code` in a supported host. The prompt self-bootstraps
+the current repository by running:
+
+```bash
+audit-code ensure --quiet
+```
+
+That command writes or refreshes the repo-local assets only when they are missing
+or stale, then normal audit execution continues without manual paths, provider
+flags, or model-selection arguments.
+
+The explicit repair and compatibility setup path remains:
 
 ```bash
 audit-code install
@@ -36,9 +57,9 @@ That bootstraps repo-local `/audit-code` surfaces for the hosts we can automate
 - VS Code prompt, custom agent, Copilot instructions, and `.vscode/mcp.json`
 - Antigravity planning-mode guidance plus the shared repo-local MCP launcher
 
-Re-run the same `audit-code install` command whenever the packaged prompt or
-skill changes. It is the single supported refresh path for the shared
-`.audit-code/install/*` assets and every generated host surface.
+`audit-code ensure` refreshes those files automatically when the packaged prompt
+or skill changes. Use `audit-code install` or `audit-code ensure --force` when
+you intentionally want to rewrite every generated host surface on demand.
 
 After bootstrap, you can smoke-test the generated host assets and launcher from the repository root:
 
@@ -161,7 +182,8 @@ Optional backend config:
 ## Practical Guidance
 
 - use `/audit-code` in conversation as the canonical product surface
-- use `audit-code install` first when you want the lowest-friction repo bootstrap
+- install once with `npm install -g auditor-lambda`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
+- use `audit-code install` when you want to repair or force-refresh repo-local host assets
 - use `audit-code prompt-path` to locate the packaged prompt asset
 - use `audit-code` from the repository root only when you need the repo-local backend fallback
 - use omitted provider or `local-subprocess` for the safest deterministic fallback behavior

package/audit-code-wrapper-lib.mjs

@@ -253,6 +253,7 @@ function printHelp({ usageName, preferredEntrypoint }) {
     '',
     'Helper commands:',
     '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
+    '- ensure lazily bootstraps repo-local /audit-code assets when they are missing or stale',
     '- install bootstraps /audit-code into supported repo-local host surfaces',
     '- verify-install smoke-tests the generated host assets and repo-local MCP launchers after install',
     '- mcp starts the local stdio MCP server for repo-local IDE integrations',
@@ -1952,7 +1953,188 @@ async function verifyInstalledBootstrap(argv) {
   process.exitCode = issueCount > 0 ? 1 : 0;
 }
 
-async function installBootstrap(argv) {
+async function readTextIfExists(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function detectBootstrapRefreshReason(root, host) {
+  const installManifestPath = join(
+    root,
+    '.audit-code',
+    'install',
+    INSTALL_MANIFEST_FILENAME,
+  );
+
+  if (!(await fileExists(installManifestPath))) {
+    return 'missing_install_manifest';
+  }
+
+  let installManifest;
+  try {
+    installManifest = JSON.parse(await readFile(installManifestPath, 'utf8'));
+  } catch {
+    return 'invalid_install_manifest';
+  }
+
+  if (installManifest?.contract_version !== 'audit-code-install/v1alpha1') {
+    return 'stale_install_manifest_contract';
+  }
+
+  const assetPaths = installManifest.asset_paths ?? {};
+  const hostCatalog = new Set(
+    (installManifest.hosts ?? []).map((entry) => entry.host),
+  );
+
+  for (const hostKey of getInstallHostKeys(host)) {
+    if (!hostCatalog.has(hostKey)) {
+      return `missing_host_surface:${hostKey}`;
+    }
+
+    const definition = INSTALL_HOST_DEFINITIONS[hostKey];
+    const requiredPathKeys = [
+      definition.primary_path_key,
+      ...definition.supporting_path_keys,
+    ];
+    for (const pathKey of requiredPathKeys) {
+      const targetPath = assetPaths[pathKey];
+      if (targetPath && !(await fileExists(targetPath))) {
+        return `missing_host_asset:${hostKey}:${pathKey}`;
+      }
+    }
+  }
+
+  const installedPrompt = await readTextIfExists(assetPaths.installedPromptPath);
+  if (installedPrompt === null) {
+    return 'missing_installed_prompt';
+  }
+  const sourcePrompt = await readFile(promptAssetPath, 'utf8');
+  if (installedPrompt !== sourcePrompt) {
+    return 'stale_installed_prompt';
+  }
+  const { body: sourcePromptBody } = splitFrontmatter(sourcePrompt);
+
+  const installedSkill = await readTextIfExists(assetPaths.installedSkillPath);
+  if (installedSkill === null) {
+    return 'missing_installed_skill';
+  }
+  const sourceSkill = (await readFile(skillAssetPath, 'utf8')).replace(/\r\n/g, '\n');
+  if (installedSkill.replace(/\r\n/g, '\n') !== sourceSkill) {
+    return 'stale_installed_skill';
+  }
+
+  for (const hostKey of getInstallHostKeys(host)) {
+    switch (hostKey) {
+      case 'codex': {
+        const codexSkill = await readTextIfExists(assetPaths.codexSkillPath);
+        if (codexSkill?.replace(/\r\n/g, '\n') !== sourceSkill) {
+          return 'stale_host_asset:codex:skill';
+        }
+        const codexPrompt = await readTextIfExists(assetPaths.codexPromptPath);
+        if (codexPrompt !== sourcePrompt) {
+          return 'stale_host_asset:codex:prompt';
+        }
+        break;
+      }
+      case 'opencode': {
+        const opencodeSkill = await readTextIfExists(assetPaths.opencodeSkillPath);
+        if (opencodeSkill?.replace(/\r\n/g, '\n') !== sourceSkill) {
+          return 'stale_host_asset:opencode:skill';
+        }
+        const opencodePrompt = await readTextIfExists(assetPaths.opencodePromptPath);
+        if (opencodePrompt !== sourcePrompt) {
+          return 'stale_host_asset:opencode:prompt';
+        }
+        const opencodeCommand = await readTextIfExists(assetPaths.opencodeCommandPath);
+        if (opencodeCommand === null) {
+          return 'missing_host_asset:opencode:command';
+        }
+        if (splitFrontmatter(opencodeCommand).body !== sourcePromptBody.trimStart()) {
+          return 'stale_host_asset:opencode:command';
+        }
+        break;
+      }
+      case 'vscode': {
+        const vscodePrompt = await readTextIfExists(assetPaths.vscodePromptPath);
+        if (vscodePrompt === null) {
+          return 'missing_host_asset:vscode:prompt';
+        }
+        if (splitFrontmatter(vscodePrompt).body !== sourcePromptBody.trimStart()) {
+          return 'stale_host_asset:vscode:prompt';
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const launcherPath =
+    assetPaths.mcpLauncherPath ?? installManifest.mcp_server_launcher_path;
+  const launcher = launcherPath ? await readTextIfExists(launcherPath) : null;
+  if (launcher === null) {
+    return 'missing_mcp_launcher';
+  }
+  if (!launcher.includes('Unable to locate an audit-code executable')) {
+    return 'stale_mcp_launcher';
+  }
+
+  return null;
+}
+
+async function ensureBootstrap(argv) {
+  const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
+  const root = resolve(getFlag(argv, '--root') ?? '.');
+  const quiet = hasFlag(argv, '--quiet');
+  const force = hasFlag(argv, '--force');
+  await assertDirectoryExists(root, 'Target repository root');
+
+  const reason = force
+    ? 'forced'
+    : await detectBootstrapRefreshReason(root, host);
+
+  if (reason) {
+    const installed = await installBootstrap(argv, { quiet: true });
+    const payload = {
+      status: 'ok',
+      action: 'installed',
+      reason,
+      host: installed.host,
+      repo_root: installed.repo_root,
+      install_manifest_path: installed.install_manifest_path,
+      mcp_server_launcher_path: installed.mcp_server_launcher_path,
+      host_count: installed.host_guidance.length,
+      file_count: installed.files.length,
+    };
+    if (!quiet) {
+      console.log(JSON.stringify(payload, null, 2));
+    }
+    return payload;
+  }
+
+  const payload = {
+    status: 'ok',
+    action: 'skipped',
+    reason: null,
+    host,
+    repo_root: root,
+    install_manifest_path: join(
+      root,
+      '.audit-code',
+      'install',
+      INSTALL_MANIFEST_FILENAME,
+    ),
+  };
+  if (!quiet) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+  return payload;
+}
+
+async function installBootstrap(argv, options = {}) {
   const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
   const root = resolve(getFlag(argv, '--root') ?? '.');
   await assertDirectoryExists(root, 'Target repository root');
@@ -2221,49 +2403,49 @@ async function installBootstrap(argv) {
     results.push({ path: sessionConfigPath, mode: 'created' });
   }
 
-  console.log(
-    JSON.stringify(
-      {
-        host,
-        repo_root: root,
-        installed_prompt_path: installedPromptPath,
-        installed_skill_path: installedSkillPath,
-        install_guide_path: installGuidePath,
-        install_manifest_path: installManifestPath,
-        mcp_server_launcher_path: mcpLauncherPath,
-        source_prompt_path: resolve(promptAssetPath),
-        source_skill_path: resolve(skillAssetPath),
-        files: results,
-        slash_command_surfaces: {
-          vscode_prompt: assetPaths.vscodePromptPath,
-          opencode_command: assetPaths.opencodeCommandPath,
-        },
-        instruction_surfaces: {
-          agents: assetPaths.agentsInstructionsPath,
-          copilot_instructions: assetPaths.copilotInstructionsPath,
-        },
-        mcp_surfaces: {
-          vscode_workspace: assetPaths.vscodeMcpConfigPath,
-          opencode_project: assetPaths.opencodeConfigPath,
-          codex_setup: assetPaths.codexMcpSetupPath,
-          shared_launcher: mcpLauncherPath,
-          claude_desktop_dxt: assetPaths.claudeDesktopDxtPath,
-          claude_desktop_mcpb: assetPaths.claudeDesktopMcpbPath,
-          antigravity_planning_guide: assetPaths.antigravityPlanningGuidePath,
-        },
-        host_guidance: hostGuidance,
-        unsupported_hosts: [],
-        next_steps: [
-          'Open the repository in your preferred host and follow the matching host_guidance entry.',
-          `Open ${installGuidePath} for repo-local quick-start steps for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.`,
-          'Run `audit-code verify-install` from the repository root to smoke-test the generated launchers and host configs.',
-          'Use the shared MCP launcher as the source of truth for local stdio MCP registration across hosts.',
-        ],
-      },
-      null,
-      2,
-    ),
-  );
+  const payload = {
+    host,
+    repo_root: root,
+    installed_prompt_path: installedPromptPath,
+    installed_skill_path: installedSkillPath,
+    install_guide_path: installGuidePath,
+    install_manifest_path: installManifestPath,
+    mcp_server_launcher_path: mcpLauncherPath,
+    source_prompt_path: resolve(promptAssetPath),
+    source_skill_path: resolve(skillAssetPath),
+    files: results,
+    slash_command_surfaces: {
+      vscode_prompt: assetPaths.vscodePromptPath,
+      opencode_command: assetPaths.opencodeCommandPath,
+    },
+    instruction_surfaces: {
+      agents: assetPaths.agentsInstructionsPath,
+      copilot_instructions: assetPaths.copilotInstructionsPath,
+    },
+    mcp_surfaces: {
+      vscode_workspace: assetPaths.vscodeMcpConfigPath,
+      opencode_project: assetPaths.opencodeConfigPath,
+      codex_setup: assetPaths.codexMcpSetupPath,
+      shared_launcher: mcpLauncherPath,
+      claude_desktop_dxt: assetPaths.claudeDesktopDxtPath,
+      claude_desktop_mcpb: assetPaths.claudeDesktopMcpbPath,
+      antigravity_planning_guide: assetPaths.antigravityPlanningGuidePath,
+    },
+    host_guidance: hostGuidance,
+    unsupported_hosts: [],
+    next_steps: [
+      'Open the repository in your preferred host and follow the matching host_guidance entry.',
+      `Open ${installGuidePath} for repo-local quick-start steps for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.`,
+      'Run `audit-code verify-install` from the repository root to smoke-test the generated launchers and host configs.',
+      'Use the shared MCP launcher as the source of truth for local stdio MCP registration across hosts.',
+    ],
+  };
+
+  if (!options.quiet) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+
+  return payload;
 }
 
 async function installHostPrompt(argv) {
@@ -2316,6 +2498,11 @@ export async function runAuditCodeWrapper({
     return;
   }
 
+  if (argv[0] === 'ensure') {
+    await ensureBootstrap(argv.slice(1));
+    return;
+  }
+
   if (argv[0] === 'install') {
     await installBootstrap(argv.slice(1));
     return;

package/docs/agent-integrations.md

@@ -31,14 +31,33 @@ The canonical prompt asset is:
 
 `skills/audit-code/audit-code.prompt.md`
 
-The preferred bootstrap path is:
+The preferred install path for users is:
 
 ```bash
-audit-code install
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH` and seeds user-level command/skill
+assets for hosts we can safely update during package installation. Once the
+slash command is available, `/audit-code` self-bootstraps the current repository
+with:
+
+```bash
+audit-code ensure --quiet
 ```
 
-That installs repo-local `/audit-code` surfaces and MCP-oriented support assets for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity.
-It also writes `.audit-code/install/GETTING-STARTED.md` with dedicated quick-start sections for each host plus `.audit-code/install/manifest.json` and a shared repo-local MCP launcher.
+`ensure` writes repo-local `/audit-code` surfaces and MCP-oriented support assets
+for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity only when they are
+missing or stale. It also writes `.audit-code/install/GETTING-STARTED.md` with
+dedicated quick-start sections for each host plus `.audit-code/install/manifest.json`
+and a shared repo-local MCP launcher.
+
+Use the explicit installer when you want to repair or force-refresh those
+repo-local assets:
+
+```bash
+audit-code install
+```
 
 Use one of these supported ways to obtain the raw prompt asset directly when you need prompt import instead:
 
@@ -57,7 +76,12 @@ Use `/audit-code` in conversation, treat the active conversation model as the de
 
 ### Codex
 
-Use `audit-code install --host codex` or the default `audit-code install` from the target repository root.
+The global npm install seeds `~/.codex/skills/audit-code/` so the command can be
+available before a repository is bootstrapped. The first `/audit-code` run then
+uses `audit-code ensure --quiet` to create or refresh repo-local Codex support.
+
+Use `audit-code install --host codex` only when you want to repair or force-refresh
+the Codex repo-local files from the target repository root.
 
 That writes a repo-local Codex skill bundle, updates `AGENTS.md` through a managed block when needed, and emits Codex-specific MCP setup guidance plus an automation recipe in `.audit-code/install/codex/`.
 The intended operator flow is still conversational first, with the generated skill and AGENTS guidance steering the active Codex session toward `/audit-code` and the MCP-backed workflow.
@@ -79,21 +103,29 @@ Manual prompt import remains a fallback, not the primary documented path.
 
 ### OpenCode
 
-Use `audit-code install` from the target repository root.
+OpenCode currently relies on repo-local command and MCP config files for the
+cleanest experience. A global `/audit-code` prompt can run `audit-code ensure --quiet`
+first; otherwise run `audit-code install` from the target repository root once.
 
 That writes `.opencode/commands/audit-code.md`, a repo-local OpenCode skill bundle, and `opencode.json` so `/audit-code` is available in the repository with no extra provider flags.
 The generated OpenCode assets also point OpenCode toward the shared auditor MCP server instead of rebuilding backend state ad hoc.
 
 ### VS Code
 
-Run `audit-code install` from the target repository root, then open `.audit-code/install/GETTING-STARTED.md` if you want the exact repo-local path that bootstrap created for VS Code chat surfaces.
+VS Code currently relies on workspace prompt and MCP config files for the
+cleanest experience. A global `/audit-code` prompt can run `audit-code ensure --quiet`
+first; otherwise run `audit-code install` from the target repository root, then
+open `.audit-code/install/GETTING-STARTED.md` if you want the exact repo-local
+path that bootstrap created for VS Code chat surfaces.
 
 That writes `.github/prompts/audit-code.prompt.md`, `.github/copilot-instructions.md`, `.github/agents/auditor.agent.md`, and `.vscode/mcp.json`.
 The expected happy path is still to invoke `/audit-code` from chat, not to start from the backend CLI.
 
 ### Antigravity
 
-Run `audit-code install` from the target repository root, then open `.audit-code/install/GETTING-STARTED.md`.
+Run `/audit-code` from a global prompt-capable host and let `audit-code ensure --quiet`
+create the repo-local guidance, or run `audit-code install` from the target
+repository root, then open `.audit-code/install/GETTING-STARTED.md`.
 
 There is still no documented native repo-local saved-workflow surface for Antigravity in this repository today, so the intended path is:
 
@@ -229,7 +261,9 @@ Only use the repo-local `audit-code` wrapper with `provider: "opencode"` when yo
 
 ### VS Code
 
-Run `audit-code install` once from the target repository root, then use `/audit-code` from chat.
+Use `/audit-code` from chat and let the prompt run `audit-code ensure --quiet`.
+Run `audit-code install` manually only when VS Code has not yet discovered the
+workspace prompt/MCP files or you want to force-refresh them.
 
 The backend fallback is still available from the integrated terminal and should keep `local-subprocess` unless you specifically need a task bridge.
 
@@ -242,7 +276,7 @@ No dedicated Antigravity provider adapter is shipped today.
 Current recommended usage is one of these:
 
 - use the skill-first conversational contract as the primary surface
-- run `audit-code install` first so compatibility files are present
+- let `/audit-code` run `audit-code ensure --quiet`, or run `audit-code install` manually so compatibility files are present
 - run `audit-code` from an Antigravity-managed terminal with `local-subprocess`
 - use `subprocess-template` if you have a reliable Antigravity-side launcher bridge
 
@@ -272,7 +306,7 @@ The product direction remains skill-first:
 For a polished operator experience today:
 
 1. treat `/audit-code` as the canonical user-facing contract
-2. use `audit-code install` first, and fall back to `audit-code prompt-path` only for hosts that still require manual prompt import
+2. install once with `npm install -g auditor-lambda`, then let `/audit-code` run `audit-code ensure --quiet` in each repository
 3. use `audit-code` as the repo-local backend fallback
 4. prefer `local-subprocess` unless you explicitly want a backend provider bridge
 5. use `subprocess-template` only when integrating a non-native editor or launcher surface

package/docs/bootstrap-install.md

@@ -1,15 +1,34 @@
 # Bootstrap install
 
-The intended setup flow is a single bootstrap step from the target repository root:
+The intended user setup is one global package install:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes the `audit-code` command available from any repository. Package
+install also seeds user-level command or skill assets for hosts we can update
+safely, including the Claude command file and Codex skill bundle.
+
+After that, the normal user flow is to invoke `/audit-code` in a supported host.
+The prompt starts by running:
+
+```bash
+audit-code ensure --quiet
+```
+
+`ensure` is idempotent. From the target repository root, it writes the
+repo-local `/audit-code` surfaces only when they are missing or stale.
+
+The explicit repair or compatibility command remains:
 
 ```bash
 audit-code install
 ```
 
-That command installs the repo-local `/audit-code` surfaces we can automate today.
-It is also the single refresh path: rerun `audit-code install` after prompt or
-skill updates to rewrite the shared install assets and every generated
-host-specific surface from the same source files.
+That command always rewrites the repo-local `/audit-code` surfaces we can
+automate today. `audit-code ensure --force` is the equivalent self-bootstrap
+entrypoint when you want forced refresh semantics.
 The generated manifest records the canonical prompt and skill source paths so
 host surfaces can be checked against one shared source of truth instead of
 drifting independently.
@@ -79,6 +98,9 @@ without supplying extra root paths, provider flags, or model-selection arguments
 
 ## What is fully automated today
 
+- global `npm install -g auditor-lambda` seeds user-level Claude command and
+  Codex skill assets when filesystem permissions allow it
+- `/audit-code` runs `audit-code ensure --quiet` before advancing the audit
 - shared installer output, manifest generation, and repo-local MCP launcher generation
 - default backend fallback session-config creation when no config exists yet
 - Codex skill-bundle and AGENTS-oriented install output

package/docs/github-copilot.md

@@ -1,12 +1,27 @@
 # GitHub Copilot setup
 
-This is the first shipped native host integration for the `/audit-code` conversation surface.
+This is one repo-local host integration for the `/audit-code` conversation surface.
 
-It is now a narrower host-specific path. The preferred setup flow is `audit-code install`, which bootstraps all supported repo-local host surfaces in one step.
+It is now a narrower host-specific path. The preferred user flow is a global
+package install plus the prompt's self-bootstrap step; `audit-code install`
+remains the explicit repair or force-refresh path.
 
 ## Recommended path
 
-From the target repository root:
+Install once:
+
+```bash
+npm install -g auditor-lambda
+```
+
+Then invoke `/audit-code` in a supported chat surface. The prompt runs:
+
+```bash
+audit-code ensure --quiet
+```
+
+If Copilot has not discovered the workspace prompt/MCP files yet, run this from
+the target repository root:
 
 ```bash
 audit-code install
@@ -29,7 +44,8 @@ audit-code install --host vscode
 
 ## Behavior
 
-- the command copies the canonical prompt payload from `skills/audit-code/audit-code.prompt.md`
+- `audit-code ensure` creates or refreshes the same files only when missing or stale
+- `audit-code install` force-refreshes the canonical prompt payload from `skills/audit-code/audit-code.prompt.md`
 - the generated prompt file explicitly sets `agent: auditor` so Copilot Chat uses the generated auditor custom agent
 - the installer upserts its managed compatibility block into `.github/copilot-instructions.md` instead of clobbering unrelated instructions
 - it prints machine-readable JSON describing the installed targets
@@ -46,5 +62,5 @@ audit-code install --root /path/to/repo
 
 The goal is to reduce conversation setup friction without repositioning the backend CLI as the primary product surface.
 
-GitHub Copilot now shares the same repo-native bootstrap path as the other currently automated hosts.
+GitHub Copilot now shares the same repo-native self-bootstrap path as the other currently automated hosts.
 The older `audit-code install-host --host copilot` alias still exists for compatibility, but it is no longer the recommended setup flow.

package/docs/next-steps.md

@@ -16,7 +16,9 @@ The repository now supports:
 - `/audit-code` as the documented canonical product route
 - packaged and repository-local access to `skills/audit-code/audit-code.prompt.md`
 - `audit-code prompt-path` as a stable prompt lookup helper
-- `audit-code install --host vscode|opencode|codex|claude-desktop|antigravity|all` as a bootstrap installer for the current host surfaces
+- `npm install -g auditor-lambda` as the intended one-time user install
+- `audit-code ensure` as an idempotent self-bootstrap helper for current repository host surfaces
+- `audit-code install --host vscode|opencode|codex|claude-desktop|antigravity|all` as an explicit repair or force-refresh installer for the current host surfaces
 - `audit-code mcp` as a first-class stdio MCP server entrypoint
 - a stable MCP contract with the `start_audit`, `get_status`, `continue_audit`, `explain_task`, `validate_artifacts`, `import_results`, and `import_runtime_updates` tools
 - repo-local MCP resources for current artifacts, operator handoff, install guidance, and the current audit report
@@ -109,7 +111,7 @@ The repository should not be described as frictionless and production-ready unti
 
 ### Codex, Claude Desktop, OpenCode, and VS Code
 
-- `audit-code install` remains the default bootstrap path
+- `audit-code ensure` remains the default self-bootstrap path and `audit-code install` remains the explicit repair path
 - the generated repo-local surfaces are obvious in installer output and in `.audit-code/install/GETTING-STARTED.md`
 - a new user can invoke `/audit-code` without guessing where prompts or commands were written
 - the generated MCP setup path works in the real host, not only in unit tests

package/docs/packaging.md

@@ -4,6 +4,7 @@ This repository validates the packaged installation story for both:
 
 1. the canonical conversation prompt asset
 2. the backend fallback `audit-code` entrypoint
+3. the self-bootstrap `audit-code ensure` path used by global slash commands
 
 It does so in two installation modes:
 
@@ -20,6 +21,10 @@ That means the package needs to ship:
 - the companion Codex/OpenCode skill asset at `skills/audit-code/SKILL.md`
 - packet-dispatch support data such as `dispatch/lens-definitions.json`
 - the backend fallback wrapper exposed as `audit-code`
+- user-level postinstall assets for hosts we can safely seed from a global npm
+  install, currently the Claude command and Codex skill bundle
+- `audit-code ensure`, so a globally installed slash command can lazily create
+  the repo-local host assets it needs in each target repository
 
 A linked-command smoke test proves the installed wrapper and prompt lookup work from the working tree.
 A packaged-install smoke test proves the same assets still work when consumed from the packed artifact that a downstream installer would receive.
@@ -52,6 +57,7 @@ That script:
 - installs it into a fresh temporary directory
 - verifies the packaged prompt asset is present and discoverable
 - verifies `audit-code install` can write the bootstrap host surfaces from the packaged install
+- verifies `audit-code ensure` can create those surfaces lazily from the packaged install
 - invokes the installed `audit-code` binary from `node_modules/.bin`
 - validates emitted JSON against `schemas/audit-code-v1alpha1.schema.json`
 - exercises the same evidence-import and completion flow used by the linked-command smoke test

package/docs/product-direction.md

@@ -33,7 +33,26 @@ audit-code prompt-path
 
 That command exists to locate the conversation prompt asset, not to reposition the CLI as the primary user surface.
 
-The preferred bootstrap installer is:
+The intended package install is:
+
+```bash
+npm install -g auditor-lambda
+```
+
+That makes the backend command globally available and lets hosts with user-level
+command or skill discovery expose `/audit-code` before any repository-local
+files exist.
+
+The conversation prompt should self-bootstrap the current repository with:
+
+```bash
+audit-code ensure --quiet
+```
+
+That command creates or refreshes repo-local `/audit-code` surfaces only when
+they are missing or stale.
+
+The explicit repair and compatibility installer is:
 
 ```bash
 audit-code install

package/docs/production-launch-bar.md

@@ -10,8 +10,10 @@ The current product surfaces are:
 
 1. `/audit-code` in conversation as the canonical user-facing route
 2. `audit-code prompt-path` as the stable way to locate the packaged prompt asset
-3. `audit-code install` as the preferred repo-local bootstrap installer
-4. `audit-code` as the repo-local backend fallback wrapper
+3. `npm install -g auditor-lambda` as the intended one-time user install
+4. `audit-code ensure` as the idempotent repo-local self-bootstrap helper
+5. `audit-code install` as the explicit repo-local repair or force-refresh installer
+6. `audit-code` as the repo-local backend fallback wrapper
 
 Anything below `dist/index.js` remains a backend or development interface rather than the primary end-user contract.
 
@@ -30,6 +32,9 @@ Anything below `dist/index.js` remains a backend or development interface rather
   - `skills/audit-code/audit-code.prompt.md`
   - `schemas/audit-code-v1alpha1.schema.json`
 - the checked-in `dist/` output is part of the shipped runtime contract for installed usage
+- global package postinstall should seed user-level command/skill assets only for
+  hosts with stable user-local paths; repo-local assets remain the responsibility
+  of `audit-code ensure` or `audit-code install`
 
 ### Backend providers
 
@@ -40,7 +45,7 @@ Anything below `dist/index.js` remains a backend or development interface rather
 ### Host surfaces
 
 - ChatGPT-style project conversations are the intended `/audit-code` product surface
-- Codex, Claude Desktop, OpenCode, VS Code / GitHub Copilot, and Antigravity repository surfaces are generated through `audit-code install`
+- Codex, Claude Desktop, OpenCode, VS Code / GitHub Copilot, and Antigravity repository surfaces are generated through `audit-code ensure` or explicit `audit-code install`
 - editor integrations that import `skills/audit-code/audit-code.prompt.md` are supported as prompt-based integrations
 - no editor-specific native install surface should be called production-ready until it has explicit documentation and a repeatable verification path
 

package/docs/production-readiness.md

@@ -16,7 +16,8 @@ What is already true:
 - npm registry state should be verified at release time rather than inferred from checked-in docs
 - malformed config and corrupted artifact handling are explicit
 - blocked fallback runs now emit structured operator handoff guidance
-- supported repo-local hosts now share a bootstrap install path via `audit-code install`
+- supported repo-local hosts now share an idempotent self-bootstrap path via `audit-code ensure`
+- `audit-code install` remains the explicit repair and force-refresh path
 - configured provider-assisted review can now continue to completion in a single wrapper invocation
 - the GitHub publish workflow is configured for Trusted Publishing through GitHub OIDC rather than a long-lived npm token
 
@@ -27,7 +28,7 @@ The biggest remaining gaps are product and release-operational, not core wrapper
 1. npm publication is not fully proven end to end.
    The repo now has a Trusted Publishing workflow and a passing local dry run, but npm-side trusted publisher setup plus the first GitHub Actions dry run still need to be completed outside the codebase.
 2. The primary conversation-first product still has setup friction on hosts without a verified repo-local slash-command surface.
-   Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity now share the same bootstrap command, but each generated host surface still needs real-product verification before it can be called frictionless.
+   Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity now share the same self-bootstrap command, but each generated host surface still needs real-product verification before it can be called frictionless.
 3. Provider-assisted continuation still needs polish outside the happy path.
    Configured interactive bridges can now continue through audit-task review, but operator guidance and host-specific ergonomics still need refinement when a provider cannot produce results cleanly.
 
@@ -38,7 +39,7 @@ The explicit launch bar is now documented in `docs/production-launch-bar.md`, an
 1. Confirm release operations externally.
    Validate npm package-name ownership for `auditor-lambda`, configure npm Trusted Publishing for `.github/workflows/publish-package.yml`, and run a real GitHub Actions dry run or prerelease publish from that workflow path.
 2. Extend bootstrap coverage beyond the currently automated hosts.
-   Keep `audit-code install` stable for Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity, and close the remaining friction gap for hosts that still lack a verified repo-local install surface.
+   Keep `audit-code ensure` and `audit-code install` stable for Codex, Claude Desktop, OpenCode, VS Code / Copilot, and Antigravity, and close the remaining friction gap for hosts that still lack a verified repo-local install surface.
 3. Polish provider-assisted UX.
    Keep the new continuation path explicit and inspectable while improving failure hints, host guidance, and operator recovery when a provider bridge misbehaves.
 

package/docs/usage.md

@@ -6,7 +6,28 @@ The primary product remains `/audit-code` in conversation.
 
 ## Stable installed helpers
 
-Bootstrap the supported repo-local `/audit-code` surfaces for the current repository:
+Install the package once for the current user:
+
+```bash
+npm install -g auditor-lambda
+```
+
+Then invoke `/audit-code` in a supported host. The prompt runs this idempotent
+bootstrap helper before advancing the audit:
+
+```bash
+audit-code ensure --quiet
+```
+
+Run the same helper manually when you want to create or refresh the repo-local
+host assets without starting an audit:
+
+```bash
+audit-code ensure
+```
+
+Explicitly rewrite the supported repo-local `/audit-code` surfaces for the
+current repository:
 
 ```bash
 audit-code install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/scripts/postinstall.mjs

@@ -5,23 +5,60 @@ import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 
 const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const sourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
-const destDir = join(homedir(), '.claude', 'commands');
-const destFile = join(destDir, 'audit-code.md');
+const promptSourceFile = join(pkgRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
+const skillSourceFile = join(pkgRoot, 'skills', 'audit-code', 'SKILL.md');
 
-if (!existsSync(sourceFile)) {
-  console.warn(`audit-code: skill source not found at ${sourceFile} — skipping Claude command install`);
+function readRequiredSource(path, label) {
+  if (!existsSync(path)) {
+    console.warn(`audit-code: ${label} source not found at ${path} - skipping global command install`);
+    process.exitCode = 0;
+    return null;
+  }
+
+  return readFileSync(path);
+}
+
+function writeGeneratedFile(path, content) {
+  const action = existsSync(path) ? 'updated' : 'installed';
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+  return action;
+}
+
+const promptSource = readRequiredSource(promptSourceFile, 'prompt');
+const skillSource = readRequiredSource(skillSourceFile, 'skill');
+
+if (!promptSource || !skillSource) {
   process.exit(0);
 }
 
-try {
-  mkdirSync(destDir, { recursive: true });
-  const action = existsSync(destFile) ? 'updated' : 'installed';
-  // Read then write to avoid Windows file-lock issues with copyFileSync
-  writeFileSync(destFile, readFileSync(sourceFile));
-  console.log(`audit-code: ${action} /audit-code Claude command → ${destFile}`);
-} catch (err) {
-  console.warn(`audit-code: could not install Claude command (${err.message})`);
-  console.warn(`  To install manually, run:`);
-  console.warn(`    cp "${sourceFile}" "${destFile}"`);
+const installs = [
+  {
+    label: 'Claude command',
+    path: join(homedir(), '.claude', 'commands', 'audit-code.md'),
+    content: promptSource,
+  },
+  {
+    label: 'Codex skill',
+    path: join(homedir(), '.codex', 'skills', 'audit-code', 'SKILL.md'),
+    content: skillSource,
+  },
+  {
+    label: 'Codex prompt',
+    path: join(homedir(), '.codex', 'skills', 'audit-code', 'audit-code.prompt.md'),
+    content: promptSource,
+  },
+];
+
+for (const install of installs) {
+  try {
+    const action = writeGeneratedFile(install.path, install.content);
+    console.log(`audit-code: ${action} global ${install.label} at ${install.path}`);
+  } catch (err) {
+    console.warn(`audit-code: could not install global ${install.label} (${err.message})`);
+    console.warn(`  To install manually, copy from:`);
+    console.warn(`    ${install.label === 'Codex skill' ? skillSourceFile : promptSourceFile}`);
+    console.warn(`  to:`);
+    console.warn(`    ${install.path}`);
+  }
 }

package/skills/audit-code/SKILL.md

@@ -38,13 +38,29 @@ Bounded steps are a backend implementation detail, not the intended user experie
 
 The prompt payload in `audit-code.prompt.md` remains the canonical instruction asset.
 
-The preferred setup path is:
+The intended user setup is one global package install:
 
 ```bash
-audit-code install
+npm install -g auditor-lambda
+```
+
+That makes `audit-code` available on `PATH` and seeds user-level command/skill
+assets for hosts the package can safely update. The prompt self-bootstraps the
+current repository before advancing the audit:
+
+```bash
+audit-code ensure --quiet
 ```
 
-That bootstrap writes repo-local host assets for Codex, Claude Desktop, OpenCode, VS Code, and Antigravity plus shared MCP setup guidance.
+That idempotent bootstrap writes repo-local host assets for Codex, Claude Desktop,
+OpenCode, VS Code, and Antigravity plus shared MCP setup guidance only when they
+are missing or stale.
+
+Use the explicit installer for repair or forced refresh:
+
+```bash
+audit-code install
+```
 
 Use direct prompt import only when the target host still needs it after bootstrap.
 

package/skills/audit-code/audit-code.prompt.md

@@ -33,7 +33,20 @@ and ingest results mechanically.
 
 ## Step 1 - Advance Deterministic State
 
-Run:
+First, make sure the repository has the minimal local assets required by the
+current host:
+
+```bash
+audit-code ensure --quiet
+```
+
+Inside the `auditor-lambda` repository itself, use:
+
+```bash
+node audit-code.mjs ensure --quiet
+```
+
+Then run:
 
 ```bash
 audit-code