@ornexus/neocortex 4.0.1

package/packages/client/dist/agent/refresh-stubs.js

@@ -0,0 +1,234 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Stub Refresh Module
+ *
+ * Detects version mismatch between installed stubs and CLI version.
+ * Re-copies full stub files from the package when outdated.
+ *
+ * Called by activate.ts BEFORE updateAgentDescription() to ensure
+ * the stub file has all current sections (Banner, Plugin Guard, etc.)
+ * before the regex patcher runs.
+ *
+ * Never throws -- stub refresh is non-critical.
+ *
+ * Story 55.1
+ */
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { setSecureFilePermissions } from '../config/secure-config.js';
+// -- Banner Frame Constants ---------------------------------------------------
+const BANNER_INNER = 60;
+const BANNER_PREFIX_INNER = 25;
+// -- Version Patching ---------------------------------------------------------
+/**
+ * Replace all version strings in a stub file with the given version.
+ * Handles 4 patterns:
+ *   1. Emoji description: 🧠 Neocortex vX.Y.Z
+ *   2. Plain markdown header: # Neocortex vX.Y.Z
+ *   3. Banner line: │      ###  ########      vX.Y.Z ...│
+ *   4. YAML version field: version: 'X.Y.Z'
+ *
+ * Never throws -- version patching is best-effort.
+ * Story 71.2
+ */
+export function patchVersionInFile(filePath, version) {
+    try {
+        let content = readFileSync(filePath, 'utf-8');
+        const original = content;
+        // Pattern 1: Emoji description/header (🧠 Neocortex vX.Y.Z)
+        content = content.replace(/🧠 Neocortex v[\d.]+/g, `🧠 Neocortex v${version}`);
+        // Pattern 2: Plain markdown header (# Neocortex vX.Y.Z)
+        content = content.replace(/# Neocortex v[\d.]+/g, `# Neocortex v${version}`);
+        // Pattern 3: Banner version line (│      ###  ########      vX.Y.Z ...│)
+        content = content.replace(/^(│      ###  ########      v)[\d.]+(\s*│)$/gm, () => {
+            const ver = `v${version}`;
+            const pad = BANNER_INNER - BANNER_PREFIX_INNER - ver.length;
+            return `\u2502      ###  ########      ${ver}${' '.repeat(Math.max(0, pad))}\u2502`;
+        });
+        // Pattern 4: YAML version field (version: 'X.Y.Z')
+        content = content.replace(/version: '[\d.]+'/g, `version: '${version}'`);
+        if (content !== original) {
+            writeFileSync(filePath, content, 'utf-8');
+        }
+    }
+    catch {
+        // Non-critical -- version patching is best-effort
+    }
+}
+const STUB_TARGETS = [
+    {
+        destDir: join(homedir(), '.claude', 'agents', 'neocortex'),
+        sourceDir: 'claude-code',
+        files: ['neocortex.md', 'neocortex.agent.yaml'],
+    },
+    {
+        destDir: join(homedir(), '.gemini', 'agents'),
+        sourceDir: 'gemini-cli',
+        files: ['agent.md'],
+    },
+    {
+        destDir: join(homedir(), '.cursor', 'agents'),
+        sourceDir: 'cursor',
+        files: ['agent.md'],
+    },
+    {
+        destDir: join(homedir(), '.codex'),
+        sourceDir: 'codex',
+        files: ['agents.md'],
+    },
+    {
+        destDir: join(homedir(), '.vscode'),
+        sourceDir: 'vscode',
+        files: ['agent.md'],
+    },
+    {
+        destDir: join(homedir(), '.agent', 'skills', 'neocortex'),
+        sourceDir: 'antigravity',
+        files: ['skill/SKILL.md'],
+    },
+];
+// -- Package Root Resolution --------------------------------------------------
+/**
+ * Find the monorepo / npm package root by walking up from this file's location.
+ * Looks for a package.json with name '@ornexus/neocortex' (monorepo root) or
+ * '@neocortex/client' (client package root that contains targets-stubs after build).
+ *
+ * Returns null if not found within 10 levels.
+ */
+export function findPackageRoot() {
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        let dir = dirname(thisFile);
+        for (let i = 0; i < 10; i++) {
+            try {
+                const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+                if (pkg.name === '@ornexus/neocortex') {
+                    return dir;
+                }
+            }
+            catch { /* no package.json at this level */ }
+            dir = dirname(dir);
+        }
+    }
+    catch { /* fallback */ }
+    return null;
+}
+// -- Version Comparison -------------------------------------------------------
+/**
+ * Read the installed version from .version file in the dest directory.
+ * Returns null if file doesn't exist or is unreadable.
+ */
+function readInstalledVersion(destDir) {
+    try {
+        const versionFile = join(destDir, '.version');
+        if (existsSync(versionFile)) {
+            return readFileSync(versionFile, 'utf-8').trim() || null;
+        }
+    }
+    catch { /* unreadable */ }
+    return null;
+}
+/**
+ * Refresh installed stubs if CLI version differs from installed version.
+ *
+ * For each stub target:
+ *   1. Read .version from install dir
+ *   2. Compare with cliVersion
+ *   3. If different (or .version missing): re-copy all stub files + write .version
+ *   4. If same: skip (no-op)
+ *
+ * When options.forceCreate is true, creates destDir if it doesn't exist.
+ * When options.targetFilter is set, only processes matching target.
+ *
+ * Never throws -- stub refresh is non-critical.
+ * Returns the number of targets that were refreshed.
+ */
+export function refreshStubs(cliVersion, options) {
+    try {
+        const forceCreate = options?.forceCreate ?? false;
+        const targetFilter = options?.targetFilter;
+        const packageRoot = findPackageRoot();
+        if (!packageRoot) {
+            return 0;
+        }
+        // targets-stubs/ is at the package root level
+        const stubsRoot = join(packageRoot, 'targets-stubs');
+        if (!existsSync(stubsRoot)) {
+            return 0;
+        }
+        let refreshed = 0;
+        for (const target of STUB_TARGETS) {
+            try {
+                // If targetFilter is set, skip non-matching targets
+                if (targetFilter && target.sourceDir !== targetFilter) {
+                    continue;
+                }
+                // Epic 67 - Story 67.3: If forceCreate, create destDir when it doesn't exist
+                if (!existsSync(target.destDir)) {
+                    if (forceCreate) {
+                        mkdirSync(target.destDir, { recursive: true });
+                    }
+                    else {
+                        continue;
+                    }
+                }
+                const installedVersion = readInstalledVersion(target.destDir);
+                if (installedVersion === cliVersion) {
+                    continue; // Already up to date
+                }
+                // Source directory for this target
+                const sourceDir = join(stubsRoot, target.sourceDir);
+                if (!existsSync(sourceDir)) {
+                    continue;
+                }
+                // Copy each file
+                let copiedAny = false;
+                for (const file of target.files) {
+                    const src = join(sourceDir, file);
+                    const dest = join(target.destDir, file);
+                    if (existsSync(src)) {
+                        // Ensure parent directory exists (handles nested paths like skill/SKILL.md)
+                        mkdirSync(dirname(dest), { recursive: true });
+                        copyFileSync(src, dest);
+                        // Story 71.2: Substitute version strings in copied stubs
+                        if (file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml')) {
+                            patchVersionInFile(dest, cliVersion);
+                        }
+                        // Story 66.3 AC1: Apply ACL/chmod after copy (runs after patchVersionInFile rewrite)
+                        setSecureFilePermissions(dest);
+                        copiedAny = true;
+                    }
+                }
+                // Write .version file
+                if (copiedAny) {
+                    const versionPath = join(target.destDir, '.version');
+                    writeFileSync(versionPath, cliVersion + '\n', 'utf-8');
+                    // Story 66.3 AC2: Apply ACL/chmod on .version file
+                    setSecureFilePermissions(versionPath);
+                    refreshed++;
+                }
+            }
+            catch {
+                // Non-critical -- continue with next target
+            }
+        }
+        return refreshed;
+    }
+    catch {
+        // Non-critical -- entire function is best-effort
+        return 0;
+    }
+}

