sinapse-ai 1.25.2 → 1.26.0

package/.agents/skills/react-bits-frontend/SKILL.md

@@ -10,8 +10,16 @@ not as a black-box library.
 
 ## Locate the corpus
 
-Resolve the SINAPSE package/repository root, then read
-`docs/framework/react-bits/index.md`. Read only the category needed:
+Resolve the corpus in this exact order, then read `index.md` from the first
+location that contains the complete corpus:
+
+1. `<project>/docs/framework/react-bits/`
+2. `<installed-package>/docs/framework/react-bits/`
+3. `~/.sinapse/docs/framework/react-bits/`
+
+The project location wins so a project can pin or extend its installed research.
+The package location supports package-managed runs, and the global SINAPSE home
+supports `--global-only` installs. Read only the category needed:
 
 - `animations.md` for wrappers, cursors, trails, transitions and interactive effects.
 - `text-animations.md` for headline, counter, scramble, marquee and reveal work.
@@ -21,8 +29,9 @@ Resolve the SINAPSE package/repository root, then read
 - `audit-findings.md` when dependency, prop, variant or upstream accuracy matters.
 - `inventory.json` for exact machine-readable props, dependencies and variant state.
 
-If the corpus cannot be found, read `references/corpus-map.md`, then verify current
-facts against the official registry and source before implementation.
+If none of those locations has all nine files, state which locations were checked,
+ask the user to run the relevant SINAPSE install/update, then verify current facts
+against the official registry and source before implementation.
 
 ## Workflow
 

package/.claude/skill-manifest.json

