@vicentelyrio/netherite 1.0.0 → 1.1.0

package/README.md

@@ -30,6 +30,10 @@ npx @vicentelyrio/netherite             # the app, at http://127.0.0.1:4747
 
 To type less, install it once with `npm install --global @vicentelyrio/netherite`; the command is then just `netherite`.
 
+Already have docs or decision records? `npx @vicentelyrio/netherite scan` drafts a list of them and
+`import` writes it. Or ask your agent to migrate them (the `netherite-migrate` skill, installed by
+`init`). See [Migrate](https://vicentelyrio.github.io/netherite/migrate).
+
 `init` is safe to run again. `npx @vicentelyrio/netherite serve --no-open` starts the same thing without opening
 a browser. The server listens on `127.0.0.1` only.
 

package/dist/bin.mjs

@@ -6079,6 +6079,282 @@ const raised = (repo, input = {}) => {
 	}
 	return out.sort((x, y) => (y.date ?? "").localeCompare(x.date ?? "") || x.key.localeCompare(y.key));
 };
+const labels = {
+	"already-imported": "already imported",
+	"nested-agent-file": "per-folder agent files (agents read them in place; they would fill the context budget)",
+	stub: "stubs that only point at another file",
+	"managed-by-a-tool": "folders another tool manages and rewrites",
+	"not-documentation": "changelogs, licences and similar",
+	template: "templates",
+	"test-data": "test fixtures, golden files and snapshots",
+	"decision-index": "the index of a decision record folder (the records are the content)",
+	"maybe-a-secret": "files that look like they hold a secret (not read into the batch)",
+	"too-large": "files over 1 MB"
+};
+/** Folders that are never walked into. */
+const pruned = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	"out",
+	"coverage",
+	".next",
+	".nuxt",
+	".turbo",
+	".cache",
+	".parcel-cache",
+	"target",
+	"vendor",
+	"__pycache__",
+	".venv",
+	"venv",
+	".tox",
+	".gradle",
+	".idea",
+	".vscode",
+	".yarn",
+	".pnpm-store",
+	".terraform"
+]);
+/** Folders that another tool owns and keeps rewriting. */
+const managedFolders = /* @__PURE__ */ new Set([
+	"openspec",
+	".changeset",
+	".changes",
+	"changelog.d",
+	".vitepress"
+]);
+/** Hidden folders that still hold things worth importing. */
+const hiddenKept = /* @__PURE__ */ new Set([
+	".ai",
+	".claude",
+	".cursor",
+	".github",
+	".agents"
+]);
+const markdown = /\.(md|mdx|mdc|markdown)$/i;
+const agentFile = /^(AGENTS|CLAUDE|GEMINI)\.md$/;
+const notDocs = /^(changelog|changes|history|license|licence|copying|notice|authors|contributors|code_of_conduct)(\.[a-z]+)?$/i;
+const templateName = /(^|[-_.])(template|tpl)([-_.]|$)|^_template|issue_template|pull_request_template/i;
+const secretPattern = /(npm_[A-Za-z0-9]{36}|gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk-[A-Za-z0-9]{32,}|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35})/;
+const adrFolder = /(^|\/)(adrs?|decisions?|architecture-decisions?|rfcs?|arch)(\/|$)/i;
+const runbookWords = /(^|[/_.-])(runbooks?|playbooks?|on-?call|oncall|incident)([/_.-]|$)/i;
+const maxBytes = 1048576;
+const examplesPerGroup = 4;
+const pad = (n, width) => String(n).padStart(width, "0");
+/** An ADR's number from its file name: `0062-x.md`, `adr-7-x.md`, `12_x.md`. */
+const adrNumber = (name) => {
+	const m = name.match(/^(?:adr[-_ ]*)?(\d{1,5})(?:[-_. ]|$)/i);
+	return m === null ? void 0 : Number(m[1]);
+};
+/** The status a decision record states: `Status: x`, `- **Status:** x`, or a `## Status` section. */
+const adrStatus = (text) => {
+	const line = text.match(/^\s*[-*]?\s*\**status\**:\**\s*(.+)$/im)?.[1];
+	const section = text.match(/^#{1,4}\s*status\s*\r?\n+\s*([^\r\n#].*)$/im)?.[1];
+	const raw = (line ?? section)?.replace(/[*_`[\]]/g, "").trim().toLowerCase();
+	if (raw === void 0 || raw === "") return void 0;
+	if (raw.startsWith("superseded")) return "superseded";
+	if (raw.startsWith("deprecated") || raw.startsWith("retired") || raw.startsWith("rejected")) return "deprecated";
+	if (raw.startsWith("accepted") || raw.startsWith("approved") || raw.startsWith("adopted")) return "accepted";
+	if (raw.startsWith("proposed") || raw.startsWith("draft")) return "proposed";
+};
+/** The date a decision record states, `YYYY-MM-DD`. */
+const adrDate = (text) => text.match(/^\s*[-*]?\s*\**date\**:\**\s*(\d{4}-\d{2}-\d{2})/im)?.[1] ?? text.match(/^date:\s*["']?(\d{4}-\d{2}-\d{2})/im)?.[1];
+/** Matchers for the root `.gitignore`: plain names and globs, not negations. */
+const gitignored = (text) => {
+	const patterns = (text ?? "").split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== "" && !l.startsWith("#") && !l.startsWith("!")).flatMap((raw) => {
+		const anchored = raw.startsWith("/") || raw.replace(/\/$/, "").includes("/");
+		const body = raw.replace(/^\//, "").replace(/\/$/, "");
+		return anchored ? [body, `${body}/**`] : [
+			`**/${body}`,
+			`**/${body}/**`,
+			body,
+			`${body}/**`
+		];
+	});
+	if (patterns.length === 0) return (_path) => false;
+	const match = picomatch(patterns, { dot: true });
+	return (path) => match(path);
+};
+const isStub = (text) => {
+	const body = text.replace(/\s+/g, " ").trim();
+	return body.length < 80 && /^@\S+\.md$/.test(body);
+};
+/**
+* Walks the repository from the workspace root and sorts every Markdown file and agent file into a
+* draft batch or a group of files left out.
+*/
+const surveyRepository = (workspace, index, options = {}) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const root = workspace.root;
+	const contentFolder = path.relative(root, workspace.contentRoot).split(path.sep).join("/");
+	const ignoreFile = yield* fs.readFileString(path.join(root, ".gitignore")).pipe(Effect.orElseSucceed(() => void 0));
+	const isIgnored = gitignored(ignoreFile);
+	const imported = new Set(index.items().flatMap((item) => {
+		const data = item.parsed.frontmatter?.data;
+		const source = typeof data === "object" && data !== null ? data.source : void 0;
+		return typeof source === "string" ? [normalizeSource(source)] : [];
+	}));
+	const skipped = /* @__PURE__ */ new Map();
+	const skip = (reason, file) => {
+		const list = skipped.get(reason) ?? [];
+		list.push(file);
+		skipped.set(reason, list);
+	};
+	const files = [];
+	let scanned = 0;
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (dir) => Effect.gen(function* () {
+		const real = yield* fs.realPath(path.join(root, dir)).pipe(Effect.orElseSucceed(() => dir));
+		if (seen.has(real)) return;
+		seen.add(real);
+		const names = yield* fs.readDirectory(path.join(root, dir)).pipe(Effect.orElseSucceed(() => []));
+		for (const name of [...names].sort()) {
+			const rel = dir === "" ? name : `${dir}/${name}`;
+			const info = yield* fs.stat(path.join(root, rel)).pipe(Effect.option);
+			if (info._tag === "None") continue;
+			if (info.value.type === "Directory") {
+				if (pruned.has(name) || rel === ".netherite" || rel === contentFolder) continue;
+				if (name.startsWith(".") && !hiddenKept.has(name)) continue;
+				if (isIgnored(rel)) continue;
+				if (managedFolders.has(name)) {
+					yield* countManaged(rel);
+					continue;
+				}
+				yield* walk(rel);
+			} else if (info.value.type === "File") {
+				scanned++;
+				if (!isIgnored(rel)) files.push(rel);
+			}
+		}
+	});
+	const countManaged = (dir) => Effect.gen(function* () {
+		const entries = yield* fs.readDirectory(path.join(root, dir), { recursive: true }).pipe(Effect.orElseSucceed(() => []));
+		for (const entry of entries) if (markdown.test(entry)) {
+			scanned++;
+			skip("managed-by-a-tool", `${dir}/${entry.split(path.sep).join("/")}`);
+		}
+	});
+	yield* walk("");
+	const gitMap = options.git === void 0 ? void 0 : yield* pathMap(options.git, root);
+	const typed = [];
+	for (const file of files) {
+		const name = file.split("/").pop() ?? file;
+		const isConvention = agentFile.test(name) || name === ".cursorrules" || /^\.cursor\/rules\//.test(file) || file === ".github/copilot-instructions.md" || /^\.ai\/context\//.test(file);
+		if (!markdown.test(name) && name !== ".cursorrules") continue;
+		if (!isConvention && file.startsWith(".claude/")) continue;
+		if (!isConvention && file.startsWith(".github/")) continue;
+		if (notDocs.test(name)) {
+			skip("not-documentation", file);
+			continue;
+		}
+		if (templateName.test(name) || /(^|\/)templates?\//i.test(file)) {
+			skip("template", file);
+			continue;
+		}
+		if (/(^|\/)(tests?|__tests__|__fixtures__|fixtures?|golden|__snapshots__)\//i.test(file)) {
+			skip("test-data", file);
+			continue;
+		}
+		if (adrFolder.test(file) && /^(readme|index)\.[a-z]+$/i.test(name)) {
+			skip("decision-index", file);
+			continue;
+		}
+		if (imported.has(file)) {
+			skip("already-imported", file);
+			continue;
+		}
+		const depth = file.split("/").length;
+		if (agentFile.test(name) && depth > 3 && options.nestedAgentFiles !== true) {
+			skip("nested-agent-file", file);
+			continue;
+		}
+		const info = yield* fs.stat(path.join(root, file)).pipe(Effect.option);
+		if (info._tag === "Some" && Number(info.value.size) > maxBytes) {
+			skip("too-large", file);
+			continue;
+		}
+		const text = yield* fs.readFileString(path.join(root, file)).pipe(Effect.orElseSucceed(() => void 0));
+		if (text === void 0) continue;
+		if (secretPattern.test(text)) {
+			skip("maybe-a-secret", file);
+			continue;
+		}
+		if (isStub(text)) {
+			skip("stub", file);
+			continue;
+		}
+		const lower = file.toLowerCase();
+		let type;
+		if (isConvention) type = "context";
+		else if (adrFolder.test(lower) && !/(^|\/)(readme|index)\.[a-z]+$/i.test(lower)) type = "adr";
+		else if (runbookWords.test(lower)) type = "runbook";
+		else type = "doc";
+		typed.push({
+			entry: {
+				source: file,
+				type
+			},
+			text
+		});
+	}
+	const notes = [];
+	const numbers = /* @__PURE__ */ new Map();
+	const entries = [];
+	const padding = 5;
+	for (const { entry, text } of typed) {
+		if (entry.type !== "adr") {
+			entries.push(entry);
+			continue;
+		}
+		const name = entry.source.split("/").pop() ?? entry.source;
+		const n = adrNumber(name);
+		const fields = {};
+		const status = adrStatus(text);
+		if (status !== void 0) fields.status = status;
+		let date = adrDate(text);
+		if (date === void 0 && options.git !== void 0 && gitMap !== void 0) date = (yield* options.git.firstCommit(gitMap.toGit(entry.source)).pipe(Effect.orElseSucceed(() => void 0)))?.date.slice(0, 10);
+		if (date !== void 0) fields.date = date;
+		let id;
+		if (n !== void 0) {
+			const taken = numbers.get(n);
+			if (taken === void 0) {
+				numbers.set(n, entry.source);
+				id = `ADR-${pad(n, padding)}`;
+			} else notes.push(`${entry.source} has the number ${n}, like ${taken}: it will get the next free ID unless you give it one`);
+		}
+		entries.push({
+			source: entry.source,
+			type: "adr",
+			...id === void 0 ? {} : { id },
+			...Object.keys(fields).length === 0 ? {} : { fields }
+		});
+	}
+	const order = {
+		adr: 0,
+		doc: 1,
+		runbook: 2,
+		context: 3
+	};
+	const depthOf = (s) => s.source.split("/").length;
+	entries.sort((a, b) => order[a.type] - order[b.type] || depthOf(a) - depthOf(b) || a.source.localeCompare(b.source));
+	const groups = [...skipped.entries()].map(([reason, list]) => ({
+		reason,
+		label: labels[reason],
+		count: list.length,
+		examples: list.slice(0, examplesPerGroup)
+	}));
+	const rank = Object.keys(labels);
+	groups.sort((a, b) => rank.indexOf(a.reason) - rank.indexOf(b.reason));
+	return {
+		scanned,
+		entries,
+		skipped: groups,
+		notes
+	};
+});
 const day = (iso) => iso === void 0 ? void 0 : new Date(iso).toISOString().slice(0, 10);
 const holdsOf = (spans) => spans.filter((s) => s.phase === "blocked").map((s) => ({
 	from: day(s.from),
@@ -9755,7 +10031,7 @@ const makeState = (repo, options = {}) => Effect.gen(function* () {
 		}
 	};
 });
-// ../../packages/cli/dist/cli-C6627ZbR.mjs
+// ../../packages/cli/dist/cli-BK4CDEKf.mjs
 const exitCodes = {
 	ok: 0,
 	findings: 1,
@@ -9799,10 +10075,10 @@ const reportFailure = (env, error) => {
 			return exitCodes.findings;
 	}
 };
-const count = (n) => n.toLocaleString("en-US");
+const count$1 = (n) => n.toLocaleString("en-US");
 const describe$1 = (t, check) => {
 	const state = check ? t.stale ? "out of date" : "up to date" : t.status;
-	return `${t.path.padEnd(10)} ${state.padEnd(11)} ≈${count(t.tokens)} of ${count(t.budget)} tokens, ${t.included.length} ${t.included.length === 1 ? "item" : "items"}`;
+	return `${t.path.padEnd(10)} ${state.padEnd(11)} ≈${count$1(t.tokens)} of ${count$1(t.budget)} tokens, ${t.included.length} ${t.included.length === 1 ? "item" : "items"}`;
 };
 /** Renders the context items into `CLAUDE.md` and `AGENTS.md`, or with `--check` only compares. */
 const contextSync = (env, options) => Effect.gen(function* () {
@@ -9817,8 +10093,8 @@ const contextSync = (env, options) => Effect.gen(function* () {
 		}
 		for (const t of report.targets) {
 			if (t.omitted.length === 0) continue;
-			env.out.error(`${t.path}: ${t.omitted.length} ${t.omitted.length === 1 ? "item does" : "items do"} not fit in the ${count(t.budget)}-token budget:`);
-			for (const o of t.omitted) env.out.error(`  ${o.id || o.path}  ${o.title}  (${o.priority}, ≈${count(o.tokens)} tokens)`);
+			env.out.error(`${t.path}: ${t.omitted.length} ${t.omitted.length === 1 ? "item does" : "items do"} not fit in the ${count$1(t.budget)}-token budget:`);
+			for (const o of t.omitted) env.out.error(`  ${o.id || o.path}  ${o.title}  (${o.priority}, ≈${count$1(o.tokens)} tokens)`);
 		}
 		if (options.check && report.stale) {
 			env.out.error("Context is out of date. Run `netherite context sync` and commit the result.");
@@ -9838,7 +10114,7 @@ const describe = (r, dryRun) => {
 		case "failed": return `failed   ${where}  ${r.reason ?? ""}`.trimEnd();
 	}
 };
-const summary = (report) => {
+const summary$1 = (report) => {
 	const { counts } = report;
 	return [
 		`${counts.created} ${report.dryRun ? "to create" : "created"}`,
@@ -9892,7 +10168,7 @@ const importCommand = (env, options) => Effect.gen(function* () {
 		else {
 			if (report.dryRun) env.out.line("Dry run: nothing was written.");
 			for (const r of report.results) env.out.line(describe(r, report.dryRun));
-			env.out.line(summary(report));
+			env.out.line(summary$1(report));
 			if (report.relinked.links > 0) env.out.line(`Linked ${report.relinked.links} references between imported files, in ${report.relinked.items} items.`);
 			if (!report.dryRun && report.counts.created + report.counts.updated > 0) env.out.line("Nothing is committed. Run `netherite lint`, then review the changes in git.");
 		}
@@ -10099,7 +10375,9 @@ This skill needs two things beyond the \`netherite\` MCP tools: to read files in
 
 ## 1. Survey (read only)
 
-Look for what is already written down. Skip \`node_modules\`, build output, vendored code, \`CHANGELOG\`, \`LICENSE\`, generated files and the Netherite content folder itself.
+Start with \`netherite scan --json\`. It walks the repository, writes nothing, and returns a draft batch (\`batch\`), the files it left out with the reason (\`skipped\`), and things to check (\`notes\`). It already skips \`node_modules\`, build output, vendored code, changelogs and licences, templates, test fixtures, files that look like they hold a secret, per-folder agent files, stubs, folders another tool manages, and what is already imported; it gives decision records their numbers, statuses and dates. Read what it returns instead of walking the tree yourself, then check it by hand against the list below: it classifies by path and file name, so it can be wrong about a type, and it does not read the text for meaning.
+
+What to look for, and what the scan may have missed:
 
 - **Docs:** \`README*\`, \`docs/\`, \`doc/\`, \`wiki/\`, guides, architecture notes, \`CONTRIBUTING.md\`.
 - **Runbooks:** \`runbooks/\`, \`playbooks/\`, \`ops/\`, on-call and deploy notes, step-by-step operations.
@@ -10114,7 +10392,7 @@ Some finds are not for import, and you say so in the table, with a count:
 - **Folders managed by another tool** (\`openspec/\`, changesets, generated reference docs, an indexed wiki): ask, and recommend skip. The tool owns them and keeps rewriting them.
 - **Blocks written by another tool** inside a file (\`<!-- BEGIN:... -->\`): the tool re-adds them, so leave them out of the text you import.
 
-Show the person the list as a table with counts per type, and what you left out.
+Show the person the scan's list as a table with counts per type, and what it left out.
 
 ## 2. Ask, one question at a time
 
@@ -10132,7 +10410,7 @@ Use the \`netherite-plan\` skill: one project, one task per batch, and in each t
 
 ## 4. Each batch
 
-1. Set the task \`doing\`. Write the batch as JSON to \`.netherite/local/migration-<n>.json\` (it is not committed). See https://vicentelyrio.github.io/netherite/reference/import for the format; \`netherite import --help\` lists the flags. When many files share one format (dozens of decision records, say), write a small script that builds the batch from them instead of typing entries, show the person the table and three entries in full, and run it again for the next batch.
+1. Set the task \`doing\`. Write the batch as JSON to \`.netherite/local/migration-<n>.json\` (it is not committed), starting from the scan's \`batch\` (\`netherite scan --out .netherite/local/migration-<n>.json\` writes one) and taking the entries of this batch from it. See https://vicentelyrio.github.io/netherite/reference/import for the format; \`netherite import --help\` lists the flags. When many files share one format (dozens of decision records, say), write a small script that builds the batch from them instead of typing entries, show the person the table and three entries in full, and run it again for the next batch.
 2. **Entries.**
    - ADRs: \`id\` from the number in the file name, written with the workspace's padding (\`ADR-00004\`). Read the status line the way the record means it, and map it to \`fields.status\` (\`accepted\`, \`proposed\`, \`deprecated\`, \`superseded\`): a record that is wholly "superseded by" another is \`superseded\`, \`retired\` is \`deprecated\`, and a record that is only amended or partly superseded stays \`accepted\`. Do not lose the nuance: keep the original status line in \`body\` as \`**Status as written:** ...\`, put a word such as \`provisional\` in \`fields.tags\`, and keep a "Revisit when" line. Put the record's date in \`fields.date\`; if it has none, use the date the file was first committed (\`git log --diff-filter=A --format=%as -1 -- <path>\`). A record with no stated status is \`proposed\`: never invent \`accepted\`. Leave out \`deciders\` unless the record names them: the person running the import did not decide it. When a record's status and date are lines at the top rather than headings, take them out of \`body\` once they are fields.
    - Docs and runbooks: \`covers\` is what the doc **describes**, not everything it mentions, and it decides when the doc shows as stale. Propose globs (\`src/auth/**\`) only for paths that exist and that the doc is about, and leave \`covers\` out when unsure: a wrong one means false alarms. Never cover absolute paths, \`.env*\` files, or the code the doc says it is moving away from. In one real monorepo, 59 of 90 docs mentioned an existing path and few were about it.
@@ -10888,6 +11166,90 @@ const renumberCommand = (env, options) => Effect.gen(function* () {
 	});
 	return yield* Effect.catch(run, (error) => Effect.succeed(reportFailure(env, error)));
 });
+const defaultOut = ".netherite/local/scan.json";
+const typeNames = {
+	adr: "decision records",
+	doc: "docs",
+	runbook: "runbooks",
+	context: "agent and convention files"
+};
+const count = (n) => n.toLocaleString("en-US");
+const leftOut = (survey) => {
+	const lines = [];
+	if (survey.skipped.length > 0) {
+		lines.push("", "Left out:");
+		for (const group of survey.skipped) {
+			lines.push(`  ${String(group.count).padStart(4)}  ${group.label}`);
+			const shown = group.examples.join(", ");
+			lines.push(`        e.g. ${shown}${group.count > group.examples.length ? ", ..." : ""}`);
+		}
+	}
+	return lines;
+};
+const summary = (survey, out) => {
+	const lines = [];
+	const by = (type) => survey.entries.filter((e) => e.type === type).length;
+	const parts = Object.keys(typeNames).filter((t) => by(t) > 0).map((t) => `${by(t)} ${typeNames[t]}`);
+	lines.push(`Looked at ${count(survey.scanned)} files and found ${survey.entries.length} to bring in: ${parts.join(", ")}.`, ...leftOut(survey));
+	if (survey.notes.length > 0) {
+		lines.push("", "Look at these before importing:");
+		for (const note of survey.notes) lines.push(`  - ${note}`);
+	}
+	lines.push("", `The draft is in ${out}. It is not committed, and .netherite/local is ignored by git.`, "Open it, take out what you do not want, add a \"title\" or \"fields\" where you know better, then:", `  netherite import ${out} --dry-run`, "", "A decision record takes the status and date it states, or the date of its first commit.", "Nothing has been written to your documents.");
+	return lines;
+};
+const skipHint = { "nested-agent-file": "Add --nested-agent-files to include them." };
+/**
+* Looks through the repository for what is already written down (docs, runbooks, decision
+* records, the files agents read) and writes a draft batch for `netherite import`. It only reads:
+* the one file it writes is the draft.
+*/
+const scanCommand = (env, options) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const run = Effect.gen(function* () {
+		const repo = yield* openRepo(path.resolve(env.cwd, options.dir));
+		const git = yield* workspaceGit(repo.workspace);
+		const survey = yield* surveyRepository(repo.workspace, repo.index, {
+			git,
+			nestedAgentFiles: options.nestedAgentFiles
+		});
+		const batch = {
+			mode: "copy",
+			entries: survey.entries
+		};
+		if (options.json) {
+			json(env.out, {
+				batch,
+				scanned: survey.scanned,
+				skipped: survey.skipped,
+				notes: survey.notes
+			});
+			return exitCodes.ok;
+		}
+		if (survey.entries.length === 0) {
+			env.out.line(`Looked at ${count(survey.scanned)} files and found nothing to bring in.`);
+			for (const line of leftOut(survey)) env.out.line(line);
+			return exitCodes.ok;
+		}
+		const target = options.out ?? defaultOut;
+		const file = path.resolve(repo.workspace.root, target);
+		if ((yield* fs.exists(file)) && !options.force) {
+			env.out.error(`${target} already exists. Pass --force to replace it, or --out to write somewhere else.`);
+			return exitCodes.usage;
+		}
+		yield* fs.makeDirectory(path.dirname(file), { recursive: true });
+		yield* fs.writeFileString(file, `${JSON.stringify(batch, null, 2)}\n`);
+		const shown = path.relative(env.cwd, file).split(path.sep).join("/") || target;
+		for (const line of summary(survey, shown)) env.out.line(line);
+		for (const group of survey.skipped) {
+			const hint = skipHint[group.reason];
+			if (hint !== void 0) env.out.line(`  (${group.label.split(" (")[0]}: ${hint})`);
+		}
+		return exitCodes.ok;
+	});
+	return yield* Effect.catch(run, (error) => Effect.succeed(reportFailure(env, error)));
+});
 /** The app bundled next to the program (see the release packaging), if there is one. */
 const bundledApp = () => fileURLToPath(new URL("./app", import.meta.url));
 /** Opens a page with the operating system's default browser. */
@@ -11034,9 +11396,22 @@ const makeCli = (env, state, version = "0.0.0") => {
 		template: c.template,
 		json: c.json
 	}), finish)).pipe(Command.withDescription("Create an item with the next free ID."));
+	const scanCmd = Command.make("scan", {
+		dir,
+		out: Flag.String("out").pipe(Flag.optional, Flag.withDescription("Where to write the draft batch, from the workspace root. Default: .netherite/local/scan.json.")),
+		nestedAgentFiles: Flag.Boolean("nested-agent-files").pipe(Flag.withDefault(false), Flag.withDescription("Include the AGENTS.md and CLAUDE.md files deep in the tree. They are left out by default: agents read them in place, and they would fill the context budget.")),
+		force: Flag.Boolean("force").pipe(Flag.withDefault(false), Flag.withDescription("Replace a draft that is already there.")),
+		json: jsonFlag
+	}, (c) => Effect.flatMap(scanCommand(env, {
+		dir: c.dir,
+		out: Option.getOrUndefined(c.out),
+		nestedAgentFiles: c.nestedAgentFiles,
+		force: c.force,
+		json: c.json
+	}), finish)).pipe(Command.withDescription("Look through the repository for docs, runbooks, decision records and agent files, and write a draft batch for `netherite import`. It only reads, and writes nothing but the draft."));
 	const importCmd = Command.make("import", {
 		dir,
-		file: Argument.String("batch").pipe(Argument.withDescription("A JSON file: a list of entries, or { \"mode\": \"copy\", \"entries\": [...] }. Each entry has source, type (doc, runbook, context or adr) and optionally title, id, fields, body and mode.")),
+		file: Argument.String("batch").pipe(Argument.withDescription("A JSON file: a list of entries, or { \"mode\": \"copy\", \"entries\": [...] }. Each entry has source, type (doc, runbook, context or adr) and optionally title, id, fields, body and mode. `netherite scan` writes a draft of one.")),
 		update: Flag.Boolean("update").pipe(Flag.withDefault(false), Flag.withDescription("Bring items that were already imported up to date with their source.")),
 		dryRun: Flag.Boolean("dry-run").pipe(Flag.withDefault(false), Flag.withDescription("Say what would happen and write nothing.")),
 		stub: Flag.Boolean("stub").pipe(Flag.withDefault(false), Flag.withDescription("With mode \"move\", leave a one-line note where the original was.")),
@@ -11142,6 +11517,7 @@ const makeCli = (env, state, version = "0.0.0") => {
 	return Command.make("netherite", serveFlags, serve).pipe(Command.withDescription("Typed, linked knowledge in your git repository. Documentation: https://vicentelyrio.github.io/netherite/"), Command.withSubcommands([
 		initCmd,
 		newCmd,
+		scanCmd,
 		importCmd,
 		templatesCmd,
 		lintCmd,
@@ -11163,7 +11539,7 @@ const runCli = (argv, env, version = "0.0.0") => {
 	return Command.runWith(root, { version })(argv).pipe(Effect.map(() => state.code), Effect.catch(() => Effect.succeed(exitCodes.usage)));
 };
 // package.json
-var version = "1.0.0";
+var version = "1.1.0";
 // src/bin.ts
 const stop = new AbortController();
 for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => stop.abort());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vicentelyrio/netherite",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A typed, linked knowledge base in Markdown and git: a CLI, an MCP server for agents, and a local app.",
   "license": "MIT",
   "repository": {
@@ -70,7 +70,7 @@
     "@netherite/schema": "0.0.0",
     "@netherite/server": "0.0.0",
     "@netherite/web": "0.0.0",
-    "@types/node": "^24.0.0",
+    "@types/node": "^26.0.0",
     "tsdown": "^0.23.4",
     "typescript": "^7.0.2",
     "vitest": "^5.0.5"