showdar-skills 0.2.0 → 0.2.2

package/README.md

@@ -1,21 +1,18 @@
 # Showdar Skills
 
+[![npm version](https://img.shields.io/npm/v/showdar-skills?logo=npm)](https://www.npmjs.com/package/showdar-skills)
 [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue?logo=opensourceinitiative&logoColor=white)](./LICENSE)
 [![15 skills](https://img.shields.io/badge/skills-15-6f42c1)](#skill-catalog)
 
 Production-grade software engineering skills for coding agents. Showdar covers
-requirements, planning, design, implementation, debugging, QA, security,
-operations, release readiness, and Git workflows with lightweight intent
+the full lifecycle—from requirements and planning through implementation, QA,
+security, operations, release readiness, and Git—with lightweight intent
 routing and progressive knowledge loading.
 
-> npm publication: prepared for the first release; `showdar-skills@0.2.0` is
-> not published yet.
-
 ## Quick start
 
-After the first npm publication, install the CLI globally and add project
-skills explicitly:
+Install the CLI, then install a role-oriented skill profile into your project:
 
 ```bash
 npm install -g showdar-skills
@@ -24,7 +21,7 @@ showdar init --ai codex --profile developer
 showdar doctor
 ```
 
-The current source-install alternative is:
+To install from source instead:
 
 ```bash
 git clone https://github.com/caongocquy/showdar-skills.git
@@ -32,17 +29,20 @@ cd showdar-skills
 npm install -g .
 ```
 
-CLI installation and skill installation are separate. Installing the CLI
-globally does not install skills globally; `showdar init` controls the project
-or user scope where skills are copied.
+Showdar works with Codex, OpenCode, Claude Code, and universal agent skill
+directories. Choose `backend`, `qa`, or `product` when that gives discovery a
+more precise context; use `full` when you want all capabilities available.
 
 ## Why Showdar?
 
-- 15 focused skills for the software lifecycle, instead of one oversized prompt.
-- Native discovery for Codex, OpenCode, and Claude Code.
-- Evidence-first workflows with bounded safety and verification contracts.
-- Searchable data, references, scripts, stack guidance, and examples loaded only
-  when the selected task needs them.
+- **15 focused skills** instead of one oversized agent prompt.
+- **Lifecycle coverage** from product rules to implementation, verification,
+  security, operations, release readiness, and Git completion.
+- **Intent-based discovery** that selects the workflow matching the request.
+- **Progressive knowledge loading** for deeper references, data, scripts, and
+  examples only when the selected task needs them.
+- **Safe boundaries** around security findings, production operations, release
+  readiness, and destructive Git actions.
 
 ## How it works
 
@@ -66,34 +66,43 @@ SKILL.md
 ```
 
 The 15 skills are not eagerly loaded as full prompts. Lightweight descriptions
-help the agent choose a skill, then that skill loads its workflow and deeper
+help the agent choose one skill; that skill then loads its workflow and deeper
 knowledge progressively.
 
-## Supported agents and destinations
+## Supported agents
 
-| Agent target | Project scope | Global scope |
+| Target | Project destination | Global destination |
 | --- | --- | --- |
-| Codex | `.agents/skills/` | `~/.agents/skills/` |
-| Universal | `.agents/skills/` | `~/.agents/skills/` |
-| OpenCode | `.opencode/skills/` + `.opencode/commands/showdar/` | `~/.config/opencode/skills/` + `~/.config/opencode/commands/showdar/` |
+| Codex / Universal | `.agents/skills/` | `~/.agents/skills/` |
+| OpenCode skills | `.opencode/skills/` | `~/.config/opencode/skills/` |
+| OpenCode commands | `.opencode/commands/showdar/` | `~/.config/opencode/commands/showdar/` |
 | Claude Code | `.claude/skills/` | `~/.claude/skills/` |
 
-Codex and Universal intentionally share `.agents/skills/`; `--ai all` avoids
-duplicating that physical destination. OpenCode receives both skills and
-native `/showdar/...` command files.
+Codex and Universal intentionally share `.agents/skills/`. OpenCode receives
+both skills and native `/showdar/...` command files.
+
+## Project and global installation
+
+Global CLI installation and global skill installation are separate decisions.
+The CLI is installed once; `showdar init` controls where its managed skills go.
 
-### Project and global installation
+### Project scope
 
 Project scope is the default and writes to the current project:
 
 ```bash
 cd my-project
-showdar init --scope project --ai codex --profile developer
+showdar init --ai codex --profile developer
 showdar status
 showdar doctor
 ```
 
-Global scope does not require a Git repository:
+This creates `.agents/skills/` for Codex/Universal, or the corresponding native
+target directories. Project ownership is recorded in `.showdar.json`.
+
+### Global scope
+
+Global scope installs user-level skills and does not require a Git repository:
 
 ```bash
 showdar init --scope global --ai codex --profile developer
@@ -101,24 +110,22 @@ showdar status --scope global
 showdar doctor --scope global
 ```
 
-Global CLI installation is not global skill installation. Project ownership is
-stored in `.showdar.json`; global ownership is stored in `~/.showdar/global.json`.
-Only Showdar-owned paths are refreshed or removed.
+Global ownership is recorded in `~/.showdar/global.json`. Only Showdar-owned
+paths are refreshed or removed.
 
 ## Profiles
 
-Choose a role-specific profile for more precise discovery, or use `full` when
-all capabilities are useful. `full` exposes all 15 skills but still does not
-eagerly load all skill bodies.
+Role-specific profiles improve routing precision. `full` exposes every skill,
+but still does not eagerly load every skill body.
 
-| Profile | Skills |
-| --- | ---: |
-| `minimal` | 8 |
-| `developer` | 12 |
-| `backend` | 14 |
-| `qa` | 9 |
-| `product` | 6 |
-| `full` | 15 |
+| Profile | Skills | Best for |
+| --- | ---: | --- |
+| `minimal` | 8 | Focused everyday assistance |
+| `developer` | 12 | General application development |
+| `backend` | 14 | APIs, services, and runtime operations |
+| `qa` | 9 | Testing and quality workflows |
+| `product` | 6 | Product, requirements, and design work |
+| `full` | 15 | All capabilities |
 
 Legacy aliases remain compatible:
 
@@ -131,7 +138,7 @@ New manifests store the canonical `developer` profile.
 
 ## Skill catalog
 
-All 15 entries remain first-class Showdar skills.
+All 15 entries are first-class Showdar skills.
 
 ### Analysis and planning
 
@@ -173,47 +180,36 @@ All 15 entries remain first-class Showdar skills.
 | `showdar-recover` | Interrupted or partial engineering work must be reconstructed from repository evidence before continuing. |
 | `showdar-git` | Performing local Git inspection, staging, commits, branch integration, conflicts, cleanup, or explicitly requested remote Git actions. |
 
-## Typical software workflow
+## A typical software workflow
 
 ```text
 Requirements
-    |
-    v
-Plan
-    |
-    +--> Design
-    |
-    v
-Build
-    |
-    +--> Debug
-    +--> Test
-    |
-    v
-Quality
-    |
-    v
-Review / Security
-    |
-    v
-Ship readiness
-    |
-    +--> Ops
-    |
-    v
+     |
+     v
+Plan -----> Design
+     |
+     v
+Build ----> Debug / Test / Quality
+     |
+     v
+Review ---> Security
+     |
+     v
+Ship readiness -----> Ops
+     |
+     v
 Git completion
 ```
 
-This is a composition guide, not a mandatory sequence. Choose the skill that
-matches the current intent.
+This is a mental model, not a mandatory pipeline. Choose the skill that matches
+the current intent.
 
 ## Usage examples
 
-Codex discovers installed native skills from natural requests or explicit names:
+Codex discovers installed skills from natural requests or explicit names:
 
 ```text
 $showdar-requirements review this ticket for missing rules
-$showdar-plan plan the implementation
 $showdar-debug find the root cause of this crash
 $showdar-quality create regression scenarios
 $showdar-security threat model this auth flow
@@ -221,7 +217,7 @@ $showdar-ops inspect the deployment setup
 $showdar-git commit only the current task changes
 ```
 
-OpenCode uses native commands when initialized with `--ai opencode` or
+OpenCode exposes native commands after initialization with `--ai opencode` or
 `--ai all`:
 
 ```text
@@ -234,16 +230,13 @@ OpenCode uses native commands when initialized with `--ai opencode` or
 
 ## Safety boundaries
 
-- `showdar-ship` verifies readiness; it does not automatically deploy or create
-  CI/CD.
-- `showdar-ops` performs operational work when requested. Remote or production
-  mutation requires explicit intent, target, and authorization.
-- `showdar-git` preserves unrelated work and does not imply push, force-push, or
-  destructive cleanup.
-- `showdar-security` performs defensive, evidence-based analysis and never
-  exposes secret values.
-- `showdar-requirements` records assumptions and open decisions instead of
-  inventing stakeholder or business choices.
+| Skill | Boundary |
+| --- | --- |
+| `showdar-ship` | Verifies readiness; it does not deploy or create CI/CD by default. |
+| `showdar-ops` | Handles operational work; remote or production mutation requires explicit intent, target, and authorization. |
+| `showdar-git` | Does not imply push, force-push, or destructive cleanup. |
+| `showdar-security` | Performs defensive, evidence-based analysis and never exposes secret values. |
+| `showdar-requirements` | Records assumptions and open decisions instead of inventing business decisions. |
 
 ## CLI reference
 
@@ -256,50 +249,36 @@ showdar validate
 showdar remove [--scope <project|global>]
 ```
 
-`--ai` accepts `codex`, `opencode`, `claude`, `universal`, or `all`.
-`--scope` defaults to `project`; `--profile` accepts the six canonical profiles
-and the `mobile`/`web` aliases. Run `showdar --help` or a command's `--help`
-for the current options.
+Main flags are `--ai`, `--profile`, and `--scope`. `--ai` accepts `codex`,
+`opencode`, `claude`, `universal`, or `all`. `--scope` defaults to `project`;
+`--profile` accepts the six canonical profiles and the `mobile`/`web` aliases.
+Run `showdar --help` or a command's `--help` for current options.
 
-`showdar validate` validates the installed Showdar package, not the target
-application. `showdar doctor` checks managed files against ownership hashes;
-`showdar remove` removes only those managed paths and preserves unrelated files.
+`showdar validate` validates the installed Showdar package. `showdar doctor`
+checks managed files against ownership hashes, while `showdar remove` removes
+only those managed paths and preserves unrelated files.
 
-## Refreshing skills
+## Updating and refreshing
 
-There is no separate `showdar update` command. Reinstall the CLI, then rerun
-`showdar init` with the same scope, target, and profile:
+There is no separate `showdar update` command:
 
 ```bash
-# Future npm install
+# Upgrade the CLI from npm
 npm install -g showdar-skills@latest
 
-# Source development
-npm install -g .
-
+# Refresh Showdar-owned skills in the selected scope
 showdar init --scope project --ai codex --profile developer
 ```
 
-Initialization is idempotent and refreshes Showdar-owned files. Use
+For source development, reinstall from the checkout with `npm install -g .`.
+Re-running `showdar init` is idempotent and refreshes managed files. Use
 `showdar remove` for project scope or `showdar remove --scope global` for the
 user installation.
 
-## Maintainer release notes
-
-The first release is manual because the package does not exist on npm yet:
-
-```bash
-npm pack
-npm publish ./showdar-skills-0.2.0.tgz
-```
+## Maintainer release guide
 
-After the package exists, configure npm Trusted Publishing for the
-`caongocquy/showdar-skills` GitHub Actions workflow named `publish.yml`. The
-workflow runs only for `v*` tags, verifies the tag/package version, uses OIDC
-with provenance, and contains no npm token. It skips an already-published
-version and fails on registry errors other than a real E404. Trusted
-Publishing is not configured yet. The repository's `RELEASING.md` contains
-the maintainer runbook.
+Release and Trusted Publishing instructions live in the
+[maintainer release guide](https://github.com/caongocquy/showdar-skills/blob/main/RELEASING.md).
 
 ## Development
 
@@ -312,11 +291,11 @@ npm run eval
 npm pack --dry-run
 ```
 
-Showdar stays dependency-light and uses Node.js built-ins for its CLI,
-validator, search engine, installer, and tests. Supporting knowledge remains
-in each skill's `data/`, `references/`, `scripts/`, `stacks/`, and `examples/`
+Showdar is dependency-light and uses Node.js built-ins for its CLI, validator,
+search engine, installer, and tests. Supporting knowledge remains in each
+skill's `data/`, `references/`, `scripts/`, `stacks/`, and `examples/`
 directories so the selected workflow can load it progressively.
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/bin/showdar.js

@@ -49,6 +49,10 @@ async function main() {
   const version = await packageVersion();
 
   if (command === 'help' || command === '--help' || command === '-h') return printHelp(version);
+  if (command === '--version' || command === '-V') {
+    console.log(version);
+    return;
+  }
   if (args.includes('--help') || args.includes('-h')) return printHelp(version, command);
 
   const scope = ['init', 'status', 'doctor', 'remove'].includes(command) ? scopeAfter(args) : null;
@@ -83,6 +87,10 @@ async function main() {
       ? await initGlobal({ homeRoot: homedir(), packageRoot, profile, ai, skillIds, commandNames, packageVersion: version })
       : await initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames, packageVersion: version });
     console.log(`Showdar Skills installed.\nScope: ${scope}\nProfile: ${profile}\nAI: ${ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nOpenCode commands: ${result.commands}`);
+    if (scope === 'project') {
+      console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}\nSkipped duplicate copies: ${result.skippedDuplicates}`);
+    }
+    for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
     if (scope === 'global') console.log(`Manifest: ${globalManifestPath()}`);
     if (result.targets.includes('codex')) console.log('Codex: invoke skills directly with $showdar-<name> or let native skill discovery route by description.');
     if (result.targets.includes('opencode')) console.log('OpenCode: use native skill discovery or /showdar/<command>.');
@@ -97,7 +105,9 @@ async function main() {
       return;
     }
     console.log(`Showdar Skills\nScope: ${result.scope}\nProfile: ${result.profile}\nAI: ${result.ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nCommands: ${result.commands}\nHealth: ${result.healthy ? 'OK' : 'BROKEN'}`);
+    if (scope === 'project') console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}`);
     for (const issue of result.issues) console.log(`- ${issue}`);
+    for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
     if (command === 'doctor' && !result.healthy) process.exitCode = 1;
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/src/project.js

@@ -100,6 +100,15 @@ function ownedPathSet(manifest) {
   return new Set((manifest?.files ?? []).map((entry) => entry.path));
 }
 
+function uniqueRoots(targets, resolveRoot) {
+  const roots = new Map();
+  for (const target of targets) {
+    const root = resolveRoot(target);
+    if (!roots.has(path.resolve(root))) roots.set(path.resolve(root), { root, target });
+  }
+  return [...roots.values()];
+}
+
 function safeOwnedPath(baseRoot, relative, allowedRoots = []) {
   if (typeof relative !== 'string' || !relative) return null;
   const roots = [baseRoot, ...allowedRoots].map((root) => path.resolve(root));
@@ -124,20 +133,45 @@ async function copyOwned({ baseRoot, source, destination, priorOwned, newFiles }
   newFiles.push({ path: relative, hash: await hashTree(destination) });
 }
 
-async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [] }) {
+async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
   await mkdir(baseRoot, { recursive: true });
   const targets = resolveTargets(ai);
   const prior = await readManifest(manifestPath);
   const priorOwned = ownedPathSet(prior);
   const desiredPaths = new Set();
 
-  const skillRoots = new Map();
-  for (const target of targets) {
-    const root = skillRootForTarget(target);
-    skillRoots.set(path.resolve(root), root);
+  const skillRoots = uniqueRoots(targets, skillRootForTarget);
+  const globalManifest = scope === 'project' && globalSkillRootForTarget
+    ? await readManifest(globalManifestPath(homeRoot))
+    : null;
+  const globalOwned = ownedPathSet(globalManifest);
+  const globalSatisfaction = [];
+  const installedSkillIds = new Set();
+  const globallySatisfiedSkillIds = new Set();
+  let skippedDuplicates = 0;
+  const skillDestinations = [];
+
+  for (const skillId of skillIds) {
+    if (!(await exists(path.join(packageRoot, 'skills', skillId, 'SKILL.md')))) throw new Error(`Skill asset not found: ${skillId}`);
   }
-  for (const root of skillRoots.values()) {
-    for (const skillId of skillIds) desiredPaths.add(manifestPathFor(baseRoot, path.join(root, skillId)));
+
+  for (const { root, target } of skillRoots) {
+    for (const skillId of skillIds) {
+      const destination = path.join(root, skillId);
+      const relative = manifestPathFor(baseRoot, destination);
+      const destinationExists = await exists(destination);
+      const globalPath = globalSkillRootForTarget ? path.join(globalSkillRootForTarget(target), skillId) : null;
+      const globalRelative = globalPath ? manifestPathFor(homeRoot, globalPath) : null;
+      const globalAvailable = Boolean(globalPath && globalOwned.has(globalRelative) && await exists(globalPath));
+      if (scope === 'project' && globalAvailable && !destinationExists) {
+        skippedDuplicates += 1;
+        globallySatisfiedSkillIds.add(skillId);
+        globalSatisfaction.push({ skill: skillId, target, path: globalRelative });
+      } else {
+        desiredPaths.add(relative);
+        skillDestinations.push({ destination, skillId });
+      }
+    }
   }
   if (targets.includes('opencode')) {
     for (const name of commandNames) desiredPaths.add(manifestPathFor(baseRoot, path.join(commandRoot(), `${name}.md`)));
@@ -149,12 +183,10 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
   }
 
   const files = [];
-  for (const root of skillRoots.values()) {
-    for (const skillId of skillIds) {
-      const source = path.join(packageRoot, 'skills', skillId);
-      if (!(await exists(path.join(source, 'SKILL.md')))) throw new Error(`Skill asset not found: ${skillId}`);
-      await copyOwned({ baseRoot, source, destination: path.join(root, skillId), priorOwned, newFiles: files });
-    }
+  for (const { destination, skillId } of skillDestinations) {
+    const source = path.join(packageRoot, 'skills', skillId);
+    await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: files });
+    installedSkillIds.add(skillId);
   }
 
   if (targets.includes('opencode')) {
@@ -174,16 +206,27 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
     ai,
     targets,
     skills: [...skillIds],
+    satisfiedByGlobal: globalSatisfaction,
     commands: targets.includes('opencode') ? [...commandNames] : [],
     files,
   };
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeJsonAtomic(manifestPath, manifest);
   if (agentsRoot) await writeAgentsBlock(agentsRoot, skillIds);
-  return inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope });
+  const result = await inspectInstallation({
+    baseRoot, manifestPath, agentsRoot, scope, homeRoot,
+    globalSkillRootForTarget,
+  });
+  return {
+    ...result,
+    requestedSkills: skillIds.length,
+    installedSkills: installedSkillIds.size,
+    satisfiedByGlobal: globallySatisfiedSkillIds.size,
+    skippedDuplicates,
+  };
 }
 
-export async function initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
+export async function initProject({ projectRoot, homeRoot = homedir(), packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
   return initInstallation({
     baseRoot: projectRoot,
     manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
@@ -195,7 +238,9 @@ export async function initProject({ projectRoot, packageRoot, profile, ai, skill
     commandNames,
     packageVersion,
     scope: 'project',
+    homeRoot,
     skillRootForTarget: (target) => skillRootFor(target, projectRoot),
+    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
     commandRoot: () => opencodeCommandRoot(projectRoot),
   });
 }
@@ -219,17 +264,79 @@ export async function initGlobal({ homeRoot = homedir(), packageRoot, profile, a
   });
 }
 
-async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [] }) {
+async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
   let manifest;
   try { manifest = await readManifest(manifestPath); }
-  catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: [error.message] }; }
-  if (!manifest) return { installed: false, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, commands: 0, issues: ['Showdar is not installed.'] };
+  catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, requestedSkills: 0, installedSkills: 0, satisfiedByGlobal: 0, commands: 0, issues: [error.message], warnings: [] }; }
+  if (!manifest) return { installed: false, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, requestedSkills: 0, installedSkills: 0, satisfiedByGlobal: 0, commands: 0, issues: ['Showdar is not installed.'], warnings: [] };
 
   const issues = [];
