@cleocode/core 2026.3.47 → 2026.3.49

package/dist/init.d.ts

@@ -16,7 +16,7 @@
  *   9. Core skill installation via CAAMP
  *  10. NEXUS project registration
  *  11. Project type detection (--detect)
- *  12. Injection refresh (--update-docs)
+ *  12. Injection refresh
  *  13. Git hook installation (commit-msg, pre-commit)
  *  14. GitHub issue/PR templates (.github/ directory)
  *
@@ -39,8 +39,6 @@ export interface InitOptions {
     force?: boolean;
     /** Auto-detect project configuration. */
     detect?: boolean;
-    /** Update agent documentation injections only. */
-    updateDocs?: boolean;
     /** Run codebase analysis and store findings to brain.db. */
     mapCodebase?: boolean;
 }

package/dist/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA8BH,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAaD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8D9F;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FzF;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAID;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAwBtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgS7E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAiB/F;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBnF"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AA8BH,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAaD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqE9F;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+FzF;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAiDf;AAID;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAwBtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA2R7E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAiB/F;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAyBnF"}

package/dist/project-info.d.ts

@@ -32,4 +32,9 @@ export declare function getProjectInfo(cwd?: string): Promise<ProjectInfo>;
  * Returns null if the file is missing or unparseable.
  */
 export declare function getProjectInfoSync(cwd?: string): ProjectInfo | null;
+/**
+ * Update the project name in project-info.json.
+ * Used by `cleo upgrade --name` and programmatic consumers.
+ */
+export declare function updateProjectName(cwd: string, name: string): void;
 //# sourceMappingURL=project-info.d.ts.map