package/packages/client/dist/agent/update-agent-yaml.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Update agent.yaml files across all known locations.
+ * Returns count of files updated.
+ *
+ * Never throws.
+ */
+export declare function updateAgentYaml(version: string, tier?: string): number;
+/**
+ * Update agent.yaml at a specific file path (used for testing).
+ * Returns true if the file was modified.
+ *
+ * Never throws.
+ */
+export declare function updateAgentYamlAt(filePath: string, version: string, tier?: string): boolean;

package/packages/client/dist/agent/update-agent-yaml.js

@@ -0,0 +1,102 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Agent YAML Updater
+ *
+ * Patches neocortex.agent.yaml with current version and tier-based title.
+ *
+ * Patches TWO fields:
+ *   1. version: 'X.X.X'
+ *   2. title: 'Development Orchestrator (Tier)'
+ *
+ * Called after:
+ *   - refreshStubs() (ensures YAML exists with current structure)
+ *   - updateAgentDescription() (ensures consistency across all surfaces)
+ *
+ * Never throws -- YAML update is non-critical.
+ *
+ * Story 55.2
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// -- Constants ----------------------------------------------------------------
+const TIER_LABELS = {
+    free: 'Free',
+    pro: 'Pro',
+    enterprise: 'Enterprise',
+};
+// Regex patterns for YAML fields (simple key: 'value' format)
+const VERSION_PATTERN = /^(\s*version:\s*)'[^']*'/m;
+const TITLE_PATTERN = /^(\s*title:\s*)'[^']*'/m;
+const HOME_YAML_FILES = [
+    join(homedir(), '.claude', 'agents', 'neocortex', 'neocortex.agent.yaml'),
+];
+// -- Internal -----------------------------------------------------------------
+/**
+ * Patch a single agent.yaml file with version and tier.
+ * Returns true if file was modified.
+ */
+function patchYamlFile(filePath, version, tier) {
+    try {
+        if (!existsSync(filePath)) {
+            return false;
+        }
+        let content = readFileSync(filePath, 'utf-8');
+        const original = content;
+        const label = TIER_LABELS[tier.toLowerCase()] ?? 'Free';
+        // Patch version
+        if (VERSION_PATTERN.test(content)) {
+            content = content.replace(VERSION_PATTERN, `$1'${version}'`);
+        }
+        // Patch title
+        if (TITLE_PATTERN.test(content)) {
+            content = content.replace(TITLE_PATTERN, `$1'Development Orchestrator (${label})'`);
+        }
+        if (content === original) {
+            return false;
+        }
+        writeFileSync(filePath, content, 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// -- Public API ---------------------------------------------------------------
+/**
+ * Update agent.yaml files across all known locations.
+ * Returns count of files updated.
+ *
+ * Never throws.
+ */
+export function updateAgentYaml(version, tier) {
+    const resolvedTier = tier ?? 'free';
+    let updated = 0;
+    // Home-level files
+    for (const filePath of HOME_YAML_FILES) {
+        if (patchYamlFile(filePath, version, resolvedTier)) {
+            updated++;
+        }
+    }
+    return updated;
+}
+/**
+ * Update agent.yaml at a specific file path (used for testing).
+ * Returns true if the file was modified.
+ *
+ * Never throws.
+ */
+export function updateAgentYamlAt(filePath, version, tier) {
+    return patchYamlFile(filePath, version, tier ?? 'free');
+}

package/packages/client/dist/agent/update-description.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Build the banner version line with correct padding.
+ */
+export declare function buildBannerVersionLine(version: string): string;
+/**
+ * Build the banner tier line with correct padding.
+ */
+export declare function buildBannerTierLine(tier: string): string;
+/**
+ * Build the dynamic description string (without quotes/prefix).
+ */
+export declare function buildDescription(version: string, tier: string): string;
+/**
+ * Read the current tier from ~/.neocortex/config.json.
+ * Returns 'free' if config doesn't exist or tier is missing.
+ */
+export declare function readTierFromConfig(): string;
+/**
+ * Update agent descriptions across ALL known platform files:
+ *   1. Home-level files (Claude Code, Gemini CLI)
+ *   2. Project-level files (Cursor, VSCode, Codex, Antigravity) -- discovered via git root
+ *
+ * Never throws -- description update is non-critical.
+ * Returns count of files updated.
+ */
+export declare function updateAgentDescription(version: string, tier?: string): number;
+/**
+ * Update agent description for a specific file path (used by install scripts
+ * for project-level files where paths are dynamic).
+ *
+ * Never throws -- description update is non-critical.
+ */
+export declare function updateAgentDescriptionAt(filePath: string, type: 'yaml' | 'h1', version: string, tier?: string): boolean;

package/packages/client/dist/agent/update-description.js

@@ -0,0 +1,251 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Agent Description Updater (Multi-Platform)
+ *
+ * Updates the installed agent description across ALL supported platforms
+ * with dynamic values: version, tier, and branding.
+ *
+ * Patches THREE surfaces per file (when present):
+ *   1. YAML frontmatter `description: "..."` or Markdown H1 `# ...`
+ *   2. ASCII banner version line:  `│      ###  ########      vX.X.X ...│`
+ *   3. ASCII banner tier line:     `│ ##   ###  ######  ##    OrNexus Team (Tier) ...│`
+ *
+ * Supported platforms (home-level):
+ *   - Claude Code:  ~/.claude/agents/neocortex/neocortex.md  (YAML frontmatter)
+ *   - Gemini CLI:   ~/.gemini/agents/agent.md                (YAML frontmatter)
+ *
+ * Supported platforms (project-level, discovered via git root):
+ *   - Cursor:       <root>/.cursor/agents/neocortex.md       (YAML frontmatter)
+ *   - VSCode:       <root>/.github/agents/neocortex.md       (YAML frontmatter)
+ *   - Codex:        <root>/AGENTS.md                         (Markdown H1)
+ *   - Antigravity:  <root>/.agent/skills/neocortex/SKILL.md  (YAML frontmatter)
+ *
+ * Called after:
+ *   - License activation (activate.ts)
+ *   - Install (install.sh via sed fallback for all platforms)
+ *
+ * Format: 🧠 Neocortex vX.X.X (Tier) | OrNexus Team
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// ── Constants ─────────────────────────────────────────────────────────────
+const CONFIG_FILE = join(homedir(), '.neocortex', 'config.json');
+const TIER_LABELS = {
+    free: 'Free',
+    pro: 'Pro',
+    enterprise: 'Enterprise',
+};
+/**
+ * Banner frame geometry.
+ * Frame is 62 chars wide: │ + 60 inner chars + │
+ * Both dynamic lines have a 25-char inner prefix (after the leading │).
+ */
+const BANNER_INNER_WIDTH = 60;
+const BANNER_PREFIX_INNER = 25; // chars after leading │, before dynamic content
+// YAML frontmatter: description: "..."
+const YAML_DESCRIPTION_PATTERN = /^description:\s*".*"$/m;
+// Markdown H1: # 🧠 Neocortex vX.X.X (Tier) | OrNexus Team
+// Also matches legacy format: # 🧠 Neocortex vX.X.X - Development Orchestrator | OrNexus Team (Tier)
+const H1_DESCRIPTION_PATTERN = /^# 🧠 Neocortex v[\d.]+(?:\s*\([^)]+\)\s*\| OrNexus Team|\s*-\s*Development Orchestrator \| OrNexus Team \([^)]+\))$/m;
+// Banner version line: │      ###  ########      vX.X.X<spaces>│
+const BANNER_VERSION_PATTERN = /^│      ###  ########      v[\d.]+\s*│$/m;
+// Banner tier line: │ ##   ###  ######  ##    OrNexus Team (<Tier>)<spaces>│
+const BANNER_TIER_PATTERN = /^│ ##   ###  ######  ##    OrNexus Team \([^)]*\)\s*│$/m;
+/**
+ * All known home-directory agent files, grouped by description format.
+ */
+const HOME_AGENT_FILES = [
+    // Claude Code (home-level)
+    { path: join(homedir(), '.claude', 'agents', 'neocortex', 'neocortex.md'), type: 'yaml' },
+    // Gemini CLI (home-level)
+    { path: join(homedir(), '.gemini', 'agents', 'agent.md'), type: 'yaml' },
+];
+/**
+ * Known project-level agent file paths (relative to project root).
+ * These are patched after license activation so the tier reflects reality.
+ */
+const PROJECT_AGENT_FILES = [
+    // Cursor
+    { relativePath: join('.cursor', 'agents', 'neocortex.md'), type: 'yaml' },
+    // VSCode / GitHub Copilot
+    { relativePath: join('.github', 'agents', 'neocortex.md'), type: 'yaml' },
+    // Codex
+    { relativePath: 'AGENTS.md', type: 'h1' },
+    // Antigravity
+    { relativePath: join('.agent', 'skills', 'neocortex', 'SKILL.md'), type: 'yaml' },
+];
+// ── Project Root Discovery ────────────────────────────────────────────────
+/**
+ * Discover the git project root, or null if not in a git repo.
+ * Never throws -- returns null on any failure.
+ */
+function discoverProjectRoot() {
+    try {
+        const root = execSync('git rev-parse --show-toplevel', {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Banner Helpers ────────────────────────────────────────────────────────
+/**
+ * Build a right-padded banner line.
+ * Prefix is the fixed art portion INCLUDING the leading │ (26 chars).
+ * Content is the dynamic text. Padding fills to inner width, then closing │.
+ *
+ * Total: │(1) + prefixInner(25) + content + pad + │(1) = 62 chars.
+ */
+function buildBannerLine(prefix, content) {
+    const padLen = BANNER_INNER_WIDTH - BANNER_PREFIX_INNER - content.length;
+    const padding = padLen > 0 ? ' '.repeat(padLen) : '';
+    return `${prefix}${content}${padding}\u2502`; // \u2502 = │
+}
+/**
+ * Build the banner version line with correct padding.
+ */
+export function buildBannerVersionLine(version) {
+    return buildBannerLine('\u2502      ###  ########      ', `v${version}`);
+}
+/**
+ * Build the banner tier line with correct padding.
+ */
+export function buildBannerTierLine(tier) {
+    const label = TIER_LABELS[tier.toLowerCase()] ?? 'Free';
+    return buildBannerLine('\u2502 ##   ###  ######  ##    ', `OrNexus Team (${label})`);
+}
+// ── Public API ────────────────────────────────────────────────────────────
+/**
+ * Build the dynamic description string (without quotes/prefix).
+ */
+export function buildDescription(version, tier) {
+    const label = TIER_LABELS[tier.toLowerCase()] ?? 'Free';
+    return `\u{1F9E0} Neocortex v${version} (${label}) | OrNexus Team`;
+}
+/**
+ * Read the current tier from ~/.neocortex/config.json.
+ * Returns 'free' if config doesn't exist or tier is missing.
+ */
+export function readTierFromConfig() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const raw = readFileSync(CONFIG_FILE, 'utf-8');
+            const config = JSON.parse(raw);
+            return config.tier ?? 'free';
+        }
+    }
+    catch {
+        // Config missing or corrupted
+    }
+    return 'free';
+}
+/**
+ * Patch ASCII banner lines (version + tier) in file content.
+ * Returns the patched content, or the original if no banner found.
+ */
+function patchBannerLines(content, version, tier) {
+    let patched = content;
+    // Patch version line
+    if (BANNER_VERSION_PATTERN.test(patched)) {
+        patched = patched.replace(BANNER_VERSION_PATTERN, buildBannerVersionLine(version));
+    }
+    // Patch tier line
+    if (BANNER_TIER_PATTERN.test(patched)) {
+        patched = patched.replace(BANNER_TIER_PATTERN, buildBannerTierLine(tier));
+    }
+    return patched;
+}
+/**
+ * Update a single file's description and banner.
+ * Supports YAML frontmatter, H1 header, and ASCII banner lines.
+ *
+ * Never throws -- description update is non-critical.
+ */
+function updateFile(filePath, type, description, version, tier) {
+    try {
+        if (!existsSync(filePath)) {
+            return false;
+        }
+        let content = readFileSync(filePath, 'utf-8');
+        const original = content;
+        // 1. Patch description (YAML frontmatter or H1 header)
+        if (type === 'yaml') {
+            if (YAML_DESCRIPTION_PATTERN.test(content)) {
+                content = content.replace(YAML_DESCRIPTION_PATTERN, `description: "${description}"`);
+            }
+        }
+        else {
+            if (H1_DESCRIPTION_PATTERN.test(content)) {
+                content = content.replace(H1_DESCRIPTION_PATTERN, `# ${description}`);
+            }
+        }
+        // 2. Patch ASCII banner lines (version + tier) if present
+        content = patchBannerLines(content, version, tier);
+        if (content === original) {
+            return false; // Already up to date
+        }
+        writeFileSync(filePath, content, 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Update agent descriptions across ALL known platform files:
+ *   1. Home-level files (Claude Code, Gemini CLI)
+ *   2. Project-level files (Cursor, VSCode, Codex, Antigravity) -- discovered via git root
+ *
+ * Never throws -- description update is non-critical.
+ * Returns count of files updated.
+ */
+export function updateAgentDescription(version, tier) {
+    const resolvedTier = tier ?? readTierFromConfig();
+    const description = buildDescription(version, resolvedTier);
+    let updated = 0;
+    // 1. Home-level files (existing behavior)
+    for (const { path, type } of HOME_AGENT_FILES) {
+        if (updateFile(path, type, description, version, resolvedTier)) {
+            updated++;
+        }
+    }
+    // 2. Project-level files (discover git root, then check known paths)
+    const projectRoot = discoverProjectRoot();
+    if (projectRoot) {
+        for (const { relativePath, type } of PROJECT_AGENT_FILES) {
+            const fullPath = join(projectRoot, relativePath);
+            if (updateFile(fullPath, type, description, version, resolvedTier)) {
+                updated++;
+            }
+        }
+    }
+    return updated;
+}
+/**
+ * Update agent description for a specific file path (used by install scripts
+ * for project-level files where paths are dynamic).
+ *
+ * Never throws -- description update is non-critical.
+ */
+export function updateAgentDescriptionAt(filePath, type, version, tier) {
+    const resolvedTier = tier ?? readTierFromConfig();
+    const description = buildDescription(version, resolvedTier);
+    return updateFile(filePath, type, description, version, resolvedTier);
+}

package/packages/client/dist/cache/crypto-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/** On-disk envelope format. expiresAt is inside the encrypted data payload. */
+export interface EncryptedEnvelope {
+    /** Base64-encoded initialization vector (12 bytes) */
+    iv: string;
+    /** Base64-encoded PBKDF2 salt */
+    salt: string;
+    /** Base64-encoded GCM auth tag */
+    tag: string;
+    /** Base64-encoded encrypted data (contains plaintext + expiresAt) */
+    data: string;
+}
+export declare function deriveKey(passphrase: string, salt: Buffer): Buffer;
+export declare function encrypt(plaintext: string, passphrase: string, ttlMs?: number): string;
+export interface DecryptResult {
+    plaintext: string;
+    expired: boolean;
+}
+export declare function decrypt(envelopeJson: string, passphrase: string): DecryptResult;