+  const warnings = [];
+  const projectOwned = ownedPathSet(manifest);
+  const targets = manifest.targets?.length ? manifest.targets : manifest.ai ? resolveTargets(manifest.ai) : [];
+  const skillIds = manifest.skills ?? [];
+  const globalManifest = scope === 'project' && globalSkillRootForTarget
+    ? await readManifest(globalManifestPath(homeRoot))
+    : null;
+  const globalOwned = ownedPathSet(globalManifest);
+  const globalSatisfiedPaths = new Set();
+  const installedSkillIds = new Set();
+  const globallySatisfiedSkillIds = new Set();
+  const recordedGlobalSkills = new Set((manifest.satisfiedByGlobal ?? []).map((entry) => entry?.skill).filter(Boolean));
+
+  if (scope === 'project' && globalSkillRootForTarget) {
+    const projectRoots = uniqueRoots(targets, (target) => skillRootFor(target, baseRoot));
+    const globalRoots = uniqueRoots(targets, globalSkillRootForTarget);
+    const globalSkills = new Set();
+    for (const { root } of globalRoots) {
+      const prefix = `${manifestPathFor(homeRoot, root)}/`;
+      for (const entry of globalManifest?.files ?? []) {
+        if (!entry.path.startsWith(prefix)) continue;
+        const skillId = entry.path.slice(prefix.length).split('/')[0];
+        if (!skillId.startsWith('showdar-')) continue;
+        if (globalOwned.has(entry.path) && await exists(path.join(homeRoot, entry.path))) globalSkills.add(skillId);
+      }
+    }
+    const extra = [...globalSkills].filter((skillId) => !skillIds.includes(skillId)).sort();
+    if (extra.length) warnings.push(`Global Showdar installation exposes skills outside project profile "${manifest.profile ?? 'unknown'}": ${extra.join(', ')}. Project deduplication prevents duplicate copies but cannot hide globally installed skills. For strict project profile isolation: showdar remove --scope global`);
+
+    for (const { root, target } of projectRoots) {
+      for (const skillId of skillIds) {
+        const projectPath = path.join(root, skillId);
+        const projectRelative = manifestPathFor(baseRoot, projectPath);
+        const projectExists = await exists(projectPath);
+        const projectIsOwned = projectOwned.has(projectRelative);
+        const globalPath = path.join(globalSkillRootForTarget(target), skillId);
+        const globalRelative = manifestPathFor(homeRoot, globalPath);
+        const globalExists = await exists(globalPath);
+        const globalIsOwned = globalOwned.has(globalRelative);
+
+        if (projectExists && projectIsOwned) installedSkillIds.add(skillId);
+        if (projectExists && projectIsOwned && globalExists && globalIsOwned) {
+          warnings.push(`Duplicate Showdar skill discovery:\n  ${skillId}\n    project: ${projectPath}\n    global: ${globalPath}\n  To prefer project isolation: showdar remove --scope global`);
+        } else if (!projectExists && globalExists && globalIsOwned) {
+          globalSatisfiedPaths.add(projectRelative);
+          globallySatisfiedSkillIds.add(skillId);
+        } else if (!projectExists && !globalExists) {
+          issues.push(recordedGlobalSkills.has(skillId)
+            ? `Globally satisfied skill is missing: ${skillId} (${globalPath})`
+            : `Missing requested skill: ${projectPath}`);
+        } else if (projectExists && !projectIsOwned) {
+          issues.push(`Project skill path is not Showdar-owned: ${projectPath}`);
+        } else if (globalExists && !globalIsOwned) {
+          warnings.push(`Global skill path is not Showdar-owned: ${globalPath}`);
+        }
+      }
+    }
+  }
+
   for (const entry of manifest.files ?? []) {
     const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
     if (!target) { issues.push(`Invalid managed path: ${entry.path}`); continue; }
-    if (!(await exists(target))) { issues.push(`Missing managed path: ${entry.path}`); continue; }
+    if (!(await exists(target))) {
+      if (!globalSatisfiedPaths.has(entry.path)) issues.push(`Missing managed path: ${entry.path}`);
+      continue;
+    }
     const actual = await hashTree(target);
     if (actual !== entry.hash) issues.push(`Managed path drift detected: ${entry.path}`);
   }