package/dist/project-info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-info.d.ts","sourceRoot":"","sources":["../src/project-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqBvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA2BnE"}
+{"version":3,"file":"project-info.d.ts","sourceRoot":"","sources":["../src/project-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqBvE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CA2BnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASjE"}

package/dist/upgrade.d.ts

@@ -48,12 +48,18 @@ export interface UpgradeResult {
  * @param options.dryRun  Preview changes without applying
  * @param options.includeGlobal  Also check global ~/.cleo
  * @param options.autoMigrate  Auto-migrate storage if needed (default: true)
+ * @param options.forceDetect  Force re-detection of project type (ignore staleness)
+ * @param options.mapCodebase  Run full codebase analysis and store to brain.db
+ * @param options.projectName  Update project name in project-info and nexus
  * @param options.cwd  Project directory override
  */
 export declare function runUpgrade(options?: {
     dryRun?: boolean;
     includeGlobal?: boolean;
     autoMigrate?: boolean;
+    forceDetect?: boolean;
+    mapCodebase?: boolean;
+    projectName?: string;
     cwd?: string;
 }): Promise<UpgradeResult>;
 //# sourceMappingURL=upgrade.d.ts.map

package/dist/upgrade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoCH,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2BAA2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/F,OAAO,CAAC,aAAa,CAAC,CA41BxB"}
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoCH,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,2BAA2B;AAC3B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,gBAAgB,EAAE,MAAM,CAAC;QACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAC9B,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GACL,OAAO,CAAC,aAAa,CAAC,CAg4BxB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.3.47",
+  "version": "2026.3.49",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,10 +36,10 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.3.47",
-    "@cleocode/contracts": "2026.3.47",
-    "@cleocode/skills": "2026.3.47",
-    "@cleocode/agents": "2026.3.47"
+    "@cleocode/contracts": "2026.3.49",
+    "@cleocode/adapters": "2026.3.49",
+    "@cleocode/agents": "2026.3.49",
+    "@cleocode/skills": "2026.3.49"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/__tests__/injection-chain.test.ts

@@ -257,8 +257,9 @@ describe('E2E: injection chain validation (T4694)', () => {
     expect(existsSync(join(testDir, 'CLAUDE.md'))).toBe(true);
     expect(existsSync(join(testDir, 'AGENTS.md'))).toBe(true);
 
-    // Run updateDocs mode
-    const result = await initProject({ updateDocs: true });
+    // Run updateDocs directly (no longer available via initProject flag — use upgrade path)
+    const { updateDocs } = await import('../init.js');
+    const result = await updateDocs();
     expect(result.updateDocsOnly).toBe(true);
     expect(result.initialized).toBe(true);
   });

package/src/bootstrap.ts

@@ -53,6 +53,14 @@ export async function bootstrapGlobalCleo(options?: BootstrapOptions): Promise<B
     isDryRun: options?.dryRun ?? false,
   };
 
+  // Step 0: Ensure global home structure and clean stale artifacts
+  try {
+    const { ensureGlobalHome } = await import('./scaffold.js');
+    await ensureGlobalHome();
+  } catch {
+    // Best-effort — don't fail bootstrap if cleanup fails
+  }
+
   // Step 1: Ensure global templates
   await ensureGlobalTemplatesBootstrap(ctx, options?.packageRoot);
 
@@ -135,19 +143,20 @@ async function injectAgentsHub(ctx: BootstrapContext): Promise<void> {
     if (!ctx.isDryRun) {
       await mkdir(globalAgentsDir, { recursive: true });
 
-      // Strip any legacy CLEO blocks first (handles bare and versioned markers)
+      // Consolidate: strip ALL legacy CLEO blocks AND duplicate CAAMP blocks,
+      // then inject a single clean block. CAAMP 1.8.0 idempotency doesn't
+      // consolidate pre-existing duplicates — it only prevents new ones.
       if (existsSync(globalAgentsMd)) {
         const content = await readFile(globalAgentsMd, 'utf8');
-        const stripped = content.replace(
-          /\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g,
-          '',
-        );
-        if (stripped !== content) {
-          await writeFile(globalAgentsMd, stripped, 'utf8');
-        }
+        const stripped = content
+          .replace(/\n?<!-- CLEO:START[^>]*-->[\s\S]*?<!-- CLEO:END -->\n?/g, '')
+          .replace(/\n?<!-- CAAMP:START -->[\s\S]*?<!-- CAAMP:END -->\n?/g, '')
+          .trim();
+        // Write clean file (empty or user content only)
+        await writeFile(globalAgentsMd, stripped ? `${stripped}\n` : '', 'utf8');
       }
 
-      // Direct call — CAAMP 1.8.0 handles idempotency
+      // Single inject call on a clean file — no duplicates possible
       const expectedContent = '@~/.cleo/templates/CLEO-INJECTION.md';
       const action = await inject(globalAgentsMd, expectedContent);
       ctx.created.push(`~/.agents/AGENTS.md (${action})`);

package/src/init.ts

@@ -16,7 +16,7 @@
  *   9. Core skill installation via CAAMP
  *  10. NEXUS project registration
  *  11. Project type detection (--detect)
- *  12. Injection refresh (--update-docs)
+ *  12. Injection refresh
  *  13. Git hook installation (commit-msg, pre-commit)
  *  14. GitHub issue/PR templates (.github/ directory)
  *
@@ -68,8 +68,6 @@ export interface InitOptions {
   force?: boolean;
   /** Auto-detect project configuration. */
   detect?: boolean;
-  /** Update agent documentation injections only. */
-  updateDocs?: boolean;
   /** Run codebase analysis and store findings to brain.db. */
   mapCodebase?: boolean;
 }
@@ -132,12 +130,19 @@ export async function initAgentDefinition(created: string[], warnings: string[])
   await mkdir(dirname(globalAgentsDir), { recursive: true });
 
   try {
-    // Check if symlink already exists
+    // Check if symlink already exists and points to correct target
     try {
       const stat = await lstat(globalAgentsDir);
-      if (stat.isSymbolicLink() || stat.isDirectory()) {
-        // Already installed
-        return;
+      if (stat.isSymbolicLink()) {
+        const { readlink } = await import('node:fs/promises');
+        const currentTarget = await readlink(globalAgentsDir);
+        if (currentTarget === agentSourceDir) {
+          return; // Symlink intact and pointing to correct location
+        }
+        // Stale symlink — remove and recreate
+        await unlink(globalAgentsDir);
+      } else if (stat.isDirectory()) {
+        return; // Copied dir, leave as-is
       }
     } catch {
       // Doesn't exist, proceed to create
@@ -472,11 +477,6 @@ export async function updateDocs(): Promise<InitResult> {
  * @task T4707
  */
 export async function initProject(opts: InitOptions = {}): Promise<InitResult> {
-  // Handle --update-docs (T4686)
-  if (opts.updateDocs) {
-    return updateDocs();
-  }
-
   const cleoDir = getCleoDirAbsolute();
   const projRoot = getProjectRoot();
 

package/src/injection.ts

@@ -281,7 +281,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
       status: 'warning',
       message: 'AGENTS.md not found in project root',
       details: { path: agentsMdPath, exists: false },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -311,7 +311,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
       status: 'warning',
       message: 'AGENTS.md exists but has no CAAMP markers',
       details: { path: agentsMdPath, hasCaampMarker: false },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -323,7 +323,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
       status: 'warning',
       message: `CAAMP markers unbalanced: ${startCount} START vs ${endCount} END`,
       details: { path: agentsMdPath, startCount, endCount },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -352,7 +352,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
         status: 'warning',
         message: `Missing @ reference targets: ${missing.join(', ')}`,
         details: { path: agentsMdPath, missing, totalRefs: refs.length },
-        fix: 'cleo init --update-docs',
+        fix: 'cleo upgrade',
       };
     }
   }
@@ -372,7 +372,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
           status: 'warning',
           message: `CLAUDE.md CAAMP markers unbalanced: ${cStartCount} START vs ${cEndCount} END`,
           details: { file: 'CLAUDE.md', startCount: cStartCount, endCount: cEndCount },
-          fix: 'cleo init --update-docs',
+          fix: 'cleo upgrade',
         };
       }
 
@@ -383,7 +383,7 @@ export function checkInjection(projectRoot: string): InjectionCheckResult {
           status: 'warning',
           message: 'CLAUDE.md has no CAAMP markers',
           details: { file: 'CLAUDE.md', hasCaampMarker: false },
-          fix: 'cleo init --update-docs',
+          fix: 'cleo upgrade',
         };
       }
     } catch {

package/src/project-info.ts

@@ -8,7 +8,7 @@
  * @task T5333
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getCleoDirAbsolute } from './paths.js';
@@ -92,3 +92,18 @@ export function getProjectInfoSync(cwd?: string): ProjectInfo | null {
     return null;
   }
 }
