bi-superpowers 1.0.0 → 1.1.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "AI-powered skills for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.",
-    "version": "1.0.0",
+    "version": "1.1.1",
     "repository": "https://github.com/luquimbo/bi-superpowers"
   },
   "plugins": [

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bi-superpowers",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "author": {
     "name": "Lucas Sanchez"
   },

package/.claude-plugin/skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "bi-superpowers",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "skillCount": 9,
   "skills": [
     {

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "spec": "open-plugin-spec@1",
   "name": "bi-superpowers",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
   "author": {
     "name": "Lucas Sanchez"

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 BI Agent Superpowers contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 BI Agent Superpowers contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -38,7 +38,7 @@ Works with **Codex**, **Claude Code**, **GitHub Copilot**, **Gemini CLI**, and *
 
 Fully open source under MIT. No account, no login, no license keys — every command works offline.
 
-> Status: `v1.0.x` is the current stable release line. Every public slash command lives under the `/bi-*` namespace.
+> Status: `v1.1.x` is the current stable release line. Every public slash command lives under the `/bi-*` namespace.
 >
 > Validation baseline: developed and stress-tested first in **Codex**. Other agents are shipped as compatibility targets unless a release note says otherwise.
 
@@ -432,6 +432,7 @@ super uninstall --dry-run    # Preview what an uninstall would remove
 super kickoff                # Advanced: generate optional local Claude Code plugin files
 super recharge               # Regenerate optional local Claude Code plugin artifacts
 super create-from-template   # Scaffold a new PBIP project from templates/<name>/ into pbip-files/
+super template-path --template base-template  # Print the packaged template path
 super powers                 # List available skills
 super scan                   # Compare source skills with generated artifacts
 super checkup                # Validate skill content
@@ -466,12 +467,15 @@ super create-from-template --template base-template --name <projectName>
 super create-from-template --template base-template --name <projectName> --target /path/to/project
 super create-from-template --template base-template --name <projectName> --dry-run
 super create-from-template --template base-template --name <projectName> --force
+super create-from-template --template base-template --name <projectName> --force --replace-project <oldName>
 ```
 
-Used by the `bi-kickoff` skill PHASE 0 Option A (start from template) so agents do not have to copy files by hand. The command copies `templates/<name>/` into `<target>/pbip-files/<projectName>.*`, renames the PBIP descriptor and the `.SemanticModel/` / `.Report/` folders, rewrites internal cross-references (`.pbip → Report.path`, `definition.pbir → datasetReference.byPath.path`), and regenerates the Fabric `logicalId` in both `.platform` files. It refuses to overwrite an existing PBIP unless `--force` is passed, skips the template's own `AGENTS.md`, skips local Desktop/editor state such as `.pbi`, `localSettings.json`, `cache.abf`, and `DAXQueries`, and when forced cleans only the destination `<projectName>.pbip`, `<projectName>.SemanticModel`, and `<projectName>.Report` paths before copying again.
+Used by the `bi-kickoff` skill PHASE 0 Option A (start from template) so agents do not have to copy files by hand. The command copies `templates/<name>/` into `<target>/pbip-files/<projectName>.*`, renames the PBIP descriptor and the `.SemanticModel/` / `.Report/` folders, rewrites internal cross-references (`.pbip → Report.path`, `definition.pbir → datasetReference.byPath.path`), and regenerates the Fabric `logicalId` in both `.platform` files. It refuses to overwrite an existing PBIP unless `--force` is passed, skips the template's own `AGENTS.md`, skips local Desktop/editor state such as `.pbi`, `localSettings.json`, `cache.abf`, and `DAXQueries`, and when forced cleans only the destination project paths before copying again. If there is exactly one PBIP in the destination, `--force` replaces that project even when the new `--name` differs; if there are multiple PBIPs, pass `--replace-project <oldName>` so the command cannot guess the wrong project.
 
 The packaged template is `base-template`, the canonical dynamic-first reference for new Power BI projects. Dynamic metric format strings stay safe and unscaled for numeric visuals; compact abbreviations live in dedicated text helper measures for KPI labels.
 
+`super template-path --template base-template` prints the installed template folder path. Skills use it instead of hard-coded developer machine paths.
+
 `super mcp-setup` is intentionally not part of normal setup. It only refreshes MCP config inside an existing local Claude Code plugin created by `super kickoff`; it refuses to write repo-local config in arbitrary projects. For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and normal Claude Code user-level installs, use `super install --all --yes`.
 
 ---
@@ -623,7 +627,7 @@ node_modules/
 **/.pbi/localSettings.json
 ```
 
-`templates/` ships the canonical `templates/base-template/` PBIP package with `AGENTS.md`, semantic model, and report definition. It is the "template-as-reference" used by all specialist skills and the source for the `bi-kickoff` "create from template" branch invoked via `super create-from-template`, which copies `templates/base-template/` into `<user-repo>/pbip-files/<projectName>.*` with renaming, cross-reference rewriting, and regenerated logicalIds. The base template includes Power Query pre-converted currency base columns, packaged sample queries grouped under `Sample Dataset\Dimensiones` and `Sample Dataset\Hechos`, `_GC Métrica` / `_GC Tipo cálculo` calculation groups, guarded metric dispatch, metric-aware dynamic dimensions through `_PC Dimensión`, a `Equipos métricas[Equipo]` slicer for filtering the metric selector by team, multi-team metric memberships through `_Aux Métrica-Equipo`, nine Equipos (eight operating teams plus `Dirección`) for the Andina Nexus product-and-services demo company, team-specific model-view diagrams, safe unscaled numeric model formats, compact KPI label helpers, cleaned key metadata, and a `Data = "Demo"` contract on appendable business tables. Demo IDs are entity-coded text values such as `ClienteA25D`, so relationships stay on the original ID columns while real rows can append with `Data = "Real"` and their own source IDs. `/bi-powerquery` creates the user-side real staging queries; the template itself does not ship unloaded `*_Real` queries. `/bi-scorecard` uses `base-template` as a metrics-catalog reference for Service scorecards; it does not add a universal targets model to the template.
+`templates/` ships the canonical `templates/base-template/` PBIP package with `AGENTS.md`, semantic model, and report definition. It is the "template-as-reference" used by all specialist skills and the source for the `bi-kickoff` "create from template" branch invoked via `super create-from-template`, which copies `templates/base-template/` into `<user-repo>/pbip-files/<projectName>.*` with renaming, cross-reference rewriting, and regenerated logicalIds. The base template includes Power Query pre-converted currency base columns, packaged sample queries grouped under `Sample Dataset\Dimensiones` and `Sample Dataset\Hechos`, `_GC Métrica` / `_GC Tipo cálculo` calculation groups, guarded metric dispatch, metric-aware dynamic dimensions through `_PC Dimensión`, a `Equipos métricas[Equipo]` slicer for filtering the metric selector by team, multi-team metric memberships through `_Aux Métrica-Equipo`, nine Equipos (eight operating teams plus `Dirección`) for the Andina Nexus product-and-services demo company, team-specific model-view diagrams, safe unscaled numeric model formats, compact KPI label helpers, cleaned key metadata, and a `Data = "Demo"` contract on appendable business tables. Demo facts now share full-calendar weekly drivers from the `FechaInicio` parameter through the current model date; sales, project execution, finance, marketing, operations, payroll, returns, tasks, and customer acquisition are derived from shared business drivers instead of independent random grids. Demo IDs are entity-coded text values such as `ClienteA25D` and shared helper values such as `EQUA00A`, so relationships stay on the original ID columns while real rows can append with `Data = "Real"` and their own source IDs; visible customer and country labels are capped at 13 values each so dynamic-dimension slicers stay readable without shrinking the customer cohort. `/bi-powerquery` creates the user-side real staging queries; the template itself does not ship unloaded `*_Real` queries. `/bi-scorecard` uses `base-template` as a metrics-catalog reference for Service scorecards; it does not add a universal targets model to the template.
 `validation/` is repo-only. It stores sanitized validation descriptors and playbooks for project QA; private project paths live in `validation.local.json`, which must never be committed.
 
 ---
@@ -716,8 +720,9 @@ For a live Power BI Desktop smoke test of the canonical template, use
 `validation/cases/base-template-smoke-test.md` after the structural validation
 passes. `super smoke-test` will probe the open Desktop sessions automatically
 and keep the one that matches the expected evidence, including seven metrics per
-team plus weekly fact, metric, and compatible dimension coverage for the last
-720 days.
+team, full `FechaInicio` → current-day calendar coverage, zero business
+invariant failures, and complete metric plus compatible metric-dimension
+coverage.
 
 To discover the repo playbooks or print one in full:
 
@@ -743,13 +748,18 @@ npm run build:plugin
 npm test
 npm run lint
 npm run format:check
+npm audit --omit=dev --audit-level=moderate
+node bin/cli.js validate-projects --project base-template
+node bin/cli.js smoke-test --json
+node bin/cli.js scan --verbose
+npm pack --dry-run --ignore-scripts
 git add package.json package-lock.json commands/ skills/ .claude-plugin/ .plugin/ .mcp.json
 git commit -m "chore: release vX.Y.Z"
 git tag -a vX.Y.Z -m "vX.Y.Z"
 git push origin main --follow-tags
 ```
 
-The publish workflow runs on `v*` tag pushes. Manual dispatch is constrained to an already-tagged release commit on `main`.
+The publish workflow runs on `v*` tag pushes. Manual dispatch is constrained to an already-tagged release commit on `main`. CI refuses mismatched tag/package versions and publishes from GitHub Actions without npm provenance because this repository is private. Do not create retrospective tags for already-published versions.
 
 ---
 

package/bin/cli.js

@@ -51,6 +51,7 @@ let validateCasesCommand;
 let validateProjectsCommand;
 let smokeTestCommand;
 let createFromTemplateCommand;
+let templatePathCommand;
 let tui;
 try {
   lintCommand = require('./commands/lint'); // checkup: skill file validation
@@ -65,6 +66,7 @@ try {
   validateProjectsCommand = require('./commands/validate-projects'); // repo/project validation harness
   smokeTestCommand = require('./commands/smoke-test'); // live base-template smoke test
   createFromTemplateCommand = require('./commands/create-from-template'); // PBIP scaffold from templates/
+  templatePathCommand = require('./commands/template-path'); // portable absolute template path
   tui = require('./utils/tui'); // colors, tables, boxes for CLI output
 } catch (_) {
   // Expected during `npm install` — modules become available after deps are linked.
@@ -178,6 +180,7 @@ Primary commands:
   kickoff [path]         Optional: generate a repo-local Claude Code plugin
   recharge [path]        Optional: regenerate an existing repo-local Claude Code plugin
   create-from-template   Scaffold a new PBIP project from templates/<name>/ into pbip-files/
+  template-path          Print the portable absolute path of a packaged template
   build-desktop          Build the .mcpb extension for Claude Desktop
   mcp-setup              Refresh MCP config for an existing Claude Code local plugin
   powers                 List available skills and MCPs
@@ -216,6 +219,7 @@ Examples:
   super create-from-template --list                                          # List bundled templates
   super create-from-template --template base-template --name bi-personal     # Scaffold from base template
   super create-from-template --template base-template --name bi-personal --dry-run # Preview only
+  super template-path --template base-template                              # Print packaged template path
 
 Open source — MIT licensed.
 Documentation: https://bi-superpowers.dev
@@ -669,7 +673,7 @@ function getUpgradeCommand(userAgent) {
 function resetUpdateCheckStateAfterUpgrade(homeDir) {
   try {
     const { resetState } = require('./commands/update-check');
-    resetState(path.join(homeDir, '.bi-superpowers'));
+    resetState(path.join(homeDir, '.bi-superpowers'), PACKAGE_NAME);
     return true;
   } catch (_) {
     return false;
@@ -762,6 +766,7 @@ function getCommandConfig() {
   return {
     skillsDir: SKILLS_DIR,
     packageDir: PACKAGE_DIR,
+    packageName: PACKAGE_NAME,
     version: VERSION,
   };
 }
@@ -795,6 +800,7 @@ const runCreateFromTemplate = createCommandWrapper(
   createFromTemplateCommand,
   'Create from template'
 );
+const runTemplatePath = createCommandWrapper(templatePathCommand, 'Template path');
 
 // Register wrapper-based commands into the command map (phase 2).
 commands.install = runInstall;
@@ -810,6 +816,7 @@ commands['smoke-test'] = runSmokeTest;
 commands['validate-cases'] = runValidateCases;
 commands['validate-projects'] = runValidateProjects;
 commands['create-from-template'] = runCreateFromTemplate;
+commands['template-path'] = runTemplatePath;
 commands.lint = runLint;
 commands.diff = runDiff;
 commands.watch = runWatch;

package/bin/commands/create-from-template.js

@@ -19,6 +19,7 @@
  *   super create-from-template --list
  *   super create-from-template --template base-template --name <projectName> --dry-run
  *   super create-from-template --template base-template --name <projectName> --force
+ *   super create-from-template --template base-template --name <projectName> --force --replace-project <existingName>
  */
 
 const path = require('path');
@@ -30,6 +31,7 @@ function parseArgs(args) {
     targetDir: process.cwd(),
     projectName: null,
     force: false,
+    replaceProject: null,
     dryRun: false,
     list: false,
     json: false,
@@ -45,6 +47,8 @@ function parseArgs(args) {
       options.projectName = readValue(args, ++index, arg);
     } else if (arg === '--force' || arg === '-f') {
       options.force = true;
+    } else if (arg === '--replace-project') {
+      options.replaceProject = readValue(args, ++index, arg);
     } else if (arg === '--dry-run') {
       options.dryRun = true;
     } else if (arg === '--list' || arg === '-l') {
@@ -146,6 +150,7 @@ async function createFromTemplateCommand(args, config = {}) {
       targetDir: options.targetDir,
       projectName: options.projectName,
       force: options.force,
+      replaceProject: options.replaceProject,
       dryRun: options.dryRun,
     });
 

package/bin/commands/install.js

@@ -37,6 +37,13 @@ const readline = require('readline');
 const { AGENTS, UNIVERSAL_DIR } = require('../lib/agents');
 const { writeMcpConfigForAgent } = require('../lib/mcp-config');
 const { getSkillPurpose } = require('../lib/generators/shared');
+const {
+  readInstallManifest,
+  writeInstallManifest,
+  isManifestOwnedSymlink,
+  isVerifiedLegacyManagedSymlink,
+  createInstallManifest,
+} = require('../lib/install-manifest');
 
 /**
  * Detect which agents are installed by checking their config directories.
@@ -250,7 +257,13 @@ async function resolveSelectedAgents(opts, baseDir, chalk) {
  * each selected agent's skill directory to point at the universal copy.
  * @returns {{agentResults: Array, copyFallbacks: number}}
  */
-function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
+function performInstall(
+  skillsSourceDir,
+  skillDirs,
+  selectedAgents,
+  baseDir,
+  previousManifest = null
+) {
   // Always install to the universal path first. This is the source of
   // truth that all other agent dirs symlink to.
   const universalTarget = path.join(baseDir, UNIVERSAL_DIR);
@@ -265,17 +278,34 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
 
   for (const agentId of selectedAgents) {
     const agent = AGENTS[agentId];
-    if (agent.dir === UNIVERSAL_DIR) continue; // Already handled above.
+    if (agent.dir === UNIVERSAL_DIR) {
+      agentResults.push({
+        agentId,
+        agent: agent.name,
+        method: 'universal',
+        dir: agent.dir,
+        path: universalTarget,
+        target: universalTarget,
+      });
+      continue;
+    }
 
     const agentTarget = path.join(baseDir, agent.dir);
+    const existingTarget = fs.lstatSync(agentTarget, { throwIfNoEntry: false });
 
     // If a real directory already exists (not a symlink), copy into it
     // directly so we don't destroy user data.
-    if (fs.existsSync(agentTarget) && !fs.lstatSync(agentTarget).isSymbolicLink()) {
+    if (existingTarget && !existingTarget.isSymbolicLink()) {
       for (const skill of skillDirs) {
         copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
       }
-      agentResults.push({ agent: agent.name, method: 'copied', dir: agent.dir });
+      agentResults.push({
+        agentId,
+        agent: agent.name,
+        method: 'copied',
+        dir: agent.dir,
+        path: agentTarget,
+      });
       continue;
     }
 
@@ -284,20 +314,39 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
       fs.mkdirSync(parentDir, { recursive: true });
     }
 
-    // Remove any pre-existing symlink so we can recreate it cleanly.
-    if (fs.existsSync(agentTarget) || fs.lstatSync(agentTarget, { throwIfNoEntry: false })) {
-      try {
-        fs.unlinkSync(agentTarget);
-      } catch (_) {
-        /* target didn't exist after all — that's fine */
+    // A symlink is removed only when the manifest proves ownership, or when
+    // it is a verified pre-manifest install that points at our universal
+    // skills and contains the complete shipped skill set.
+    if (existingTarget && existingTarget.isSymbolicLink()) {
+      const owned =
+        isManifestOwnedSymlink(previousManifest, agentId, agentTarget, universalTarget) ||
+        isVerifiedLegacyManagedSymlink(agentTarget, universalTarget, skillDirs);
+      if (!owned) {
+        agentResults.push({
+          agentId,
+          agent: agent.name,
+          method: 'preserved-foreign',
+          dir: agent.dir,
+          path: agentTarget,
+          error: 'Existing symlink is not owned by bi-superpowers.',
+        });
+        continue;
       }
+      fs.unlinkSync(agentTarget);
     }
 
     try {
       // Relative symlink from the agent's dir to the universal dir.
       const relPath = path.relative(parentDir, universalTarget);
       fs.symlinkSync(relPath, agentTarget);
-      agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
+      agentResults.push({
+        agentId,
+        agent: agent.name,
+        method: 'symlinked',
+        dir: agent.dir,
+        path: agentTarget,
+        target: universalTarget,
+      });
     } catch (symlinkErr) {
       // Windows without admin can't create symlinks. Fall back to copy
       // and remember so we can warn the user at the end.
@@ -309,9 +358,11 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
         copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
       }
       agentResults.push({
+        agentId,
         agent: agent.name,
         method: 'copied',
         dir: agent.dir,
+        path: agentTarget,
         fallbackReason: symlinkErr.code || symlinkErr.message,
       });
     }
@@ -346,11 +397,11 @@ function configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk) {
       if (configPath) {
         const relPath = configPath.replace(baseDir, '~');
         console.log(chalk.green(`  ✓ ${relPath} — ${agent.name}`));
-        results.push({ agent: agent.name, configPath, success: true });
+        results.push({ agentId, agent: agent.name, configPath, success: true });
       }
     } catch (err) {
       console.log(chalk.red(`  ✗ ${agent.name}: ${err.message}`));
-      results.push({ agent: agent.name, success: false, error: err.message });
+      results.push({ agentId, agent: agent.name, success: false, error: err.message });
     }
   }
   return results;
@@ -373,7 +424,9 @@ async function installCommand(args, config) {
 
   // Locate the skills inside the installed package.
   const packageDir = config.packageDir || path.dirname(path.dirname(__dirname));
+  const packageName = config.packageName || 'bi-superpowers';
   const skillsSourceDir = path.join(packageDir, 'skills');
+  const previousManifest = readInstallManifest(baseDir, packageName);
 
   if (!fs.existsSync(skillsSourceDir)) {
     console.error(
@@ -432,7 +485,13 @@ async function installCommand(args, config) {
   let agentResults;
   let copyFallbacks;
   try {
-    const result = performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir);
+    const result = performInstall(
+      skillsSourceDir,
+      skillDirs,
+      selectedAgents,
+      baseDir,
+      previousManifest
+    );
     agentResults = result.agentResults;
     copyFallbacks = result.copyFallbacks;
   } catch (err) {
@@ -449,6 +508,11 @@ async function installCommand(args, config) {
 
   // Report per agent.
   for (const result of agentResults) {
+    if (result.method === 'universal') continue;
+    if (result.method === 'preserved-foreign') {
+      console.log(chalk.yellow(`  ⚠ ${result.dir}/ preserved — ${result.agent}: ${result.error}`));
+      continue;
+    }
     const icon = result.method === 'symlinked' ? '→' : '✓';
     console.log(chalk.green(`  ${icon} ${result.dir}/ (${result.method}) — ${result.agent}`));
   }
@@ -468,7 +532,7 @@ async function installCommand(args, config) {
   const mcpResults = configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk);
 
   // Build the final summary box.
-  const totalAgents = agentResults.length + (universalAgents.length > 0 ? 1 : 0);
+  const totalAgents = selectedAgents.length;
   const mcpSuccess = mcpResults.filter((r) => r.success).length;
   const mcpFailures = mcpResults.filter((r) => !r.success);
   const hasFailures = mcpFailures.length > 0;
@@ -511,10 +575,14 @@ async function installCommand(args, config) {
   );
 
   // Opt-in: register the Claude Code SessionStart auto-update hook.
+  let autoUpdateEnabled = Boolean(
+    previousManifest && previousManifest.autoUpdate && previousManifest.autoUpdate.enabled
+  );
   if (opts.autoUpdate) {
     try {
       const { enableAutoupdate } = require('./autoupdate');
       enableAutoupdate(packageDir);
+      autoUpdateEnabled = true;
       console.log(
         chalk.green('\n  ✓ Auto-update enabled (Claude Code SessionStart hook).') +
           chalk.gray('\n    New Claude Code sessions self-update via npm (throttled, background).')
@@ -524,6 +592,22 @@ async function installCommand(args, config) {
     }
   }
 
+  try {
+    const manifest = createInstallManifest({
+      packageName,
+      packageVersion: config.version,
+      skillNames: skillDirs,
+      universalTarget: path.join(baseDir, UNIVERSAL_DIR),
+      agentResults,
+      mcpResults,
+      autoUpdateEnabled,
+    });
+    writeInstallManifest(baseDir, manifest);
+  } catch (err) {
+    console.log(chalk.yellow(`\n  ⚠ Could not write install ownership manifest: ${err.message}`));
+    process.exitCode = 2;
+  }
+
   if (hasFailures) {
     // Non-zero exit so CI/scripts know something went wrong. Exit code 2
     // distinguishes partial failure (skills ok, some MCPs failed) from
@@ -537,6 +621,7 @@ module.exports = installCommand;
 module.exports.parseArgs = parseArgs;
 module.exports.detectAgents = detectAgents;
 module.exports.copySkillDir = copySkillDir;
+module.exports.performInstall = performInstall;
 module.exports.formatFsError = formatFsError;
 module.exports.AGENTS = AGENTS;
 module.exports.UNIVERSAL_DIR = UNIVERSAL_DIR;

package/bin/commands/session-update.js

@@ -27,6 +27,8 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { spawn, execSync } = require('child_process');
+const { compareVersions, readInstalledVersion } = require('./update-check');
+const { packageKey } = require('../lib/install-manifest');
 
 const PACKAGE_NAME = (() => {
   try {
@@ -38,13 +40,12 @@ const PACKAGE_NAME = (() => {
 
 const DEFAULT_THROTTLE_SECONDS = 3600; // once per hour
 const STATE_DIR = '.bi-superpowers';
-const STATE_FILE = 'autoupdate-state.json';
 
 /**
  * Absolute path to the auto-update state file under the given home dir.
  */
-function stateFilePath(homeDir) {
-  return path.join(homeDir, STATE_DIR, STATE_FILE);
+function stateFilePath(homeDir, packageName = PACKAGE_NAME) {
+  return path.join(homeDir, STATE_DIR, `autoupdate-state-${packageKey(packageName)}.json`);
 }
 
 /**
@@ -141,19 +142,48 @@ function applyUpdate(deps = {}) {
   const nowMs = typeof deps.nowMs === 'number' ? deps.nowMs : Date.now();
   const cliPath = deps.cliPath || path.join(__dirname, '..', 'cli.js');
   const execFn = deps.execFn || ((cmd) => execSync(cmd, { stdio: 'ignore', windowsHide: true }));
+  const installedVersion = deps.installedVersion || readInstalledVersion();
+  const getLatestVersion =
+    deps.getLatestVersion ||
+    (() => {
+      const raw = execSync(`npm view ${PACKAGE_NAME} version --json`, {
+        encoding: 'utf8',
+        windowsHide: true,
+      });
+      const parsed = JSON.parse(String(raw).trim());
+      return Array.isArray(parsed) ? parsed.at(-1) : parsed;
+    });
 
   const state = readState(file);
   try {
+    const latestVersion = deps.latestVersion || getLatestVersion();
+    state.installedVersion = installedVersion;
+    state.latestVersion = latestVersion;
+    state.lastVersionCheck = nowMs;
+
+    if (
+      installedVersion &&
+      latestVersion &&
+      compareVersions(installedVersion, latestVersion) >= 0
+    ) {
+      state.lastResult = 'up-to-date';
+      writeState(file, state);
+      return { updated: false, installedVersion, latestVersion };
+    }
+
     execFn(`npm install -g ${PACKAGE_NAME}@latest`);
     // Refresh the per-agent skill + MCP copies from the freshly installed package.
     execFn(`node "${cliPath}" install --all --yes`);
     state.lastUpgrade = nowMs;
     state.lastResult = 'ok';
+    writeState(file, state);
+    return { updated: true, installedVersion, latestVersion };
   } catch (err) {
     state.lastResult = 'error';
     state.lastError = err && err.message ? String(err.message).slice(0, 300) : 'unknown';
   }
   writeState(file, state);
+  return { updated: false, error: state.lastError };
 }
 
 /**

package/bin/commands/template-path.js

@@ -0,0 +1,62 @@
+/**
+ * Template Path Command
+ * =====================
+ *
+ * Prints the absolute path of a packaged template so skills and scripts can
+ * stay portable across npm, Git checkouts, and different user profiles.
+ */
+
+const path = require('path');
+const { resolveTemplate } = require('../lib/template-scaffold');
+
+function parseArgs(args) {
+  const options = { templateName: 'base-template', json: false };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--template' || arg === '-t') {
+      const value = args[++index];
+      if (!value || value.startsWith('-')) {
+        throw new Error(`${arg} requires a value`);
+      }
+      options.templateName = value;
+    } else if (arg === '--json') {
+      options.json = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function templatePathCommand(args, config = {}) {
+  let options;
+  try {
+    options = parseArgs(args || []);
+    const packageDir = config.packageDir || path.resolve(__dirname, '..', '..');
+    const template = resolveTemplate(packageDir, options.templateName);
+    if (options.json) {
+      console.log(
+        JSON.stringify(
+          {
+            template: template.name,
+            path: template.path,
+            pbipFile: template.pbipFile,
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+    console.log(template.path);
+  } catch (error) {
+    if (options && options.json) {
+      console.log(JSON.stringify({ error: error.message }, null, 2));
+    } else {
+      console.error(`Error: ${error.message}`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+module.exports = Object.assign(templatePathCommand, { parseArgs });