auriga-cli 1.18.3 → 1.18.5

package/dist/api-types.d.ts

@@ -1,4 +1,10 @@
-export type ItemStatus = "installed" | "update-available" | "not-installed";
+export type ItemStatus = "installed" | "update-available" | "not-installed"
+/** Dual-Agent plugin where some target Agents have the plugin installed
+ *  and some don't (e.g. Claude side installed, Codex side missing). Distinct
+ *  from `update-available` because the action is "install on the missing
+ *  side", not "upgrade to a newer version". The missing agents are
+ *  enumerated in `PluginState.missingAgents`. */
+ | "partial-install";
 /**
  * Per-category scan scope. Each category (workflow / skills / plugins / hooks)
  * can be independently scanned in either user scope (~/.claude/, ~/.codex/)
@@ -53,9 +59,15 @@ export interface PluginState {
      *  `agents.length === 2` the UI shows a BOTH badge and Apply installs to
      *  each agent in turn. Status is aggregated across all targeted agents:
      *  `installed` ⇔ all agents installed; `not-installed` ⇔ all not-installed;
-     *  any partial state (one side installed, other not) → `update-available`
-     *  so a single Apply backfills the missing side. */
+     *  partial state (some installed, some not) → `partial-install`; agent-
+     *  uniform version drift → `update-available`. */
     agents: ApplyAgent[];
+    /** Agents that target this plugin but don't have it installed. Populated
+     *  iff `status === "partial-install"`. Lets the UI render per-agent
+     *  ✓/✗ marks and tell the user exactly which side needs `auriga-cli`
+     *  to backfill. Always omitted for `installed` / `not-installed` /
+     *  `update-available`. */
+    missingAgents?: ApplyAgent[];
     currentVersion?: string;
     expectedVersion?: string;
     versionSource: "upstream-live" | "catalog";