+
+/**
+ * Update the project name in project-info.json.
+ * Used by `cleo upgrade --name` and programmatic consumers.
+ */
+export function updateProjectName(cwd: string, name: string): void {
+  const cleoDir = getCleoDirAbsolute(cwd);
+  const infoPath = join(cleoDir, 'project-info.json');
+  if (!existsSync(infoPath)) return;
+
+  const data = JSON.parse(readFileSync(infoPath, 'utf-8')) as Record<string, string>;
+  data.projectName = name;
+  data.lastUpdated = new Date().toISOString();
+  writeFileSync(infoPath, `${JSON.stringify(data, null, 2)}\n`);
+}

package/src/upgrade.ts

@@ -85,10 +85,21 @@ export interface UpgradeResult {
  * @param options.dryRun  Preview changes without applying
  * @param options.includeGlobal  Also check global ~/.cleo
  * @param options.autoMigrate  Auto-migrate storage if needed (default: true)
+ * @param options.forceDetect  Force re-detection of project type (ignore staleness)
+ * @param options.mapCodebase  Run full codebase analysis and store to brain.db
+ * @param options.projectName  Update project name in project-info and nexus
  * @param options.cwd  Project directory override
  */
 export async function runUpgrade(
-  options: { dryRun?: boolean; includeGlobal?: boolean; autoMigrate?: boolean; cwd?: string } = {},
+  options: {
+    dryRun?: boolean;
+    includeGlobal?: boolean;
+    autoMigrate?: boolean;
+    forceDetect?: boolean;
+    mapCodebase?: boolean;
+    projectName?: string;
+    cwd?: string;
+  } = {},
 ): Promise<UpgradeResult> {
   const isDryRun = options.dryRun ?? false;
   const autoMigrate = options.autoMigrate ?? true;
@@ -635,7 +646,9 @@ export async function runUpgrade(
         }
       }
     } else {
-      const contextResult = await ensureProjectContext(projectRootForContext, { staleDays: 30 });
+      const contextResult = await ensureProjectContext(projectRootForContext, {
+        staleDays: options.forceDetect ? 0 : 30,
+      });
       actions.push({
         action: 'project_context_detection',
         status: contextResult.action === 'skipped' ? 'skipped' : 'applied',
@@ -886,6 +899,40 @@ export async function runUpgrade(
       /* best-effort */
     }
 
+    // Run codebase mapping if requested (delegates to core mapCodebase)
+    if (options.mapCodebase) {
+      try {
+        const { mapCodebase } = await import('./codebase-map/index.js');
+        const mapResult = await mapCodebase(projectRootForMaint, { storeToBrain: true });
+        actions.push({
+          action: 'codebase_map',
+          status: 'applied',
+          details: `Analyzed: ${mapResult.stack?.languages?.length ?? 0} languages, ${mapResult.concerns?.todos?.length ?? 0} TODOs found`,
+        });
+      } catch (err) {
+        actions.push({
+          action: 'codebase_map',
+          status: 'error',
+          details: `Codebase mapping failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    }
+
+    // Update project name if requested (delegates to core updateProjectName)
+    if (options.projectName) {
+      try {
+        const { updateProjectName } = await import('./project-info.js');
+        await updateProjectName(projectRootForMaint, options.projectName);
+        actions.push({
+          action: 'project_name_update',
+          status: 'applied',
+          details: `Project name set to "${options.projectName}"`,
+        });
+      } catch {
+        /* best-effort */
+      }
+    }
+
     // GitHub issue/PR templates — install missing ones, warn if absent
     try {
       const { existsSync: fsExistsSync } = await import('node:fs');

package/src/validation/doctor/checks.ts

@@ -211,7 +211,7 @@ export function checkAgentsMdHub(projectRoot?: string): CheckResult {
       status: 'warning',
       message: 'AGENTS.md not found in project root',
       details: { path: agentsMdPath, exists: false },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -236,7 +236,7 @@ export function checkAgentsMdHub(projectRoot?: string): CheckResult {
       status: 'warning',
       message: 'AGENTS.md exists but has no CAAMP:START marker',
       details: { path: agentsMdPath, hasCaampMarker: false },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -709,7 +709,7 @@ export function checkCaampMarkerIntegrity(projectRoot?: string): CheckResult {
       status: 'warning',
       message: `CAAMP marker issues: ${issues.join('; ')}`,
       details: { issues },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }
 
@@ -797,7 +797,7 @@ export function checkAtReferenceTargetExists(projectRoot?: string): CheckResult
       status: 'warning',
       message: `Missing @ reference targets: ${missing.join(', ')}`,
       details: { missing, totalRefs: refs.length },
-      fix: 'cleo init --update-docs',
+      fix: 'cleo upgrade',
     };
   }