@@ -250,9 +357,13 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
     profile: manifest.profile ?? null,
     ai: manifest.ai ?? null,
     targets: manifest.targets ?? [],
-    skills: (manifest.skills ?? []).length,
+    skills: skillIds.length,
+    requestedSkills: skillIds.length,
+    installedSkills: scope === 'project' && globalSkillRootForTarget ? installedSkillIds.size : skillIds.length,
+    satisfiedByGlobal: scope === 'project' && globalSkillRootForTarget ? globallySatisfiedSkillIds.size : 0,
     commands: (manifest.commands ?? []).length,
     issues,
+    warnings,
   };
 }
 
@@ -268,8 +379,15 @@ async function removeInstallation({ baseRoot, manifestPath, agentsRoot, managedR
   if (agentsRoot) await removeAgentsBlock(agentsRoot);
 }
 
-export async function inspectProject(projectRoot) {
-  return inspectInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), agentsRoot: projectRoot, scope: 'project' });
+export async function inspectProject(projectRoot, { homeRoot = homedir() } = {}) {
+  return inspectInstallation({
+    baseRoot: projectRoot,
+    manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
+    agentsRoot: projectRoot,
+    scope: 'project',
+    homeRoot,
+    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
+  });
 }
 
 export async function inspectGlobal({ homeRoot = homedir() } = {}) {