create-byan-agent 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.19.0] - 2026-06-01
+
+### Added - Platform migrated to the by-type (Gen3) layout
+
+The 2.18.0 tooling could migrate `_byan/` to the by-type layout, but the
+platform code still resolved the old module layout. This release makes the read
+side layout-aware, then executes the physical cutover (Phase B), and finally
+makes fresh installs born on the by-type layout. The platform repo, the install
+template and the resolver are now all on Gen3, with a Gen2 fallback retained for
+existing installs.
+
+#### Read side — layout-aware resolution (F12-F14)
+
+- **F12 — read-side layout resolver.** New `src/byan-v2/lib/layout-resolver.js`
+  resolves agents, soul/tao, knowledge, memory and config Gen3-first with a Gen2
+  fallback. Adopted across `elo-store`, the fact-check stack, the agent packager,
+  the webui chat bridge/detector, the stub generators and the Claude Code hooks.
+- **F13 — webui `api.js`.** Moved off the dead Gen1 `_bmad/` tree: install
+  detection, rollback target, the scaffolded skeleton and the base-config writer
+  now use `_byan/` (tolerant of a legacy `_bmad/` checkout). The base-config
+  writer guards on `resolveConfig()` so it does not shadow the authoritative
+  `_byan/bmb/config.yaml`.
+- **F14 — completeness audit + the breaks it surfaced.** A multi-agent audit of
+  all layout-path references confirmed 7 breaks the resolver adoption had missed:
+  6 drifted `install/templates/.claude/hooks/*` mirrors (re-synced to their
+  already-correct source twins) and `install/src/webui/chat/session-manager.js`
+  (chat history dir hardcoded to `_byan/_memory/`, now resolved Gen3-first).
+
+#### Cutover — the physical move (F16-F18)
+
+- **F16 — migration map completed + body-reference rewriter.** The migration map
+  gained the retained-module rule (module `config`/`help`/`teams`/`data` and core
+  `base`/`activation`/`model-selector` stay in place), the testarch and resources
+  rules, and the workers move. New `rewrite-refs.js` + `byan-rewrite-refs` CLI
+  rewrite intra-file `_byan/...` references for `move` entries only, so the pass
+  is idempotent (`split`/`keep` targets stay untouched).
+- **F18 — Phase B executed.** The platform `_byan/` tree was physically moved to
+  the by-type layout: agents to `agent/<name>/`, workflows to `workflow/simple/`,
+  knowledge to `connaissance/`, memory to `memoire/`, tasks to `command/`,
+  workers to `worker/`, and the root soul to `agent/byan/`. Content references and
+  manifest path columns were rewritten and `INDEX.md` regenerated. `config.yaml`
+  was left in place (its readers depend on the keys a split would separate). The
+  flagship-agent collision (byan/marc/rachid existing in both the flat and a
+  module dir with different bodies) resolves module-wins: the module copy is
+  canonical at `_byan/agent/<name>/<name>.md`, the flat copy preserved at
+  `_byan/agent/<name>-flat/`.
+
+#### Tooling and enforcement (F16, F19, F20)
+
+- **F19 — yanstaller migrates existing projects.** The update hook
+  (`install/lib/fs-migration-hook.js`) runs the full chain — `migrate-fs` ->
+  `rewrite-refs` -> `rewrite-manifests` -> `reconcile-manifests` -> `build-index`
+  — so an existing install converges to the by-type layout. It stays dormant
+  unless `BYAN_FS_MIGRATE=1` or `_byan/_config/migrate-fs.enabled` is set, and it
+  backs up `_byan/` before acting. New `byan-rewrite-manifests` CLI rewrites the
+  manifest path columns.
+- **F20 — strict scope-guard glob fix.** `matchesPrefix` reduced a glob to its
+  literal prefix before matching, so an `allowedPath` like `_byan/**` or
+  `src/**/*.test.js` is honored instead of refusing writes inside the intended
+  directory; non-glob prefixes keep their exact behavior.
+
+#### Born Gen3 — fresh installs (F21)
+
+- **F21 — install template on the by-type layout.** `install/templates/_byan/`
+  was migrated to Gen3 (the same chain, with the bundled MCP server left
+  byte-identical), and `create-byan-agent-v2.js` was updated to match: the copy
+  whitelist now lists the by-type dirs (`agent`, `workflow`, `connaissance`,
+  `command`, `worker`, `memoire`) alongside the retained module dirs, and the
+  active soul (soul/tao/soul-memory/creator-soul) is written to
+  `_byan/agent/byan/` so it resolves Gen3-first. A new
+  `install/__tests__/template-gen3-layout.test.js` guards the template shape and
+  the installer whitelist against a regression to Gen2.
+
+### Notes
+
+- The Gen2 fallback in the resolver remains, so an install that predates this
+  release keeps working; the F19 hook converts it to Gen3 on update when enabled.
+- `byan_version` in the installed configs is unchanged (separate axis, per the
+  2.18.0 release convention).
+- See `docs/refactor/` for the per-feature notes: `F12-layout-adoption.md` (read
+  side), `F7-migration-map.md` (map + rewriter) and `README.md` (index).
+
+---
+
 ## [2.18.0] - 2026-05-27
 
 ### Added - BYAN refactor: workflow atomisation + by-type file system tooling

