create-quiver 0.9.1 → 0.12.0

package/src/create-quiver/lib/init-docs.js

@@ -1,6 +1,12 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const {
+  buildQuiverConfig,
+  buildQuiverInternalGitignore,
+  quiverInternalPaths,
+  resolveInitPackageScripts,
+} = require('./init-layout');
 const { writeState } = require('./state');
 
 function ensureDir(dirPath) {
@@ -199,7 +205,58 @@ function writeFrontMatter(filePath, fields) {
   return nextContent;
 }
 
-function mergePackageJson(projectRoot, templateRoot, skipIfExists) {
+const ROOT_GITIGNORE_DEFAULTS = [
+  'node_modules/',
+  '.DS_Store',
+  'dist/',
+  'coverage/',
+];
+
+function normalizeGitignorePattern(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return trimmed;
+  }
+
+  return trimmed.replace(/\/+$/g, '');
+}
+
+function mergeLineList(existingText, defaults) {
+  const existingLines = existingText
+    .split(/\r?\n/)
+    .filter((line, index, lines) => line.length > 0 || index < lines.length - 1);
+  const seen = new Set(existingLines.map(normalizeGitignorePattern).filter(Boolean));
+  const nextLines = [...existingLines];
+
+  for (const line of defaults) {
+    const normalized = normalizeGitignorePattern(line);
+    if (!seen.has(normalized)) {
+      nextLines.push(line);
+      seen.add(normalized);
+    }
+  }
+
+  return `${nextLines.join('\n').replace(/\s+$/g, '')}\n`;
+}
+
+function mergeRootGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const exists = fs.existsSync(gitignorePath);
+  const existingText = exists
+    ? fs.readFileSync(gitignorePath, 'utf8')
+    : '';
+
+  ensureDir(path.dirname(gitignorePath));
+  fs.writeFileSync(gitignorePath, mergeLineList(existingText, ROOT_GITIGNORE_DEFAULTS));
+  return exists ? 'merged' : 'created';
+}
+
+function resolvePackageName(projectRoot, options = {}) {
+  return options.projectSlug
+    || toProjectSlug(options.projectName || path.basename(projectRoot) || 'Quiver Project');
+}
+
+function mergePackageJson(projectRoot, templateRoot, options = {}) {
   const packageTemplate = path.join(templateRoot, 'package.template.json');
   const packageJsonPath = path.join(projectRoot, 'package.json');
 
@@ -207,24 +264,168 @@ function mergePackageJson(projectRoot, templateRoot, skipIfExists) {
     return 'missing';
   }
 
+  const profile = options.profile || 'default';
+  const scripts = resolveInitPackageScripts(profile, { legacyScripts: options.legacyScripts === true });
+
   if (!fs.existsSync(packageJsonPath)) {
-    fs.copyFileSync(packageTemplate, packageJsonPath);
+    const template = JSON.parse(fs.readFileSync(packageTemplate, 'utf8'));
+    template.name = resolvePackageName(projectRoot, options);
+    template.scripts = scripts;
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify(template, null, 2)}\n`);
     return 'created';
   }
 
   const existing = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-  const template = JSON.parse(fs.readFileSync(packageTemplate, 'utf8'));
+
+  if (typeof existing.name !== 'string' || existing.name.trim().length === 0) {
+    existing.name = resolvePackageName(projectRoot, options);
+  }
 
   existing.scripts = {
     ...(existing.scripts || {}),
-    ...(template.scripts || {}),
+    ...scripts,
   };
 
   fs.writeFileSync(packageJsonPath, `${JSON.stringify(existing, null, 2)}\n`);
-  return skipIfExists ? 'merged' : 'updated';
+  return options.migrateMode ? 'merged' : 'updated';
 }
 
-function buildReadme(projectName, projectSlug) {
+function buildReadme(projectName, projectSlug, profile = 'default') {
+  if (profile === 'minimal') {
+    return `# ${projectName}
+
+[Descripción breve del proyecto]
+
+## Quick Start
+
+Run Quiver from this project root. Do not install it globally.
+
+\`\`\`bash
+npm install
+npx create-quiver analyze
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
+\`\`\`
+
+## AI Workflow
+
+Use \`AGENTS.md\` first, then \`docs/AI_CONTEXT.md\` and \`docs/AI_ONBOARDING_PROMPT.md\` for the working contract.
+
+\`\`\`bash
+npm run quiver:prepare -- --dry-run
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+\`\`\`
+
+When a real spec exists, execute one approved slice at a time:
+
+\`\`\`bash
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+\`\`\`
+
+## Documentation
+
+- [AI Context](./docs/AI_CONTEXT.md)
+- [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md)
+- [Commands](./docs/COMMANDS.md)
+- [Workflow](./docs/WORKFLOW.md)
+`;
+  }
+
+  if (profile !== 'full') {
+    return `# ${projectName}
+
+[Descripción breve del proyecto]
+
+## Quick Start
+
+Run Quiver from this project root. Do not install it globally.
+
+\`\`\`bash
+npm install
+npx create-quiver analyze
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
+\`\`\`
+
+After \`analyze\`, use \`docs/PROJECT_MAP.md\` for the detected stack, package manager, and command surface.
+
+## AI-First Workflow
+
+Quiver keeps the visible contract small: start with \`README.md\`, \`AGENTS.md\`, and \`docs/\`. Specs and slices should be created only after a real requirement and a reviewed, approved technical plan.
+
+Use dry-runs before spending model tokens:
+
+\`\`\`bash
+npm run quiver:prepare -- --dry-run
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+\`\`\`
+
+When a real spec exists, execute one approved slice at a time:
+
+\`\`\`bash
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+\`\`\`
+
+## Project NPM Scripts
+
+The generated project includes \`quiver:*\` npm scripts that call the Node CLI:
+
+\`\`\`bash
+npm run quiver:analyze
+npm run quiver:prepare -- --dry-run
+npm run quiver:plan
+npm run quiver:graph
+npm run quiver:next
+npm run quiver:doctor
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:pr -- --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:spec:start -- specs/<spec-slug>
+npm run quiver:spec:status -- specs/<spec-slug>
+npm run quiver:spec:close -- specs/<spec-slug> --dry-run
+\`\`\`
+
+## Documentation
+
+- [Agents](./AGENTS.md)
+- [AI Context](./docs/AI_CONTEXT.md)
+- [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md)
+- [Commands](./docs/COMMANDS.md)
+- [Workflow](./docs/WORKFLOW.md)
+- [GitFlow PR Guide](./docs/GITFLOW_PR_GUIDE.md)
+- [Support Matrix](./docs/SUPPORT_MATRIX.md)
+- [Troubleshooting](./docs/TROUBLESHOOTING.md)
+`;
+  }
+
   return `# ${projectName}
 
 [Descripción breve del proyecto]
@@ -259,16 +460,56 @@ If you need to target another directory from outside the project, pass \`--dir\`
 
 After you run \`analyze\`, open \`docs/PROJECT_MAP.md\` for the detected stack, package manager, and command surface.
 
+## AI-First Workflow
+
+Quiver is designed for an AI-first workflow: a planner agent reads the project context and prepares acceptance criteria, technical plans, specs, slices, and PR notes; executor agents then work one approved slice at a time with minimal context.
+
+Start with dry-runs so you can inspect the provider, role, context pack, and invocation before spending model tokens:
+
+\`\`\`bash
+npm run quiver:prepare -- --dry-run
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:spec:start -- specs/${projectSlug}
+npm run quiver:ai:prompt-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:pr -- --dry-run --input specs/${projectSlug}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+\`\`\`
+
+Remove \`--dry-run\` only after the phase output is approved and the local provider CLI is ready.
+
 ## Project NPM Scripts
 
 The generated project includes \`quiver:*\` npm scripts that call the Node CLI and are the preferred repeatable workflow:
 
 \`\`\`bash
 npm run quiver:analyze
+npm run quiver:prepare -- --dry-run
 npm run quiver:plan
 npm run quiver:graph
 npm run quiver:next
 npm run quiver:doctor
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:ai:pr -- --dry-run --input specs/${projectSlug}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:spec:start -- specs/${projectSlug}
+npm run quiver:spec:status -- specs/${projectSlug}
+npm run quiver:spec:close -- specs/${projectSlug} --dry-run
 npm run quiver:migrate
 npm run quiver:start-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-slice -- specs/${projectSlug}/slices/slice-01/slice.json
@@ -281,6 +522,8 @@ npm run quiver:refresh-active-slices
 
 The \`quiver:graph\` script prints the tree view by default; use \`npx create-quiver graph --format mermaid\` for PR-ready Markdown and \`--format dot\` when you want Graphviz source.
 The \`quiver:next\` script points to the next ready slice and can auto-start it behind a confirmation prompt.
+The \`quiver:ai:*\` scripts standardize planner/executor AI flows. Use dry-run first: onboarding and planning dry-runs do not require provider auth, \`quiver:ai:execute-plan -- --dry-run --commit --mode manual\` prints manual prompts, \`--mode delegated\` prints safe waves, and \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, SSH inputs, and \`pr.md\` without creating a PR. Add \`--create\` only after reviewing the plan.
+Use \`quiver:spec:create\`, \`quiver:spec:start\`, \`quiver:spec:status\`, and \`quiver:spec:close\` for one spec generation and worktree per spec.
 Use \`npx create-quiver next --all-ready\` when you want the full ready level instead of a single suggestion.
 The legacy Bash wrappers remain in \`tools/scripts/\` for compatibility, but new project-level automation should prefer the \`quiver:*\` scripts and the direct \`npx create-quiver ...\` commands below.
 \`npm run quiver:migrate\` is only for projects that were already initialized by Quiver.
@@ -311,7 +554,7 @@ Use \`{{GRAPH_COMMAND}} --format mermaid\` for GitHub-friendly graph embeds or \
 If the project never ran Quiver initialization before, do not use \`migrate\` as bootstrap. Run:
 
 \`\`\`bash
-npx create-quiver --name "Project Name"
+npx create-quiver init --name "Project Name"
 \`\`\`
 
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
@@ -339,6 +582,8 @@ Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verda
 
 Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
 
+Usa el rol planner para onboarding, criterios de aceptación, plan técnico y generación de specs/slices. Usa el rol executor solo cuando exista un slice aprobado y debas ejecutar su handoff con contexto mínimo.
+
 No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
 
 Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
@@ -355,6 +600,8 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 ## First Slice Workflow
 
+Use this section only for projects generated with the full compatibility layout. In the default AI-first layout, create real specs and slices with \`npx create-quiver spec create\` after acceptance criteria are approved and the technical plan is reviewed and approved.
+
 1. Review or refine specs/${projectSlug}/SPEC.md.
 2. Create the first slice from specs/${projectSlug}/slices/slice-template/slice.json.
 3. Review the plan with \`{{PLAN_COMMAND}}\` or \`npm run quiver:plan\`.
@@ -392,15 +639,33 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 `;
 }
 
