@aiwg/cli 2026.8.7 → 2026.8.8

package/dist/src/artifacts/move.js

@@ -6,10 +6,24 @@ import { syncFortemiCoreIndex } from './fortemi-core-sync.js';
 import { PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 const GITIGNORE_BLOCK = [
     '',
-    '# AIWG artifact root pointer (local/private path)',
+    '# AIWG external artifact corpus (retain the project-local control plane)',
+    '!.aiwg/',
+    '.aiwg/*',
+    '!.aiwg/AIWG.md',
+    '!.aiwg/aiwg.config',
+    '!.aiwg/frameworks/',
+    '.aiwg/frameworks/*',
+    '!.aiwg/frameworks/registry.json',
+    '',
+    '# AIWG artifact root pointer (machine-local/private path)',
     PROJECT_AIWG_LOCATION_FILE,
     '',
 ].join('\n');
+const LOCAL_CONTROL_PLANE_FILES = [
+    'AIWG.md',
+    'aiwg.config',
+    path.join('frameworks', 'registry.json'),
+];
 async function exists(filePath) {
     try {
         await access(filePath);
@@ -49,7 +63,8 @@ async function ensureGitignorePointer(projectDir, dryRun) {
             throw error;
     }
     const lines = current.split(/\r?\n/).map(line => line.trim());
-    if (lines.includes(PROJECT_AIWG_LOCATION_FILE))
+    const required = GITIGNORE_BLOCK.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    if (required.every(line => lines.includes(line)))
         return false;
     if (!dryRun) {
         const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
@@ -57,6 +72,28 @@ async function ensureGitignorePointer(projectDir, dryRun) {
     }
     return true;
 }
+async function materializeLocalControlPlane(projectDir, artifactRoot, dryRun) {
+    const localRoot = path.join(projectDir, '.aiwg');
+    for (const relativePath of LOCAL_CONTROL_PLANE_FILES) {
+        const sourcePath = path.join(artifactRoot, relativePath);
+        if (!(await exists(sourcePath)))
+            continue;
+        const destinationPath = path.join(localRoot, relativePath);
+        const sourceContent = await readFile(sourcePath);
+        if (await exists(destinationPath)) {
+            const destinationContent = await readFile(destinationPath);
+            if (!sourceContent.equals(destinationContent)) {
+                throw new Error(`Local AIWG control-plane file differs from the external artifact root: ${destinationPath}. `
+                    + 'Reconcile the files before attaching the corpus.');
+            }
+            continue;
+        }
+        if (!dryRun) {
+            await mkdir(path.dirname(destinationPath), { recursive: true });
+            await writeFile(destinationPath, sourceContent);
+        }
+    }
+}
 async function writePointer(projectDir, pointerValue, dryRun) {
     const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
     if (!dryRun) {
@@ -134,6 +171,7 @@ export async function moveProjectArtifacts(options) {
     if (!dryRun && !attach) {
         await moveDirectory(source, destination);
     }
+    await materializeLocalControlPlane(projectDir, destination, dryRun);
     await writePointer(projectDir, pointerValue, dryRun);
     let reindexed = false;
     let fortemiSynced = false;

package/dist/src/cli/handlers/regenerate.js

@@ -26,6 +26,7 @@ import { generate as generateContextFiles, discoverDeployedArtifacts, shouldEmit
 import { resolveActiveProvider } from '../provider-resolution.js';
 import { getProviderContextDiscoveryPathStrings } from '../../providers/provider-definitions.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { selectRegenerateBranch } from '../regenerate-selector.js';
 async function handleRegenerate(args, cwd) {
     if (args.includes('--help') || args.includes('-h')) {
         console.log(`
@@ -40,7 +41,8 @@ async function handleRegenerate(args, cwd) {
     or commands — use 'aiwg refresh' for that.
 
   Options:
-    --workspace             Canonical WORKSPACE.md → AIWG.md graph (default)
+    (no branch flag)        Intelligently select workspace refresh or adoption preview
+    --workspace             Explicit canonical WORKSPACE.md → AIWG.md graph
     --existing-project      Transactionally extract an established project into WORKSPACE.md
     --legacy, --full-inject Legacy inline compatibility branch
     --apply                 Apply --existing-project after its mandatory preflight
@@ -57,6 +59,7 @@ async function handleRegenerate(args, cwd) {
     aiwg regenerate --workspace
     aiwg regenerate --existing-project --dry-run
     aiwg regenerate --existing-project --apply
+    aiwg regenerate --apply
     aiwg regenerate --full-inject
     aiwg regenerate --dry-run
     aiwg regenerate --provider codex
@@ -69,9 +72,9 @@ async function handleRegenerate(args, cwd) {
     const skipAiwgMd = args.includes('--no-aiwg-md');
     const skipAgentsMd = args.includes('--no-agents-md');
     const skipWorkspaceMd = args.includes('--no-workspace-md');
-    const legacy = args.includes('--legacy') || args.includes('--full-inject');
-    const workspace = args.includes('--workspace');
-    const existingProject = args.includes('--existing-project');
+    const requestedLegacy = args.includes('--legacy') || args.includes('--full-inject');
+    const requestedWorkspace = args.includes('--workspace');
+    const requestedExistingProject = args.includes('--existing-project');
     const apply = args.includes('--apply');
     const valueFlags = new Set(['--provider']);
     const booleanFlags = new Set([
@@ -95,23 +98,27 @@ async function handleRegenerate(args, cwd) {
             });
         }
     }
-    const selectedBranches = Number(legacy) + Number(workspace) + Number(existingProject);
+    const selectedBranches = Number(requestedLegacy) + Number(requestedWorkspace) + Number(requestedExistingProject);
     if (selectedBranches > 1)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
             message: 'Choose exactly one regenerate branch: --workspace, --existing-project, or --full-inject.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (apply && !existingProject)
+    if (dryRun && apply)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: '--apply is only valid with --existing-project.',
+            message: 'Choose either --dry-run or --apply.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (existingProject && dryRun && apply)
+    const selection = await selectRegenerateBranch(cwd, args);
+    const legacy = selection.branch === 'legacy';
+    const existingProject = selection.branch === 'existing-project';
+    if (apply && !existingProject)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: 'Choose either --dry-run or --apply for --existing-project.',
+            message: '--apply is only valid when the existing-project branch is selected.',
+            hint: 'Use `aiwg regenerate --existing-project --apply`, or run without --apply to inspect the selected branch.',
             exitCode: EXIT_CODES.USAGE,
         });
     if (existingProject && (force || skipAiwgMd || skipAgentsMd || skipWorkspaceMd))
@@ -140,6 +147,9 @@ async function handleRegenerate(args, cwd) {
     console.log(`  Provider: ${provider}`);
     console.log(`  Target:   ${target}`);
     console.log(`  Branch:   ${legacy ? 'legacy full injection' : existingProject ? 'canonical existing-project extraction' : 'canonical workspace graph'}`);
+    console.log(`  Selected: ${selection.explicit ? 'explicit' : 'inferred'} — ${selection.reason}`);
+    if (selection.evidence.length > 0)
+        console.log(`  Evidence: ${selection.evidence.join(', ')}`);
     if (existingProject) {
         const preflight = await migrateWorkspaceContext(target, {
             dryRun: true,

package/dist/src/cli/handlers/sessions.js

@@ -1203,15 +1203,16 @@ function projectRootCandidate(start) {
     catch {
         current = resolve(start);
     }
-    let gitRoot = null;
     while (true) {
         if (existsSync(resolve(current, '.aiwg', 'aiwg.config')))
             return current;
-        if (!gitRoot && existsSync(resolve(current, '.git')))
-            gitRoot = current;
+        // A repository root is the project boundary. Do not let an unrelated
+        // ancestor workspace configuration capture session catalog reads.
+        if (existsSync(resolve(current, '.git')))
+            return current;
         const parent = dirname(current);
         if (parent === current)
-            return gitRoot;
+            return null;
         current = parent;
     }
 }

package/dist/src/cli/handlers/subcommands.js

@@ -47,6 +47,8 @@ export const quickrefHandler = {
                 console.log(`${verb} ${result.skillName}`);
                 console.log(`  Source: ${result.sourcePath}`);
                 console.log(`  Output: ${result.outputPath}`);
+                for (const warning of result.warnings)
+                    console.log(`  Warning: ${warning}`);
                 if (ctx.dryRun) {
                     console.log('\n--- preview ---\n');
                     console.log(result.content);
@@ -850,6 +852,26 @@ export const promoteHandler = {
             console.log(`✓ Promoted '${positional}' → ${result.plan?.destination}`);
             if (cleanup) {
                 console.log('  Source removed from .aiwg/');
+                try {
+                    const { deployProjectQuickref, generateProjectQuickref, hasProjectQuickref } = await import('../../extensions/project-quickref.js');
+                    if (await hasProjectQuickref(projectDir)) {
+                        if (config.providers.length > 0) {
+                            for (const provider of config.providers)
+                                await deployProjectQuickref(projectDir, provider);
+                            console.log(`  Managed project quickref refreshed for: ${config.providers.join(', ')}.`);
+                        }
+                        else {
+                            await generateProjectQuickref(projectDir);
+                            console.log('  Managed project quickref generated; no providers are configured for deployment.');
+                        }
+                    }
+                    else {
+                        console.log('  Managed project quickref is now empty; run `aiwg doctor --project-local` to inspect deployed stale copies.');
+                    }
+                }
+                catch (error) {
+                    console.log(`  Managed project quickref refresh failed: ${error.message}`);
+                }
             }
             return { exitCode: 0 };
         }
@@ -956,6 +978,14 @@ export const newBundleHandler = {
             catch {
                 // .gitignore management is best-effort; don't fail the scaffold
             }
+            try {
+                const { generateProjectQuickref } = await import('../../extensions/project-quickref.js');
+                await generateProjectQuickref(ctx.cwd);
+                console.log('  → Managed project quickref refreshed from discovered capabilities.');
+            }
+            catch (error) {
+                console.log(`  → Managed project quickref refresh deferred: ${error.message}`);
+            }
             // #1235 / #1758 — auto-rebuild the project graph and refresh the
             // Fortemi Core static cache so the new bundle is immediately
             // discoverable via top-level `aiwg discover` / `aiwg show`.

package/dist/src/cli/handlers/use.js

@@ -1079,18 +1079,17 @@ async function deployProjectLocalBundles(opts) {
         : discovery.bundles.filter(b => b.type !== 'provider');
     if (targetBundles.length === 0) {
         if (!onlyBundleId) {
-            const { loadProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
-            const quickref = await loadProjectQuickref(projectDir);
-            if (quickref.exists) {
-                try {
+            const { hasProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
+            try {
+                if (await hasProjectQuickref(projectDir)) {
                     await deployProjectQuickref(projectDir, provider, { dryRun });
                     if (verbose || dryRun)
                         ui.dim(`  + project quickref -> ${provider}`);
                 }
-                catch (error) {
-                    ui.warn(`Project quickref deployment failed: ${error.message}`);
-                    return { deployed: 0, failed: 1, bundles: [] };
-                }
+            }
+            catch (error) {
+                ui.warn(`Project quickref deployment failed: ${error.message}`);
+                return { deployed: 0, failed: 1, bundles: [] };
             }
         }
         return { deployed: 0, failed: 0, bundles: [] };
@@ -1204,22 +1203,20 @@ async function deployProjectLocalBundles(opts) {
             }
         }
     }
-    // A committed `.aiwg/quickref.json` is the canonical orientation source.
-    // Refresh its provider kernel copy whenever project-local bundles deploy so
-    // `aiwg use <bundle>` keeps the always-visible surface in sync.
-    const { loadProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
-    const quickref = await loadProjectQuickref(projectDir);
-    if (quickref.exists) {
-        try {
+    // Refresh the project kernel quickref from either legacy operator input or
+    // managed project-local discovery whenever bundles deploy.
+    const { hasProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
+    try {
+        if (await hasProjectQuickref(projectDir)) {
             const quickrefResult = await deployProjectQuickref(projectDir, provider, { dryRun });
             if (verbose || dryRun) {
                 ui.dim(`  + project quickref -> ${quickrefResult.provider}${quickrefResult.emulated ? ' (emulated)' : ''}`);
             }
         }
-        catch (error) {
-            failed++;
-            ui.warn(`Project quickref deployment failed: ${error.message}`);
-        }
+    }
+    catch (error) {
+        failed++;
+        ui.warn(`Project quickref deployment failed: ${error.message}`);
     }
     return { deployed, failed, bundles: targetBundles };
 }

package/dist/src/cli/regenerate-selector.js

@@ -0,0 +1,94 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { auditWorkspaceContext, PROJECT_EXTRACTION_END, PROJECT_EXTRACTION_START, WORKSPACE_MANAGED_END, WORKSPACE_MANAGED_START, WORKSPACE_OPERATOR_END, WORKSPACE_OPERATOR_START, } from '../smiths/context-pipeline/index.js';
+import { AiwgError, EXIT_CODES } from './errors.js';
+function markerPair(content, start, end) {
+    const startIndex = content.indexOf(start);
+    const endIndex = content.indexOf(end);
+    const present = startIndex >= 0 || endIndex >= 0;
+    return {
+        present,
+        valid: !present || (startIndex >= 0 && endIndex > startIndex
+            && content.indexOf(start, startIndex + start.length) < 0
+            && content.indexOf(end, endIndex + end.length) < 0),
+    };
+}
+function malformedWorkspace(message) {
+    throw new AiwgError({
+        code: 'ERR_USAGE_REGENERATE_STATE_MALFORMED',
+        message,
+        hint: 'Repair the managed marker pair or restore WORKSPACE.md from version control, then rerun `aiwg regenerate --dry-run`.',
+        exitCode: EXIT_CODES.USAGE,
+    });
+}
+async function readOptional(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function selectRegenerateBranch(cwd, args) {
+    const legacy = args.includes('--legacy') || args.includes('--full-inject');
+    const workspace = args.includes('--workspace');
+    const existingProject = args.includes('--existing-project');
+    if (legacy)
+        return { branch: 'legacy', state: 'legacy-context', reason: 'explicit legacy compatibility branch', evidence: ['--legacy/--full-inject'], explicit: true };
+    if (workspace)
+        return { branch: 'workspace', state: 'fresh', reason: 'explicit canonical workspace branch', evidence: ['--workspace'], explicit: true };
+    if (existingProject)
+        return { branch: 'existing-project', state: 'established-unextracted', reason: 'explicit existing-project adoption branch', evidence: ['--existing-project'], explicit: true };
+    const workspaceContent = await readOptional(path.join(cwd, 'WORKSPACE.md'));
+    let workspaceMarkers = null;
+    if (workspaceContent !== null) {
+        workspaceMarkers = {
+            managed: markerPair(workspaceContent, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END),
+            operator: markerPair(workspaceContent, WORKSPACE_OPERATOR_START, WORKSPACE_OPERATOR_END),
+            extraction: markerPair(workspaceContent, PROJECT_EXTRACTION_START, PROJECT_EXTRACTION_END),
+        };
+        const { managed, operator, extraction } = workspaceMarkers;
+        if (!managed.valid || !operator.valid || !extraction.valid) {
+            malformedWorkspace('WORKSPACE.md contains an incomplete, duplicated, or out-of-order AIWG managed marker pair.');
+        }
+        if (extraction.present && !managed.present)
+            malformedWorkspace('WORKSPACE.md contains a project-extraction block without the canonical workspace managed graph.');
+        if (managed.present !== operator.present)
+            malformedWorkspace('WORKSPACE.md contains only part of the canonical managed/operator structure.');
+    }
+    const audit = await auditWorkspaceContext(cwd);
+    const projectSources = audit.plan.projectSources;
+    const operatorSources = audit.sources
+        .filter((source) => source.path !== 'WORKSPACE.md' && source.operatorContent.trim().length > 0)
+        .map((source) => source.path);
+    if (workspaceContent !== null) {
+        const { managed, extraction } = workspaceMarkers;
+        if (managed.present && extraction.present)
+            return {
+                branch: 'workspace', state: 'adopted', reason: 'canonical workspace already contains an extracted project snapshot', evidence: ['WORKSPACE.md project-extraction marker'], explicit: false,
+            };
+        if (managed.present && projectSources.length > 0)
+            return {
+                branch: 'existing-project', state: 'canonical-unextracted', reason: 'canonical workspace exists but stable project metadata has not been adopted', evidence: projectSources, explicit: false,
+            };
+        if (managed.present)
+            return {
+                branch: 'workspace', state: 'fresh', reason: 'canonical workspace exists and no stable project sources were detected', evidence: ['WORKSPACE.md managed graph'], explicit: false,
+            };
+        return {
+            branch: 'existing-project', state: 'operator-owned-workspace', reason: 'operator-owned WORKSPACE.md requires transactional adoption before canonical refresh', evidence: ['WORKSPACE.md without AIWG managed markers', ...projectSources], explicit: false,
+        };
+    }
+    if (projectSources.length > 0)
+        return {
+            branch: 'existing-project', state: 'established-unextracted', reason: 'stable existing-project sources were detected without an extracted workspace snapshot', evidence: projectSources, explicit: false,
+        };
+    if (audit.legacyCompatible || operatorSources.length > 0)
+        return {
+            branch: 'existing-project', state: 'legacy-context', reason: 'operator-authored provider context requires transactional adoption', evidence: operatorSources, explicit: false,
+        };
+    return { branch: 'workspace', state: 'fresh', reason: 'no prior workspace setup or stable project sources were detected', evidence: [], explicit: false };
+}
+//# sourceMappingURL=regenerate-selector.js.map

package/dist/src/extensions/project-local-doctor.js

@@ -54,12 +54,15 @@ export async function buildProjectLocalDoctorSection(opts) {
     const quickrefAudit = await auditProjectQuickref(projectDir, config?.providers ?? []);
     const quickrefErrors = [...quickrefAudit.errors];
     if (quickrefAudit.exists) {
-        const quickrefRelPath = projectRelativePathIfInside(projectDir, projectAiwgPath(projectDir, 'quickref.json'));
-        const ignored = quickrefRelPath
-            ? await checkBundleManifestIgnored(projectDir, quickrefRelPath)
-            : null;
-        if (ignored === true && quickrefRelPath) {
-            quickrefErrors.push(`${quickrefRelPath} is ignored by git; canonical project quickref source must be committed`);
+        for (const name of ['quickref.json', 'quickref.config.json']) {
+            const sourcePath = projectAiwgPath(projectDir, name);
+            const quickrefRelPath = projectRelativePathIfInside(projectDir, sourcePath);
+            const ignored = quickrefRelPath
+                ? await checkBundleManifestIgnored(projectDir, quickrefRelPath)
+                : null;
+            if (ignored === true && quickrefRelPath) {
+                quickrefErrors.push(`${quickrefRelPath} is ignored by git; operator project quickref input must be committed`);
+            }
         }
     }
     // No project-local content → no section at all
@@ -236,6 +239,7 @@ export async function buildProjectLocalDoctorSection(opts) {
             }
             lines.push('    Project-local bundle source should be tracked. Add to .gitignore:');
             lines.push('      !.aiwg/quickref.json');
+            lines.push('      !.aiwg/quickref.config.json');
             lines.push('      !.aiwg/addons/');
             lines.push('      !.aiwg/extensions/');
             lines.push('      !.aiwg/frameworks/');

package/dist/src/extensions/project-local-gitignore.js

@@ -39,6 +39,7 @@ export const AIWG_GITIGNORE_BLOCK = [
     AIWG_GITIGNORE_SENTINEL,
     '!.aiwg/aiwg.config',
     '!.aiwg/quickref.json',
+    '!.aiwg/quickref.config.json',
     '!.aiwg/addons/',
     '!.aiwg/extensions/',
     '!.aiwg/frameworks/',
@@ -120,11 +121,14 @@ export async function appendAiwgSourceTrackBlock(projectDir) {
     // runs.
     if (report.hasManagedBlock) {
         const path = join(projectDir, '.gitignore');
-        const existing = await readFile(path, 'utf8');
-        if (!existing.split(/\r?\n/).some(line => line.trim() === '!.aiwg/quickref.json')) {
+        let existing = await readFile(path, 'utf8');
+        const required = ['!.aiwg/quickref.json', '!.aiwg/quickref.config.json'];
+        const missing = required.filter(negation => !existing.split(/\r?\n/).some(line => line.trim() === negation));
+        if (missing.length > 0) {
             const sep = existing.endsWith('\n') ? '' : '\n';
-            await writeFile(path, `${existing}${sep}!.aiwg/quickref.json\n`, 'utf8');
-            return { added: true, reason: 'updated managed block to track .aiwg/quickref.json' };
+            existing = `${existing}${sep}${missing.join('\n')}\n`;
+            await writeFile(path, existing, 'utf8');
+            return { added: true, reason: `updated managed block to track ${missing.join(', ')}` };
         }
         return { added: false, reason: 'block already present — no change' };
     }

package/dist/src/extensions/project-quickref.js

@@ -7,13 +7,15 @@
  */
 import { createHash } from 'crypto';
 import { access, mkdir, readFile, readdir, rm, writeFile } from 'fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'path';
+import { basename, dirname, isAbsolute, join, resolve } from 'path';
 import { homedir } from 'os';
 import { z } from 'zod';
 import { getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
 import { OPERATIONAL_SHOW_TYPES } from '../artifacts/types.js';
 import { projectAiwgPath } from '../config/project-artifacts.js';
 import { appendAiwgSourceTrackBlock } from './project-local-gitignore.js';
+import { discoverProjectLocalBundles } from './project-local-discovery.js';
+import { enumerateBundleArtifacts } from './shadow-resolver.js';
 const OWNERSHIP_MARKER = '.aiwg-project-quickref.json';
 const ShowHintSchema = z.object({
     type: z.enum(OPERATIONAL_SHOW_TYPES),
@@ -35,6 +37,25 @@ export const ProjectQuickrefSchema = z.object({
     precedence: z.string().min(1).max(1024),
     entries: z.array(QuickrefEntrySchema).min(1).max(50),
 }).strict();
+const QuickrefOverrideSchema = z.object({
+    title: z.string().min(1).max(128).optional(),
+    summary: z.string().min(1).max(512).optional(),
+    discover: z.array(z.string().min(1).max(256)).max(10).optional(),
+    show: z.array(ShowHintSchema).max(20).optional(),
+    hidden: z.boolean().optional(),
+    order: z.number().int().optional(),
+}).strict();
+export const ProjectQuickrefConfigSchema = z.object({
+    version: z.literal('1'),
+    project: ProjectQuickrefSchema.shape.project.optional(),
+    precedence: z.string().min(1).max(1024).optional(),
+    entries: z.array(QuickrefEntrySchema).max(50).default([]),
+    discovery: z.object({
+        enabled: z.boolean().default(true),
+        excludeBundles: z.array(z.string().min(1)).max(200).default([]),
+        overrides: z.record(z.string(), QuickrefOverrideSchema).default({}),
+    }).strict().default({ enabled: true, excludeBundles: [], overrides: {} }),
+}).strict();
 function sha256(content) {
     return createHash('sha256').update(content).digest('hex');
 }
@@ -78,6 +99,158 @@ export async function loadProjectQuickref(projectDir) {
         return { sourcePath, errors: [`${sourcePath}: invalid JSON: ${error.message}`], exists: true };
     }
 }
+function slug(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return normalized || 'project';
+}
+async function inferredProject(projectDir) {
+    let packageName = basename(resolve(projectDir));
+    let description = `Managed project-specific orientation for ${packageName}.`;
+    try {
+        const parsed = JSON.parse(await readFile(join(projectDir, 'package.json'), 'utf8'));
+        if (parsed.name)
+            packageName = parsed.name;
+        if (parsed.description)
+            description = parsed.description.slice(0, 512);
+    }
+    catch {
+        // package metadata is optional
+    }
+    const id = slug(packageName);
+    const name = packageName
+        .replace(/^@[^/]+\//, '')
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map(part => part[0]?.toUpperCase() + part.slice(1))
+        .join(' ') || 'Project';
+    return { id, name, description };
+}
+async function loadManagedConfig(projectDir) {
+    const path = projectAiwgPath(projectDir, 'quickref.config.json');
+    const raw = await readIfPresent(path);
+    if (raw === null)
+        return { path };
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path}: invalid JSON: ${error.message}`);
+    }
+    const parsed = ProjectQuickrefConfigSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error(parsed.error.issues.map(issue => `${path}: ${issue.path.join('.') || '(root)'}: ${issue.message}`).join('\n'));
+    }
+    return { path, config: parsed.data };
+}
+function dedupe(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = value.trim().toLowerCase();
+        if (!key || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function dedupeShow(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = `${value.type}:${value.name.toLowerCase()}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Resolve legacy operator input or synthesize a managed definition from project-local bundles. */
+export async function resolveProjectQuickref(projectDir) {
+    const legacy = await loadProjectQuickref(projectDir);
+    if (legacy.exists) {
+        if (!legacy.definition)
+            throw new Error(legacy.errors.join('\n'));
+        return {
+            definition: legacy.definition,
+            exists: true,
+            sourcePath: legacy.sourcePath,
+            provenance: 'legacy',
+            warnings: [],
+        };
+    }
+    const managed = await loadManagedConfig(projectDir);
+    const discovery = await discoverProjectLocalBundles(projectDir);
+    if (discovery.errors.length > 0) {
+        throw new Error(discovery.errors.map(error => `${error.path}: ${error.field}: ${error.actual}`).join('\n'));
+    }
+    if (!managed.config && discovery.bundles.length === 0) {
+        return { exists: false, sourcePath: managed.path, provenance: 'managed', warnings: [] };
+    }
+    const config = managed.config ?? ProjectQuickrefConfigSchema.parse({ version: '1' });
+    const excluded = new Set(config.discovery.excludeBundles.map(id => id.toLowerCase()));
+    const warnings = [];
+    const candidates = [];
+    if (config.discovery.enabled) {
+        for (const bundle of discovery.bundles) {
+            if (excluded.has(bundle.id.toLowerCase()))
+                continue;
+            const override = config.discovery.overrides[bundle.id];
+            if (override?.hidden)
+                continue;
+            const artifacts = (await enumerateBundleArtifacts(bundle.artifactPath ?? bundle.bundlePath))
+                .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+            const inferredShow = dedupeShow(artifacts.map(artifact => ({
+                type: artifact.type,
+                name: artifact.id,
+            }))).slice(0, 8);
+            if (artifacts.length > inferredShow.length && inferredShow.length === 8) {
+                warnings.push(`${bundle.id}: show hints truncated from ${artifacts.length} artifacts to 8`);
+            }
+            let discover = override?.discover ?? dedupe([
+                bundle.id,
+                bundle.manifest.name,
+                ...(bundle.manifest.keywords ?? []),
+            ]).slice(0, 3);
+            const show = override?.show ? dedupeShow(override.show) : inferredShow;
+            if (discover.length === 0 && show.length === 0)
+                discover = [bundle.id];
+            candidates.push({
+                order: override?.order ?? 0,
+                type: bundle.type,
+                id: bundle.id,
+                entry: {
+                    title: override?.title ?? bundle.manifest.name,
+                    summary: override?.summary ?? bundle.manifest.description,
+                    discover,
+                    show,
+                },
+            });
+        }
+    }
+    candidates.sort((a, b) => a.order - b.order || a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+    const discoveredEntries = candidates.map(candidate => candidate.entry);
+    const entries = [...discoveredEntries, ...config.entries];
+    if (entries.length > 50)
+        warnings.push(`quickref entries truncated from ${entries.length} to 50`);
+    const bounded = entries.slice(0, 50);
+    if (bounded.length === 0) {
+        return { exists: false, sourcePath: managed.path, provenance: 'managed', warnings };
+    }
+    return {
+        definition: {
+            version: '1',
+            project: config.project ?? await inferredProject(projectDir),
+            precedence: config.precedence ?? 'Use project-local capabilities before generic AIWG workflows when they apply.',
+            entries: bounded,
+        },
+        exists: true,
+        sourcePath: managed.path,
+        provenance: 'managed',
+        warnings,
+    };
+}
+export async function hasProjectQuickref(projectDir) {
+    return (await resolveProjectQuickref(projectDir)).exists;
+}
 export function renderProjectQuickref(definition) {
     const skillName = projectQuickrefSkillName(definition.project.id);
     const lines = [
@@ -111,11 +284,9 @@ export function renderProjectQuickref(definition) {
     return lines.join('\n');
 }
 export async function generateProjectQuickref(projectDir, options = {}) {
-    const loaded = await loadProjectQuickref(projectDir);
-    if (!loaded.exists)
+    const loaded = await resolveProjectQuickref(projectDir);
+    if (!loaded.exists || !loaded.definition)
         throw new Error(`Project quickref source not found: ${loaded.sourcePath}`);
-    if (!loaded.definition)
-        throw new Error(loaded.errors.join('\n'));
     if (!options.dryRun)
         await appendAiwgSourceTrackBlock(projectDir);
     const skillName = projectQuickrefSkillName(loaded.definition.project.id);
@@ -127,6 +298,14 @@ export async function generateProjectQuickref(projectDir, options = {}) {
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, content, 'utf8');
     }
+    if (!options.dryRun && loaded.provenance === 'managed') {
+        const snapshotPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', 'definition.json');
+        const snapshot = JSON.stringify(loaded.definition, null, 2) + '\n';
+        if (await readIfPresent(snapshotPath) !== snapshot) {
+            await mkdir(dirname(snapshotPath), { recursive: true });
+            await writeFile(snapshotPath, snapshot, 'utf8');
+        }
+    }
     if (!options.dryRun) {
         const generatedRoot = projectAiwgPath(projectDir, 'generated', 'project-quickref');
         try {
@@ -149,6 +328,8 @@ export async function generateProjectQuickref(projectDir, options = {}) {
         content,
         changed,
         dryRun: options.dryRun ?? false,
+        provenance: loaded.provenance,
+        warnings: loaded.warnings,
     };
 }
 function resolveProviderSkillsRoot(provider, projectDir, homeDir) {
@@ -206,9 +387,9 @@ async function findStaleOwnedQuickrefs(root, projectDir, keepName, global) {
 }
 export async function deployProjectQuickref(projectDir, provider, options = {}) {
     const generated = await generateProjectQuickref(projectDir, { dryRun: options.dryRun });
-    const loaded = await loadProjectQuickref(projectDir);
+    const loaded = await resolveProjectQuickref(projectDir);
     if (!loaded.definition)
-        throw new Error(loaded.errors.join('\n'));
+        throw new Error(`Project quickref source not found: ${loaded.sourcePath}`);
     const target = resolveProviderSkillsRoot(provider, projectDir, options.homeDir ?? homedir());
     const targetDir = join(target.root, generated.skillName);
     const targetPath = join(targetDir, 'SKILL.md');
@@ -259,11 +440,17 @@ export async function deployProjectQuickref(projectDir, provider, options = {})
     };
 }
 export async function auditProjectQuickref(projectDir, providers, options = {}) {
-    const loaded = await loadProjectQuickref(projectDir);
+    let loaded;
+    try {
+        loaded = await resolveProjectQuickref(projectDir);
+    }
+    catch (error) {
+        return { exists: true, errors: [error.message], drift: [] };
+    }
     if (!loaded.exists)
-        return { exists: false, errors: loaded.errors, drift: [] };
+        return { exists: false, errors: [], drift: [] };
     if (!loaded.definition)
-        return { exists: true, errors: loaded.errors, drift: [] };
+        return { exists: true, errors: ['project quickref definition unavailable'], drift: [] };
     const content = renderProjectQuickref(loaded.definition);
     const skillName = projectQuickrefSkillName(loaded.definition.project.id);
     const generatedPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', skillName, 'SKILL.md');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.7",
+  "version": "2026.8.8",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/plugin/package-plugins.mjs

@@ -657,6 +657,13 @@ for (const [id, sourceRoot] of MANIFEST_PLUGIN_SOURCES) {
     keywords: manifest.keywords || manifest.tags || [],
     category: manifest.category || 'productivity',
     sourceRoot,
+    declaredSkills: manifest.skills ?? [],
+    // Plugin payloads run outside the checkout. Rewrite references back to
+    // their packaged root, including the pre-rename Ralph path retained by
+    // older Agent Loop documentation.
+    selfReferenceRoots: id === 'agent-loop'
+      ? [sourceRoot, 'agentic/code/addons/ralph']
+      : [sourceRoot],
   };
 }
 
@@ -774,6 +781,48 @@ function copyDir(src, dest, dryRun = false, filter = null) {
   return copied;
 }
 
+function rewritePackagedSelfReferences(pluginDir, roots = []) {
+  if (roots.length === 0) return;
+  const pending = [pluginDir];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(target);
+      } else if (entry.isFile() && /\.(?:md|json|ya?ml)$/.test(entry.name)) {
+        const original = fs.readFileSync(target, 'utf8');
+        let rewritten = original;
+        for (const root of roots) {
+          rewritten = rewritten.replaceAll(`${root}/`, '${CLAUDE_PLUGIN_ROOT}/');
+        }
+        if (rewritten !== original) fs.writeFileSync(target, rewritten, 'utf8');
+      }
+    }
+  }
+}
+
+function pruneUndeclaredPackagedSkills(pluginDir, declaredSkills) {
+  if (!declaredSkills) return;
+  const skillsRoot = path.join(pluginDir, 'skills');
+  if (!fs.existsSync(skillsRoot)) return;
+  const allowed = new Set(declaredSkills);
+  for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && !allowed.has(entry.name)) {
+      fs.rmSync(path.join(skillsRoot, entry.name), { recursive: true, force: true });
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const skillId = path.basename(entry.name, '.md');
+      if (allowed.has(skillId)) {
+        const skillDir = path.join(skillsRoot, skillId);
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.renameSync(path.join(skillsRoot, entry.name), path.join(skillDir, 'SKILL.md'));
+      } else {
+        fs.rmSync(path.join(skillsRoot, entry.name), { force: true });
+      }
+    }
+  }
+}
+
 // Clean plugin directory (except .claude-plugin)
 function cleanPlugin(pluginDir) {
   if (!fs.existsSync(pluginDir)) return;
@@ -811,6 +860,10 @@ function packagePlugin(name, config, options) {
     console.log(`  📁 Copying self-contained source from ${config.sourceRoot}...`);
     const count = copyDir(config.sourceRoot, pluginDir, options.dryRun);
     console.log(`     ${count} files`);
+    if (!options.dryRun) {
+      rewritePackagedSelfReferences(pluginDir, config.selfReferenceRoots);
+      pruneUndeclaredPackagedSkills(pluginDir, config.declaredSkills);
+    }
   }
 
   // Copy sources