@@ -1,6 +1,7 @@
 {
   "version": 1,
   "skillIds": [
+    "react-bits-frontend",
     "sinapse",
     "sinapse-agent",
     "sinapse-analyst",

package/.claude/skills/react-bits-frontend/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: react-bits-frontend
+description: Select, install, adapt, combine, optimize, and audit official React Bits components for React, Next.js, Vite, Astro islands, and SINAPSE frontend projects. Use for animated text, cursors, reveals, cards, navigation, galleries, WebGL backgrounds, shaders, particles, motion systems, React Bits CLI/MCP commands, component props/dependencies, or when improving an existing page with React Bits while preserving accessibility, mobile performance, lifecycle cleanup, design-system fit, and license compliance.
+---
+
+# React Bits Frontend
+
+Use the source-grounded SINAPSE corpus to implement React Bits as application code,
+not as a black-box library.
+
+## Locate the corpus
+
+Resolve the corpus in this exact order, then read `index.md` from the first
+location that contains the complete corpus:
+
+1. `<project>/docs/framework/react-bits/`
+2. `<installed-package>/docs/framework/react-bits/`
+3. `~/.sinapse/docs/framework/react-bits/`
+
+The project location wins so a project can pin or extend its installed research.
+The package location supports package-managed runs, and the global SINAPSE home
+supports `--global-only` installs. Read only the category needed:
+
+- `animations.md` for wrappers, cursors, trails, transitions and interactive effects.
+- `text-animations.md` for headline, counter, scramble, marquee and reveal work.
+- `components.md` for cards, navigation, galleries, inputs and compound UI.
+- `backgrounds.md` for Canvas/WebGL/shader/particle backgrounds.
+- `implementation-playbook.md` for integration, composition, accessibility and tuning.
+- `audit-findings.md` when dependency, prop, variant or upstream accuracy matters.
+- `inventory.json` for exact machine-readable props, dependencies and variant state.
+
+If none of those locations has all nine files, state which locations were checked,
+ask the user to run the relevant SINAPSE install/update, then verify current facts
+against the official registry and source before implementation.
+
+## Workflow
+
+1. Inspect the target stack, component architecture, design tokens, performance budget
+   and existing animation/scroll ownership.
+2. Translate the visual request into a user-experience function.
+3. Search the relevant catalog and shortlist at most three candidates.
+4. Compare visual fit, dependencies, runtime engine, props, interaction model,
+   accessibility, mobile cost and compatibility with existing effects.
+5. Open the official source for the selected variant. Treat source and registry as
+   authoritative when docs conflict.
+6. Run `npm view <package>` for every declared dependency before installing it.
+7. Prefer TS-TW or TS-CSS in TypeScript projects. Never use the three empty CurvedInput
+   variants recorded in the snapshot; use JS-CSS or verify that upstream fixed them.
+8. Install through shadcn/jsrepo or copy manually. Keep upstream provenance and the
+   required license notice for substantial copies.
+9. Wrap the imported component behind a local application component. Map design
+   tokens, content, breakpoints and quality presets at that boundary.
+10. Implement reduced-motion behavior, semantic fallback, keyboard/focus behavior,
+    cleanup and static/mobile fallback.
+11. Test load, resize, route unmount/remount, long scroll, coarse pointer, reduced
+    motion and low-power mobile. Measure frame time and memory.
+12. Report component, variant, source SHA/URL, dependencies, adaptations, fallbacks and
+    remaining risks.
+
+## Composition rules
+
+- Use one dominant motion effect per viewport and no more than two support effects.
+- Prefer the lowest-cost engine that satisfies the visual objective.
+- Allow only one owner for smooth scroll, custom cursor and each render loop.
+- Do not stack multiple heavy WebGL/physics backgrounds without an explicit budget.
+- Pause offscreen/hidden loops and dispose GPU resources on unmount.
+- Preserve content and interaction when animation is disabled or fails.
+
+## Accuracy rules
+
+- Do not repeat the promotional “140+” as an exact count. The pinned snapshot has 139.
+- Do not infer functional variants from registry names alone; inspect source bytes/code.
+- Use registry JSON for install dependencies and source for actual API/behavior.
+- Note documentation typos and per-variant divergences from `audit-findings.md`.
+- Do not redistribute React Bits components as a standalone library, bundle, or port.

package/.codex/scripts/sync-codex-native.js

@@ -34,6 +34,10 @@ function isPathInside(parentPath, candidatePath) {
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 
+function isSafeSkillId(skillId) {
+  return typeof skillId === 'string' && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(skillId);
+}
+
 function readCanonicalSource(projectRoot, sourcePath) {
   if (!sourcePath) {
     throw new Error('Codex agent pointer does not declare a canonical source');
@@ -329,6 +333,14 @@ function readCodexCatalog(projectRoot = PROJECT_ROOT) {
   if (typeof catalog.genericAgentSkillId !== 'string' || !catalog.genericAgentSkillId.trim()) {
     throw new Error('Codex catalog does not declare genericAgentSkillId');
   }
+  const catalogSkillIds = [
+    ...catalog.expectedSkillIds,
+    ...catalog.publicAliasSkillIds,
+    catalog.genericAgentSkillId,
+  ];
+  if (catalogSkillIds.some((skillId) => !isSafeSkillId(skillId))) {
+    throw new Error('Codex catalog contains an unsafe skill ID');
+  }
   return catalog;
 }
 

package/.sinapse-ai/data/entity-registry.yaml

@@ -1,7 +1,7 @@
 metadata:
   version: 1.0.0
-  lastUpdated: '2026-07-15T08:35:27.084Z'
-  entityCount: 817
+  lastUpdated: '2026-07-15T14:30:07.448Z'
+  entityCount: 818
   checksumAlgorithm: sha256
   resolutionRate: 100
 entities:
@@ -166,8 +166,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:1f385982ca84a8232f3f6b1fce4257ca3971a5fd24830b5389477f9a5a8e943a
-      lastVerified: '2026-07-15T08:12:47.676Z'
+      checksum: sha256:86db5a2578b6a0b4849fde4e0f4a197a41560a3a213b247f0edd8522d857ffea
+      lastVerified: '2026-07-15T13:41:11.702Z'
     local:
       path: bin/commands/local.js
       layer: L1
@@ -276,8 +276,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:b51998a172a91e134330847185c078d317ed9be2da6746de3af18d209b7e08d9
-      lastVerified: '2026-07-15T08:12:47.677Z'
+      checksum: sha256:05056e197ecb29e6f63a1d86d9d77d944e3083021bf632b48a76eb4cb2223b95
+      lastVerified: '2026-07-15T13:41:11.703Z'
     command-generator:
       path: bin/lib/command-generator.js
       layer: L1
@@ -299,6 +299,7 @@ entities:
         - constants
         - squads
         - fs-utils
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -306,8 +307,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:ed3f86d0349e4a709240728c0872bf44c3ebb2f1b8f3522c83e2f43c9b8c5647
-      lastVerified: '2026-07-15T02:37:43.455Z'
+      checksum: sha256:837f10f3ce227b1f3ff9b3d4c9e824e8928cd67ec07b0dcebd78e85468eed003
+      lastVerified: '2026-07-15T13:41:11.703Z'
     constants:
       path: bin/lib/constants.js
       layer: L1
@@ -413,7 +414,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -421,8 +423,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:d28b19935a9c75408df9da7430fc3ca9568bdea0cfc1ae3c01d0025ad19fc2a3
-      lastVerified: '2026-07-15T07:09:56.286Z'
+      checksum: sha256:898fbe5a00cf1bb77bc8e8a34ee40337145912374a2e809789a02d5345fdd679
+      lastVerified: '2026-07-15T14:30:07.273Z'
     header:
       path: bin/lib/header.js
       layer: L1
@@ -475,6 +477,28 @@ entities:
         extensionPoints: []
       checksum: sha256:dc7cc1109f2bbdb7b3c5927df0de2418925842bdacdc0ba82815bfa2783d0b42
       lastVerified: '2026-06-22T02:41:18.152Z'
+    provider-contract:
+      path: bin/lib/provider-contract.js
+      layer: L1
+      type: script
+      purpose: Entity at bin\lib\provider-contract.js
+      keywords:
+        - provider
+        - contract
+      usedBy:
+        - command-generator
+        - global-provider-adapters
+        - provider-parity
+      dependencies: []
+      externalDeps: []
+      plannedDeps: []
+      lifecycle: production
+      adaptability:
+        score: 0.7
+        constraints: []
+        extensionPoints: []
+      checksum: sha256:a18d271a73b2f371213af4d9503e302e9237920057afd521b723c96efd28fda0
+      lastVerified: '2026-07-15T13:41:11.704Z'
     provider-parity:
       path: bin/lib/provider-parity.js
       layer: L1
@@ -486,7 +510,8 @@ entities:
       usedBy:
         - install
         - update
-      dependencies: []
+      dependencies:
+        - provider-contract
       externalDeps: []
       plannedDeps: []
       lifecycle: production
@@ -494,8 +519,8 @@ entities:
         score: 0.7
         constraints: []
         extensionPoints: []
-      checksum: sha256:592206326a2a3c5a3d89068d9ef065d698562aef40e6096d971fb793cea11c97
-      lastVerified: '2026-07-15T08:35:26.859Z'
+      checksum: sha256:5f0ff4517425fef01683f035afef1d139aede2fe47956773a398e7c761ace42d
+      lastVerified: '2026-07-15T13:41:11.704Z'
     setup-statusline:
       path: bin/lib/setup-statusline.js
       layer: L1

package/.sinapse-ai/install-manifest.yaml

@@ -7,7 +7,7 @@
 # - SHA256 hashes for change detection
 # - File types for categorization
 #
-version: 1.25.2
+version: 1.26.0
 generator: scripts/generate-install-manifest.js
 file_count: 1156
 files:
@@ -1368,9 +1368,9 @@ files:
     type: data
     size: 9671
   - path: data/entity-registry.yaml
-    hash: sha256:ed0919b2bc3479beb4e46d3ccfbbbda66e46161c7eebc9018b9f0c8e5278d7f1
+    hash: sha256:08edc9d3cde1bf956cce462004670a3d2924a691a16c27bdfd2bf1ce4de037f8
     type: data
-    size: 559991
+    size: 560701
   - path: data/learned-patterns.yaml
     hash: sha256:1a4cd045c087b9dfd7046ff1464a9d2edb85fba77cf0b6fba14f4bb9004c741e
     type: data

package/CHANGELOG.md

@@ -1,16 +1,17 @@
-## [1.25.2](https://github.com/caioimori/sinapse-ai/compare/1.25.1...1.25.2) (2026-07-15)
+## [1.26.0](https://github.com/caioimori/sinapse-ai/compare/1.25.3...1.26.0) (2026-07-15)
+
+### Features
+
+* deliver React Bits across providers [Story react-bits-distribution-parity] ([aa191f1](https://github.com/caioimori/sinapse-ai/commit/aa191f102dc417e3a0182c02661907e474226abb))
 
 ### Bug Fixes
 
-* **docs:** align public Claude and Codex guidance [Story Cross-Provider] ([8c005ec](https://github.com/caioimori/sinapse-ai/commit/8c005ec4f0c5702131564cb5d3d52fee8ed85b50))
-* **docs:** close public provider guidance gaps [Story Cross-Provider] ([43f76e2](https://github.com/caioimori/sinapse-ai/commit/43f76e2b405ffae61598d8999f043a1d24ea24a5))
+* **docs:** align provider skill metrics [Story react-bits-distribution-parity] ([729d120](https://github.com/caioimori/sinapse-ai/commit/729d120ee1735473d01971efdb746be59d2d19d8))
+* **react-bits:** harden corpus delivery and orchestration [Story react-bits-distribution-parity] ([6456062](https://github.com/caioimori/sinapse-ai/commit/6456062cd756826e6bc14c698ebde07298d8a5eb))
 
 ### Documentation
 
-* harden provider backup guidance [Story cross-provider-cli-quality] ([5f4bffd](https://github.com/caioimori/sinapse-ai/commit/5f4bffd351c7ac1c0ee5cde2d7388e34409e0566))
-* **story:** normalize validation terminology [Story sinapse-only-catalog-cleanup] ([7e0ecb9](https://github.com/caioimori/sinapse-ai/commit/7e0ecb9fb01a6626ccc7c665d262c38c61196120))
-* **story:** reconcile post-release evidence [Story sinapse-only-catalog-cleanup] ([3c10c65](https://github.com/caioimori/sinapse-ai/commit/3c10c65fcfdca77ec0d1c1af6a2831af39b0adf0))
-* **story:** record SINAPSE 1.25.1 release [Story sinapse-only-catalog-cleanup] ([ba9f776](https://github.com/caioimori/sinapse-ai/commit/ba9f77607879c6efe8511e38cfeab6c71d2335c4))
+* close installer parity release evidence [Story hotfix-installer-provider-adapter-parity-1.25.3] ([#386](https://github.com/caioimori/sinapse-ai/issues/386)) ([ceafcb8](https://github.com/caioimori/sinapse-ai/commit/ceafcb8ac522835c264115e9ee16cba6e49e173c))
 
 # Changelog
 

package/README.en.md

@@ -309,7 +309,7 @@ Both IDEs have access to all 17 squads, 172 agents, workflows, and knowledge bas
 | Native agents | 172 | 172 |
 | Direct activation | `@agent-name` | `$sinapse-agent agent-id` |
 | Primary routing | `@sinapse-orqx` | `$snps` |
-| Installed skills | 36 | 37 |
+| Installed skills | 37 | 37 |
 | Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
 | Validation source | `npm run validate:providers` | `npm run validate:codex-native` |
 

package/README.md

@@ -331,7 +331,7 @@ Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowled
 | Agentes nativos | 172 | 172 |
 | Ativação direta | `@agent-name` | `$sinapse-agent agent-id` |
 | Roteamento principal | `@sinapse-orqx` | `$snps` |
-| Skills instaladas | 36 | 37 |
+| Skills instaladas | 37 | 37 |
 | Hooks registrados | 20 registros nativos | 9 eventos de lifecycle via bridge |
 | Fonte de validação | `npm run validate:providers` | `npm run validate:codex-native` |
 

package/bin/commands/install.js

@@ -50,6 +50,10 @@ const {
 } = require('../lib/command-generator');
 const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
 const { assertProviderAdapterParity } = require('../lib/provider-parity');
+const {
+  copyReactBitsCapabilitySync,
+  REACT_BITS_SKILL_RELATIVE_PATH,
+} = require('../../packages/installer/src/installer/react-bits-corpus');
 // Follow-up #13 — wire the transactional backup/rollback engine into the
 // installer so an in-place UPGRADE (upsert) that fails mid-flight is restored
 // to its previous state instead of leaving ~/.sinapse half-updated.
@@ -317,7 +321,12 @@ async function cmdInstallGlobal(opts = {}) {
   // rich, frontmatter'd stubs are always the final word. Idempotent.
   try {
     const commandsDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
-    const reconciled = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir });
+    const reconciled = deliverGlobalProviderAdapters({
+      llmChoice,
+      home: HOME,
+      commandsDir,
+      reactBitsSkillPath: path.join(SINAPSE_HOME, REACT_BITS_SKILL_RELATIVE_PATH),
+    });
     const total = reconciled.claude.length + reconciled.codex.length + reconciled.skills.length;
     if (total) logger.always(`  ${GREEN}OK${NC} Global provider adapters reconciled (${total} artifacts)`);
   } catch (e) {
@@ -557,10 +566,13 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
     logger.always(`  ${GREEN}OK${NC} core development (${coreAgents} agents)`);
   }
 
+  const reactBits = copyReactBitsCapabilitySync(ROOT, SINAPSE_HOME);
+  if (reactBits.files.length) logger.always(`  ${GREEN}OK${NC} React Bits corpus (${reactBits.files.length} files)`);
+
   // Phase 2: Generate agent commands (shared with `update` via command-generator).
   logger.always(`\n${CYAN}Phase 2:${NC} Generating agent commands`);
   const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
-  const { writtenAgents, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -570,8 +582,17 @@ function installFatalPhases({ squads, squadsDir, isUpsert, llmChoice, existing,
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} total command files`);
 
   // Phase 2b: Install global agents based on LLM choice
-  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const globalAdapters = deliverGlobalProviderAdapters({
+    llmChoice,
+    home: HOME,
+    commandsDir: commandStagingDir,
+    reactBitsSkillPath: path.join(SINAPSE_HOME, REACT_BITS_SKILL_RELATIVE_PATH),
+  });
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   const installedAgentFilenames = new Set([...globalAdapters.claude, ...globalAdapters.codex]);
   const installedIdes = [];
   if (globalAdapters.claude.length) installedIdes.push('claude-code');

package/bin/commands/uninstall.js

@@ -170,7 +170,7 @@ function removeOrqxAgentsFrom(dir) {
   return removeInstalledAgentsFrom(dir);
 }
 
-const MANAGED_GLOBAL_SKILL_IDS = ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent'];
+const MANAGED_GLOBAL_SKILL_IDS = ['snps', 'sinapse', 'snps-orqx', 'sinapse-orqx', 'sinapse-agent', 'react-bits-frontend'];
 const MANAGED_GLOBAL_SKILL_MARKER = 'SINAPSE-MANAGED:global-skill';
 
 function removeManagedGlobalSkills(home = HOME, options = {}) {

package/bin/commands/update.js

@@ -36,6 +36,10 @@ const {
 } = require('./uninstall');
 const { regenerateAgentCommands } = require('../lib/command-generator');
 const { deliverGlobalProviderAdapters, getGlobalCommandStagingDir } = require('../lib/global-provider-adapters');
+const {
+  copyReactBitsCapabilitySync,
+  REACT_BITS_SKILL_RELATIVE_PATH,
+} = require('../../packages/installer/src/installer/react-bits-corpus');
 const { assertProviderAdapterParity } = require('../lib/provider-parity');
 const { execSync } = require('child_process');
 
@@ -164,13 +168,16 @@ async function cmdUpdateGlobal() {
     logger.always(`  ${GREEN}OK${NC} core development`);
   }
 
+  const reactBits = copyReactBitsCapabilitySync(ROOT, SINAPSE_HOME);
+  if (reactBits.files.length) logger.always(`  ${GREEN}OK${NC} React Bits corpus (${reactBits.files.length} files)`);
+
   // Phase 2: Regenerate commands — shared with `install` so `update` produces the
   // SAME complete set (every specialist command + the rich master Imperator stubs),
   // not just the `-orqx` subset it used to write.
   logger.always(`\n${CYAN}Phase 2:${NC} Regenerating commands`);
   const commandStagingDir = getGlobalCommandStagingDir({ llmChoice, sinapseHome: SINAPSE_HOME, claudeCommandsDir: CLAUDE_COMMANDS_DIR });
   rmDirSync(commandStagingDir);
-  const { writtenAgents, totalAgents } = regenerateAgentCommands({
+  const { writtenAgents, canonicalAgents, totalAgents } = regenerateAgentCommands({
     sinapseHome: SINAPSE_HOME,
     commandsDir: commandStagingDir,
     squads,
@@ -180,8 +187,17 @@ async function cmdUpdateGlobal() {
   logger.always(`  ${GREEN}OK${NC} ${writtenAgents.size} command files (${totalAgents} agents total)`);
 
   // Phase 2b: Install global agents based on LLM choice
-  const globalAdapters = deliverGlobalProviderAdapters({ llmChoice, home: HOME, commandsDir: commandStagingDir });
-  const activeAgentCount = assertProviderAdapterParity(llmChoice, globalAdapters, totalAgents);
+  const globalAdapters = deliverGlobalProviderAdapters({
+    llmChoice,
+    home: HOME,
+    commandsDir: commandStagingDir,
+    reactBitsSkillPath: path.join(SINAPSE_HOME, REACT_BITS_SKILL_RELATIVE_PATH),
+  });
+  const activeAgentCount = assertProviderAdapterParity(
+    llmChoice,
+    globalAdapters,
+    canonicalAgents,
+  );
   if (globalAdapters.claude.length) logger.always(`  ${GREEN}OK${NC} Claude Code global agents (${globalAdapters.claude.length})`);
   if (globalAdapters.codex.length) logger.always(`  ${GREEN}OK${NC} Codex global agents (${globalAdapters.codex.length} TOML, ${globalAdapters.skills.length} skills)`);
 

package/bin/lib/command-generator.js

@@ -20,6 +20,7 @@ const { toForwardSlash, atomicWriteFileSync } = require('./fs-utils');
 // sync-counts uses so the master-stub headline can never drift from README/persona
 // (Constitution Article VII). Fails open to 0 if the dir is unavailable.
 const CORE_AGENTS_DIR = path.join(ROOT, '.sinapse-ai', 'development', 'agents');
+const { MASTER_ALIAS_ENTRY_POINTS } = require('./provider-contract');
 
 function countCoreAgents(dir = CORE_AGENTS_DIR) {
   try {
@@ -207,7 +208,7 @@ If the task requires expertise outside this squad:
  * @param {string} [deps.commandsDir] - Target commands dir.
  * @param {Array}  deps.squads - Squad descriptors ({ name, agents, ... }).
  * @param {string} [deps.sinapseMasterDest] - Path to the installed sinapse/ master squad.
- * @returns {{ writtenAgents: Set<string>, totalAgents: number }}
+ * @returns {{ writtenAgents: Set<string>, canonicalAgents: Array<{ id: string, file: string, origin: string }>, aliasEntryPoints: string[], totalAgents: number }}
  */
 function regenerateAgentCommands(deps = {}) {
   const {
@@ -222,20 +223,21 @@ function regenerateAgentCommands(deps = {}) {
     throw new Error('regenerateAgentCommands: `squads` array is required');
   }
 
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  // Clear old commands (dir may not exist on a fresh install — guarded).
-  try {
-    for (const f of fs.readdirSync(commandsDir)) {
-      fs.unlinkSync(path.join(commandsDir, f));
-    }
-  } catch { /* dir may not exist yet */ }
-
   const sinapseBase = toForwardSlash(sinapseHome);
   const writtenAgents = new Set();
+  const catalogById = new Map();
+  const definitions = [];
+
+  function registerDefinition(definition) {
+    const previous = catalogById.get(definition.id);
+    if (previous) {
+      throw new Error(`Duplicate canonical agent ID "${definition.id}" from ${previous.origin} and ${definition.origin}`);
+    }
+    catalogById.set(definition.id, definition);
+    definitions.push(definition);
+  }
 
-  // 1. A command/subagent for EVERY agent (not only -orqx), so every specialist
-  //    is invokable via @agent and /SINAPSE:agents:agent.
+  // Inventory every canonical definition before clearing or writing commands.
   for (const squad of squads) {
     const squadPath = `${sinapseBase}/${squad.name}`;
     const agentsDir = path.join(sinapseHome, squad.name, 'agents');
@@ -244,10 +246,14 @@ function regenerateAgentCommands(deps = {}) {
     const squadAgents = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
     for (const file of squadAgents) {
       const agentId = file.replace('.md', '');
-      const meta = extractAgentMeta(path.join(agentsDir, file));
-      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, squad.name, squadPath, file);
-      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-      writtenAgents.add(file);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(agentsDir, file),
+        squadName: squad.name,
+        squadPath,
+        hasManifest: true,
+      });
     }
   }
 
@@ -257,29 +263,37 @@ function regenerateAgentCommands(deps = {}) {
   if (fs.existsSync(coreAgentsDir)) {
     const coreBase = toForwardSlash(coreDevelopmentDest);
     for (const file of fs.readdirSync(coreAgentsDir).filter(f => f.endsWith('.md'))) {
-      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_') || writtenAgents.has(file)) continue;
+      if (file === 'README.md' || file === 'MEMORY.md' || file.startsWith('_')) continue;
       const agentId = file.replace('.md', '');
-      const meta = extractAgentMeta(path.join(coreAgentsDir, file));
-      const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'core', coreBase, file, { hasManifest: false });
-      atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-      writtenAgents.add(file);
+      registerDefinition({
+        id: agentId,
+        file,
+        origin: path.join(coreAgentsDir, file),
+        squadName: 'core',
+        squadPath: coreBase,
+        hasManifest: false,
+      });
     }
   }
 
-  // 2. Commands for sinapse/ master squad agents.
-  if (fs.existsSync(sinapseMasterDest)) {
-    const masterAgentsDir = path.join(sinapseMasterDest, 'agents');
-    if (fs.existsSync(masterAgentsDir)) {
-      for (const file of fs.readdirSync(masterAgentsDir).filter(f => f.endsWith('.md'))) {
-        if (writtenAgents.has(file)) continue;
-        const agentId = file.replace('.md', '');
-        const meta = extractAgentMeta(path.join(masterAgentsDir, file));
-        const squadPath = `${sinapseBase}/sinapse`;
-        const cmdContent = generateCommandMd(agentId, meta.name, meta.icon, 'sinapse', squadPath, file);
-        atomicWriteFileSync(path.join(commandsDir, `${agentId}.md`), cmdContent);
-        writtenAgents.add(file);
-      }
-    }
+  fs.mkdirSync(commandsDir, { recursive: true });
+  for (const file of fs.readdirSync(commandsDir)) {
+    fs.unlinkSync(path.join(commandsDir, file));
+  }
+
+  for (const definition of definitions) {
+    const meta = extractAgentMeta(definition.origin);
+    const cmdContent = generateCommandMd(
+      definition.id,
+      meta.name,
+      meta.icon,
+      definition.squadName,
+      definition.squadPath,
+      definition.file,
+      { hasManifest: definition.hasManifest },
+    );
+    atomicWriteFileSync(path.join(commandsDir, definition.file), cmdContent);
+    writtenAgents.add(definition.file);
   }
 
   // 3. Master entry points (@sinapse, @snps, @sinapse-orqx, @snps-orqx) → rich
@@ -301,7 +315,16 @@ function regenerateAgentCommands(deps = {}) {
     }
   }
 
-  return { writtenAgents, totalAgents: writtenAgents.size };
+  const aliasEntryPoints = [...MASTER_ALIAS_ENTRY_POINTS]
+    .filter((id) => writtenAgents.has(`${id}.md`));
+  const canonicalAgents = definitions.map(({ id, file, origin }) => ({ id, file, origin }));
+
+  return {
+    writtenAgents,
+    canonicalAgents,
+    aliasEntryPoints,
+    totalAgents: canonicalAgents.length,
+  };
 }
 
 module.exports = {
@@ -309,4 +332,5 @@ module.exports = {
   generateMasterStub,
   regenerateAgentCommands,
   countCoreAgents,
+  MASTER_ALIAS_ENTRY_POINTS,
 };