@basou/cli 0.31.0 → 0.32.0

package/dist/program.js

@@ -3658,13 +3658,17 @@ import {
   readMarkdownFile as readMarkdownFile4,
   reconcileSourceRoots,
   removeMarkerSection,
+  renderAnchorStarter,
+  renderViewPresetBlock,
   renderWithMarkers as renderWithMarkers4,
   resolveRepositoryRoot as resolveRepositoryRoot8,
   safeSimpleGit,
+  seedMarkers,
   summarizePresetPlan,
   summarizeRosterDrift,
   summarizeSymlinkPlan,
   summarizeWiring,
+  summarizeWiringDrift,
   unknownManifestKeys,
   writeManifest as writeManifest2,
   writeMarkdownFile as writeMarkdownFile5
@@ -3674,7 +3678,7 @@ var CANONICAL_FILE = "AGENTS.md";
 function registerProjectCommand(program) {
   const project = program.command("project").description("Inspect a project's declared repo roster (read-only)");
   project.command("check").description(
-    "Compare the declared repo roster (manifest `repos`) against the capture config (`source_roots`) and surface drift (read-only, advisory)"
+    "Surface project drift (read-only, advisory): the declared repo roster (manifest `repos`) vs the capture config (`source_roots`), AND the instruction-file wiring vs basou's native topology \u2014 a missing AGENTS.md canonical (repo or workspace view), incomplete spokes, conflicts, or collisions"
   ).option("--json", "Output the result as JSON").option("-v, --verbose", "Show error causes").action(async (opts) => {
     await runProjectCheck(opts);
   });
@@ -3749,8 +3753,11 @@ function registerProjectCommand(program) {
   project.command("new").argument("[repos...]", "Extra repo paths (besides the anchor) to seed into the roster").description(
     "Scaffold a new project from scratch at the current Git repository (the anchor): create `.basou/` and seed the manifest with a candidate `repos` roster (the anchor plus any given repos, which must already be git repositories) and a `workspace.view` placeholder. Dry-run by default; pass --apply to write. Pass --no-view for a solo project. The greenfield entry point \u2014 declare visibility/language per repo afterward, then run `basou project derive --apply` to materialize the wiring"
   ).option("--apply", "Create `.basou/` and write the seeded manifest (default: dry-run preview)").option(
+    "--project-name <name>",
+    "The project's product name (a simple name \u2014 letters, digits, '.', '-', '_'): sets `project.name` and the default view path (a `<name>-workspace` sibling). Omit to fall back to the anchor directory name; use --view for a custom view path"
+  ).option(
     "--view <path>",
-    "Override the workspace view path (default: a <name>-workspace sibling)"
+    "Override the workspace view path (default: a `<name>-workspace` sibling, where <name> is --project-name or the anchor directory name)"
   ).option("--no-view", "Solo project: declare no workspace view").option(
     "--local-only",
     "Write a .basou/ full-exclude .gitignore block (keep the trail out of version control) instead of the default ignore+commit block"
@@ -3763,10 +3770,10 @@ function registerProjectCommand(program) {
     await runProjectDerive(opts);
   });
   project.command("retrofit").argument(
-    "<repo>",
-    "The declared roster repo whose hand-authored AGENTS.md to relocate (e.g. ../foo)"
+    "[repo]",
+    "The declared roster repo whose hand-authored AGENTS.md to relocate (e.g. ../foo). Omit to run only the workspace view's canonical auto-migration"
   ).description(
-    "Fold an existing repo's hand-authored AGENTS.md into the project topology: move the repo's regular-file `AGENTS.md` to the anchor canonical (`agents/<repo>/AGENTS.md`) and replace it with a symlink, so the prose lives at the single source of truth. Dry-run by default; pass --apply to relocate. The onboarding counterpart to `new` for a repo that already carries its own AGENTS.md \u2014 run it before `basou project derive`, which then adds the preset block, the CLAUDE.md / Copilot spokes, and the .gitignore. Non-destructive: it refuses when the destination canonical already exists (it never clobbers it), and skips a repo whose AGENTS.md is already a symlink or absent. The anchor (`.`) is refused"
+    "Fold an existing repo's hand-authored AGENTS.md into the project topology: move the repo's regular-file `AGENTS.md` to the anchor canonical (`agents/<repo>/AGENTS.md`) and replace it with a symlink, so the prose lives at the single source of truth. Dry-run by default; pass --apply to relocate. The onboarding counterpart to `new` for a repo that already carries its own AGENTS.md \u2014 run it before `basou project derive`, which then adds the preset block, the CLAUDE.md / Copilot spokes, and the .gitignore. Non-destructive: it refuses when the destination canonical already exists (it never clobbers it), and skips a repo whose AGENTS.md is already a symlink or absent. The anchor (`.`) is refused. The workspace view's own canonical is auto-migrated when it is markerless prose (the generated block is prepended, the prose kept): omit the repo argument to perform that migration \u2014 a repo-argument run only reports it"
   ).option(
     "--apply",
     "Relocate the AGENTS.md to the canonical and recreate the symlink (default: dry-run preview)"
@@ -3797,18 +3804,39 @@ async function doRunProjectCheck(options, ctx) {
   const repositoryRoot = await resolveBasouRootForCommand(cwd, "project check");
   const paths = basouPaths10(repositoryRoot);
   const manifest = await readManifest6(paths);
-  const summary = summarizeRosterDrift({
+  const roster = summarizeRosterDrift({
     ...manifest.repos !== void 0 ? { repos: manifest.repos } : {},
     sourceRoots: effectiveSourceRoots(manifest)
   });
+  let wiring;
+  const rosterRepos2 = manifest.repos ?? [];
+  if (rosterRepos2.length > 0) {
+    const anchorReal = realpathSync(repositoryRoot);
+    const repoFacts = rosterRepos2.map(
+      (entry) => gatherRepoSymlinks(repositoryRoot, anchorReal, entry)
+    );
+    let view = { kind: "no-view" };
+    const viewPath = manifest.workspace.view;
+    if (viewPath !== void 0) {
+      const viewDir = resolveViewDir(repositoryRoot, viewPath);
+      view = gatherViewSymlinks(repositoryRoot, anchorReal, rosterRepos2, viewDir);
+    }
+    wiring = summarizeWiringDrift({ repos: repoFacts, view });
+  }
+  const result = {
+    roster,
+    ...wiring !== void 0 ? { wiring } : {},
+    ok: roster.ok && (wiring?.ok ?? true)
+  };
   if (options.json === true) {
-    console.log(JSON.stringify(summary));
+    console.log(JSON.stringify(result));
   } else {
-    console.log(renderProjectCheck(summary));
+    console.log(renderProjectCheck(result));
   }
-  return summary;
+  return result;
 }
-function renderProjectCheck(summary) {
+function renderProjectCheck(result) {
+  const summary = result.roster;
   const lines = [];
   lines.push("# Project composition check (declared vs captured)");
   lines.push("");
@@ -3843,8 +3871,58 @@ function renderProjectCheck(summary) {
     for (const p of summary.extra) lines.push(`- ${p}`);
     lines.push("");
   }
+  const w = result.wiring;
+  if (w !== void 0) {
+    lines.push("## Instruction-file wiring drift (declared topology vs on-disk)");
+    if (w.ok) {
+      lines.push(
+        "\u2705 Every present repo's and the view's instruction files (AGENTS.md + spokes) are wired as declared."
+      );
+    } else {
+      if (w.missingCanonicals.length > 0) {
+        lines.push(`\u26A0\uFE0F Missing instruction canonical (AGENTS.md): ${w.missingCanonicals.length}`);
+        for (const m of w.missingCanonicals) {
+          const where = m.target === "view" ? `view "${m.name}"` : m.target === "repo-self" ? `${m.name} (self)` : m.name;
+          lines.push(`- ${where} \u2014 canonical AGENTS.md absent`);
+        }
+      }
+      if (w.incompleteWiring.length > 0) {
+        lines.push(
+          `\u26A0\uFE0F Incomplete wiring (canonical present, spokes missing): ${w.incompleteWiring.length}`
+        );
+        for (const i of w.incompleteWiring) {
+          const where = i.target === "view" ? `view "${i.path}"` : i.path;
+          lines.push(`- ${where}: ${i.files.join(", ")}`);
+        }
+      }
+      if (w.conflicts.length > 0) {
+        lines.push(
+          `\u26A0\uFE0F Wiring conflicts (existing file/link, left untouched): ${w.conflicts.length}`
+        );
+        for (const c of w.conflicts) {
+          const where = c.target === "view" ? `view "${c.path}"` : c.path;
+          const detail = c.reason === "mismatch" && c.actualTarget !== void 0 ? `mismatch -> ${c.actualTarget}` : c.reason;
+          lines.push(`- ${where} ${c.file}: ${detail}`);
+        }
+      }
+      if (w.collisions.length > 0) {
+        lines.push(`\u26A0\uFE0F Canonical-name collisions (ambiguous, not wired): ${w.collisions.length}`);
+        for (const c of w.collisions) {
+          const who = c.view === true ? `${c.repos.join(", ")} + view` : c.repos.join(", ");
+          lines.push(`- agents/${c.canonicalName}/AGENTS.md <- ${who}`);
+        }
+      }
+    }
+    if (w.unreachable.length > 0) {
+      lines.push(
+        `\u2139\uFE0F Declared repos not present on this machine (advisory \u2014 not counted as drift): ${w.unreachable.length}`
+      );
+      for (const u of w.unreachable) lines.push(`- ${u}`);
+    }
+    lines.push("");
+  }
   lines.push(
-    "Note: read-only advisory. It only shows the difference between the declaration (repos) and the capture config (source_roots); it does not enforce."
+    "Note: read-only advisory. It shows the difference between the declaration (repos) and the capture config (source_roots), and the instruction-file wiring vs basou's native topology; it does not enforce or generate."
   );
   return lines.join("\n");
 }
@@ -4298,6 +4376,17 @@ function inspectSymlink(filePath, expectedTarget) {
   const actual = readlinkSync(filePath);
   return actual === expectedTarget ? { state: "correct" } : { state: "mismatch", actualTarget: actual };
 }
+function anchorCanonicalState(filePath) {
+  let st;
+  try {
+    st = lstatSync(filePath);
+  } catch (error) {
+    if (hasErrorCode(error) && error.code === "ENOENT") return "absent";
+    return "broken";
+  }
+  if (st.isSymbolicLink()) return existsSync(filePath) ? "usable" : "broken";
+  return st.isFile() ? "usable" : "broken";
+}
 function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
   const mode = instructionMode(entry);
   const isSelf = mode === "self";
@@ -4309,7 +4398,42 @@ function gatherRepoSymlinks(repositoryRoot, anchorReal, entry) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
   }
   if (real === anchorReal) {
-    return { ...base, isAnchor: true, reachable: true, canonicalPresent: false, files: [] };
+    const anchorCanonical = join9(real, CANONICAL_FILE);
+    const anchorState = anchorCanonicalState(anchorCanonical);
+    if (anchorState === "absent") {
+      return { ...base, isAnchor: true, reachable: true, canonicalPresent: false, files: [] };
+    }
+    if (anchorState === "broken") {
+      return {
+        ...base,
+        isAnchor: true,
+        reachable: true,
+        canonicalPresent: true,
+        canonicalName: basename5(real),
+        files: [{ name: CANONICAL_FILE, expectedTarget: CANONICAL_FILE, state: "blocked" }]
+      };
+    }
+    const anchorFiles = expectedSymlinkTargets(
+      real,
+      anchorCanonical,
+      "self"
+    ).map((spec) => {
+      const { state, actualTarget } = inspectSymlink(join9(real, spec.name), spec.target);
+      return {
+        name: spec.name,
+        expectedTarget: spec.target,
+        state,
+        ...actualTarget !== void 0 ? { actualTarget } : {}
+      };
+    });
+    return {
+      ...base,
+      isAnchor: true,
+      reachable: true,
+      canonicalPresent: true,
+      canonicalName: basename5(real),
+      files: anchorFiles
+    };
   }
   if (!existsSync(join9(real, ".git"))) {
     return { ...base, isAnchor: false, reachable: false, canonicalPresent: false, files: [] };
@@ -4363,6 +4487,53 @@ function applySymlinkPlan(repositoryRoot, plan) {
 function failureReason(error) {
   return hasErrorCode(error) ? error.code : "unknown error";
 }
+function viewCanonicalCollision(repositoryRoot, roster, viewName) {
+  for (const entry of roster) {
+    let name;
+    try {
+      name = basename5(realpathSync(resolve7(repositoryRoot, entry.path)));
+    } catch {
+      name = basename5(resolve7(repositoryRoot, entry.path));
+    }
+    if (name === viewName) return entry.path;
+  }
+  return void 0;
+}
+function gatherViewSymlinks(repositoryRoot, anchorReal, roster, viewDir) {
+  const viewName = basename5(viewDir);
+  const collision = viewCanonicalCollision(repositoryRoot, roster, viewName);
+  if (collision !== void 0) return { kind: "collision", viewName, repoPath: collision };
+  const canonicalFile = canonicalFileFor(anchorReal, viewName);
+  if (!existsSync(canonicalFile)) return { kind: "missing-canonical", viewName };
+  const files = expectedSymlinkTargets(viewDir, canonicalFile, "hub").map(
+    (spec) => {
+      const { state, actualTarget } = inspectSymlink(join9(viewDir, spec.name), spec.target);
+      return {
+        name: spec.name,
+        expectedTarget: spec.target,
+        state,
+        ...actualTarget !== void 0 ? { actualTarget } : {}
+      };
+    }
+  );
+  return { kind: "gathered", viewName, files };
+}
+function applyViewSymlinks(viewDir, files) {
+  const created = [];
+  const failed = [];
+  for (const f of files) {
+    if (f.state !== "missing") continue;
+    const filePath = join9(viewDir, f.name);
+    try {
+      mkdirSync(dirname3(filePath), { recursive: true });
+      symlinkSync(f.expectedTarget, filePath);
+      created.push(f.name);
+    } catch (error) {
+      failed.push({ file: f.name, message: failureReason(error) });
+    }
+  }
+  return { created, failed };
+}
 async function doRunProjectSymlinks(options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveBasouRootForCommand(cwd, "project symlinks");
@@ -4382,11 +4553,33 @@ async function doRunProjectSymlinks(options, ctx) {
       for (const f of failed) failures.push({ repo: plan.path, file: f.file, message: f.message });
     }
   }
+  let view;
+  let viewCreated = [];
+  const viewFailures = [];
+  if (roster.length > 0) {
+    const viewPath = manifest.workspace.view;
+    if (viewPath === void 0) {
+      view = { kind: "no-view" };
+    } else {
+      const viewDir = resolveViewDir(repositoryRoot, viewPath);
+      view = gatherViewSymlinks(repositoryRoot, anchorReal, roster, viewDir);
+      if (options.apply === true && view.kind === "gathered") {
+        const { created, failed } = applyViewSymlinks(viewDir, view.files);
+        viewCreated = created;
+        for (const f of failed) viewFailures.push(f);
+      }
+    }
+  }
+  const viewClean = view === void 0 || view.kind === "no-view" || view.kind === "gathered" && view.files.every((f) => f.state === "correct");
   const result = {
     ...summary,
+    ok: summary.ok && viewClean,
     hasRoster: roster.length > 0,
     applied: createdCount > 0,
-    failures
+    failures,
+    ...view !== void 0 ? { view } : {},
+    viewCreated,
+    viewFailures
   };
   if (options.json === true) {
     console.log(JSON.stringify(result));
@@ -4434,7 +4627,7 @@ function renderProjectSymlinks(result) {
     );
   } else {
     lines.push(
-      "\u2139\uFE0F No symlink needs generating, but there are conflicts / collisions / a missing canonical / unreachable repos (see below)."
+      "\u2139\uFE0F No repo symlink needs generating, but there are conflicts / collisions / a missing canonical / unreachable repos, or the workspace view's spokes need attention (see below)."
     );
   }
   lines.push("");
@@ -4483,11 +4676,61 @@ function renderProjectSymlinks(result) {
     for (const p of result.unreachable) lines.push(`- ${p}`);
     lines.push("");
   }
+  appendViewSymlinksSection(lines, result);
   lines.push(
     "Note: an existing file or a symlink pointing elsewhere is never overwritten; only the missing links are created (GEMINI.md is discontinued and not generated)."
   );
   return lines.join("\n");
 }
+function appendViewSymlinksSection(lines, result) {
+  const view = result.view;
+  if (view === void 0 || view.kind === "no-view") return;
+  lines.push("## Workspace view spokes (the view's own instruction files)");
+  if (view.kind === "collision") {
+    lines.push(
+      `\u26A0\uFE0F ${view.viewName}: the view shares its canonical name with the roster repo \`${view.repoPath}\` \u2014 both would own \`agents/${view.viewName}/${CANONICAL_FILE}\`, so no view spoke is wired. Rename the view directory or the repo to disambiguate, then re-run.`
+    );
+    lines.push("");
+    return;
+  }
+  if (view.kind === "missing-canonical") {
+    lines.push(
+      `\u2139\uFE0F ${view.viewName}: the view canonical \`agents/${view.viewName}/${CANONICAL_FILE}\` does not exist yet \u2014 run \`basou project preset --apply\` first (or \`basou project derive --apply\`), then re-run.`
+    );
+    lines.push("");
+    return;
+  }
+  const failedFiles = new Set(result.viewFailures.map((f) => f.file));
+  const missing = view.files.filter((f) => f.state === "missing");
+  const attempted = result.viewCreated.length > 0 || result.viewFailures.length > 0;
+  if (missing.length === 0) {
+    lines.push(`\u2705 ${view.viewName}: the view's instruction spokes are correctly wired.`);
+  } else if (!attempted) {
+    lines.push(`${view.viewName}: view spokes to create (dry-run; pass --apply to write):`);
+    for (const f of missing) lines.push(`    ${f.name} -> ${f.expectedTarget}`);
+  } else {
+    lines.push(`${view.viewName}: view spokes created:`);
+    for (const f of missing) {
+      if (failedFiles.has(f.name)) continue;
+      lines.push(`    ${f.name} -> ${f.expectedTarget}`);
+    }
+  }
+  if (result.viewFailures.length > 0) {
+    lines.push(`  Failed:`);
+    for (const f of result.viewFailures) lines.push(`    ${f.file}: ${f.message}`);
+  }
+  const conflicts = view.files.filter(
+    (f) => f.state === "mismatch" || f.state === "occupied" || f.state === "blocked"
+  );
+  if (conflicts.length > 0) {
+    lines.push(`  Conflicts (left untouched):`);
+    for (const f of conflicts) {
+      const detail = f.state === "mismatch" ? `points elsewhere (currently: ${f.actualTarget ?? "?"})` : f.state === "occupied" ? "a real file/directory" : "an uninspectable path";
+      lines.push(`    ${f.name}: ${detail}`);
+    }
+  }
+  lines.push("");
+}
 async function runProjectWorkspace(options, ctx = {}) {
   try {
     await doRunProjectWorkspace(options, ctx);
@@ -4878,6 +5121,86 @@ async function gatherRepoPreset(repositoryRoot, anchorReal, entry) {
     ...section.kind === "ok" ? { currentBlock: section.generated } : {}
   };
 }
+function normalizeViewBlock(s) {
+  return s.replace(/\r\n/g, "\n").replace(/\n+$/, "");
+}
+function viewPresetReposFor(repositoryRoot, roster) {
+  let anchorReal;
+  try {
+    anchorReal = realpathSync(repositoryRoot);
+  } catch {
+    anchorReal = void 0;
+  }
+  return roster.map((entry) => {
+    const abs = resolve7(repositoryRoot, entry.path);
+    let real;
+    try {
+      real = realpathSync(abs);
+    } catch {
+      real = void 0;
+    }
+    const name = basename5(real ?? abs);
+    const isAnchor = real !== void 0 && anchorReal !== void 0 ? real === anchorReal : abs === repositoryRoot;
+    return {
+      name,
+      ...entry.visibility !== void 0 ? { visibility: entry.visibility } : {},
+      ...entry.language !== void 0 ? { language: entry.language } : {},
+      ...isAnchor ? { anchor: true } : instructionMode(entry) === "self" ? { self: true } : {}
+    };
+  });
+}
+function gatherViewPreset(repositoryRoot, anchorReal, viewName, roster) {
+  const collision = viewCanonicalCollision(repositoryRoot, roster, viewName);
+  if (collision !== void 0) return { kind: "collision", viewName, repoPath: collision };
+  const desiredBlock = renderViewPresetBlock({
+    viewName,
+    repos: viewPresetReposFor(repositoryRoot, roster)
+  });
+  const canonicalFile = canonicalFileFor(anchorReal, viewName);
+  let content;
+  try {
+    content = readFileSync(canonicalFile, "utf8");
+  } catch (error) {
+    if (hasErrorCode(error) && error.code === "ENOENT") {
+      return {
+        kind: "plan",
+        action: "create",
+        canonicalName: viewName,
+        viewName,
+        block: desiredBlock
+      };
+    }
+    return { kind: "unreadable", canonicalName: viewName, viewName };
+  }
+  const section = parseMarkers(content);
+  if (section.kind === "ok") {
+    if (normalizeViewBlock(section.generated) === normalizeViewBlock(desiredBlock)) {
+      return { kind: "in-sync", canonicalName: viewName, viewName };
+    }
+    return {
+      kind: "plan",
+      action: "update",
+      canonicalName: viewName,
+      viewName,
+      block: desiredBlock
+    };
+  }
+  return { kind: "conflict", canonicalName: viewName, viewName, reason: section.kind };
+}
+async function applyViewPreset(anchorReal, outcome) {
+  const file = canonicalFileFor(anchorReal, outcome.canonicalName);
+  const label = canonicalLabelFor(outcome.canonicalName);
+  let isLink = false;
+  try {
+    isLink = lstatSync(file).isSymbolicLink();
+  } catch {
+    isLink = false;
+  }
+  if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
+  if (outcome.action === "create") mkdirSync(dirname3(file), { recursive: true });
+  const existing = await readMarkdownFile4(file);
+  await writeMarkdownFile5(file, renderWithMarkers4(existing, outcome.block, label));
+}
 async function applyPresetPlan(anchorReal, plan) {
   const file = canonicalFileFor(anchorReal, plan.canonicalName);
   const label = canonicalLabelFor(plan.canonicalName);
@@ -4910,7 +5233,12 @@ async function doRunProjectPreset(options, ctx) {
   const anchorReal = realpathSync(repositoryRoot);
   const facts = [];
   for (const entry of roster) facts.push(await gatherRepoPreset(repositoryRoot, anchorReal, entry));
-  const summary = summarizePresetPlan(facts);
+  const viewPath = manifest.workspace.view;
+  const viewCanonicalName = roster.length > 0 && viewPath !== void 0 ? basename5(resolveViewDir(repositoryRoot, viewPath)) : void 0;
+  const summary = summarizePresetPlan(
+    facts,
+    viewCanonicalName !== void 0 ? { viewCanonicalName } : void 0
+  );
   const failures = [];
   let writtenCount = 0;
   if (options.apply === true && summary.plans.length > 0) {
@@ -4923,11 +5251,30 @@ async function doRunProjectPreset(options, ctx) {
       }
     }
   }
+  let view;
+  let viewApplied = false;
+  let viewFailure;
+  if (roster.length > 0) {
+    view = viewCanonicalName === void 0 ? { kind: "no-view" } : gatherViewPreset(repositoryRoot, anchorReal, viewCanonicalName, roster);
+    if (options.apply === true && view.kind === "plan") {
+      try {
+        await applyViewPreset(anchorReal, view);
+        viewApplied = true;
+      } catch (error) {
+        viewFailure = presetFailureReason(error);
+      }
+    }
+  }
+  const viewClean = view === void 0 || view.kind === "no-view" || view.kind === "in-sync";
   const result = {
     ...summary,
+    ok: summary.ok && viewClean,
     hasRoster: roster.length > 0,
     applied: writtenCount > 0,
-    failures
+    failures,
+    ...view !== void 0 ? { view } : {},
+    viewApplied,
+    ...viewFailure !== void 0 ? { viewFailure } : {}
   };
   if (options.json === true) {
     console.log(JSON.stringify(result));
@@ -4980,7 +5327,7 @@ function renderProjectPreset(result) {
     );
   } else {
     lines.push(
-      "\u2139\uFE0F No repo needs generating, but there are marker conflicts / collisions / undeclared / unreachable repos (see below)."
+      "\u2139\uFE0F No repo needs generating, but there are marker conflicts / collisions / undeclared / unreachable repos, or the workspace view canonical needs attention (see below)."
     );
   }
   lines.push("");
@@ -5017,10 +5364,11 @@ function renderProjectPreset(result) {
   }
   if (result.collisions.length > 0) {
     lines.push(
-      `## Canonical collisions (${result.collisions.length}) \u2014 another repo shares the same-named canonical (not auto-generated)`
+      `## Canonical collisions (${result.collisions.length}) \u2014 another repo (or the workspace view) shares the same-named canonical (not auto-generated)`
     );
     for (const c of result.collisions) {
-      lines.push(`- agents/${c.canonicalName}/AGENTS.md \u2190 ${c.repos.join(", ")}`);
+      const suffix = c.view === true ? " + the workspace view (rename the view directory or the repo to disambiguate)" : "";
+      lines.push(`- agents/${c.canonicalName}/AGENTS.md \u2190 ${c.repos.join(", ")}${suffix}`);
     }
     lines.push("");
   }
@@ -5050,11 +5398,46 @@ function renderProjectPreset(result) {
     for (const p of result.unreachable) lines.push(`- ${p}`);
     lines.push("");
   }
+  appendViewPresetSection(lines, result);
   lines.push(
     "Note: only the marker region is generated; the canonical's hand-authored content (outside the markers) is preserved. The generated content is derived from the manifest declaration."
   );
   return lines.join("\n");
 }
+function appendViewPresetSection(lines, result) {
+  const view = result.view;
+  if (view === void 0 || view.kind === "no-view") return;
+  const canonical2 = canonicalLabelFor(view.viewName);
+  lines.push("## Workspace view canonical (the view's own AGENTS.md)");
+  if (view.kind === "collision") {
+    lines.push(
+      `\u26A0\uFE0F ${view.viewName}: shares its canonical name with the roster repo \`${view.repoPath}\` \u2014 both would own ${canonical2}, so neither side is generated. Rename the view directory or the repo to disambiguate, then re-run.`
+    );
+  } else if (view.kind === "in-sync") {
+    lines.push(`\u2705 ${view.viewName}: in sync with ${canonical2} (nothing to generate).`);
+  } else if (view.kind === "plan") {
+    if (result.viewApplied) {
+      lines.push(`\u2705 ${view.viewName} [${view.action}] \u2192 ${canonical2}`);
+    } else if (result.viewFailure !== void 0) {
+      lines.push(`- ${view.viewName} [${view.action}] \u2192 ${canonical2}: ${result.viewFailure}`);
+    } else {
+      lines.push(
+        `- ${view.viewName} [${view.action}] \u2192 ${canonical2} (dry-run; pass --apply to write):`
+      );
+      for (const bl of view.block.split("\n")) lines.push(`    ${bl}`);
+    }
+  } else if (view.kind === "conflict") {
+    const detail = view.reason === "no_markers" ? "no marker region" : `malformed markers (${view.reason})`;
+    lines.push(
+      `\u26A0\uFE0F ${view.viewName}: ${canonical2} has ${detail}, so it is not overwritten. Add \`${GENERATED_START}\` / \`${GENERATED_END}\` where the block should go (or run \`basou project retrofit\` to prepend it, preserving your prose).`
+    );
+  } else {
+    lines.push(
+      `\u26A0\uFE0F ${view.viewName}: ${canonical2} could not be read (a directory, permissions, etc.). Resolve it by hand, then re-run.`
+    );
+  }
+  lines.push("");
+}
 async function runProjectArchive(target, options, ctx = {}) {
   try {
     await doRunProjectArchive(target, options, ctx);
@@ -5837,10 +6220,21 @@ async function resolveRepositoryRootForNew(cwd) {
     throw error;
   }
 }
+function validateProjectName(name) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+    throw new Error(
+      `Invalid --project-name "${name}": use a simple name (letters, digits, '.', '-', '_'; starting with a letter or digit; no spaces or path separators). For a custom view path, use --view.`
+    );
+  }
+  return name;
+}
 async function doRunProjectNew(repos, options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveRepositoryRootForNew(cwd);
   const workspaceName = basename5(repositoryRoot);
+  const productName = options.projectName !== void 0 ? validateProjectName(options.projectName) : void 0;
+  const viewStem = productName ?? workspaceName;
+  const viewOverridesProjectName = productName !== void 0 && typeof options.view === "string";
   const declared = repos.map((p) => {
     const abs = resolve7(cwd, p);
     let real;
@@ -5865,11 +6259,15 @@ async function doRunProjectNew(repos, options, ctx) {
     if (rel !== "." && !rosterPaths.includes(rel)) rosterPaths.push(rel);
   }
   const roster = rosterPaths.map((path) => ({ path }));
-  const viewPath = options.view === false ? null : options.view ?? `../${workspaceName}-workspace`;
+  const viewPath = options.view === false ? null : options.view ?? `../${viewStem}-workspace`;
   const sourceRoots = [...rosterPaths, ...viewPath !== null ? [viewPath] : []];
   const paths = basouPaths10(repositoryRoot);
   const existed = existsSync(paths.files.manifest);
-  const manifest = createManifest2({ workspaceName, sourceRoots });
+  const manifest = createManifest2({
+    workspaceName,
+    sourceRoots,
+    ...productName !== void 0 ? { projectName: productName } : {}
+  });
   manifest.repos = roster;
   if (viewPath !== null) manifest.workspace.view = viewPath;
   let applied = false;
@@ -5885,8 +6283,10 @@ async function doRunProjectNew(repos, options, ctx) {
   }
   const result = {
     workspaceName,
+    projectName: productName ?? null,
     repos: roster,
     view: viewPath,
+    viewOverridesProjectName,
     sourceRoots,
     invalidRepos: [],
     existed,
@@ -5919,11 +6319,12 @@ function renderProjectNew(result) {
     );
     lines.push("");
   }
+  const identity = result.projectName ?? result.workspaceName;
   if (result.applied) {
-    lines.push(`\u2705 Created \`.basou/\` for \`${result.workspaceName}\` and seeded the manifest:`);
+    lines.push(`\u2705 Created \`.basou/\` for \`${identity}\` and seeded the manifest:`);
   } else {
     lines.push(
-      `Will create \`.basou/\` for \`${result.workspaceName}\` and seed the manifest (dry-run; pass --apply to write):`
+      `Will create \`.basou/\` for \`${identity}\` and seed the manifest (dry-run; pass --apply to write):`
     );
   }
   lines.push("");
@@ -5932,9 +6333,16 @@ function renderProjectNew(result) {
     lines.push(`- ${r.path}${r.path === "." ? " (anchor)" : ""}`);
   }
   lines.push("");
+  if (result.projectName !== null) {
+    lines.push(`project name: ${result.projectName}`);
+    lines.push("");
+  }
   lines.push(
     result.view !== null ? `workspace view: ${result.view}` : "workspace view: none (solo project)"
   );
+  if (result.viewOverridesProjectName) {
+    lines.push("  (note: --view set this path, so --project-name did not drive the view name)");
+  }
   lines.push("");
   lines.push(`source_roots (${result.sourceRoots.length}):`);
   for (const s of result.sourceRoots) lines.push(`- ${s}`);
@@ -5980,25 +6388,79 @@ async function doRunProjectDerive(options, ctx) {
   const stepOpts = { apply };
   console.log("# Generate project wiring in one pass (declaration \u2192 wiring)");
   console.log("");
-  console.log("## 1/5 sync source_roots (roster \u2192 capture config)");
+  console.log("## 1/6 sync source_roots (roster \u2192 capture config)");
   await doRunProjectSync(stepOpts, stepCtx);
   console.log("");
-  console.log("## 2/5 generate instruction-file A preset (declaration \u2192 canonical)");
+  console.log("## 2/6 generate instruction-file A preset (declaration \u2192 canonical)");
   await doRunProjectPreset(stepOpts, stepCtx);
   console.log("");
-  console.log("## 3/5 generate instruction-file symlinks (each repo \u2192 canonical)");
+  console.log("## 3/6 seed the anchor's own AGENTS.md (greenfield only; create-only)");
+  await doRunProjectSeedAnchor(stepOpts, stepCtx);
+  console.log("");
+  console.log("## 4/6 generate instruction-file symlinks (each repo \u2192 canonical)");
   await doRunProjectSymlinks(stepOpts, stepCtx);
   console.log("");
-  console.log("## 4/5 generate workspace view (aggregate the roster repos)");
+  console.log("## 5/6 generate workspace view (aggregate the roster repos)");
   await doRunProjectWorkspace(stepOpts, stepCtx);
   console.log("");
-  console.log("## 5/5 generate .gitignore (exclude public repos' instruction files)");
+  console.log("## 6/6 generate .gitignore (exclude public repos' instruction files)");
   await doRunProjectGitignore(stepOpts, stepCtx);
   console.log("");
   console.log(
     apply ? "\u2705 Ran every step (each is idempotent, so a partial apply recovers on re-run)." : "\u2139\uFE0F Dry-run preview. Pass --apply to write the changes, then re-run."
   );
 }
+async function doRunProjectSeedAnchor(options, ctx) {
+  const cwd = ctx.cwd ?? process.cwd();
+  const repositoryRoot = await resolveBasouRootForCommand(cwd, "project derive");
+  const paths = basouPaths10(repositoryRoot);
+  const manifest = await readManifest6(paths);
+  const roster = manifest.repos ?? [];
+  console.log("# Anchor instruction-file seed (the planning master's own AGENTS.md)");
+  console.log("");
+  if (roster.length === 0) {
+    console.log("\u2139\uFE0F No repo roster declared \u2014 nothing to seed.");
+    return;
+  }
+  const anchorDoc = join9(repositoryRoot, CANONICAL_FILE);
+  if (pathPresent(anchorDoc)) {
+    console.log(
+      `\u2705 The anchor's own \`${CANONICAL_FILE}\` already exists \u2014 hand-maintained, left untouched.`
+    );
+    return;
+  }
+  const viewPath = manifest.workspace.view;
+  const viewName = viewPath !== void 0 ? basename5(resolveViewDir(repositoryRoot, viewPath)) : void 0;
+  const repos = viewPresetReposFor(repositoryRoot, roster);
+  const content = renderAnchorStarter({
+    anchorName: basename5(repositoryRoot),
+    ...manifest.project?.name !== void 0 ? { projectName: manifest.project.name } : {},
+    ...viewName !== void 0 ? { viewName } : {},
+    repos
+  });
+  if (options.apply !== true) {
+    console.log(
+      `- ${CANONICAL_FILE} [create] \u2192 the anchor's own AGENTS.md (dry-run; pass --apply to write). A create-only starter; hand-maintain it afterward \u2014 basou never rewrites it.`
+    );
+    return;
+  }
+  try {
+    writeFileSync(anchorDoc, content, { flag: "wx" });
+    console.log(
+      `\u2705 Seeded the anchor's own \`${CANONICAL_FILE}\` (create-only starter \u2014 hand-maintain it from here; basou never rewrites it).`
+    );
+  } catch (error) {
+    if (hasErrorCode(error) && error.code === "EEXIST") {
+      console.log(
+        `\u2705 The anchor's own \`${CANONICAL_FILE}\` already exists \u2014 hand-maintained, left untouched.`
+      );
+      return;
+    }
+    console.log(
+      `\u26A0\uFE0F Could not seed the anchor's \`${CANONICAL_FILE}\`: ${presetFailureReason(error)}`
+    );
+  }
+}
 async function runProjectRetrofit(repo, options, ctx = {}) {
   try {
     await doRunProjectRetrofit(repo, options, ctx);
@@ -6037,7 +6499,7 @@ function pathPresent(p) {
     return false;
   }
 }
-function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, argReal) {
+function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, argReal, viewCanonicalName) {
   const declaredEntry = roster.find((entry) => {
     const entryAbs = resolve7(repositoryRoot, entry.path);
     if (argReal !== void 0) {
@@ -6061,6 +6523,7 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
       isAnchor: false,
       reachable: false,
       canonicalName,
+      ...viewCanonicalName !== void 0 ? { viewCanonicalName } : {},
       agentsState: "absent",
       canonicalExists: false,
       regularSpokes: []
@@ -6076,6 +6539,7 @@ function gatherRetrofit(repositoryRoot, anchorReal, roster, argPath, argAbs, arg
     isAnchor,
     reachable,
     canonicalName,
+    ...viewCanonicalName !== void 0 ? { viewCanonicalName } : {},
     agentsState: inspectAgentsState(join9(argReal, CANONICAL_FILE)),
     canonicalExists: pathPresent(canonicalFile),
     regularSpokes: regularFileSpokes(argReal)
@@ -6102,6 +6566,44 @@ function relocateAgentsFile(repoReal, canonicalFile) {
     return { ok: false, message: failureReason(error), partial: true };
   }
 }
+function gatherViewRetrofit(repositoryRoot, anchorReal, viewPath, roster) {
+  if (viewPath === void 0) return { kind: "no-view" };
+  const viewDir = resolveViewDir(repositoryRoot, viewPath);
+  const viewName = basename5(viewDir);
+  const collision = viewCanonicalCollision(repositoryRoot, roster, viewName);
+  if (collision !== void 0) return { kind: "collision", viewName, repoPath: collision };
+  const canonicalFile = canonicalFileFor(anchorReal, viewName);
+  let content;
+  try {
+    content = readFileSync(canonicalFile, "utf8");
+  } catch (error) {
+    if (hasErrorCode(error) && error.code === "ENOENT") return { kind: "absent", viewName };
+    return { kind: "unreadable", viewName };
+  }
+  const section = parseMarkers(content);
+  if (section.kind === "ok") return { kind: "already-marked", viewName };
+  if (section.kind === "no_markers") {
+    const block = renderViewPresetBlock({
+      viewName,
+      repos: viewPresetReposFor(repositoryRoot, roster)
+    });
+    return { kind: "seed", viewName, block };
+  }
+  return { kind: "malformed", viewName, reason: section.kind };
+}
+async function applyViewRetrofit(anchorReal, outcome) {
+  const file = canonicalFileFor(anchorReal, outcome.viewName);
+  const label = canonicalLabelFor(outcome.viewName);
+  let isLink = false;
+  try {
+    isLink = lstatSync(file).isSymbolicLink();
+  } catch {
+    isLink = false;
+  }
+  if (isLink) throw new Error(`Canonical is a symlink in ${label}`);
+  const existing = await readMarkdownFile4(file);
+  await writeMarkdownFile5(file, seedMarkers(existing, outcome.block, label));
+}
 async function doRunProjectRetrofit(repo, options, ctx) {
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveBasouRootForCommand(cwd, "project retrofit");
@@ -6109,6 +6611,36 @@ async function doRunProjectRetrofit(repo, options, ctx) {
   const manifest = await readManifest6(paths);
   const roster = manifest.repos ?? [];
   const anchorReal = realpathSync(repositoryRoot);
+  const viewPath = manifest.workspace.view;
+  if (repo === void 0) {
+    let view2;
+    let viewApplied = false;
+    let viewFailure;
+    if (roster.length > 0) {
+      view2 = gatherViewRetrofit(repositoryRoot, anchorReal, viewPath, roster);
+      if (options.apply === true && view2.kind === "seed") {
+        try {
+          await applyViewRetrofit(anchorReal, view2);
+          viewApplied = true;
+        } catch (error) {
+          viewFailure = presetFailureReason(error);
+        }
+      }
+    }
+    const result2 = {
+      kind: "view-only",
+      hasRoster: roster.length > 0,
+      ...view2 !== void 0 ? { view: view2 } : {},
+      viewApplied,
+      ...viewFailure !== void 0 ? { viewFailure } : {}
+    };
+    if (options.json === true) {
+      console.log(JSON.stringify(result2));
+    } else {
+      console.log(renderProjectRetrofit(result2));
+    }
+    return result2;
+  }
   const argAbs = resolve7(repositoryRoot, repo);
   let argReal;
   try {
@@ -6116,7 +6648,16 @@ async function doRunProjectRetrofit(repo, options, ctx) {
   } catch {
     argReal = void 0;
   }
-  const facts = gatherRetrofit(repositoryRoot, anchorReal, roster, repo, argAbs, argReal);
+  const viewCanonicalName = viewPath !== void 0 ? basename5(resolveViewDir(repositoryRoot, viewPath)) : void 0;
+  const facts = gatherRetrofit(
+    repositoryRoot,
+    anchorReal,
+    roster,
+    repo,
+    argAbs,
+    argReal,
+    viewCanonicalName
+  );
   const plan = classifyRetrofit(facts);
   let applied = false;
   let failure;
@@ -6131,12 +6672,19 @@ async function doRunProjectRetrofit(repo, options, ctx) {
       partial = res.partial;
     }
   }
+  let view;
+  if (roster.length > 0) {
+    view = gatherViewRetrofit(repositoryRoot, anchorReal, viewPath, roster);
+  }
   const result = {
+    kind: "repo",
     ...plan,
     hasRoster: roster.length > 0,
     applied,
     ...failure !== void 0 ? { failure } : {},
-    ...partial ? { partial } : {}
+    ...partial ? { partial } : {},
+    ...view !== void 0 ? { view } : {},
+    viewApplied: false
   };
   if (options.json === true) {
     console.log(JSON.stringify(result));
@@ -6145,6 +6693,47 @@ async function doRunProjectRetrofit(repo, options, ctx) {
   }
   return result;
 }
+var MARKER_PORTABILITY_NOTE = "The marker pair can later be moved anywhere in the file by hand \u2014 `basou project preset` rewrites only the region between the markers.";
+function appendViewRetrofitSection(lines, result) {
+  const view = result.view;
+  if (view === void 0 || view.kind === "no-view" || view.kind === "absent" || view.kind === "already-marked")
+    return;
+  const canonical2 = `agents/${view.viewName}/${CANONICAL_FILE}`;
+  lines.push("## Workspace view canonical (auto-migrate the view's own AGENTS.md)");
+  if (view.kind === "seed") {
+    if (result.kind === "repo") {
+      lines.push(
+        `\`${canonical2}\` is markerless prose. Run \`basou project retrofit\` (no repo argument) to prepend the generated block, preserving the prose.`
+      );
+      lines.push(MARKER_PORTABILITY_NOTE);
+    } else if (result.viewApplied) {
+      lines.push(
+        `\u2705 Prepended the generated block into \`${canonical2}\` (your hand-written prose is preserved below it).`
+      );
+      lines.push(MARKER_PORTABILITY_NOTE);
+    } else if (result.viewFailure !== void 0) {
+      lines.push(`\u26A0\uFE0F Could not seed \`${canonical2}\`: ${result.viewFailure}. Nothing was changed.`);
+    } else {
+      lines.push(
+        `\`${canonical2}\` is markerless prose. Retrofit will prepend the generated block, preserving the prose (dry-run; pass --apply to write).`
+      );
+      lines.push(MARKER_PORTABILITY_NOTE);
+    }
+  } else if (view.kind === "collision") {
+    lines.push(
+      `\u26A0\uFE0F The view shares its canonical name with the roster repo \`${view.repoPath}\` \u2014 both would own \`${canonical2}\`, so nothing is migrated. Rename the view directory or the repo to disambiguate, then re-run.`
+    );
+  } else if (view.kind === "malformed") {
+    lines.push(
+      `\u26A0\uFE0F \`${canonical2}\` has malformed markers (${view.reason}), so it is not rewritten. Fix the \`${GENERATED_START}\` / \`${GENERATED_END}\` pair by hand, then re-run.`
+    );
+  } else {
+    lines.push(
+      `\u26A0\uFE0F \`${canonical2}\` could not be read (a directory, permissions, etc.). Resolve it by hand, then re-run.`
+    );
+  }
+  lines.push("");
+}
 function appendSpokeChecklist(lines, spokes) {
   if (spokes.length === 0) return;
   lines.push(
@@ -6169,6 +6758,25 @@ function renderProjectRetrofit(result) {
     );
     return lines.join("\n");
   }
+  if (result.kind === "view-only") {
+    const view = result.view;
+    if (view === void 0 || view.kind === "no-view") {
+      lines.push(
+        "\u2139\uFE0F No `workspace.view` declared \u2014 there is no view canonical to migrate. Pass a repo argument to relocate a repo's AGENTS.md instead."
+      );
+    } else if (view.kind === "absent") {
+      lines.push(
+        `\u2139\uFE0F The view canonical \`agents/${view.viewName}/${CANONICAL_FILE}\` does not exist yet \u2014 run \`basou project preset --apply\` (or \`basou project derive --apply\`) to create it; there is nothing to migrate.`
+      );
+    } else if (view.kind === "already-marked") {
+      lines.push(
+        `\u2705 \`agents/${view.viewName}/${CANONICAL_FILE}\` already has a BASOU:GENERATED region. Nothing to migrate.`
+      );
+    } else {
+      appendViewRetrofitSection(lines, result);
+    }
+    return lines.join("\n").trimEnd();
+  }
   const canonical2 = `agents/${result.canonicalName}/${CANONICAL_FILE}`;
   if (result.action === "refuse") {
     if (result.reason === "not-declared") {
@@ -6191,12 +6799,18 @@ function renderProjectRetrofit(result) {
       lines.push(
         `\u26A0\uFE0F \`${result.path}/${CANONICAL_FILE}\` could not be inspected (a parent component is not a directory, a permission error, or the path is neither a regular file nor a symlink). Resolve it by hand, then re-run.`
       );
+    } else if (result.reason === "view-collision") {
+      lines.push(
+        `\u26A0\uFE0F \`${result.path}\` shares its canonical name with the workspace view \u2014 \`${canonical2}\` would be owned by both, so relocating would corrupt one with the other. Rename the view directory or the repo to disambiguate, then re-run.`
+      );
     } else if (result.reason === "canonical-exists") {
       lines.push(
         `\u26A0\uFE0F The destination canonical \`${canonical2}\` already exists. Not relocating, to avoid clobbering it. If the canonical is the source of truth, the repo's AGENTS.md is redundant (remove it, then run \`basou project symlinks\`); otherwise reconcile the two by hand.`
       );
     }
-    return lines.join("\n");
+    lines.push("");
+    appendViewRetrofitSection(lines, result);
+    return lines.join("\n").trimEnd();
   }
   if (result.action === "skip") {
     if (result.reason === "already-symlink") {
@@ -6210,6 +6824,7 @@ function renderProjectRetrofit(result) {
     }
     lines.push("");
     appendSpokeChecklist(lines, result.regularSpokes);
+    appendViewRetrofitSection(lines, result);
     return lines.join("\n").trimEnd();
   }
   if (result.failure !== void 0) {
@@ -6223,7 +6838,9 @@ function renderProjectRetrofit(result) {
     } else {
       lines.push("Nothing was changed. Resolve the cause and re-run.");
     }
-    return lines.join("\n");
+    lines.push("");
+    appendViewRetrofitSection(lines, result);
+    return lines.join("\n").trimEnd();
   }
   if (result.applied) {
     lines.push(
@@ -6238,6 +6855,7 @@ function renderProjectRetrofit(result) {
   }
   lines.push("");
   appendSpokeChecklist(lines, result.regularSpokes);
+  appendViewRetrofitSection(lines, result);
   lines.push(
     result.applied ? "Next: run `basou project derive --apply` to add the preset block, the CLAUDE.md / Copilot spokes, and the .gitignore." : "After applying, run `basou project derive --apply` to finish the wiring (preset block, CLAUDE.md / Copilot spokes, .gitignore)."
   );