package/install/bin/build-copilot-stubs.js

@@ -13,6 +13,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const layoutResolver = require('../../src/byan-v2/lib/layout-resolver');
 
 const ROOT = path.resolve(__dirname, '..', '..');
 const AGENTS_DIR = path.join(ROOT, '.github', 'agents');
@@ -31,14 +32,18 @@ function stripFrontmatter(content) {
 }
 
 function buildByanStub() {
-  const agentContent = readFile(path.join(BYAN_DIR, 'agents', 'byan.md'));
+  // Layout resolver: Gen3 _byan/agent/byan/ first, Gen2 fallback.
+  const agentHit = layoutResolver.resolveAgent('byan', { projectRoot: ROOT });
+  const agentContent = agentHit ? readFile(agentHit.path) : null;
   if (!agentContent) {
-    console.error('Cannot read _byan/agents/byan.md');
+    console.error('Cannot find the byan agent file (looked in Gen3 _byan/agent/byan/ and Gen2 layouts)');
     process.exit(1);
   }
 
-  const soulContent = readFile(path.join(BYAN_DIR, 'soul.md'));
-  const taoContent = readFile(path.join(BYAN_DIR, 'tao.md'));
+  const soulHit = layoutResolver.resolveSoul('soul', { projectRoot: ROOT });
+  const taoHit = layoutResolver.resolveSoul('tao', { projectRoot: ROOT });
+  const soulContent = soulHit ? readFile(soulHit.path) : null;
+  const taoContent = taoHit ? readFile(taoHit.path) : null;
   const soulActivation = readFile(path.join(BYAN_DIR, 'core', 'activation', 'soul-activation.md'));
 
   const agentBody = stripFrontmatter(agentContent);
@@ -80,16 +85,20 @@ ${activationBody}
 }
 
 function buildModuleAgentStub(agentName, moduleName) {
-  const agentPath = path.join(BYAN_DIR, moduleName, 'agents', `${agentName}.md`);
+  // Resolve the agent across layouts (Gen3 _byan/agent/<name>/, Gen2 flat +
+  // per-module); fall back to the explicit module path passed on the CLI.
+  const agentHit = layoutResolver.resolveAgent(agentName, { projectRoot: ROOT });
+  const agentPath = agentHit ? agentHit.path : path.join(BYAN_DIR, moduleName, 'agents', `${agentName}.md`);
   const agentContent = readFile(agentPath);
   if (!agentContent) {
-    console.error(`Cannot read ${agentPath}`);
+    console.error(`Cannot read agent ${agentName} (looked via resolver and ${path.relative(ROOT, agentPath)})`);
     return null;
   }
 
   const agentBody = stripFrontmatter(agentContent);
 
-  const soulPath = path.join(BYAN_DIR, moduleName, 'agents', `${agentName}-soul.md`);
+  // Soul sibling lives next to the resolved agent file.
+  const soulPath = path.join(path.dirname(agentPath), `${agentName}-soul.md`);
   const soulContent = readFile(soulPath);
   const soulSection = soulContent ? `\n<!-- soul: ${agentName}-soul.md -->\n${stripFrontmatter(soulContent)}\n` : '';
 

package/install/bin/create-byan-agent-v2.js

@@ -1215,13 +1215,12 @@ async function install(options = {}) {
   const isManual = installMode === 'manual' && manualSelection;
   const manualPlatformList = isManual ? manualSelection.platforms : [];
   
-  await fs.ensureDir(path.join(byanDir, 'bmb', 'agents'));
-  await fs.ensureDir(path.join(byanDir, 'bmb', 'workflows', 'byan', 'steps'));
-  await fs.ensureDir(path.join(byanDir, 'bmb', 'workflows', 'byan', 'templates'));
-  await fs.ensureDir(path.join(byanDir, 'bmb', 'workflows', 'byan', 'data'));
+  // By-type (Gen3) layout. fs.copy below creates the deep subdirs from the
+  // template; these ensureDir calls only guarantee the base dirs exist.
+  await fs.ensureDir(path.join(byanDir, 'agent'));
   await fs.ensureDir(path.join(byanDir, 'core'));
   await fs.ensureDir(path.join(byanDir, '_config'));
-  await fs.ensureDir(path.join(byanDir, '_memory'));
+  await fs.ensureDir(path.join(byanDir, 'memoire'));
   await fs.ensureDir(path.join(byanDir, '_output'));
   
   // Create platform directories based on selection
@@ -1239,11 +1238,16 @@ async function install(options = {}) {
   const copySpinner = ora('Installing BYAN platform files...').start();
   
   try {
-    // Copy the entire _byan/ structure (all modules, agents, configs, activation)
+    // Copy the entire _byan/ structure (by-type Gen3 layout: agents, workflows,
+    // knowledge, memory and commands live in dedicated top-level dirs; the
+    // module dirs keep only their config/help/teams/data).
     const byanSource = path.join(templateDir, '_byan');
-    
-    // Core directories to copy from templates/_byan/ → project/_byan/
-    const byanDirs = ['agents', 'core', 'bmb', 'bmm', 'tea', 'cis', '_config', '_memory', 'data', 'workflows'];
+
+    // Directories to copy from templates/_byan/ → project/_byan/.
+    // Gen3 by-type dirs (agent, workflow, connaissance, command, worker,
+    // memoire) plus the retained module config dirs and _config/data.
+    const byanDirs = ['agent', 'workflow', 'connaissance', 'command', 'worker', 'memoire',
+      'core', 'bmb', 'bmm', 'tea', 'cis', '_config', 'data'];
     
     for (const dir of byanDirs) {
       const source = path.join(byanSource, dir);
@@ -1264,7 +1268,7 @@ async function install(options = {}) {
     }
     
     copySpinner.text = 'Copied platform files...';
-    console.log(chalk.green(`  ✓ Platform: _byan/ (agents, core, bmb, bmm, tea, cis, config)`));
+    console.log(chalk.green(`  ✓ Platform: _byan/ (agent, workflow, connaissance, command, worker, memoire, config)`));
     
     // Copy cost optimizer worker if enabled
     if (interviewAnswers && interviewAnswers.costOptimizer) {
@@ -1347,7 +1351,7 @@ async function install(options = {}) {
               copilotCount++;
             } else {
               // Generate stub if no template exists
-              const stubContent = `---\nname: "${stubName}"\ndescription: "${agentName} agent from BYAN platform"\n---\n\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.\n\n<agent-activation CRITICAL="TRUE">\n1. LOAD the FULL agent file from {project-root}/_bmad/*/agents/${agentName}.md\n2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n3. FOLLOW every step in the <activation> section precisely\n4. DISPLAY the welcome/greeting as instructed\n5. PRESENT the numbered menu\n6. WAIT for user input before proceeding\n</agent-activation>\n`;
+              const stubContent = `---\nname: "${stubName}"\ndescription: "${agentName} agent from BYAN platform"\n---\n\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.\n\n<agent-activation CRITICAL="TRUE">\n1. LOAD the FULL agent file from {project-root}/_byan/agent/${agentName}/${agentName}.md (new layout); if absent, {project-root}/_byan/*/agents/${agentName}.md (legacy layout)\n2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n3. FOLLOW every step in the <activation> section precisely\n4. DISPLAY the welcome/greeting as instructed\n5. PRESENT the numbered menu\n6. WAIT for user input before proceeding\n</agent-activation>\n`;
               await fs.writeFile(destFile, stubContent, 'utf8');
               copilotCount++;
             }
@@ -1364,7 +1368,7 @@ async function install(options = {}) {
         for (const agentName of selectedAgents) {
           const skillName = agentName === 'hermes' ? 'hermes' : `bmad-${agentName}`;
           const skillPath = path.join(codexPromptsDir, `${skillName}.md`);
-          const skillContent = `# ${agentName} Skill\n\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified.\n\n<agent-activation CRITICAL="TRUE">\n1. LOAD the FULL agent file from {project-root}/_bmad/*/agents/${agentName}.md\n2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n3. FOLLOW every step in the <activation> section precisely\n4. DISPLAY the welcome/greeting as instructed\n5. PRESENT the numbered menu\n6. WAIT for user input before proceeding\n</agent-activation>\n\n## Usage\ncodex skill ${skillName} [prompt]\n\n## Examples\n- codex skill ${skillName}\n- codex skill ${skillName} "help me with my project"\n`;
+          const skillContent = `# ${agentName} Skill\n\nYou must fully embody this agent's persona and follow all activation instructions exactly as specified.\n\n<agent-activation CRITICAL="TRUE">\n1. LOAD the FULL agent file from {project-root}/_byan/agent/${agentName}/${agentName}.md (new layout); if absent, {project-root}/_byan/*/agents/${agentName}.md (legacy layout)\n2. READ its entire contents - this contains the complete agent persona, menu, and instructions\n3. FOLLOW every step in the <activation> section precisely\n4. DISPLAY the welcome/greeting as instructed\n5. PRESENT the numbered menu\n6. WAIT for user input before proceeding\n</agent-activation>\n\n## Usage\ncodex skill ${skillName} [prompt]\n\n## Examples\n- codex skill ${skillName}\n- codex skill ${skillName} "help me with my project"\n`;
           await fs.writeFile(skillPath, skillContent, 'utf8');
           codexCount++;
         }
@@ -1546,32 +1550,39 @@ async function install(options = {}) {
   
   if (soulMode !== 'skip') {
     const soulSpinner = ora('Setting up Soul & Voice system...').start();
-    const soulDir = byanDir; // _byan/ root for soul files
-    
+    const soulDir = byanDir; // _byan/ root — *-reference / *-template inspiration files
+    // Gen3: the active soul/tao/memory live with the byan agent so the resolver
+    // and soul-activation.md find them at _byan/agent/byan/.
+    const soulActiveDir = path.join(byanDir, 'agent', 'byan');
+    await fs.ensureDir(soulActiveDir);
+
     try {
       if (soulMode === 'creator') {
-        // Copy Yan's soul files as active soul (creator mode = Yan's soul)
-        const creatorSoulSrc = path.join(templateDir, '_byan', 'creator-soul.md');
-        const byanSoulSrc = path.join(templateDir, '_byan', 'byan-soul.md');
-        const byanTaoSrc = path.join(templateDir, '_byan', 'byan-tao.md');
-        const byanMemorySrc = path.join(templateDir, '_byan', 'byan-soul-memory.md');
+        // Copy Yan's soul files as active soul (creator mode = Yan's soul).
+        // The active soul files live with the byan agent (Gen3: _byan/agent/byan/);
+        // the *-reference / *-template files stay at the _byan/ root.
+        const byanAgentDir = path.join(templateDir, '_byan', 'agent', 'byan');
+        const creatorSoulSrc = path.join(byanAgentDir, 'creator-soul.md');
+        const byanSoulSrc = path.join(byanAgentDir, 'byan-soul.md');
+        const byanTaoSrc = path.join(byanAgentDir, 'byan-tao.md');
+        const byanMemorySrc = path.join(byanAgentDir, 'byan-soul-memory.md');
         const soulRefSrc = path.join(templateDir, '_byan', 'byan-soul-reference.md');
         const taoRefSrc = path.join(templateDir, '_byan', 'byan-tao-reference.md');
         const memoryRefSrc = path.join(templateDir, '_byan', 'soul-memory-reference.md');
         
         // Copy creator-soul as-is (Yan's soul = the original)
         if (await fs.pathExists(creatorSoulSrc)) {
-          await fs.copy(creatorSoulSrc, path.join(soulDir, 'creator-soul.md'));
+          await fs.copy(creatorSoulSrc, path.join(soulActiveDir, 'creator-soul.md'));
         }
         // Copy Yan's active soul files (what soul-activation.md actually reads)
         if (await fs.pathExists(byanSoulSrc)) {
-          await fs.copy(byanSoulSrc, path.join(soulDir, 'soul.md'));
+          await fs.copy(byanSoulSrc, path.join(soulActiveDir, 'soul.md'));
         }
         if (await fs.pathExists(byanTaoSrc)) {
-          await fs.copy(byanTaoSrc, path.join(soulDir, 'tao.md'));
+          await fs.copy(byanTaoSrc, path.join(soulActiveDir, 'tao.md'));
         }
         if (await fs.pathExists(byanMemorySrc)) {
-          await fs.copy(byanMemorySrc, path.join(soulDir, 'soul-memory.md'));
+          await fs.copy(byanMemorySrc, path.join(soulActiveDir, 'soul-memory.md'));
         }
         // Copy references for inspiration
         if (await fs.pathExists(soulRefSrc)) {
@@ -1598,13 +1609,13 @@ async function install(options = {}) {
         const memoryTemplateSrc = path.join(templateDir, '_byan', 'soul-memory-template.md');
         
         if (await fs.pathExists(creatorTemplateSrc)) {
-          await fs.copy(creatorTemplateSrc, path.join(soulDir, 'creator-soul.md'));
+          await fs.copy(creatorTemplateSrc, path.join(soulActiveDir, 'creator-soul.md'));
         }
         if (await fs.pathExists(soulTemplateSrc)) {
-          await fs.copy(soulTemplateSrc, path.join(soulDir, 'soul.md'));
+          await fs.copy(soulTemplateSrc, path.join(soulActiveDir, 'soul.md'));
         }
         if (await fs.pathExists(memoryTemplateSrc)) {
-          await fs.copy(memoryTemplateSrc, path.join(soulDir, 'soul-memory.md'));
+          await fs.copy(memoryTemplateSrc, path.join(soulActiveDir, 'soul-memory.md'));
         }
         
         soulSpinner.succeed('Soul system installed (Blank mode — empty templates)');
@@ -1627,11 +1638,11 @@ async function install(options = {}) {
         
         const soulFiles = ['creator-soul.md', 'soul.md', 'soul-memory.md', 'tao.md'];
         let imported = 0;
-        
+
         for (const file of soulFiles) {
           const src = path.join(importPath, file);
           if (await fs.pathExists(src)) {
-            await fs.copy(src, path.join(soulDir, file));
+            await fs.copy(src, path.join(soulActiveDir, file));
             imported++;
             console.log(chalk.green(`  + ${file} imported`));
           }
@@ -1676,16 +1687,16 @@ async function install(options = {}) {
   const verifySpinner = ora('Verifying installation...').start();
   
   const checks = [
-    { name: 'Agents directory', path: path.join(bmbDir, 'agents') },
-    { name: 'BYAN agent', path: path.join(bmbDir, 'agents', 'byan.md') },
-    { name: 'Workflows', path: path.join(bmbDir, 'workflows', 'byan') },
+    { name: 'Agents directory', path: path.join(byanDir, 'agent') },
+    { name: 'BYAN agent', path: path.join(byanDir, 'agent', 'byan', 'byan.md') },
+    { name: 'Workflows', path: path.join(byanDir, 'workflow') },
     { name: 'Config', path: configPath }
   ];
-  
-  // Soul system checks
+
+  // Soul system checks (Gen3: active soul lives with the byan agent)
   if (soulMode && soulMode !== 'skip') {
-    checks.push({ name: 'Soul file', path: path.join(byanDir, 'soul.md') });
-    checks.push({ name: 'Soul memory', path: path.join(byanDir, 'soul-memory.md') });
+    checks.push({ name: 'Soul file', path: path.join(byanDir, 'agent', 'byan', 'soul.md') });
+    checks.push({ name: 'Soul memory', path: path.join(byanDir, 'agent', 'byan', 'soul-memory.md') });
   }
   
   // Platform-specific checks based on installation mode

package/install/lib/exchange/agent-packager.js

@@ -3,6 +3,7 @@ const path = require('path');
 const crypto = require('crypto');
 const yaml = require('js-yaml');
 const zlib = require('zlib');
+const layoutResolver = require('../../../src/byan-v2/lib/layout-resolver');
 
 const BYAN_MIN_VERSION = '2.8.0';
 const FORMAT_VERSION = '1.0';
@@ -153,18 +154,11 @@ class AgentPackager {
   }
 
   async _findAgentFile(name) {
-    const candidates = [
-      path.join(this.projectRoot, '_byan', 'agents', `${name}.md`),
-    ];
-
-    const bmadModules = ['core', 'bmm', 'bmb', 'tea', 'cis'];
-    for (const mod of bmadModules) {
-      candidates.push(path.join(this.projectRoot, '_bmad', mod, 'agents', `${name}.md`));
-    }
-
-    for (const candidate of candidates) {
-      if (await fs.pathExists(candidate)) return candidate;
-    }
+    // Layout resolver: Gen3 _byan/agent/<name>/ first, then Gen2 flat
+    // _byan/agents/, Gen2 per-module _byan/<module>/agents/ (previously NOT
+    // searched — agents like dev/analyst live there), then Gen1 _bmad/.
+    const hit = layoutResolver.resolveAgent(name, { projectRoot: this.projectRoot });
+    if (hit) return hit.path;
 
     const githubDir = path.join(this.projectRoot, '.github', 'agents');
     if (await fs.pathExists(githubDir)) {
@@ -270,11 +264,11 @@ class AgentPackager {
 
   _resolveTargetDir(agentName, targetModule) {
     if (targetModule) {
-      const moduleDir = path.join(this.projectRoot, '_bmad', sanitizeName(targetModule), 'agents');
+      const moduleDir = path.join(this.projectRoot, '_byan', sanitizeName(targetModule), 'agents');
       assertInsideRoot(moduleDir, this.projectRoot);
       return moduleDir;
     }
-    return path.join(this.projectRoot, '_bmad-output', 'bmb-creations', agentName);
+    return path.join(this.projectRoot, '_byan-output', 'bmb-creations', agentName);
   }
 
   async _generateStubs(agentName, metadata) {
@@ -294,7 +288,7 @@ class AgentPackager {
         "You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.",
         '',
         '<agent-activation CRITICAL="TRUE">',
-        `1. LOAD the FULL agent file from {project-root}/_bmad-output/bmb-creations/${agentName}/${agentName}.md`,
+        `1. LOAD the FULL agent file from {project-root}/_byan-output/bmb-creations/${agentName}/${agentName}.md`,
         '2. READ its entire contents - this contains the complete agent persona, menu, and instructions',
         '3. LOAD the soul activation protocol from {project-root}/_byan/core/activation/soul-activation.md and EXECUTE it silently',
         '4. FOLLOW every step in the <activation> section precisely',
@@ -322,9 +316,9 @@ class AgentPackager {
         "You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.",
         '',
         '<agent-activation CRITICAL="TRUE">',
-        `1. LOAD the FULL agent file from @bmad-output/bmb-creations/${agentName}/${agentName}.md`,
+        `1. LOAD the FULL agent file from @byan-output/bmb-creations/${agentName}/${agentName}.md`,
         '2. READ its entire contents - this contains the complete agent persona, menu, and instructions',
-        '3. LOAD the soul activation protocol from @bmad/core/activation/soul-activation.md and EXECUTE it silently',
+        '3. LOAD the soul activation protocol from @byan/core/activation/soul-activation.md and EXECUTE it silently',
         '4. Execute ALL activation steps exactly as written in the agent file',
         '5. Follow the agent\'s persona and menu system precisely',
         '6. Stay in character throughout the session',
@@ -339,25 +333,38 @@ class AgentPackager {
   }
 
   async _getAgentDirectories() {
-    const dirs = [
-      { dir: path.join(this.projectRoot, '_byan', 'agents'), module: 'byan' }
-    ];
-
-    const bmadModules = ['core', 'bmm', 'bmb', 'tea', 'cis'];
-    for (const mod of bmadModules) {
-      dirs.push({
-        dir: path.join(this.projectRoot, '_bmad', mod, 'agents'),
-        module: mod
-      });
+    // Derive scan dirs from the layout resolver (existing dirs only, Gen3-first).
+    // Gen3 _byan/agent/<name>/ is nested: expand each agent folder into its own
+    // flat scan dir so the <name>.md inside is picked up by the flat reader in
+    // listExportableAgents(). Gen2 flat + per-module dirs come through directly,
+    // which is what fixes the bug where _byan/<module>/agents/ was never scanned.
+    const dirs = [];
+    for (const d of layoutResolver.agentDirs({ projectRoot: this.projectRoot })) {
+      if (d.nested) {
+        const entries = await fs.readdir(d.dir, { withFileTypes: true });
+        for (const e of entries) {
+          if (e.isDirectory()) dirs.push({ dir: path.join(d.dir, e.name), module: 'agent' });
+        }
+      } else {
+        const mod = d.layout === 'gen2-flat' ? 'byan' : (d.rel.split('/')[1] || d.layout);
+        dirs.push({ dir: d.dir, module: mod });
+      }
     }
 
-    const bmadOutputDir = path.join(this.projectRoot, '_bmad-output', 'bmb-creations');
-    if (await fs.pathExists(bmadOutputDir)) {
-      const entries = await fs.readdir(bmadOutputDir, { withFileTypes: true });
+    // User-created agents: canonical _byan-output/bmb-creations plus the legacy
+    // _bmad-output/bmb-creations (older installs) so existing creations are not
+    // lost during the transition.
+    const creationRoots = [
+      path.join(this.projectRoot, '_byan-output', 'bmb-creations'),
+      path.join(this.projectRoot, '_bmad-output', 'bmb-creations'),
+    ];
+    for (const creationsDir of creationRoots) {
+      if (!await fs.pathExists(creationsDir)) continue;
+      const entries = await fs.readdir(creationsDir, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isDirectory()) {
           dirs.push({
-            dir: path.join(bmadOutputDir, entry.name),
+            dir: path.join(creationsDir, entry.name),
             module: 'bmb-creations'
           });
         }

package/install/lib/fs-migration-hook.js

@@ -18,10 +18,26 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
-const LEGACY_MODULES = ['bmm', 'bmb', 'tea', 'cis'];
+const LEGACY_MODULES = ['core', 'bmm', 'bmb', 'tea', 'cis'];
+
+// True iff a directory holds at least one *.md agent file. We probe the agent
+// FILES, not the module directory: a migrated tree keeps module dirs around for
+// the retained module-scoped infra (e.g. _byan/bmb/config.yaml), so an empty
+// _byan/<mod>/agents/ (or its absence) must read as "already migrated".
+function hasAgentFiles(dir) {
+  try {
+    return fs.readdirSync(dir).some((f) => f.endsWith('.md'));
+  } catch {
+    return false;
+  }
+}
 
 function hasLegacyLayout(projectRoot) {
-  return LEGACY_MODULES.some((m) => fs.existsSync(path.join(projectRoot, '_byan', m)));
+  const locations = [path.join(projectRoot, '_byan', 'agents')]; // flat agents
+  for (const m of LEGACY_MODULES) {
+    locations.push(path.join(projectRoot, '_byan', m, 'agents'));
+  }
+  return locations.some(hasAgentFiles);
 }
 
 function isEnabled({ projectRoot, env }) {
@@ -52,11 +68,21 @@ function runFsMigration({ projectRoot, env = process.env, exec = execSync, backu
   const run = (bin, args = '') =>
     exec(`node "${path.join(binDir, bin)}" --root "${projectRoot}"${args}`, { cwd: projectRoot, stdio: 'inherit' });
 
+  // Full sequence: move the files, then fix every reference to the moved files
+  // (content bodies + manifest path columns), dedup, and rebuild the index. The
+  // module-wins collision rule in migration-map reconciles flat-vs-module
+  // duplicate agents during the move (module canonical, flat -> <name>-flat).
   run('byan-migrate-fs.js', ' --apply');
+  run('byan-rewrite-refs.js', ' --apply');
+  run('byan-rewrite-manifests.js', ' --apply');
   run('byan-reconcile-manifests.js', ' --apply');
   run('byan-build-index.js');
 
-  return { ran: true, backup: backupPath, steps: ['migrate', 'reconcile', 'build-index'] };
+  return {
+    ran: true,
+    backup: backupPath,
+    steps: ['migrate', 'rewrite-refs', 'rewrite-manifests', 'reconcile', 'build-index'],
+  };
 }
 
 module.exports = { shouldMigrate, runFsMigration, hasLegacyLayout };

package/install/lib/platforms/codex.js

@@ -63,7 +63,7 @@ async function generatePrompt(promptsDir, agentName, config) {
 You must fully embody this agent's persona and follow all activation instructions exactly as specified.
 
 <agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from {project-root}/_bmad/*/agents/${agentName}.md
+1. LOAD the FULL agent file from {project-root}/_byan/agent/${agentName}/${agentName}.md (new layout); if absent, {project-root}/_byan/*/agents/${agentName}.md (legacy layout)
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
 3. FOLLOW every step in the <activation> section precisely
 4. DISPLAY the welcome/greeting as instructed

package/install/lib/platforms/copilot-cli.js

@@ -94,7 +94,7 @@ ${yamlUtils.dump(frontmatter).trim()}
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
 
 <agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from {project-root}/_bmad/*/agents/${agentName}.md
+1. LOAD the FULL agent file from {project-root}/_byan/agent/${agentName}/${agentName}.md (new layout); if absent, {project-root}/_byan/*/agents/${agentName}.md (legacy layout)
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
 3. FOLLOW every step in the <activation> section precisely
 4. DISPLAY the welcome/greeting as instructed

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "BYAN v2.2.2 - Intelligent AI agent installer with multi-platform native support (GitHub Copilot CLI, Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"

package/install/src/webui/api.js

@@ -21,6 +21,7 @@ try { GistClient = require('../../lib/exchange/gist-client'); } catch { GistClie
 
 const fs = require('fs');
 const path = require('path');
+const layoutResolver = require('../../../src/byan-v2/lib/layout-resolver');
 
 const { createBridge } = require('./chat/bridge');
 const { detectCLIs, detectAgents } = require('./chat/cli-detector');
@@ -63,8 +64,19 @@ function readPackageVersion() {
   }
 }
 
+// The current platform install lives under _byan/. _bmad/ is the dead Gen1
+// marker, tolerated only so a legacy checkout is still recognized as installed.
+function installRoot(projectRoot) {
+  const byan = path.join(projectRoot, '_byan');
+  if (fs.existsSync(byan)) return byan;
+  const bmad = path.join(projectRoot, '_bmad');
+  if (fs.existsSync(bmad)) return bmad;
+  return byan;
+}
+
 function isByanInstalled(projectRoot) {
-  return fs.existsSync(path.join(projectRoot, '_bmad'));
+  return fs.existsSync(path.join(projectRoot, '_byan')) ||
+         fs.existsSync(path.join(projectRoot, '_bmad'));
 }
 
 function detectPlatforms(projectRoot) {
@@ -227,7 +239,7 @@ const routes = {
     }
 
     try {
-      const targetPath = path.join(server.projectRoot, '_bmad');
+      const targetPath = installRoot(server.projectRoot);
       await backuper.restore(backupPath, targetPath);
       json(res, 200, { success: true, message: 'Rollback complete' });
     } catch (err) {
@@ -687,18 +699,22 @@ function sleep(ms) {
   return new Promise(r => setTimeout(r, ms));
 }
 
+// Safety-net skeleton created after yanstaller runs. It mirrors yanstaller's
+// Gen2 output (_byan/), so it must stay Gen2 here — emitting Gen3 would create
+// a mixed install the FS migrator does not expect. When the platform cuts over
+// to Gen3 (templates + yanstaller), this skeleton follows.
 function ensureDirectoryStructure(projectRoot) {
   const dirs = [
-    '_bmad',
-    '_bmad/_config',
-    '_bmad/_memory',
-    '_bmad/core',
-    '_bmad/core/agents',
-    '_bmad/core/workflows',
-    '_bmad/core/tasks',
-    '_bmad-output',
-    '_bmad-output/planning-artifacts',
-    '_bmad-output/implementation-artifacts'
+    '_byan',
+    '_byan/_config',
+    '_byan/_memory',
+    '_byan/core',
+    '_byan/core/agents',
+    '_byan/core/workflows',
+    '_byan/core/tasks',
+    '_byan-output',
+    '_byan-output/planning-artifacts',
+    '_byan-output/implementation-artifacts'
   ];
 
   for (const dir of dirs) {
@@ -710,16 +726,21 @@ function ensureDirectoryStructure(projectRoot) {
 }
 
 function writeBaseConfig(projectRoot, config) {
-  const configPath = path.join(projectRoot, '_bmad', 'core', 'config.yaml');
-  if (fs.existsSync(configPath)) return;
+  // Only scaffold a minimal config when the platform has NONE. resolveConfig
+  // also matches _byan/bmb/config.yaml (the authoritative installed config
+  // carrying byan_version + installed_agents); writing a root _byan/config.yaml
+  // over it would shadow it in the resolver chain and break version detection.
+  if (layoutResolver.resolveConfig({ projectRoot })) return;
 
+  const configPath = path.join(projectRoot, '_byan', 'config.yaml');
   const content = [
     `user_name: ${config.userName || 'User'}`,
     `communication_language: ${config.language || 'English'}`,
     `document_output_language: ${config.language || 'English'}`,
-    `output_folder: "{project-root}/_bmad-output"`
+    `output_folder: "{project-root}/_byan-output"`
   ].join('\n') + '\n';
 
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, content, 'utf8');
 }
 
@@ -831,4 +852,12 @@ function sanitizeUploadFilename(name) {
   return String(name).replace(/[^a-zA-Z0-9_.\-]/g, '').substring(0, 200);
 }
 
-module.exports = { resolve, routes };
+module.exports = {
+  resolve,
+  routes,
+  // Exposed for unit tests (layout-aware install helpers).
+  isByanInstalled,
+  installRoot,
+  ensureDirectoryStructure,
+  writeBaseConfig
+};