@alveolus/arch 0.1.0 → 0.3.0

package/dist/{cli-CwPCGjDg.mjs → docs-DsQHpTtV.mjs}

@@ -1,5 +1,5 @@
 import { Command, CommanderError, Option } from "commander";
-import { existsSync } from "node:fs";
+import { existsSync, globSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, matchesGlob, normalize, relative, resolve, sep } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -640,6 +640,7 @@ var LayerShape = class {
 var Location = class {
 	area;
 	context;
+	subdomain;
 	layer;
 	folder;
 	foldersInLayer;
@@ -649,6 +650,7 @@ var Location = class {
 	constructor(props) {
 		this.area = props.area;
 		this.context = props.context;
+		this.subdomain = props.subdomain;
 		this.layer = props.layer;
 		this.folder = props.folder;
 		this.foldersInLayer = props.foldersInLayer ?? [];
@@ -659,6 +661,9 @@ var Location = class {
 	get isInBoundedContext() {
 		return this.area === "context";
 	}
+	get isInCoreDomain() {
+		return this.isInBoundedContext && this.subdomain === "core";
+	}
 	get isInSharedKernel() {
 		return this.area === "shared-kernel";
 	}
@@ -693,39 +698,44 @@ var Layout = class {
 			area: dirname(file) === this.settings.rootDir ? "root" : "outside",
 			fileName
 		});
-		const area = folder.isSharedKernel ? "shared-kernel" : "context";
-		const context = folder.name;
+		const inside = this.insideOf(folder);
 		const directories = this.directoriesBetween(folder.dir, file);
 		if (directories.length === 0) return new Location({
-			area,
-			context,
+			...inside,
 			fileName,
 			isCompositionRoot: this.isCompositionRoot(fileName)
 		});
 		const layerIndex = this.layerIndexOf(directories, folder.isSharedKernel);
-		if (layerIndex === void 0) return new Location({
-			area,
-			context,
-			fileName,
-			isCompositionRoot: folder.isSharedKernel && directories.length === 1 && this.isCompositionRoot(fileName)
-		});
+		if (layerIndex === void 0) {
+			const isFeatureRoot = folder.isSharedKernel && directories.length === 1;
+			return new Location({
+				...inside,
+				fileName,
+				isCompositionRoot: isFeatureRoot && this.isCompositionRoot(fileName)
+			});
+		}
 		const layer = directories[layerIndex];
 		if (layer === void 0 || !this.isLayer(layer)) return new Location({
-			area,
-			context,
+			...inside,
 			fileName
 		});
 		const foldersInLayer = directories.slice(layerIndex + 1);
 		const subfolder = foldersInLayer.at(-1);
 		return new Location({
-			area,
-			context,
+			...inside,
 			fileName,
 			foldersInLayer,
 			layer,
 			...subfolder === void 0 ? {} : { folder: subfolder }
 		});
 	}
+	insideOf(folder) {
+		return {
+			area: folder.isSharedKernel ? "shared-kernel" : "context",
+			context: folder.name,
+			...folder.subdomain === void 0 ? {} : { subdomain: folder.subdomain }
+		};
+	}
 	layerIndexOf(directories, isSharedKernel) {
 		if (this.isLayer(directories[0] ?? "")) return 0;
 		if (isSharedKernel && this.isLayer(directories[1] ?? "")) return 1;
@@ -901,6 +911,16 @@ var Wording = class {
 //#region src/rules/framework/rule.ts
 var Rule = class {
 	wording = new Wording();
+	filesOf(architecture) {
+		const files = [];
+		for (const file of architecture.files) if (this.checks(file, architecture)) files.push(file);
+		return files;
+	}
+	checks(file, architecture) {
+		if (this.meta.contexts === "every") return true;
+		const location = architecture.locationOf(file);
+		return !location.isInBoundedContext || location.isInCoreDomain;
+	}
 	finding(file, line, symbol, messageId, data = {}) {
 		return {
 			data,
@@ -916,7 +936,7 @@ var Rule = class {
 var ClassRule = class extends Rule {
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) for (const codeClass of file.classes) findings.push(...this.findingsFor(codeClass, file, architecture));
+		for (const file of this.filesOf(architecture)) for (const codeClass of file.classes) findings.push(...this.findingsFor(codeClass, file, architecture));
 		return findings;
 	}
 };
@@ -925,7 +945,7 @@ var ClassRule = class extends Rule {
 var ImportRule = class extends Rule {
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			if (!this.appliesTo(file, architecture)) continue;
 			for (const dependency of file.dependencies) {
 				const finding = this.findingFor(dependency, file, architecture);
@@ -974,6 +994,7 @@ const shortcuts = [
 ];
 var NoDrivingShortcutRule = class extends ImportRule {
 	meta = {
+		contexts: "core",
 		description: "A driving adapter importing a port, a repository, an aggregate, an entity or a domain service instead of calling a handler.",
 		id: "layers/no-driving-shortcut",
 		messages: { shortcut: "Imports {name}, {kind}: a driving adapter calls the command and query handlers, never the ports, repositories or aggregates of the domain." }
@@ -1013,6 +1034,7 @@ var NoDrivingShortcutRule = class extends ImportRule {
 //#region src/rules/layers/no-impure-domain.rule.ts
 var NoImpureDomainRule = class extends ImportRule {
 	meta = {
+		contexts: "core",
 		description: "The domain importing a framework, a database, another layer or a package not allowed, or using the host, the clock or randomness.",
 		id: "layers/no-impure-domain",
 		messages: {
@@ -1027,7 +1049,7 @@ var NoImpureDomainRule = class extends ImportRule {
 	};
 	check(architecture) {
 		const findings = super.check(architecture);
-		for (const file of architecture.files) if (this.appliesTo(file, architecture)) findings.push(...this.impureGlobals(file));
+		for (const file of this.filesOf(architecture)) if (this.appliesTo(file, architecture)) findings.push(...this.impureGlobals(file));
 		return findings;
 	}
 	appliesTo(file, architecture) {
@@ -1074,6 +1096,7 @@ var NoImpureDomainRule = class extends ImportRule {
 //#region src/rules/layers/no-outward-import.rule.ts
 var NoOutwardImportRule = class extends ImportRule {
 	meta = {
+		contexts: "core",
 		description: "A dependency pointing away from the domain, a file outside the layers or in the wrong folder of its layer.",
 		id: "layers/no-outward-import",
 		messages: {
@@ -1125,7 +1148,7 @@ var NoOutwardImportRule = class extends ImportRule {
 	}
 	misplacedFiles(architecture) {
 		const findings = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			const location = architecture.locationOf(file);
 			if (location.isOutside) findings.push(this.finding(file, 1, location.fileName, "outsideContexts"));
 			else if (!location.isAtRoot && !location.isInLayer && !location.isCompositionRoot) findings.push(this.finding(file, 1, location.fileName, "outsideLayers"));
@@ -1150,7 +1173,7 @@ var NoOutwardImportRule = class extends ImportRule {
 	}
 	extraCompositionRoots(architecture) {
 		const byFolder = /* @__PURE__ */ new Map();
-		for (const file of architecture.files) if (architecture.locationOf(file).isCompositionRoot) {
+		for (const file of this.filesOf(architecture)) if (architecture.locationOf(file).isCompositionRoot) {
 			const folder = dirname(file.path);
 			byFolder.set(folder, [...byFolder.get(folder) ?? [], file]);
 		}
@@ -1210,6 +1233,7 @@ var NoOutwardImportRule = class extends ImportRule {
 //#region src/rules/layers/no-portless-adapter.rule.ts
 var NoPortlessAdapterRule = class extends ClassRule {
 	meta = {
+		contexts: "core",
 		description: "A driven adapter that extends no port, a port declared outside the domain.",
 		id: "layers/no-portless-adapter",
 		messages: {
@@ -1235,11 +1259,12 @@ var NoPortlessAdapterRule = class extends ClassRule {
 //#region src/rules/strategic/no-cross-context-import.rule.ts
 var NoCrossContextImportRule = class extends ImportRule {
 	meta = {
+		contexts: "every",
 		description: "An import from another bounded context that is not its open host service, a composition root that re-exports.",
 		id: "strategic/no-cross-context-import",
 		messages: {
 			notOpenHostService: "Imports {target}: only an OpenHostService of another bounded context may be imported.",
-			outsideAntiCorruptionLayer: "Uses the open host service of {context} outside an AntiCorruptionLayer: translate it in an anti-corruption layer.",
+			outsideAntiCorruptionLayer: "Uses the open host service of {context} outside an AntiCorruptionLayer: a core context translates what it consumes in an anti-corruption layer.",
 			publishedLanguage: "Imports the published language of {context}: redeclare the fields you read in your own published-language/.",
 			reexport: "The composition root re-exports {names}: it exports its own module only, so that no other context reaches through it.",
 			sharedKernel: "The shared kernel imports no bounded context, but imports {target}."
@@ -1260,7 +1285,7 @@ var NoCrossContextImportRule = class extends ImportRule {
 		if (from.isCompositionRoot && to.isCompositionRoot) return;
 		if (to.layer === "published-language") return this.finding(file, dependency.line, dependency.label, "publishedLanguage", { context: to.context ?? "" });
 		if (!this.importsOnlyOpenHostServices(dependency, target.path, architecture)) return this.finding(file, dependency.line, dependency.label, "notOpenHostService", { target: this.wording.target(target, architecture) });
-		if (!from.isCompositionRoot && !this.declaresAntiCorruptionLayer(file, architecture)) return this.finding(file, dependency.line, dependency.label, "outsideAntiCorruptionLayer", { context: to.context ?? "" });
+		if (from.isInCoreDomain && !from.isCompositionRoot && !this.declaresAntiCorruptionLayer(file, architecture)) return this.finding(file, dependency.line, dependency.label, "outsideAntiCorruptionLayer", { context: to.context ?? "" });
 	}
 	importsOnlyOpenHostServices(dependency, path, architecture) {
 		const target = architecture.project.file(path);
@@ -1289,6 +1314,7 @@ const owned = [
 ];
 var NoFatSharedKernelRule = class extends ClassRule {
 	meta = {
+		contexts: "every",
 		description: "An aggregate, an entity, an event, a domain service, a repository or a handler in the shared kernel.",
 		id: "strategic/no-fat-shared-kernel",
 		messages: { owned: "{class} is {kind} in the shared kernel: it belongs to one bounded context; the shared kernel holds value objects, ports and their adapters." }
@@ -1308,6 +1334,7 @@ var NoFatSharedKernelRule = class extends ClassRule {
 //#region src/rules/strategic/no-leaky-host-service.rule.ts
 var NoLeakyHostServiceRule = class extends ClassRule {
 	meta = {
+		contexts: "every",
 		description: "An open host service that exposes a class of its context instead of the published language.",
 		id: "strategic/no-leaky-host-service",
 		messages: { exposes: "{member} exposes {type}, {kind}{owner}: an open host service speaks the published language." }
@@ -1346,6 +1373,7 @@ var NoLeakyHostServiceRule = class extends ClassRule {
 //#region src/rules/strategic/no-unmapped-context.rule.ts
 var NoUnmappedContextRule = class extends Rule {
 	meta = {
+		contexts: "every",
 		description: "A bounded context consuming one the context map does not allow, or two contexts that depend on each other.",
 		id: "strategic/no-unmapped-context",
 		messages: {
@@ -1367,7 +1395,7 @@ var NoUnmappedContextRule = class extends Rule {
 	}
 	consumptionsIn(architecture) {
 		const consumptions = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			const from = architecture.locationOf(file);
 			if (!from.isInBoundedContext || from.context === void 0) continue;
 			for (const dependency of file.dependencies) {
@@ -1400,6 +1428,7 @@ const holders = [
 ];
 var NoAggregateReferenceRule = class extends Rule {
 	meta = {
+		contexts: "core",
 		description: "An aggregate holding another aggregate instead of its identifier, an entity held by two aggregates.",
 		id: "tactical/no-aggregate-reference",
 		messages: {
@@ -1410,7 +1439,7 @@ var NoAggregateReferenceRule = class extends Rule {
 	};
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) for (const codeClass of file.classes) findings.push(...this.heldAggregates(codeClass, file, architecture));
+		for (const file of this.filesOf(architecture)) for (const codeClass of file.classes) findings.push(...this.heldAggregates(codeClass, file, architecture));
 		findings.push(...this.sharedEntities(architecture));
 		return findings;
 	}
@@ -1459,7 +1488,7 @@ var NoAggregateReferenceRule = class extends Rule {
 	}
 	holdingsIn(architecture) {
 		const holdings = [];
-		for (const file of architecture.files) for (const aggregate of file.classes) {
+		for (const file of this.filesOf(architecture)) for (const aggregate of file.classes) {
 			if (!architecture.is(aggregate, "AggregateRoot")) continue;
 			const visited = /* @__PURE__ */ new Set();
 			for (const through of this.heldBy(aggregate)) for (const type of through.types) for (const entity of this.entitiesReachedFrom(type, architecture, visited)) holdings.push({
@@ -1514,6 +1543,7 @@ const statementMessages = {
 };
 var NoLooseCodeRule = class extends Rule {
 	meta = {
+		contexts: "core",
 		description: "Code outside a building block in the domain or the application, outside a class in an adapter layer, anything but the module class in a composition root.",
 		id: "tactical/no-loose-code",
 		messages: {
@@ -1535,7 +1565,7 @@ var NoLooseCodeRule = class extends Rule {
 	};
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			const location = architecture.locationOf(file);
 			if (guarded$2.has(location.layer)) {
 				findings.push(...this.looseClasses(file, location.layer ?? "domain", architecture));
@@ -1585,6 +1615,7 @@ const markerWording = {
 };
 var NoMisplacedClassRule = class extends Rule {
 	meta = {
+		contexts: "core",
 		description: "A class in the wrong folder or file, two classes in one file.",
 		id: "tactical/no-misplaced-class",
 		messages: {
@@ -1595,7 +1626,7 @@ var NoMisplacedClassRule = class extends Rule {
 	};
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			findings.push(...this.extraClasses(file));
 			const [first] = file.classes;
 			const finding = first === void 0 ? void 0 : this.misplacement(first, file, architecture.locationOf(file), architecture);
@@ -1630,6 +1661,7 @@ var NoMisplacedClassRule = class extends Rule {
 //#region src/rules/tactical/command-handlers/no-foreign-command-dependency.rule.ts
 var NoForeignCommandDependencyRule = class extends InjectionRule {
 	meta = {
+		contexts: "core",
 		description: "A command handler receiving a query repository, an event publisher, another handler or a plain class.",
 		id: "tactical/no-foreign-command-dependency",
 		messages: { foreign: "The CommandHandler {class} receives {type}, {kind}: a command handler receives command repositories, ports, event translators, domain services and value objects; events leave through the outbox, never a publisher." }
@@ -1657,6 +1689,7 @@ const exempt = /* @__PURE__ */ new Set([
 const guarded$1 = /* @__PURE__ */ new Set(["domain", "application"]);
 var NoThrownFailureRule = class extends Rule {
 	meta = {
+		contexts: "core",
 		description: "A business failure thrown instead of returned, an entity method without a Result, a setter.",
 		id: "tactical/no-thrown-failure",
 		messages: {
@@ -1668,7 +1701,7 @@ var NoThrownFailureRule = class extends Rule {
 	};
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) {
+		for (const file of this.filesOf(architecture)) {
 			findings.push(...this.operationsWithoutResult(file, architecture));
 			if (guarded$1.has(architecture.locationOf(file).layer)) findings.push(...this.raisedFailures(file));
 		}
@@ -1703,6 +1736,7 @@ var NoThrownFailureRule = class extends Rule {
 //#region src/rules/tactical/domain-services/no-stateful-service.rule.ts
 var NoStatefulServiceRule = class extends InjectionRule {
 	meta = {
+		contexts: "core",
 		description: "A domain service holding a port, a repository or another service.",
 		id: "tactical/no-stateful-service",
 		messages: { foreign: "The DomainService {class} holds {type}, {kind}: a domain service holds configuration only; the command handler passes it what it needs." }
@@ -1720,6 +1754,7 @@ const guarded = [
 ];
 var NoPublicFieldRule = class extends ClassRule {
 	meta = {
+		contexts: "core",
 		description: "A public field on an aggregate, an entity, a value object or an identifier.",
 		id: "tactical/no-public-field",
 		messages: { publicField: "{member} is a public field: keep the state private, and expose what callers need through a getter." }
@@ -1738,6 +1773,7 @@ var NoPublicFieldRule = class extends ClassRule {
 //#region src/rules/tactical/query-handlers/no-foreign-query-dependency.rule.ts
 var NoForeignQueryDependencyRule = class extends InjectionRule {
 	meta = {
+		contexts: "core",
 		description: "A query handler receiving what writes or changes state.",
 		id: "tactical/no-foreign-query-dependency",
 		messages: { foreign: "The QueryHandler {class} receives {type}, {kind}: a query handler receives query repositories, ports that do not write, and value objects." }
@@ -1775,6 +1811,7 @@ var DisableDirective = class {
 var NoLooseDisableRule = class extends Rule {
 	knownRules;
 	meta = {
+		contexts: "every",
 		description: "A disable comment that names no known rule, gives no reason, or disables nothing.",
 		id: "tooling/no-loose-disable",
 		messages: {
@@ -1790,7 +1827,7 @@ var NoLooseDisableRule = class extends Rule {
 	}
 	check(architecture) {
 		const findings = [];
-		for (const file of architecture.files) for (const comment of file.disables) {
+		for (const file of this.filesOf(architecture)) for (const comment of file.disables) {
 			const finding = this.malformed(file, comment);
 			if (finding !== void 0) findings.push(finding);
 		}
@@ -1960,7 +1997,9 @@ var Report = class {
 	text() {
 		const blocks = [];
 		for (const [file, violations] of this.byFile()) blocks.push(this.block(file, violations));
-		return `${[...blocks, this.summary()].join("\n\n")}\n`;
+		const parts = [...blocks, this.summary()];
+		if (blocks.length > 0) parts.push(this.colors.dim("Why, and how to fix it: npx alveolus explain <rule>"));
+		return `${parts.join("\n\n")}\n`;
 	}
 	json() {
 		const { baselined, files, stale, suppressed, violations } = this.input;
@@ -2082,16 +2121,37 @@ var Config = class {
 		this.contextMap = config.contextMap === void 0 ? void 0 : this.validContextMap(config.contextMap, Object.keys(config.boundedContexts));
 		this.rules = config.rules;
 		const sharedKernel = config.sharedKernel ?? "shared-kernel";
-		this.contextFolders = [...Object.entries(config.boundedContexts).map(([name, folder]) => ({
-			dir: resolve(this.rootDir, folder),
-			isSharedKernel: false,
-			name
-		})), {
+		this.contextFolders = [...this.classifiedContexts(config.subdomains ?? {}, config.boundedContexts), {
 			dir: resolve(this.rootDir, sharedKernel),
 			isSharedKernel: true,
 			name: "shared kernel"
 		}];
 	}
+	classifiedContexts(subdomains, boundedContexts) {
+		const types = [
+			"core",
+			"supporting",
+			"generic"
+		];
+		const classified = /* @__PURE__ */ new Map();
+		const folders = [];
+		for (const type of types) for (const name of subdomains[type] ?? []) {
+			const folder = boundedContexts[name];
+			if (folder === void 0) throw new Error(`subdomains names ${name}, which boundedContexts does not declare.`);
+			const already = classified.get(name);
+			if (already !== void 0) throw new Error(`subdomains lists ${name} as ${already} and as ${type}: a bounded context implements one subdomain.`);
+			classified.set(name, type);
+			folders.push({
+				dir: resolve(this.rootDir, folder),
+				isSharedKernel: false,
+				name,
+				subdomain: type
+			});
+		}
+		const unclassified = Object.keys(boundedContexts).filter((name) => !classified.has(name));
+		if (unclassified.length > 0) throw new Error(`boundedContexts declares ${unclassified.join(", ")}, which subdomains does not classify: list each context under subdomains.core, subdomains.supporting or subdomains.generic.`);
+		return folders;
+	}
 	validContextMap(upstreams, contexts) {
 		const map = new ContextMap(upstreams);
 		const unknown = map.contexts.filter((name) => !contexts.includes(name));
@@ -2117,6 +2177,7 @@ const ruleSetting = z.enum([
 	"info",
 	"off"
 ]);
+const contextNames = z.array(z.string()).exactOptional();
 const schema = z.strictObject({
 	applicationDependencies: packageDependencies.exactOptional(),
 	boundedContexts: z.record(z.string(), z.string()),
@@ -2131,6 +2192,11 @@ const schema = z.strictObject({
 	root: z.string(),
 	rules: z.strictObject(Object.fromEntries(new RuleRegistry().ids.map((id) => [id, ruleSetting.exactOptional()]))).exactOptional(),
 	sharedKernel: z.string().exactOptional(),
+	subdomains: z.strictObject({
+		core: contextNames,
+		generic: contextNames,
+		supporting: contextNames
+	}).exactOptional(),
 	tsconfig: z.string().exactOptional()
 });
 var ConfigLoader = class ConfigLoader {
@@ -2709,18 +2775,91 @@ var TsMorphImporter = class TsMorphImporter extends Importer {
 		return offset !== "" && !offset.startsWith("..") && !isAbsolute(offset) && !offset.split(/[\\/]/).includes("node_modules");
 	}
 };
+const scaffolds = [
+	{
+		content: `import { defineConfig } from "@alveolus/arch";
+
+export default defineConfig({
+	boundedContexts: {},
+	root: "src",
+});
+`,
+		path: "alveolus.config.ts"
+	},
+	{
+		content: `---
+name: alveolus
+description: Domain-Driven Design with @alveolus/core and @alveolus/arch. Use when writing or changing a class of the domain, the application or an adapter, when a class extends an Alveolus building block, or when alveolus arch check reports a violation.
+---
+
+# Alveolus
+
+The documentation is installed with the package: read it with \`npx alveolus explain <topic>\`, not on the web. \`npx alveolus explain\` lists every topic.
+
+1. Before writing a class, read its building block: \`npx alveolus explain aggregates\`, \`entities\`, \`value-objects\`, \`domain-events\`, \`domain-errors\`, \`ports\`, \`repositories\`, \`command-handlers\`, \`query-handlers\`, \`result\`.
+2. Where a file goes and what each layer may import: \`npx alveolus explain project-layout\`.
+3. After each change, run \`npx alveolus arch check\`.
+4. On a violation, read the rule before changing the code: \`npx alveolus explain <rule>\`, with the rule id of the report, such as \`layers/no-impure-domain\`. Fix the cause: never turn a rule off, add a disable comment or edit \`alveolus.baseline.json\` by hand without asking.
+`,
+		path: ".claude/skills/alveolus/SKILL.md"
+	},
+	{
+		content: `## Alveolus
+
+This project uses Alveolus for Domain-Driven Design: the building blocks of \`@alveolus/core\` and the architecture checks of \`@alveolus/arch\`. The documentation is installed with the package: \`npx alveolus explain\` lists the topics and \`npx alveolus explain <topic>\` prints one, so do not look for it on the web. Run \`npx alveolus arch check\` after each change, and read the rule reported with \`npx alveolus explain <rule>\` before fixing. See \`.claude/skills/alveolus/SKILL.md\`.
+`,
+		marker: "npx alveolus explain",
+		path: "AGENTS.md"
+	}
+];
+//#endregion
+//#region src/init/init.ts
+var Init = class {
+	projectDir;
+	constructor(projectDir) {
+		this.projectDir = projectDir;
+	}
+	run() {
+		const written = [];
+		for (const scaffold of scaffolds) written.push({
+			outcome: this.write(scaffold),
+			path: scaffold.path
+		});
+		return written;
+	}
+	get hint() {
+		const claude = join(this.projectDir, "CLAUDE.md");
+		if (!existsSync(claude)) return;
+		return "CLAUDE.md exists: Claude Code reads it instead of AGENTS.md, so add a line with @AGENTS.md to it.";
+	}
+	write(scaffold) {
+		const path = join(this.projectDir, scaffold.path);
+		if (!existsSync(path)) {
+			mkdirSync(dirname(path), { recursive: true });
+			writeFileSync(path, scaffold.content);
+			return "created";
+		}
+		if (scaffold.marker === void 0) return "kept";
+		const existing = readFileSync(path, "utf8");
+		if (existing.includes(scaffold.marker)) return "kept";
+		writeFileSync(path, `${existing.trimEnd()}\n\n${scaffold.content}`);
+		return "appended";
+	}
+};
 //#endregion
 //#region src/cli/cli.ts
 var Cli = class {
 	stdout;
 	stderr;
 	cwd;
+	docs;
 	colored;
 	exitCode = 0;
-	constructor(stdout, stderr, cwd, colored = false) {
+	constructor(stdout, stderr, cwd, docs, colored = false) {
 		this.stdout = stdout;
 		this.stderr = stderr;
 		this.cwd = cwd;
+		this.docs = docs;
 		this.colored = colored;
 	}
 	async run(args) {
@@ -2740,8 +2879,30 @@ var Cli = class {
 		const arch = program.command("arch").description("Check the architecture of a Domain-Driven Design project");
 		this.withOptions(arch.command("check").description("Report the violations that are not in the baseline")).action((options) => this.check(options));
 		this.withOptions(arch.command("baseline").description(`Write the current violations to ${Baseline.fileName}`)).option("--allow-growth", "write the baseline even when it holds more entries than before").action((options) => this.baseline(options));
+		program.command("explain").description("Print a page of the documentation: a rule, a building block or a guide").argument("[topic]", "a rule id, a building block or a guide; without it, the list of topics").action((topic) => this.explain(topic));
+		program.command("init").description(`Write ${ConfigLoader.fileName}, and the instructions that tell a coding agent to read the documentation installed with the package`).option("--project <dir>", "project directory", ".").action((options) => this.init(options));
 		return program;
 	}
+	explain(topic) {
+		if (topic === void 0) {
+			this.stdout.write(`${this.docs.topics().join("\n")}\n`);
+			return;
+		}
+		const match = this.docs.find(topic);
+		if ("page" in match) {
+			this.stdout.write(match.page.text());
+			return;
+		}
+		const list = match.candidates.length === 0 ? "alveolus explain lists the topics." : `Did you mean ${match.candidates.join(", ")}?`;
+		this.stderr.write(`No page for ${topic}: ${list}\n`);
+		this.exitCode = 1;
+	}
+	init(options) {
+		const init = new Init(resolve(this.cwd, options.project));
+		for (const { outcome, path } of init.run()) this.stdout.write(`${outcome}  ${path}\n`);
+		this.stdout.write(`Name your bounded contexts in ${ConfigLoader.fileName}, then run alveolus arch check.\n`);
+		if (init.hint !== void 0) this.stderr.write(`${init.hint}\n`);
+	}
 	withOptions(command) {
 		return command.option("--project <dir>", "project directory", ".").option("--config <file>", "configuration file", ConfigLoader.fileName).option("--tsconfig <file>", "TypeScript configuration, tsconfig.json or the one set in the configuration file").addOption(new Option("--format <format>", "how violations are printed").choices([
 			"text",
@@ -2805,6 +2966,94 @@ var Cli = class {
 	}
 };
 //#endregion
-export { Config as a, RuleRegistry as c, AllowedPackages as d, Baseline as f, ConfigLoader as i, Rule as l, TsMorphImporter as n, Report as o, Importer as r, Checker as s, Cli as t, Architecture as u };
+//#region src/docs/page.ts
+const html = [
+	{
+		pattern: /<dt>/g,
+		text: "- "
+	},
+	{
+		pattern: /<\/dt>\s*<dd>/g,
+		text: ": "
+	},
+	{
+		pattern: /<[^>\n]+>/g,
+		text: ""
+	},
+	{
+		pattern: /^\t+- /gm,
+		text: "- "
+	},
+	{
+		pattern: /&lt;/g,
+		text: "<"
+	},
+	{
+		pattern: /&gt;/g,
+		text: ">"
+	},
+	{
+		pattern: /&amp;/g,
+		text: "&"
+	}
+];
+const frontmatter = /^---\n([\s\S]*?)\n---\n/;
+var Page = class {
+	topic;
+	source;
+	constructor(topic, source) {
+		this.topic = topic;
+		this.source = source;
+	}
+	get description() {
+		const header = frontmatter.exec(this.source)?.[1] ?? "";
+		return /^description: "?(.*?)"?$/m.exec(header)?.[1] ?? "";
+	}
+	text() {
+		let text = this.source.replace(frontmatter, "");
+		for (const { pattern, text: replacement } of html) text = text.replace(pattern, replacement);
+		return `${text.replace(/\n{3,}/g, "\n\n").trim()}\n`;
+	}
+};
+//#endregion
+//#region src/docs/docs.ts
+var Docs = class Docs {
+	dir;
+	static sections = [
+		"guide",
+		"integrations",
+		"core",
+		"rules"
+	];
+	constructor(dir) {
+		this.dir = dir;
+	}
+	topics() {
+		const topics = [];
+		for (const section of Docs.sections) for (const file of globSync("**/*.md", { cwd: join(this.dir, section) }).sort()) topics.push(this.topicOf(join(section, file)));
+		return topics.sort();
+	}
+	find(name) {
+		const wanted = name.replace(/\.md$/, "").replace(/\/$/, "").replace(/\\/g, "/");
+		const candidates = this.topics().filter((topic) => topic === wanted || topic.endsWith(`/${wanted}`));
+		const exact = candidates.find((topic) => topic === wanted);
+		if (exact !== void 0) return { page: this.read(exact) };
+		if (candidates.length === 1 && candidates[0] !== void 0) return { page: this.read(candidates[0]) };
+		return { candidates };
+	}
+	read(topic) {
+		const path = join(this.dir, ...topic.split("/"));
+		try {
+			return new Page(topic, readFileSync(`${path}.md`, "utf8"));
+		} catch {
+			return new Page(topic, readFileSync(join(path, "index.md"), "utf8"));
+		}
+	}
+	topicOf(file) {
+		return file.split(sep).join("/").replace(/\.md$/, "").replace(/\/index$/, "");
+	}
+};
+//#endregion
+export { TsMorphImporter as a, Config as c, RuleRegistry as d, Rule as f, Baseline as h, Init as i, Report as l, AllowedPackages as m, Page as n, Importer as o, Architecture as p, Cli as r, ConfigLoader as s, Docs as t, Checker as u };
 
-//# sourceMappingURL=cli-CwPCGjDg.mjs.map
+//# sourceMappingURL=docs-DsQHpTtV.mjs.map