@@ -63,6 +75,12 @@ export interface PluginState {
      *  "user" (Codex has no project-scope plugin concept). See WorkflowState
      *  comment on why this is typed optional. */
     observedScope?: ScanScope;
+    /** True for plugins whose source lives in an upstream marketplace, not in
+     *  this repo (skill-creator / claude-md-management / codex). The scanner
+     *  short-circuits update-available reporting for these — upgrades go
+     *  through `claude plugins update`, not us. The UI renders an EXTERNAL
+     *  badge to make the "not our jurisdiction" signal explicit. */
+    external?: boolean;
 }
 export interface HookState {
     name: string;
@@ -74,7 +92,12 @@ export interface HookState {
     observedScope?: ScanScope;
 }
 export interface StateWarning {
-    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline" | "claude-code-not-installed" | "settings-unreadable" | "skill-malformed" | "workflow-unknown-version";
+    code: "claude-cli-missing" | "codex-cli-missing" | "marketplace-offline" | "claude-code-not-installed" | "settings-unreadable" | "skill-malformed"
+    /** Project-scope CLAUDE.md (or the user-scope fallback when scanning
+     *  user scope) is present but has no recognizable `# auriga Workflow (vX.Y.Z)`
+     *  header. The row reports `not-installed`; install will back up the
+     *  existing file to `CLAUDE.md.bak` and write ours. */
+     | "workflow-foreign-claudemd";
     message: string;
 }
 export type ApplyCategory = "workflow" | "skill" | "recommended-skill" | "plugin" | "hook";

package/dist/catalog.d.ts

@@ -9,9 +9,29 @@ export interface CatalogEntry {
      *  because `plugins/<name>/.claude-plugin/plugin.json` is NOT shipped in
      *  the npm tarball (see `package.json` `files` field). */
     expectedVersion?: string;
+    /** Build-time-baked agent map for plugin entries. Derived from
+     *  `.claude/plugins.json` ∪ `.agents/plugins/install.json` — those config
+     *  files are NOT shipped in the npm tarball, so the scanner can't read
+     *  them at runtime. Baking here lets `/api/state` correctly classify
+     *  dual-Agent plugins as `["claude","codex"]` for installed users.
+     *  Absent on skill / hook entries. */
+    agents?: ("claude" | "codex")[];
+    /** True for plugins whose source lives in an UPSTREAM marketplace
+     *  (skill-creator / claude-md-management / codex), not in this repo. The
+     *  scanner uses this to disable update-available reporting — those
+     *  plugins update through `claude plugins update`, not through us. UI
+     *  surfaces an EXTERNAL badge so users know where to look. */
+    external?: boolean;
 }
 export interface Catalog {
     generatedAt: string;
+    /** Workflow content version baked from `CLAUDE.md`'s `# auriga Workflow (vX.Y.Z)`
+     *  header at build time. MUST live here rather than be read at runtime
+     *  because `CLAUDE.md` is NOT in the npm tarball — `package.json` `files`
+     *  allowlists only `dist/`. Empty string when the header is unparseable;
+     *  the scanner then degrades to "trust whatever the user has" rather than
+     *  forcing phantom update-available against an empty expected value. */
+    workflowVersion: string;
     workflowSkills: CatalogEntry[];
     recommendedSkills: CatalogEntry[];
     plugins: CatalogEntry[];

package/dist/catalog.json

@@ -1,5 +1,6 @@
 {
-  "generatedAt": "2026-05-12T13:58:42.583Z",
+  "generatedAt": "2026-05-12T16:35:23.439Z",
+  "workflowVersion": "1.7.0",
   "workflowSkills": [
     {
       "name": "brainstorming",
@@ -75,34 +76,61 @@
   "plugins": [
     {
       "name": "skill-creator",
-      "description": "Create and manage custom skills"
+      "description": "Create and manage custom skills",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "name": "claude-md-management",
-      "description": "Audit and improve CLAUDE.md files"
+      "description": "Audit and improve CLAUDE.md files",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "name": "codex",
-      "description": "Cross-model collaboration with Codex"
+      "description": "Cross-model collaboration with Codex",
+      "agents": [
+        "claude"
+      ],
+      "external": true
     },
     {
       "name": "auriga-go",
       "description": "(Claude/Codex) Workflow autopilot for the auriga workflow. Reminder-based navigation across CLAUDE.md's phases. Bundles a /goalify skill that plans an autonomous goal from a spec or work-in-progress and dispatches it via Claude Code's built-in /goal command.",
+      "agents": [
+        "claude",
+        "codex"
+      ],
       "expectedVersion": "1.1.0"
     },
     {
       "name": "auriga-git-guards",
       "description": "(Claude/Codex) Git lifecycle guardrails: commit-reminder + PR-create snapshot inject + PR-ready structural block. Bundles the git-workflow skill (Claude Code + Codex).",
+      "agents": [
+        "claude",
+        "codex"
+      ],
       "expectedVersion": "1.1.0"
     },
     {
       "name": "deep-review",
       "description": "(Claude/Codex) Multi-dimensional PR review orchestrator. Dispatches parallel reviewers (spec-conformance, correctness, test-quality, docs-sync, robustness, security, ux, performance, structure, code-quality, skill-plugin-quality) and synthesizes findings into an actionable punch list. Supports project-level custom reviewers via docs/rules/review/ and ships a reviewer-creator skill for scaffolding them.",
+      "agents": [
+        "claude",
+        "codex"
+      ],
       "expectedVersion": "0.3.1"
     },
     {
       "name": "session-instructions-loader",
       "description": "(Codex) Injects extra instruction files on session start",
+      "agents": [
+        "codex"
+      ],
       "expectedVersion": "1.0.0"
     }
   ],

package/dist/scan-catalog.js

@@ -1,37 +1,28 @@
-// Build the scan-time Catalog (the shape src/state.ts consumes) from
-// auriga-cli's installed package state. This bridges the build-time
-// `dist/catalog.json` (which carries names + descriptions for the menu)
-// and the runtime scanner's need for expected hashes + versions.
+// Build the scan-time Catalog (the shape src/state.ts consumes) from the
+// build-time `dist/catalog.json`. This module is intentionally a *thin
+// adapter* — it must NOT read any file outside `dist/catalog.json`, because
+// the npm tarball's `files` field allowlists only `dist/`. Reading from
+// `packageRoot/CLAUDE.md`, `packageRoot/.claude/plugins.json`, or
+// `packageRoot/.agents/skills/<name>/SKILL.md` succeeds in dev (where
+// packageRoot === repoRoot) but silently returns empty for npm-installed
+// users, leaving the scanner unable to surface real update signals.
 //
-// Inputs (all under packageRoot):
-//   dist/catalog.json     — names + descriptions for 5 categories
-//   skills-lock.json      — expected SHA256 for every vendored skill
-//   .claude/plugins.json  — Claude plugin entries (agent = "claude")
-//   .agents/plugins/install.json — Codex plugin entries (agent = "codex")
-//   .claude/hooks/hooks.json — registers settingsEvents per hook (event /
-//                           matcher / if) used by state.ts for drift
-//                           detection in <scope>/.claude/settings.json
-//   CLAUDE.md             — `# auriga Workflow (vX.Y.Z)` provides
-//                           workflowVersion
+// Anything the scanner needs beyond what's already in catalog.json must
+// first be baked at build time in `src/build/generate-catalog.ts`.
 //
-// Anything missing is treated as "no expectation" (empty hash / version)
-// rather than throwing; scanState will still produce a structurally valid
-// StateReport — items just classify as not-installed or installed
-// depending on whether the user-side data exists.
-import { createHash } from "node:crypto";
+// Scope of the current bake (covered fields):
+//   - workflowVersion         — from CLAUDE.md header
+//   - plugin agents map       — from .claude/plugins.json ∪ .agents/plugins/install.json
+//   - plugin expectedVersion  — from plugins/<name>/.claude-plugin/plugin.json
+//   - plugin external flag    — derived (no in-tree manifest = external)
+//
+// Out of scope for v1.18.4 (follow-up PRs):
+//   - hook expectedEvent / expectedMatcher / expectedIf (from .claude/hooks/hooks.json)
+//   - apply-time installer config (the install path reads .claude/plugins.json
+//     directly — that needs runWebUi → fetchContentRoot rewire, not bake).
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { loadCatalog } from "./catalog.js";
-async function sha256SkillMd(skillsRoot, name) {
-    try {
-        const buf = await readFile(path.join(skillsRoot, name, "SKILL.md"));
-        return createHash("sha256").update(buf).digest("hex");
-    }
-    catch {
-        return "";
-    }
-}
-const WORKFLOW_VERSION_RE = /^#\s*auriga Workflow\s*\(v([\d.]+)\)/m;
 async function tryReadFile(p) {
     try {
         return await readFile(p, "utf8");
@@ -42,24 +33,21 @@ async function tryReadFile(p) {
 }
 export async function buildScanCatalog(packageRoot) {
     const dist = loadCatalog(packageRoot);
-    // Workflow version: parse from auriga-cli's own CLAUDE.md template.
-    // If missing, leave as empty string so workflow always classifies as
-    // not-installed (no expectation set).
-    const claudeMd = await tryReadFile(path.join(packageRoot, "CLAUDE.md"));
-    const m = claudeMd ? WORKFLOW_VERSION_RE.exec(claudeMd) : null;
-    const workflowVersion = m ? m[1] : "";
-    // Skills + recommended: sha256 of each shipped SKILL.md. This is the same
-    // hash the scanner computes for `<scope>/.claude/skills/<name>/SKILL.md`
-    // at scan time, so a match means "user's installed copy is identical to
-    // the version auriga-cli ships". skills-lock.json's `computedHash` field
-    // hashes the entire skill directory (every file, sorted), which doesn't
-    // line up with the scanner's per-file model — we deliberately ignore it.
-    const skillsRoot = path.join(packageRoot, ".agents", "skills");
+    // Workflow version — baked from CLAUDE.md header at build time. See
+    // module comment for the "no runtime reads outside dist/" rule.
+    const workflowVersion = dist.workflowVersion ?? "";
+    // Skills: drift detection deliberately deferred to `npx skills update
+    // --project`, which already compares against the skill's own upstream
+    // repo HEAD. Our catalog snapshot would only know "what auriga-cli
+    // shipped at this CLI release" — at best a stale proxy that mis-reports
+    // legitimate user-side updates as drift. Setting expectedHash to "" puts
+    // classifySkillByFile into wildcard mode: row reports installed if
+    // SKILL.md exists, not-installed otherwise; never update-available.
     const skills = {};
     for (const entry of dist.workflowSkills) {
         skills[entry.name] = {
             description: entry.description,
-            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
+            expectedHash: "",
             isWorkflow: true,
         };
     }
@@ -67,73 +55,37 @@ export async function buildScanCatalog(packageRoot) {
     for (const entry of dist.recommendedSkills) {
         recommendedSkills[entry.name] = {
             description: entry.description,
-            expectedHash: await sha256SkillMd(skillsRoot, entry.name),
+            expectedHash: "",
         };
     }
-    // Plugins: split by agent based on which config file lists them. A
-    // plugin can appear in both registries (cross-agent plugins like
-    // auriga-go); we represent it once per agent.
+    // Plugins: agents + expectedVersion + external all come from
+    // dist/catalog.json now (baked in src/build/generate-catalog.ts). The
+    // previous version of this module read .claude/plugins.json +
+    // .agents/plugins/install.json at runtime — those files are NOT in the
+    // npm tarball, so for installed users every plugin defaulted to a
+    // ["claude"] agent classification (root cause of dual-Agent plugin
+    // mis-classification in v1.18.x).
     const plugins = {};
-    const claudePluginsText = await tryReadFile(path.join(packageRoot, ".claude", "plugins.json"));
-    const claudeNames = new Set();
-    if (claudePluginsText) {
-        try {
-            const parsed = JSON.parse(claudePluginsText);
-            for (const p of parsed.plugins ?? []) {
-                if (p.name)
-                    claudeNames.add(p.name);
-            }
-        }
-        catch {
-            /* ignore */
-        }
-    }
-    const codexInstallText = await tryReadFile(path.join(packageRoot, ".agents", "plugins", "install.json"));
-    const codexNames = new Set();
-    if (codexInstallText) {
-        try {
-            const parsed = JSON.parse(codexInstallText);
-            for (const p of parsed.plugins ?? []) {
-                if (p.name)
-                    codexNames.add(p.name);
-            }
-        }
-        catch {
-            /* ignore */
-        }
-    }
     for (const entry of dist.plugins) {
-        // Collect every agent that registers this plugin. A plugin can ship in
-        // both registries (cross-agent plugins like auriga-go); we emit it as
-        // a single multi-agent record so the UI shows one row + BOTH badge and
-        // Apply installs to each side.
-        const agents = [];
-        if (claudeNames.has(entry.name))
-            agents.push("claude");
-        if (codexNames.has(entry.name))
-            agents.push("codex");
-        if (agents.length === 0)
-            agents.push("claude"); // unknown defaults to claude
-        // expectedVersion comes from the build-time-baked field in dist/catalog.json
-        // (populated by `src/build/generate-catalog.ts` from
-        // `plugins/<name>/.claude-plugin/plugin.json`). It MUST be baked at build
-        // time because `plugins/<name>/` is NOT shipped in the npm tarball
-        // (`package.json` `files` field allowlists only `dist/`), so reading it
-        // at runtime from packageRoot would silently fail for npm-installed users.
+        const agents = Array.isArray(entry.agents) && entry.agents.length > 0
+            ? [...entry.agents]
+            : ["claude"]; // safety fallback: unknown shape defaults to claude
         plugins[entry.name] = {
             description: entry.description,
             agents,
             ...(typeof entry.expectedVersion === "string" && entry.expectedVersion.length > 0
                 ? { expectedVersion: entry.expectedVersion }
                 : {}),
+            ...(entry.external === true ? { external: true } : {}),
         };
     }
-    // Hooks: the scanner reads <scope>/.claude/settings.json and matches by
-    // `_marker` (see state.ts scanHooks). Drift detection compares the
-    // registered event / matcher / if values against the hook's canonical
-    // settingsEvents[0] from .claude/hooks/hooks.json. We deliberately do NOT
-    // hash index.mjs — the user's installed index.mjs lives at <scope>/.claude/
-    // hooks/<name>/index.mjs and isn't part of the settings.json drift signal.
+    // Hooks: TODO follow-up — bake expectedEvent / expectedMatcher / expectedIf
+    // into dist/catalog.json the same way agents are baked. Currently the
+    // runtime read of packageRoot/.claude/hooks/hooks.json works in dev
+    // (packageRoot === repoRoot) but fails silently for npm-installed users
+    // — `package.json` `files` allowlist doesn't ship `.claude/`. So hook
+    // drift detection is correct in dev and degraded (always "installed" if
+    // marker present) in production. Follow-up bake closes the dev/prod gap.
     const hooksJsonPath = path.join(packageRoot, ".claude", "hooks", "hooks.json");
     const hooksJsonRaw = await tryReadFile(hooksJsonPath);
     const hooksJson = hooksJsonRaw ? JSON.parse(hooksJsonRaw) : {};

package/dist/state.d.ts

@@ -15,6 +15,12 @@ export interface Catalog {
         /** Agents this plugin can install into. Length 1 or 2. */
         agents: ("claude" | "codex")[];
         expectedVersion?: string;
+        /** When true, this plugin is published in an UPSTREAM marketplace
+         *  (skill-creator / claude-md-management / codex), not in this repo.
+         *  Classifier MUST NOT report `update-available` for external plugins —
+         *  those upgrade through `claude plugins update`, not us. The UI surfaces
+         *  an EXTERNAL badge so users know to defer to the upstream tool. */
+        external?: boolean;
     }>;
     hooks: Record<string, {
         description: string;
@@ -65,23 +71,6 @@ export interface ScanOptions {
     homeDir?: string;
 }
 export declare function scanState(projectRoot: string, catalog: Catalog, opts?: ScanOptions): Promise<StateReport>;
-/**
- * Dedupe plugins by `id`, merging dual-Agent records into a single
- * multi-agent row. Aggregation rules:
- *
- *   agents:  union of all agent arrays for this id (claude before codex).
- *   status:  installed     ⇔ every agent's record is installed
- *            not-installed ⇔ every agent's record is not-installed
- *            otherwise     → update-available (partial install or any agent
- *                            with a pending update). One Apply covers all
- *                            gaps because the handler iterates `agents`.
- *
- * Non-status fields (description, currentVersion, expectedVersion,
- * versionSource) come from the first record we see. Today both sides report
- * the same description (catalog-driven) and the same versions for any
- * registry-pinned plugin, so this is safe; if a future divergence appears
- * we'll need a deliberate merge policy.
- */
 export declare function mergePluginsById(records: PluginState[]): PluginState[];
 /** Default: run `claude plugins list --json` (no scope flag — the CLI
  *  doesn't expose one) plus the `--available` variant, then filter the

package/dist/state.js

@@ -94,31 +94,27 @@ function dirExists(p) {
         return false;
     }
 }
-/**
- * Dedupe plugins by `id`, merging dual-Agent records into a single
- * multi-agent row. Aggregation rules:
- *
- *   agents:  union of all agent arrays for this id (claude before codex).
- *   status:  installed     ⇔ every agent's record is installed
- *            not-installed ⇔ every agent's record is not-installed
- *            otherwise     → update-available (partial install or any agent
- *                            with a pending update). One Apply covers all
- *                            gaps because the handler iterates `agents`.
- *
- * Non-status fields (description, currentVersion, expectedVersion,
- * versionSource) come from the first record we see. Today both sides report
- * the same description (catalog-driven) and the same versions for any
- * registry-pinned plugin, so this is safe; if a future divergence appears
- * we'll need a deliberate merge policy.
- */
 export function mergePluginsById(records) {
     const byId = new Map();
-    const statusByIdPerAgent = new Map();
+    // Per-agent (agent, status, version) tuples preserved across the fold so
+    // the aggregation step can emit `partial-install` + `missingAgents` when
+    // one side is installed and the other isn't, AND pick the *stale* side's
+    // currentVersion when status === "update-available" (otherwise the merge
+    // inherited Claude's version, producing the misleading `vX → vX` display
+    // in the v1.18.4 verification).
+    const perAgentByIdEntries = new Map();
     for (const rec of records) {
+        // Pre-merge records are per-agent: their `agents[]` array contains the
+        // single Agent this row was scanned for. The merge step below unions
+        // those into the final dual-Agent record.
+        const recAgent = rec.agents[0];
+        const perAgentEntry = recAgent
+            ? { agent: recAgent, status: rec.status, currentVersion: rec.currentVersion }
+            : null;
         const existing = byId.get(rec.id);
         if (!existing) {
             byId.set(rec.id, { ...rec });
-            statusByIdPerAgent.set(rec.id, [rec.status]);
+            perAgentByIdEntries.set(rec.id, perAgentEntry ? [perAgentEntry] : []);
             continue;
         }
         // Union agents preserving order: existing first, then any new ones.
@@ -129,28 +125,58 @@ export function mergePluginsById(records) {
                 seen.add(a);
             }
         }
-        statusByIdPerAgent.get(rec.id).push(rec.status);
+        if (perAgentEntry) {
+            perAgentByIdEntries.get(rec.id).push(perAgentEntry);
+        }
     }
-    // Fold each id's per-agent status list into the aggregated status.
-    for (const [id, statuses] of statusByIdPerAgent) {
+    // Fold per-agent tuples into the aggregated status, missingAgents, and
+    // (when applicable) the corrected currentVersion.
+    for (const [id, perAgent] of perAgentByIdEntries) {
         const rec = byId.get(id);
         if (!rec)
             continue;
-        rec.status = aggregateStatus(statuses);
+        const aggregated = aggregateStatus(perAgent);
+        rec.status = aggregated.status;
+        if (aggregated.missingAgents && aggregated.missingAgents.length > 0) {
+            rec.missingAgents = aggregated.missingAgents;
+        }
+        else {
+            delete rec.missingAgents;
+        }
+        // When status is update-available, surface the version of the *stale*
+        // agent (one whose own status was update-available). Otherwise we'd
+        // keep whichever agent's version was merged first — Claude's, which
+        // may already be at the expected version, producing a `vX → vX`
+        // pseudo-upgrade display.
+        if (rec.status === "update-available") {
+            const stale = perAgent.find((r) => r.status === "update-available");
+            if (stale?.currentVersion) {
+                rec.currentVersion = stale.currentVersion;
+            }
+        }
     }
     return Array.from(byId.values());
 }
-function aggregateStatus(statuses) {
-    if (statuses.length === 0)
-        return "not-installed";
-    if (statuses.every((s) => s === "installed"))
-        return "installed";
-    if (statuses.every((s) => s === "not-installed"))
-        return "not-installed";
-    // Anything else — partial install, pending updates on any agent, mixed
-    // — falls through to update-available so a single Apply backfills the
-    // missing pieces.
-    return "update-available";
+function aggregateStatus(records) {
+    if (records.length === 0)
+        return { status: "not-installed" };
+    if (records.every((r) => r.status === "installed"))
+        return { status: "installed" };
+    if (records.every((r) => r.status === "not-installed"))
+        return { status: "not-installed" };
+    // Mixed. If ANY agent reports not-installed, the row is partially installed
+    // — the user-facing action is "install on the missing side". Surfaces as a
+    // distinct status from version-drift `update-available` so the UI doesn't
+    // render misleading `vX → vX` upgrades (the v1.18.4 deep-review symptom).
+    const missingAgents = records
+        .filter((r) => r.status === "not-installed")
+        .map((r) => r.agent);
+    if (missingAgents.length > 0) {
+        return { status: "partial-install", missingAgents };
+    }
+    // Otherwise version drift on at least one targeted agent — single Apply
+    // upgrades the stale side(s).
+    return { status: "update-available" };
 }
 // ---------------------------------------------------------------------------
 // Workflow
@@ -160,11 +186,12 @@ function workflowPathsForScope(scope, projectRoot, home) {
     if (scope === "user") {
         return [path.join(home, ".claude", "CLAUDE.md")];
     }
-    // Project: <proj>/CLAUDE.md preferred, .claude/CLAUDE.md as fallback.
-    return [
-        path.join(projectRoot, "CLAUDE.md"),
-        path.join(projectRoot, ".claude", "CLAUDE.md"),
-    ];
+    // Project: only `<proj>/CLAUDE.md` — the auriga workflow installer
+    // (src/workflow.ts) writes here and never to `<proj>/.claude/CLAUDE.md`.
+    // The old fallback collapsed onto `$HOME/.claude/CLAUDE.md` when
+    // projectRoot === $HOME (user runs `web-ui` from home dir), leaking
+    // user-scope content into the project-scope row.
+    return [path.join(projectRoot, "CLAUDE.md")];
 }
 function scanWorkflow(scope, projectRoot, home, catalog, warnings) {
     const expectedVersion = catalog.workflowVersion;
@@ -197,14 +224,18 @@ function scanWorkflow(scope, projectRoot, home, catalog, warnings) {
         if (line.trim().length > 0)
             break;
     }
-    // CLAUDE.md exists but no recognizable auriga marker. Per spec degraded
-    // path: status remains "installed" (don't clobber user content on apply)
-    // and emit a workflow-unknown-version warning.
+    // CLAUDE.md exists but no recognizable auriga marker. The file is foreign
+    // — not our workflow. Report `not-installed` honestly; the install path
+    // (src/workflow.ts) already protects user content by backing it up to
+    // `CLAUDE.md.bak` before overwriting. Conflating "something exists here"
+    // with "auriga workflow installed" caused the v1.18.4 verification bug
+    // where running web-ui from `~` reported the user's `# Global`-headed
+    // `~/.claude/CLAUDE.md` as an installed workflow.
     warnings.push({
-        code: "workflow-unknown-version",
-        message: `CLAUDE.md present but no auriga-workflow header found; cannot determine installed version.`,
+        code: "workflow-foreign-claudemd",
+        message: `Foreign CLAUDE.md detected at the workflow path — no auriga-workflow header. Install will back up to CLAUDE.md.bak.`,
     });
-    return { status: "installed", expectedVersion, observedScope: scope };
+    return { status: "not-installed", expectedVersion, observedScope: scope };
 }
 // ---------------------------------------------------------------------------
 // Skills + recommendedSkills
@@ -373,9 +404,13 @@ function degradedClaudeRow(id, def, scope) {
         expectedVersion: def.expectedVersion,
         versionSource: "upstream-live",
         observedScope: scope,
+        ...(def.external === true ? { external: true } : {}),
     };
 }
 function classifyClaudePlugin(id, def, installed, available, scope) {
+    // `external` propagates onto every return below so the UI can surface the
+    // EXTERNAL badge regardless of install state.
+    const externalFlag = def.external === true ? { external: true } : {};
     if (!installed || typeof installed.version !== "string") {
         return {
             id,
@@ -385,9 +420,31 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: typeof available?.source?.ref === "string" ? available.source.ref : def.expectedVersion,
             versionSource: "upstream-live",
             observedScope: scope,
+            ...externalFlag,
         };
     }
     const installedVersion = installed.version;
+    // External plugin short-circuit: we don't own these, so we don't claim
+    // authority on "what version they should be at". `claude plugins update`
+    // is the right channel — the scanner just confirms presence. Status stays
+    // "installed" even if installed.version differs from any signal we have.
+    // The catalog deliberately omits `expectedVersion` for externals, but we
+    // double-down with this guard so a future regression that accidentally
+    // populates expectedVersion still can't flip externals to update-available.
+    if (def.external === true) {
+        return {
+            id,
+            description: def.description,
+            status: "installed",
+            agents: ["claude"],
+            currentVersion: installedVersion,
+            // Don't surface any "expected" on externals — the upstream tool owns
+            // the version conversation.
+            versionSource: "upstream-live",
+            observedScope: scope,
+            ...externalFlag,
+        };
+    }
     const ref = available?.source?.ref;
     const normalizedAvailable = parseRef(typeof ref === "string" ? ref : undefined);
     const normalizedInstalled = parseRef(installedVersion);
@@ -421,6 +478,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: expectedRaw,
             versionSource,
             observedScope: scope,
+            ...externalFlag,
         };
     }
     if (normalizedInstalled !== null && normalizedInstalled === expectedNormalized) {
@@ -433,6 +491,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
             expectedVersion: expectedRaw,
             versionSource,
             observedScope: scope,
+            ...externalFlag,
         };
     }
     return {
@@ -444,6 +503,7 @@ function classifyClaudePlugin(id, def, installed, available, scope) {
         expectedVersion: expectedRaw,
         versionSource,
         observedScope: scope,
+        ...externalFlag,
     };
 }
 // ---------------------------------------------------------------------------
@@ -529,10 +589,12 @@ function degradedCodexRow(id, def) {
         expectedVersion: def.expectedVersion,
         versionSource: "catalog",
         observedScope: "user",
+        ...(def.external === true ? { external: true } : {}),
     };
 }
 function classifyCodexPlugin(id, def, enabled, fsVersion) {
     const expectedVersion = def.expectedVersion;
+    const externalFlag = def.external === true ? { external: true } : {};
     if (!enabled) {
         return {
             id,
@@ -542,6 +604,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
         };
     }
     if (!fsVersion) {
@@ -553,6 +616,22 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
+        };
+    }
+    // External plugin short-circuit, same rationale as classifyClaudePlugin:
+    // we defer authority to `codex plugin marketplace update` and never flag
+    // update-available for upstream-owned plugins.
+    if (def.external === true) {
+        return {
+            id,
+            description: def.description,
+            status: "installed",
+            agents: ["codex"],
+            currentVersion: fsVersion,
+            versionSource: "catalog",
+            observedScope: "user",
+            ...externalFlag,
         };
     }
     if (!expectedVersion || fsVersion === expectedVersion) {
@@ -565,6 +644,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
             expectedVersion,
             versionSource: "catalog",
             observedScope: "user",
+            ...externalFlag,
         };
     }
     return {
@@ -576,6 +656,7 @@ function classifyCodexPlugin(id, def, enabled, fsVersion) {
         expectedVersion,
         versionSource: "catalog",
         observedScope: "user",
+        ...externalFlag,
     };
 }
 /** Return the set of plugin ids whose `[plugins."<id>"]` table has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auriga-cli",
-  "version": "1.18.3",
+  "version": "1.18.5",
   "description": "Interactive CLI to install Claude Code harness modules (Workflow, Skills, Recommended Skills, Plugins, Hooks)",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "pretest": "npm run build",
-    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js",
-    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js",
+    "test": "tsc -p tsconfig.test.json && DEV=1 node --test --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js",
+    "test:watch": "tsc -p tsconfig.test.json --watch & node --test --watch --experimental-test-module-mocks dist-test/tests/hooks.test.js dist-test/tests/hooks-uninstall.test.js dist-test/tests/skills.test.js dist-test/tests/skills-uninstall.test.js dist-test/tests/catalog.test.js dist-test/tests/cli-parse.test.js dist-test/tests/install-nontty.test.js dist-test/tests/plugins.test.js dist-test/tests/plugins-uninstall.test.js dist-test/tests/content-fetch.test.js dist-test/tests/utils.test.js dist-test/tests/guide.test.js dist-test/tests/validators.test.js dist-test/tests/entrypoint.test.js dist-test/tests/state.test.js dist-test/tests/server.test.js dist-test/tests/server-auth.test.js dist-test/tests/server-apply.test.js dist-test/tests/apply-handlers.test.js dist-test/tests/ui-fetch.test.js dist-test/tests/workflow-uninstall.test.js dist-test/tests/tarball-shape.test.js",
     "pretest:e2e": "npm run build",
     "test:e2e": "tsc -p tsconfig.test.json && node --test dist-test/tests/e2e-install.test.js",
     "pretest:web-ui-e2e": "npm run build && npm --prefix ui ci && npm --prefix ui run build",