+function buildFullProfileIndexAppendix(projectSlug) {
+  return `## Full Profile Extras
+
+- **Multi-agent workflow** - \`./MULTI_AGENT_WORKFLOW.md\`
+- **Quick AI context** - \`./ai/QUICK.md\`
+- **Standard AI context** - \`./ai/STANDARD.md\`
+- **Deep AI context** - \`./ai/DEEP.md\`
+- **Spec starter assets** - \`../specs/${projectSlug}/\`
+- **Tool notes** - \`./tools/\`
+- **Archive** - \`./archive/\`
+`;
+}
+
 function initializeProjectDocs(options) {
   const {
     projectRoot,
     projectName,
     cliVersion,
+    includeTemplates = false,
+    legacyScripts = false,
     migrateMode = false,
+    profile = 'default',
+    templateRoot: providedTemplateRoot = '',
   } = options;
 
-  const templateRoot = path.join(projectRoot, 'docs-template');
+  const templateRoot = providedTemplateRoot || path.join(projectRoot, 'docs-template');
+  const internalPaths = quiverInternalPaths(projectRoot);
   const replacements = {
     projectName,
     projectSlug: toProjectSlug(projectName),
@@ -413,17 +678,51 @@ function initializeProjectDocs(options) {
   const dirs = [
     'docs',
     'docs/ai',
-    'docs/tools',
-    'docs/archive',
-    `specs/${replacements.projectSlug}/slices/slice-template`,
-    'tools/scripts',
+    '.quiver',
+    '.quiver/scans',
   ];
 
+  if (profile === 'full') {
+    dirs.push(
+      'docs/archive',
+      'docs/examples',
+      'docs/tools',
+      `specs/${replacements.projectSlug}/slices/slice-template`,
+      'tools/scripts',
+    );
+  } else if (legacyScripts) {
+    dirs.push('tools/scripts');
+  }
+
   for (const dir of dirs) {
     ensureDir(path.join(projectRoot, dir));
   }
 
   const operations = [];
+  if (!fs.existsSync(internalPaths.configPath)) {
+    fs.writeFileSync(internalPaths.configPath, `${JSON.stringify(buildQuiverConfig(), null, 2)}\n`);
+    operations.push({ source: 'Quiver config', destination: '.quiver/config.json', result: 'created' });
+  } else {
+    operations.push({ source: 'Quiver config', destination: '.quiver/config.json', result: 'skipped' });
+  }
+
+  fs.writeFileSync(internalPaths.gitignorePath, buildQuiverInternalGitignore());
+  operations.push({ source: 'Quiver internal gitignore', destination: '.quiver/.gitignore', result: 'updated' });
+
+  const rootGitignoreResult = mergeRootGitignore(projectRoot);
+  operations.push({ source: 'root gitignore defaults', destination: '.gitignore', result: rootGitignoreResult });
+
+  if (includeTemplates) {
+    fs.mkdirSync(internalPaths.templatesDir, { recursive: true });
+    fs.cpSync(templateRoot, internalPaths.templatesDir, {
+      recursive: true,
+      force: false,
+      errorOnExist: false,
+      preserveTimestamps: true,
+    });
+    operations.push({ source: 'packaged templates', destination: '.quiver/templates', result: 'merged' });
+  }
+
   const agentsSourcePath = path.join(templateRoot, 'AGENTS.md.template');
   if (fs.existsSync(agentsSourcePath)) {
     const agentsDestinationPath = path.join(projectRoot, 'AGENTS.md');
@@ -463,17 +762,60 @@ function initializeProjectDocs(options) {
     ['specs/[project-name]/slices/pr.md.template', `specs/${replacements.projectSlug}/slices/slice-template/pr.md.template`],
   ];
 
+  const minimalTemplateDestinations = new Set([
+    'docs/AI_CONTEXT.md',
+    'docs/AI_ONBOARDING_PROMPT.md',
+    'docs/COMMANDS.md',
+    'docs/WORKFLOW.md',
+  ]);
+  const defaultTemplateDestinations = new Set([
+    ...minimalTemplateDestinations,
+    'docs/CONTEXTO.md',
+    'docs/DECISIONS.md',
+    'docs/GITFLOW_PR_GUIDE.md',
+    'docs/INDEX.md',
+    'docs/STATUS.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/TESTING_GUIDE_FOR_AI.md',
+    'docs/TROUBLESHOOTING.md',
+    'docs/ai/LESSONS.md',
+  ]);
+
   for (const [source, destination, frontMatterFactory] of templateCopies) {
+    if (profile === 'minimal' && !minimalTemplateDestinations.has(destination)) {
+      continue;
+    }
+
+    if (profile === 'default' && !defaultTemplateDestinations.has(destination)) {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
     const destinationPath = path.join(projectRoot, destination);
+    if (!migrateMode && fs.existsSync(destinationPath)) {
+      operations.push({ source, destination, result: 'skipped' });
+      continue;
+    }
+
     const result = copyRenderedFile(sourcePath, destinationPath, replacements, migrateMode, frontMatterFactory);
     operations.push({ source, destination, result });
   }
 
+  const indexPath = path.join(projectRoot, 'docs', 'INDEX.md');
+  const indexWasCreated = operations.some((operation) => (
+    operation.destination === 'docs/INDEX.md'
+    && (operation.result === 'created' || operation.result === 'created-with-frontmatter')
+  ));
+  if (profile === 'full' && indexWasCreated && fs.existsSync(indexPath)) {
+    const currentIndex = fs.readFileSync(indexPath, 'utf8').replace(/\s+$/g, '');
+    fs.writeFileSync(indexPath, `${currentIndex}\n\n${buildFullProfileIndexAppendix(replacements.projectSlug)}`);
+    operations.push({ source: 'full profile index appendix', destination: 'docs/INDEX.md', result: 'updated' });
+  }
+
   const binaryCopies = [
     ['docs/UI_STANDARDS.md', 'docs/UI_STANDARDS.md'],
     ['docs/MOCK_DATA_GUIDE.md', 'docs/MOCK_DATA_GUIDE.md'],
@@ -497,31 +839,60 @@ function initializeProjectDocs(options) {
     ['scripts/migrate-project.sh', 'tools/scripts/migrate-project.sh'],
   ];
 
+  const alwaysBinaryDestinations = new Set([
+    'docs/ai/RULES.yaml',
+  ]);
+  const legacyScriptDestinations = new Set([
+    'tools/scripts/start-slice.sh',
+    'tools/scripts/refresh-active-slices.sh',
+    'tools/scripts/check-slice-readiness.sh',
+    'tools/scripts/check-pr-readiness.sh',
+    'tools/scripts/cleanup-slice.sh',
+    'tools/scripts/check-scope.sh',
+    'tools/scripts/migrate-project.sh',
+  ]);
+
   for (const [source, destination] of binaryCopies) {
+    if (
+      profile !== 'full'
+      && !alwaysBinaryDestinations.has(destination)
+      && !(legacyScripts && legacyScriptDestinations.has(destination))
+    ) {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     const destinationPath = path.join(projectRoot, destination);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
-    const result = copyIfSourceExists(sourcePath, destinationPath, migrateMode);
+    const result = copyIfSourceExists(sourcePath, destinationPath, true);
     operations.push({ source, destination, result });
   }
 
   const aiPrinciplesSource = path.join(templateRoot, 'docs/ai/PRINCIPLES.md');
   if (fs.existsSync(aiPrinciplesSource)) {
     const aiPrinciplesDestination = path.join(projectRoot, 'docs/ai/PRINCIPLES.md');
-    const result = copyRenderedFile(
-      aiPrinciplesSource,
-      aiPrinciplesDestination,
-      replacements,
-      migrateMode,
-      frontMatterFor('AI operating principles', 'all AI work'),
-    );
+    const result = !migrateMode && fs.existsSync(aiPrinciplesDestination)
+      ? 'skipped'
+      : copyRenderedFile(
+        aiPrinciplesSource,
+        aiPrinciplesDestination,
+        replacements,
+        migrateMode,
+        frontMatterFor('AI operating principles', 'all AI work'),
+      );
     operations.push({ source: 'docs/ai/PRINCIPLES.md', destination: 'docs/ai/PRINCIPLES.md', result });
   }
 
-  const packageResult = mergePackageJson(projectRoot, templateRoot, migrateMode);
+  const packageResult = mergePackageJson(projectRoot, templateRoot, {
+    legacyScripts,
+    migrateMode,
+    profile,
+    projectName,
+    projectSlug: replacements.projectSlug,
+  });
   operations.push({ source: 'package.template.json', destination: 'package.json', result: packageResult });
 
   const mergedPackageJsonPath = path.join(projectRoot, 'package.json');
@@ -560,12 +931,21 @@ function initializeProjectDocs(options) {
   ];
 
   for (const [source, destination] of tierCopies) {
+    if (profile !== 'full') {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
     const destinationPath = path.join(projectRoot, destination);
+    if (!migrateMode && fs.existsSync(destinationPath)) {
+      operations.push({ source, destination, result: 'skipped' });
+      continue;
+    }
+
     const result = copyRenderedFile(sourcePath, destinationPath, tierReplacements, migrateMode, ({
       body,
     }) => buildFrontMatterFields({
@@ -613,7 +993,9 @@ function initializeProjectDocs(options) {
   writeState(projectRoot, nextState);
 
   const searchPath = path.join(projectRoot, 'docs', 'SEARCH.md');
-  if (!(migrateMode && fs.existsSync(searchPath))) {
+  if (profile !== 'full') {
+    operations.push({ source: 'docs/SEARCH.md', destination: 'docs/SEARCH.md', result: 'skipped-profile' });
+  } else if (!fs.existsSync(searchPath)) {
     const searchContent = `# Búsqueda por Tema
 
 **Última actualización:** ${replacements.currentDate}
@@ -662,7 +1044,7 @@ function initializeProjectDocs(options) {
 
   const readmePath = path.join(projectRoot, 'README.md');
   if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, `${renderTemplate(buildReadme(projectName, replacements.projectSlug), replacements)}\n`);
+    fs.writeFileSync(readmePath, `${renderTemplate(buildReadme(projectName, replacements.projectSlug, profile), replacements)}\n`);
     operations.push({ source: 'README.md template', destination: 'README.md', result: 'created' });
   } else {
     operations.push({ source: 'README.md template', destination: 'README.md', result: 'skipped' });
@@ -708,8 +1090,148 @@ function installSelfAsDevDep(projectRoot, version) {
   }
 }
 
+function normalizeSkippedReason(reason) {
+  if (!reason) {
+    return 'excluded path';
+  }
+
+  if (reason === 'env-file') {
+    return 'env files';
+  }
+
+  if (reason === 'git-metadata') {
+    return '.git metadata';
+  }
+
+  if (reason === 'hidden-directory') {
+    return 'hidden directories';
+  }
+
+  if (reason.startsWith('secret-file:')) {
+    return 'secret files';
+  }
+
+  if (reason.startsWith('unsafe-segment:')) {
+    const segment = reason.slice('unsafe-segment:'.length);
+    const dependencySegments = new Set(['node_modules', '.pnpm-store', '.npm', '.yarn']);
+    const outputSegments = new Set(['dist', 'build', 'coverage', 'out', 'tmp', 'temp', 'cache', '.cache', '.turbo', '.next', '.nuxt', '.parcel-cache', 'generated', 'gen', 'artifacts', 'reports', 'vendor', 'target']);
+
+    if (segment === '.quiver') {
+      return 'local AI state';
+    }
+
+    if (dependencySegments.has(segment)) {
+      return 'dependency folders';
+    }
+
+    if (outputSegments.has(segment)) {
+      return 'generated/output/cache folders';
+    }
+
+    return segment;
+  }
+
+  return reason;
+}
+
+function summarizeSkippedPaths(skippedPathDetails = [], skippedPaths = []) {
+  const counts = new Map();
+
+  const items = Array.isArray(skippedPathDetails) && skippedPathDetails.length > 0
+    ? skippedPathDetails
+    : skippedPaths.map((item) => ({ path: item, reason: 'excluded path' }));
+
+  for (const item of items) {
+    const label = normalizeSkippedReason(item.reason);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+
+  return Array.from(counts.entries()).map(([label, count]) => ({ label, count }));
+}
+
+function renderAiContextDoc(scan, options = {}) {
+  const projectName = scan?.project?.name || 'Quiver Project';
+  const projectSlug = options.projectSlug || toProjectSlug(projectName);
+  const stack = scan?.stack || {};
+  const commands = scan?.commands || {};
+  const common = commands.common || {};
+  const summaries = summarizeSkippedPaths(scan?.skipped_path_details, scan?.skipped_paths);
+  const risks = Array.isArray(scan?.risks) ? scan.risks : [];
+  const hasReadme = scan?.docs?.has_readme ? 'yes' : 'no';
+  const hasWorkflow = scan?.ci?.has_ci ? 'yes' : 'no';
+  const sourceDirs = Array.isArray(scan?.structure?.source_directories) ? scan.structure.source_directories : [];
+
+  const lines = [];
+  lines.push(`# ${projectName} AI Context`);
+  lines.push('');
+  lines.push('This file is refreshed by `npx create-quiver analyze`.');
+  lines.push('Use `docs/PROJECT_MAP.md` for stack and command details, and `.quiver/scans/PROJECT_SCAN.json` only when raw analyzer data is needed.');
+  lines.push('');
+  lines.push('## Snapshot');
+  lines.push(`- Primary stack: ${stack.primary || 'unknown'}`);
+  lines.push('- Package manager source: `docs/PROJECT_MAP.md`');
+  lines.push(`- Install: ${commands.install || 'not defined'}`);
+  lines.push(`- Dev: ${common.dev || 'not defined'}`);
+  lines.push(`- Build: ${common.build || 'not defined'}`);
+  lines.push(`- Test: ${common.test || 'not defined'}`);
+  lines.push(`- README present: ${hasReadme}`);
+  lines.push(`- GitHub Actions workflows: ${hasWorkflow}`);
+  lines.push(`- Source directories: ${sourceDirs.length > 0 ? sourceDirs.join(', ') : 'none detected'}`);
+  lines.push('');
+  lines.push('## Read First');
+  lines.push('- `docs/PROJECT_MAP.md`');
+  lines.push('- `docs/WORKFLOW.md`');
+  lines.push('- `docs/AI_ONBOARDING_PROMPT.md`');
+  lines.push('- `docs/CONTEXTO.md`');
+  lines.push('- `docs/DECISIONS.md`');
+  lines.push(`- specs/${projectSlug}/SPEC.md`);
+  lines.push('');
+  lines.push('## Assumptions and Missing Info');
+  if (risks.length > 0) {
+    for (const risk of risks) {
+      lines.push(`- ${risk}`);
+    }
+  } else {
+    lines.push('- No major repository signals are missing.');
+  }
+  lines.push('- Do not infer product or business rules that are not present in the repository.');
+  lines.push('');
+  lines.push('## Exclusions');
+  if (summaries.length > 0) {
+    for (const item of summaries) {
+      lines.push(`- ${item.label}: ${item.count}`);
+    }
+  } else {
+    lines.push('- No exclusions were needed.');
+  }
+  lines.push('');
+  lines.push('## Internal Artifacts');
+  lines.push('- Visible source: `docs/PROJECT_MAP.md`');
+  lines.push('- Internal raw scan: `.quiver/scans/PROJECT_SCAN.json`');
+  lines.push('');
+  const body = lines.join('\n');
+  const frontMatter = serializeFrontMatter(buildFrontMatterFields({
+    purpose: 'Agent-facing project context pack',
+    appliesWhen: 'after analyze, onboarding, implementation, review',
+    body,
+    currentDate: options.currentDate || new Date().toISOString().slice(0, 10),
+  }));
+
+  return `${frontMatter}\n\n${body}`;
+}
+
+function refreshAiContextDoc(projectRoot, scan, options = {}) {
+  const destinationPath = path.join(projectRoot, 'docs', 'AI_CONTEXT.md');
+  fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+  fs.writeFileSync(destinationPath, `${renderAiContextDoc(scan, options)}\n`);
+  return destinationPath;
+}
+
 module.exports = {
   initializeProjectDocs,
+  refreshAiContextDoc,
+  renderAiContextDoc,
+  summarizeSkippedPaths,
   writeFrontMatter,
   toProjectSlug,
   detectPackageManager,