backend-skeleton 1.2.0 → 1.3.0

package/README.md

@@ -32,9 +32,13 @@ check for a specific failure mode found the same way — see `DECISIONS.md` for
 
 - [Status: 1.0.0](#status-100)
 - [Quickstart](#quickstart)
+  - [Try it in 10 seconds](#try-it-in-10-seconds)
+  - [The gated workflow](#the-gated-workflow)
   - [Starting from nothing (greenfield)](#starting-from-nothing-greenfield)
   - [Publishing a feature's contract as OpenAPI (optional)](#publishing-a-features-contract-as-openapi-optional)
+  - [A CSV table of a feature's contract (optional)](#a-csv-table-of-a-features-contract-optional)
   - [Database schema (optional)](#database-schema-optional)
+  - [An ERD of your database schema (optional)](#an-erd-of-your-database-schema-optional)
   - [Applying DDL to a live database (optional)](#applying-ddl-to-a-live-database-optional)
   - [Declaring field-to-field dependencies (optional)](#declaring-field-to-field-dependencies-optional)
   - [Patching a config file (optional)](#patching-a-config-file-optional)
@@ -84,6 +88,21 @@ production -- which still splits the same way it always has:
 
 ## Quickstart
 
+### Try it in 10 seconds
+
+```bash
+npm install -g backend-skeleton   # or: npx backend-skeleton <command>
+cd <any-existing-repo>            # must be a git repository -- that's the only requirement
+bskel scan                        # zero flags: every module/controller/entity/enum this repo's
+                                   #   adapter can see, unscored -- no preflight, no feature, no
+                                   #   files written, no gate touched
+```
+
+That's a read-only look, not the gated workflow — for real feature work (collision-checked against
+a specific idea, contract-gated, codegen), see below.
+
+### The gated workflow
+
 ```bash
 npm install -g backend-skeleton   # or: npx backend-skeleton <command>
 cd <target-repo>                  # must be a git repository
@@ -193,6 +212,27 @@ bskel new --stack fastapi --slug my-service \
 The full parameter list, the measured API-validation matrix behind that split, and the warning
 behaviour are in `D-greenfield-parameters` in `DECISIONS.md`.
 
+#### Remembering your own conventions across projects (optional)
+
+If you start several projects with the same conventions, `bskel new` can record them into a
+database **you own** -- never bskel's own state, never a shared store:
+
+```bash
+export MY_PATTERNS=postgres://localhost/my_patterns    # once: run patterns/schema.sql against it
+
+bskel new --stack spring --slug billing \
+  --java-version 21 --group-id com.acme --dependencies web,data-jpa,validation,flyway \
+  --record-pattern --pattern-database-url-env MY_PATTERNS
+
+bskel pattern suggest --stack spring --pattern-database-url-env MY_PATTERNS
+```
+
+`pattern suggest` prints what you've recorded, with per-value frequency, and a ready-to-paste
+command line at the bottom -- it never runs `bskel new` for you and `bskel new` has no flag that
+would accept a suggestion as a default. Every value in a generated project is still one you typed
+in that invocation. Omitting `--record-pattern`/`--pattern-database-url-env` leaves `bskel new`
+exactly as it is today. See `D-pattern-accrual` in `DECISIONS.md`.
+
 ### Publishing a feature's contract as OpenAPI (optional)
 
 ```bash
@@ -232,6 +272,31 @@ contract's paths don't reflect (`--allow-unprefixed` overrides), and stamps ever
 reconciling a contract against its own export would make it confirm itself. See `D-openapi-export`
 in `DECISIONS.md`.
 
+### A CSV table of a feature's contract (optional)
+
+```bash
+bskel contract export-csv --feature 001-organization-management --out organization.csv
+```
+
+One row per operation, opened by someone who will never read a JSON Schema — a PM reviewing scope,
+a lead deciding whether a partial contract is good enough to waive. Fourteen columns, always, in
+the same order: `operation_id, verb, path, path_params, path_params_unverified, body,
+request_body_required, request_body_fields, response_fields, error_fields, provenance, summary,
+tags, security`.
+
+**Every column is always present, even when every row leaves it blank** — a scan-only contract
+(no `--openapi-file`) never states `summary`/`tags`/`security`, and the blank columns *are* that
+finding, not something to hide: `export-csv` prints exactly which columns are empty for every
+operation, and why, on stderr. Dropping an empty column would make the file's own shape depend on
+its content, so it never does.
+
+**Unlike `contract export`, this command is deliberately UNGATED** — it works even when the
+`contract` gate hasn't passed yet, because its single most valuable moment is reviewing a partial
+contract to decide whether to waive it. An unreflected global path-prefix signal (the thing
+`contract export` hard-refuses on) downgrades to a stderr warning here instead. `--bom` prepends a
+UTF-8 byte-order mark for Excel-on-Windows, which otherwise mangles non-ASCII text; omit it for
+`pandas`/`csv.DictReader`/`diff`, which don't want one. See `D-contract-csv` in `DECISIONS.md`.
+
 ### Database schema (optional)
 
 `bskel scan --db` additionally scans Flyway/Liquibase migration files (local only, no network).
@@ -249,6 +314,40 @@ report also carries `generated_at` — when the underlying data was actually cap
 be judged for staleness rather than trusted blindly. See `D-cross-feature-fk-inference` in
 `DECISIONS.md`.
 
+### An ERD of your database schema (optional)
+
+```bash
+bskel db erd --database-url-env BSKEL_DB_URL --schema public --out schema.mmd
+```
+
+A Mermaid `erDiagram` of the database — paste it straight into a GitHub/GitLab/Notion/Obsidian
+markdown file (fence it in \`\`\`mermaid) or [mermaid.live](https://mermaid.live) and it renders
+with no extra tooling. Works two ways:
+
+- **With `--database-url-env`**: a real, live Postgres introspection — full column types,
+  nullability, and primary/foreign keys.
+- **Without it**: falls back to scanning Flyway/Liquibase `.sql` migration files (no network, no
+  credentials needed) — a real but **degraded** diagram, clearly marked as such in the file itself:
+  every column types as `unknown`, no `PK` badge appears anywhere, and a header block spells out
+  exactly what's missing. Useful for evaluating the tool on a repo you don't have DB credentials
+  for yet.
+
+Two things this diagram deliberately does **not** guess:
+
+- **Composite foreign keys.** Postgres's own `information_schema` doesn't retain which source
+  column pairs with which target column once a foreign key spans more than one column — the raw
+  data is a cross product that can include pairs that were never declared. Rather than draw a wrong
+  relationship line, a composite FK collapses to one line labeled with all its source columns
+  joined by `+`, with the ambiguity spelled out in a `%%` comment above it. (Composite *primary*
+  keys have no such problem and render fully.)
+- **1:1 vs 1:N.** The child side of every relationship is drawn as "zero or more," never "exactly
+  one" — telling those apart needs a UNIQUE constraint check this tool doesn't perform. The header
+  says so.
+
+Whole-schema only in this version (no `--feature`/`--tables` filtering yet) — for a very large
+schema, `db erd` prints a note above 40 entities rather than silently producing an unreadable
+diagram. See `D-db-erd` in `DECISIONS.md`.
+
 ### Applying DDL to a live database (optional)
 
 `bskel patch propose --kind ddl-apply` extends the same propose/approve/apply/rollback lifecycle
@@ -385,7 +484,7 @@ below).
 |---|---|---|
 | Node.js | `>=18` | ES2022 (`Object.hasOwn`) + ESM top-level `await` — nothing newer is used anywhere in the runtime code (verified by grep across every recent-ES-addition pattern; see `D-npm-packaging` in `DECISIONS.md`) |
 | git | required | every gate is git-state-derived |
-| [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) | required for `scan`/`handles` | every scanner adapter shells out to it directly, and throws (not degrades) if it's missing |
+| [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`) | required for `scan`/`handles` | every scanner adapter shells out to it at `detect()` time behind a blanket try/catch — traced live, missing `rg` does NOT throw, it silently makes every real adapter detect nothing (degrades to the low-confidence `generic-grep` fallback). `bskel scan`'s report now carries a `rg_available: false` field plus an explicit `unknowns` warning whenever this happens, so it stays distinguishable from a genuinely-unrecognized repo — see `D-zero-config-scan` in `DECISIONS.md` |
 | `gh` (GitHub CLI) | optional | only used for `preflight`'s 3-way default-branch cross-check; already soft-guarded, never a hard requirement |
 | `python3` | optional | only needed to run this repository's own cross-language codec test — `bskel` itself never invokes `python3` |
 | a build wrapper (`gradlew`/`pom.xml`+`mvnw`/`package.json`) | optional | only `bskel verify --build` needs one; `handles emit` never compiles anything itself |

package/bin/bskel.mjs

@@ -44,7 +44,8 @@ import {
 	findCollisions, evaluateCrossFeatureFindings, waiverKey,
 	crossFeatureReportPath, loadCrossFeatureReport, loadCrossFeatureResolution, saveCrossFeatureResolution,
 } from '../lib/cross-feature-collisions.mjs';
-import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting } from '../new/index.mjs';
+import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting, reusableParamsFor } from '../new/index.mjs';
+import { recordPattern, listPatterns, getPattern, isMissingPatternTable, summarizePatternFrequency } from '../patterns/store.mjs';
 import {
 	requireSingleLineText, requireValidJavaPackageName, requireValidArtifactId,
 	requireValidPythonVersion, requireValidLicense, requireValidDatabase, requireSupportedJavaVersion,
@@ -53,6 +54,8 @@ import {
 import { DEFAULT_GROUP_ID, DEFAULT_JAVA_VERSION, resolveSpringDependencies } from '../new/spring.mjs';
 import { buildReconciliation, snapshotFromReconciliation, describeSourceFile } from '../contracts/openapi.mjs';
 import { buildOpenApiDocument, pathPrefixCandidates, unreflectedPathPrefixes, STATUS_CODE_MODES } from '../contracts/export.mjs';
+import { buildContractCsv } from '../contracts/csv.mjs';
+import { buildErdDiagram } from '../scanners/db/erd.mjs';
 import { loadCatalogEntry, listCatalogChoices, planApply, applyPlan } from '../stack/apply.mjs';
 import { PROVIDERS, PROVIDER_LOAD_ERRORS, providerById } from '../handles/registry.mjs';
 import { detectAstHelperAvailable, runAstClassify } from '../handles/providers/java-spring/ast-bridge.mjs';
@@ -65,7 +68,7 @@ import { plan as planTypeScriptExpress } from '../handles/providers/typescript-e
 import { emitObserveTypeScriptExpress } from '../handles/providers/typescript-express/observe.mjs';
 import { collectGateStatuses, runBuildCheck, checkArtifacts, checkResolverConflicts } from '../lib/verify.mjs';
 import { computeWorkflowState } from '../lib/workflow.mjs';
-import { computeDoctorChecks, WORKFLOWS as DOCTOR_WORKFLOWS } from '../lib/doctor.mjs';
+import { computeDoctorChecks, WORKFLOWS as DOCTOR_WORKFLOWS, binaryAvailable } from '../lib/doctor.mjs';
 import { parseCommand, renderCommandHelp, diagnostic } from '../lib/cli.mjs';
 import { EXIT_CODES } from '../lib/exit-codes.mjs';
 import { RESIDUAL_TEMPLATE_VAR_RE } from '../lib/template.mjs';
@@ -76,7 +79,10 @@ const SKILL_ROOT = path.resolve(__dirname, '..');
 function usage() {
 	console.error(`bskel -- backend-skeleton CLI
 
-  bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none]
+  bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none] [--record-pattern --pattern-database-url-env <NAME>]
+  bskel pattern list --pattern-database-url-env <NAME> [--stack spring|fastapi] [--json]
+  bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]
+  bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]
   bskel preflight [--max-behind N] [--offline|--no-fetch] [--allow-dirty] [--max-age-minutes N] [--fetch-timeout-seconds N] [--json]
   bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]
   bskel scan disposition --feature <id> --mode reuse|extend|replace|parallel [--module <name>] [--note "..."] [--breaking-approved]
@@ -92,6 +98,8 @@ function usage() {
   bskel feature archive <id> --reason "..." [--json]
   bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0] [--descriptions]
   bskel contract export --feature <id> [--out <path>] [--json] [--allow-unprefixed] [--status-codes range|literal]
+  bskel contract export-csv --feature <id> [--out <path>] [--bom] [--json]
+  bskel db erd [--database-url-env <NAME>] [--schema public] [--out <path>] [--json]
   bskel contract history --feature <id> [--json]
   bskel contract validate --feature <id> --file <envelope.json>
   bskel contract tool-schema --feature <id> --operation <operationId>
@@ -605,8 +613,16 @@ async function cmdScan(args) {
 	setContext('scan', flags);
 	const root = requireRepoRoot();
 	const terms = deriveTerms(flags);
-	if (terms.length === 0) {
-		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel scan [--feature <id>] --terms a,b,c   (need at least one search term, from --terms or a --feature slug)');
+	// D-zero-config-scan: only refuse when the user EXPLICITLY tried to supply terms (or a
+	// --feature) and it resolved to nothing -- a real usage mistake worth catching (a `--terms ""`/
+	// `--terms ,,` typo, or a --feature slug that pathologically derives zero words), same as
+	// before this item. Neither flag given at all is no longer an error -- it's the new zero-flag
+	// "inventory" mode (every module this adapter finds, unscored -- see scanners/index.mjs's
+	// runScan()), reachable only because the block below still gates it on `!flags.feature` before
+	// any gate/file write happens, exactly like today's ad-hoc mode already does.
+	const termsFlagGiven = args.some((a) => a === '--terms' || a.startsWith('--terms='));
+	if (terms.length === 0 && (termsFlagGiven || flags.feature)) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel scan [--feature <id>] [--terms a,b,c]   (--terms was given but resolved to no real search term -- pass at least one, e.g. --terms organization, or drop --terms entirely for a full unscored inventory of every module this repo\'s adapter finds)');
 	}
 	if (flags.feature) {
 		requireValidFeatureId(flags.feature);
@@ -614,6 +630,11 @@ async function cmdScan(args) {
 	}
 
 	const dbSchema = await resolveDbSchemaOrExit(root, flags);
+	// D-zero-config-scan: the same CLI-boundary-resolved-input pattern `dbSchema` above already
+	// establishes, applied to a second external dependency -- computed once, used on BOTH the
+	// inventory and the --feature-scoped path (a real Spring repo scanned with --feature+--terms is
+	// exactly as vulnerable to the silent detect()-time degradation as the zero-flag case).
+	const rgAvailable = binaryAvailable('rg');
 
 	// G1: a broken adapter file doesn't stop the adapters that DID load, but every `scan` run
 	// says so loudly (also see `bskel doctor`, which exits 1 while any of these remain).
@@ -622,7 +643,7 @@ async function cmdScan(args) {
 	}
 	let report;
 	try {
-		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema });
+		report = runScan({ repoRoot: root, terms, includeDb: flags.db, dbSchema, rgAvailable });
 	} catch (err) {
 		// Unreachable with the two shipped adapters (generic-grep's specificity-0 detect() is
 		// unconditional) -- becomes reachable the moment a future adapter's detect() is
@@ -1589,6 +1610,181 @@ function cmdContractExport(args) {
 	process.exitCode = EXIT.PASS;
 }
 
+// D-contract-csv: the soft-refusal counterpart to loadScanReportOrExit() above -- returns null
+// (skip the path-prefix check entirely) on ANY failure (missing file, unparseable JSON, schema
+// violation) instead of exiting. `contract export-csv` treats this check as advisory (see C5 in
+// D-contract-csv, DECISIONS.md): a scan report that can't be read is not itself a reason to block a
+// human-reviewed artifact, unlike `contract export`'s own hard guard for a machine-consumed one.
+function tryLoadScanReport(root, featureId) {
+	const scanReportPath = specPath(root, featureId, 'brownfield-scan.json');
+	if (!fs.existsSync(scanReportPath)) return null;
+	try {
+		const parsed = JSON.parse(fs.readFileSync(scanReportPath, 'utf8'));
+		const { ok } = validateAgainstSchema('scan-report.schema.json', parsed);
+		return ok ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+// D-contract-csv: a spreadsheet-shaped projection of a feature contract. Mirrors
+// cmdContractExport's overall shape (loadContract, zero-operation refusal, --out/stdout via
+// writeFileAtomic) but is deliberately UNGATED -- it never calls requireNamedGate('contract', ...)
+// and never hard-refuses on an unreflected path prefix, only warns. See D-contract-csv in
+// DECISIONS.md for the full risk-model argument (a CSV is read by a human deciding whether to
+// waive a partial contract -- gating it would make it useless exactly when it matters).
+function cmdContractExportCsv(args) {
+	const flags = parseCommand('contract export-csv', args);
+	if (flags.help) { console.log(renderCommandHelp('contract export-csv')); process.exit(0); }
+	setContext('contract export-csv', flags);
+	const root = requireRepoRoot();
+	requireValidFeatureId(flags.feature);
+
+	const contract = loadContract(root, flags.feature);
+
+	// Same positive-false-claim refusal `contract export` itself makes (see that function's own
+	// comment) -- a zero-row CSV handed to a stakeholder reads as "this feature has no API".
+	if (Object.keys(contract.operations).length === 0) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `\`${flags.feature}\`'s contract has zero operations (completeness: ${contract.completeness.status}) -- exporting it would produce a table positively claiming this API has no operations. Fix --module/--terms and re-run \`bskel contract emit --feature ${flags.feature}\`.`);
+	}
+
+	// C5 (D-contract-csv): advisory only. If the scan report cannot be read, the check is skipped
+	// silently rather than refusing (contrast cmdContractExport's loadScanReportOrExit(), which hard-exits).
+	let pathPrefixWarning = null;
+	const scanReport = tryLoadScanReport(root, flags.feature);
+	if (scanReport) {
+		const candidates = pathPrefixCandidates(scanReport.path_prefix_signals);
+		const unreflected = unreflectedPathPrefixes(contract, candidates);
+		if (unreflected.length > 0) {
+			pathPrefixWarning = `this repo's scan found a global path-prefix signal (${unreflected.join(', ')}) that ${flags.feature}'s contract paths do not reflect -- the paths in this CSV may be missing it. Re-run \`bskel contract emit --feature ${flags.feature} --openapi-file <real-generated-doc>\` to correct them, or treat this export as informational only.`;
+			console.error(`note: ${pathPrefixWarning}`);
+		}
+	}
+
+	const built = buildContractCsv({ contract });
+	if (!built.ok) {
+		// Unreachable given the zero-operation refusal above already covers this case -- kept as
+		// a real check rather than assuming buildContractCsv()'s precondition forever.
+		fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `cannot export ${flags.feature}'s contract to CSV: ${built.error}`);
+	}
+
+	// C2 (D-contract-csv): unconditional -- a reader must not have to guess whether a blank column
+	// means "nothing to show" or "the tool is broken".
+	if (built.emptyColumns.length > 0) {
+		console.error(`note: ${built.emptyColumns.length} of ${built.columns.length} columns are empty for every operation (${built.emptyColumns.join(', ')}) -- this contract was emitted without --openapi-file, so no source document ever stated them. Re-run \`bskel contract emit --feature ${flags.feature} --openapi-file <doc>\` to populate them.`);
+	}
+
+	// C4 (D-contract-csv): BOM is opt-in -- Excel-on-Windows mangles non-ASCII without one, but a
+	// BOM breaks naive parsers/`head`/`diff` for everyone else, so neither default is right for everyone.
+	const csvText = flags.bom ? `\uFEFF${built.csv}` : built.csv;
+
+	if (flags.out) {
+		const outPath = path.resolve(process.cwd(), flags.out);
+		writeFileAtomic(outPath, csvText);
+		if (flags.json) {
+			console.log(JSON.stringify({
+				schema: 'sbf.contract-export-csv/1',
+				feature_id: contract.feature_id,
+				out: flags.out,
+				row_count: built.rowCount,
+				columns: built.columns,
+				completeness: contract.completeness.status,
+				path_prefix_warning: pathPrefixWarning,
+			}, null, 2));
+		} else if (!flags.quiet) {
+			console.log(`wrote ${flags.out} -- ${built.rowCount} operation(s), completeness: ${contract.completeness.status}`);
+		}
+	} else {
+		// process.stdout.write, not console.log -- `csvText` already ends in exactly one `\n`
+		// (contracts/csv.mjs's toCsv()), and console.log would append a SECOND one, making stdout
+		// byte-different from the file --out writes. C7 (D-contract-csv): the artifact is the only
+		// thing on stdout here.
+		process.stdout.write(csvText);
+		if (flags.json) {
+			console.error('note: --json has no effect without --out -- stdout is the CSV itself. Pass --out <path> to get both.');
+		}
+	}
+	// D-process-exit-audit: NOT process.exit() -- same reasoning as cmdContractExport's own
+	// trailing comment; a 300-operation CSV can clear the 64KB pipe buffer just as easily.
+	process.exitCode = EXIT.PASS;
+}
+
+// D-db-erd: a Mermaid `erDiagram` of the database plane -- repo-independent like `bskel new`/
+// `bskel pattern *` (no --feature; the database plane is not feature-scoped, see E6 in D-db-erd,
+// DECISIONS.md). Reuses resolveDbSchemaOrExit() unchanged (via a synthetic `db: true`) so
+// --database-url-env's env-var handling and every error string stay byte-identical to `scan --db`.
+async function cmdDbErd(args) {
+	const flags = parseCommand('db erd', args);
+	if (flags.help) { console.log(renderCommandHelp('db erd')); process.exit(0); }
+	setContext('db erd', flags);
+	const root = requireRepoRoot();
+
+	// E1 (D-db-erd)'s own `--db` flag doesn't exist on this command -- the verb `db erd` implies
+	// it, so a synthetic `db: true` is threaded through to the exact same helper `scan --db` uses,
+	// never a second copy of its env-var-unset/connection-failure handling.
+	const { live, migrations } = await resolveDbSchemaOrExit(root, { ...flags, db: true });
+
+	if (!live && (!migrations || migrations.tables.length === 0)) {
+		if (migrations && migrations.tool === 'liquibase') {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `no schema to draw: this repo's Liquibase changelogs were detected (${migrations.files.length} file(s)) but none are plain .sql -- XML/YAML changelog parsing is not supported (see D-db-schema-plane in DECISIONS.md). Pass --database-url-env <NAME> for live introspection instead.`);
+		}
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'no schema to draw: no Flyway/Liquibase migration files found in this repo, and no --database-url-env was given. Pass --database-url-env <NAME> (an already-exported environment variable; never read from .env directly -- see D-db-schema-plane in DECISIONS.md) for live introspection.');
+	}
+
+	const version = JSON.parse(fs.readFileSync(path.join(SKILL_ROOT, 'package.json'), 'utf8')).version;
+	const invocation = flags['database-url-env']
+		? `bskel db erd --database-url-env ${flags['database-url-env']} --schema ${flags.schema}`
+		: 'bskel db erd';
+	const built = buildErdDiagram({ live, migrations, generatedBy: `bskel ${version} -- \`${invocation}\`` });
+	if (!built.ok) {
+		// Unreachable given the refusal above already covers both reasons buildErdDiagram() can
+		// report -- kept as a real check rather than assuming its precondition forever.
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `no schema to draw (${built.reason})`);
+	}
+
+	// E2 (D-db-erd): unconditional when degraded -- a reader must see this before the diagram, not
+	// discover it by noticing every type says `unknown`.
+	if (built.degraded) {
+		console.error(`note: this diagram is DEGRADED -- built from migration files, not a live database. Missing: ${built.missing.join(', ')}. Pass --database-url-env <NAME> for a complete diagram.`);
+	}
+	// E6 (D-db-erd): a readability nudge only, never a refusal -- whole-schema is the only mode
+	// this version supports.
+	if (built.entityCount > 40) {
+		console.error(`note: ${built.entityCount} entities -- this diagram may be dense (whole-schema only in this version; see E6 in D-db-erd, DECISIONS.md).`);
+	}
+
+	if (flags.out) {
+		const outPath = path.resolve(process.cwd(), flags.out);
+		writeFileAtomic(outPath, built.mermaid);
+		if (flags.json) {
+			console.log(JSON.stringify({
+				schema: 'sbf.db-erd/1',
+				out: flags.out,
+				plane: built.plane,
+				entity_count: built.entityCount,
+				relationship_count: built.relationshipCount,
+				unresolved_relationships: built.unresolvedRelationships,
+				external_tables: built.externalTables,
+				renames: built.renames,
+				degraded: built.degraded,
+				missing: built.missing,
+			}, null, 2));
+		} else if (!flags.quiet) {
+			console.log(`wrote ${flags.out} -- ${built.entityCount} entity(ies), ${built.relationshipCount} relationship(s), plane: ${built.plane}${built.degraded ? ' (degraded)' : ''}`);
+		}
+	} else {
+		// process.stdout.write, not console.log -- same E10 (D-db-erd) byte-exactness reasoning as
+		// cmdContractExportCsv's own C7 (built.mermaid already ends in exactly one `\n`).
+		process.stdout.write(built.mermaid);
+		if (flags.json) {
+			console.error('note: --json has no effect without --out -- stdout is the diagram itself. Pass --out <path> to get both.');
+		}
+	}
+	// D-process-exit-audit: NOT process.exit() -- a 200-table diagram can clear the 64KB pipe
+	// buffer just as easily as a schema-rich OpenAPI export.
+	process.exitCode = EXIT.PASS;
+}
+
 // A5: the `scan disposition` of contracts -- lets a human explicitly accept a `partial`
 // contract's outstanding warnings so the `contract` gate can pass. Deliberately no wildcard
 // waiver: `--all` expands to the SPECIFIC code+subject pairs present right now, recorded as
@@ -3617,6 +3813,132 @@ async function resolveNewParams(stack, flags) {
 	};
 }
 
+// D-pattern-accrual: all three pattern commands are repo-independent, like `bskel new` itself --
+// a pattern store is a user-owned CROSS-PROJECT resource, never scoped to the current repo/feature,
+// so none of them call requireRepoRoot(). Read-only; --pattern-database-url-env is required on all
+// three (mirrors O7's `handles audit` -- there is no meaningful "run without a live connection" mode).
+async function cmdPatternList(args) {
+	const flags = parseCommand('pattern list', args);
+	if (flags.help) { console.log(renderCommandHelp('pattern list')); process.exit(0); }
+	setContext('pattern list', flags);
+
+	const connectionString = process.env[flags['pattern-database-url-env']];
+	if (!connectionString) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--pattern-database-url-env ${flags['pattern-database-url-env']} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md)`);
+	}
+	if (flags.stack && !NEW_STACKS[flags.stack]) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--stack must be one of: ${Object.keys(NEW_STACKS).join(', ')} (got ${JSON.stringify(flags.stack)})`);
+	}
+
+	let records;
+	try {
+		records = await listPatterns({ connectionString, stack: flags.stack });
+	} catch (err) {
+		if (isMissingPatternTable(err)) {
+			fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', 'sbf_pattern does not exist in this database -- run patterns/schema.sql against it first (bskel never applies it automatically; see D-migration-scope in DECISIONS.md).');
+		}
+		fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', `could not query the pattern store: ${describeConnectionError(err)}`);
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify({ records }, null, 2));
+	} else {
+		console.log(`pattern store -- ${records.length} record(s)${flags.stack ? ` (stack: ${flags.stack})` : ''}`);
+		for (const r of records) {
+			console.log(`  ${r.pattern_id}  [${r.stack}]  ${r.recorded_at}  ${JSON.stringify(r.params)}`);
+		}
+	}
+	process.exit(0);
+}
+
+async function cmdPatternShow(args) {
+	const flags = parseCommand('pattern show', args);
+	if (flags.help) { console.log(renderCommandHelp('pattern show')); process.exit(0); }
+	setContext('pattern show', flags);
+	const patternId = flags._[0];
+	if (!patternId) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'usage: bskel pattern show <pattern_id> --pattern-database-url-env <NAME>');
+	}
+	const connectionString = process.env[flags['pattern-database-url-env']];
+	if (!connectionString) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--pattern-database-url-env ${flags['pattern-database-url-env']} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md)`);
+	}
+
+	let record;
+	try {
+		record = await getPattern({ connectionString, patternId });
+	} catch (err) {
+		if (isMissingPatternTable(err)) {
+			fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', 'sbf_pattern does not exist in this database -- run patterns/schema.sql against it first (bskel never applies it automatically; see D-migration-scope in DECISIONS.md).');
+		}
+		fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', `could not query the pattern store: ${describeConnectionError(err)}`);
+	}
+	if (!record) {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no pattern record with id ${patternId}`);
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(record, null, 2));
+	} else {
+		console.log(`pattern ${record.pattern_id}  [${record.stack}]  recorded ${record.recorded_at}`);
+		for (const [k, v] of Object.entries(record.params)) console.log(`  --${k} ${v}`);
+	}
+	process.exit(0);
+}
+
+// D-pattern-accrual: `suggest`'s output is TEXT only -- a per-value frequency breakdown, honest about
+// disagreement, plus one paste-ready command line built from the top-ranked value per param. Never
+// fed into `bskel new` as a default; `bskel new` has no flag that would accept it as one (see
+// D-pattern-accrual's WHY for why this is the one design decision that keeps this feature inside
+// D-greenfield-parameters' safe/unsafe line).
+async function cmdPatternSuggest(args) {
+	const flags = parseCommand('pattern suggest', args);
+	if (flags.help) { console.log(renderCommandHelp('pattern suggest')); process.exit(0); }
+	setContext('pattern suggest', flags);
+
+	const stack = NEW_STACKS[flags.stack];
+	if (!stack) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--stack must be one of: ${Object.keys(NEW_STACKS).join(', ')} (got ${JSON.stringify(flags.stack)})`);
+	}
+	const connectionString = process.env[flags['pattern-database-url-env']];
+	if (!connectionString) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--pattern-database-url-env ${flags['pattern-database-url-env']} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md)`);
+	}
+
+	let records;
+	try {
+		records = await listPatterns({ connectionString, stack: flags.stack });
+	} catch (err) {
+		if (isMissingPatternTable(err)) {
+			fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', 'sbf_pattern does not exist in this database -- run patterns/schema.sql against it first (bskel never applies it automatically; see D-migration-scope in DECISIONS.md).');
+		}
+		fail(EXIT_CODES.REFRESH_FAILED, 'REFRESH_FAILED', `could not query the pattern store: ${describeConnectionError(err)}`);
+	}
+
+	const summary = summarizePatternFrequency(records, stack.reusableParams);
+	const suggestedFlags = summary.map(({ param, values }) => `--${param} ${values[0].value}`).join(' ');
+	const suggestedCommand = `bskel new --stack ${stack.id} --slug <name>${suggestedFlags ? ` ${suggestedFlags}` : ''}`;
+
+	if (flags.json) {
+		console.log(JSON.stringify({ stack: stack.id, total_records: records.length, summary, suggested_command: suggestedCommand }, null, 2));
+	} else {
+		console.log(`pattern suggest -- ${records.length} recorded ${stack.id} run(s)`);
+		if (records.length === 0) {
+			console.log('  (no patterns recorded yet for this stack -- nothing to suggest)');
+		} else {
+			for (const { param, values } of summary) {
+				for (const { value, count, total } of values) {
+					console.log(`  --${param} ${value}   (${count}/${total} runs)`);
+				}
+			}
+			console.log('');
+			console.log('suggested command (edit before running -- bskel never applies this automatically):');
+			console.log(`  ${suggestedCommand}`);
+		}
+	}
+	process.exit(0);
+}
+
 async function cmdNew(args) {
 	const flags = parseCommand('new', args);
 	if (flags.help) { console.log(renderCommandHelp('new')); process.exit(0); }
@@ -3628,6 +3950,21 @@ async function cmdNew(args) {
 	}
 	requireValidSlug(flags.slug);
 	requireStackParams(stack, flags);
+	// D-pattern-accrual: checked BEFORE any network call or filesystem write, same ordering
+	// principle P2b's own comment states above -- a usage mistake (flag given without its required
+	// partner, or an env var that was never exported) must never leave a half-scaffolded project
+	// behind. The actual DB write later in this function is a SEPARATE, best-effort concern; this
+	// block only validates that recording, if requested, is even POSSIBLE to attempt.
+	let patternConnectionString = null;
+	if (flags['record-pattern']) {
+		if (!flags['pattern-database-url-env']) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', '--record-pattern requires --pattern-database-url-env <NAME>. Nothing was written.');
+		}
+		patternConnectionString = process.env[flags['pattern-database-url-env']];
+		if (!patternConnectionString) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--pattern-database-url-env ${flags['pattern-database-url-env']} names an environment variable that isn't set -- export it first (never read from .env directly; see D-db-schema-plane in DECISIONS.md). Nothing was written.`);
+		}
+	}
 
 	let stackParams;
 	let warnings;
@@ -3671,6 +4008,27 @@ async function cmdNew(args) {
 	}
 	execFileSync('git', commitArgs, { cwd: dir });
 
+	// D-pattern-accrual: best-effort, deliberately AFTER the project is already scaffolded and
+	// committed -- failing here would be strictly worse than not recording (the project the user
+	// asked for already exists). Only ever a stderr warning, never a fail()/non-zero exit; records
+	// ONLY the flags new/index.mjs's reusableParamsFor(stack) names, and only the ones the user
+	// actually typed (a param the user never passed stays absent from `params`, not defaulted in --
+	// an omission is itself real information for `pattern suggest`, see patterns/store.mjs).
+	if (patternConnectionString) {
+		const patternParams = {};
+		for (const param of reusableParamsFor(stack.id)) {
+			if (flags[param] != null) patternParams[param] = String(flags[param]);
+		}
+		try {
+			await recordPattern({ connectionString: patternConnectionString, stack: stack.id, params: patternParams });
+		} catch (err) {
+			const hint = isMissingPatternTable(err)
+				? 'sbf_pattern does not exist in this database -- run patterns/schema.sql against it first (bskel never applies it automatically; see D-migration-scope).'
+				: describeConnectionError(err);
+			console.error(`warning: --record-pattern could not write to the pattern store: ${hint}`);
+		}
+	}
+
 	const { postScaffoldNotes = [], ...resultRest } = result;
 	if (flags.json) {
 		console.log(JSON.stringify({ stack: flags.stack, dir, ...resultRest, warnings, postScaffoldNotes }, null, 2));
@@ -3779,6 +4137,7 @@ async function dispatchCommand(cmd, rest) {
 			const subArgs = rest.slice(1);
 			if (sub === 'emit') return cmdContractEmit(subArgs);
 			if (sub === 'export') return cmdContractExport(subArgs);
+			if (sub === 'export-csv') return cmdContractExportCsv(subArgs);
 			if (sub === 'history') return cmdContractHistory(subArgs);
 			if (sub === 'validate') return cmdContractValidate(subArgs);
 			if (sub === 'tool-schema') return cmdContractToolSchema(subArgs);
@@ -3871,6 +4230,20 @@ async function dispatchCommand(cmd, rest) {
 			return cmdServe(rest);
 		case 'new':
 			return cmdNew(rest);
+		case 'pattern': {
+			if (rest[0] === 'list') return cmdPatternList(rest.slice(1));
+			if (rest[0] === 'show') return cmdPatternShow(rest.slice(1));
+			if (rest[0] === 'suggest') return cmdPatternSuggest(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
+		}
+		case 'db': {
+			if (rest[0] === 'erd') return await cmdDbErd(rest.slice(1));
+			usage();
+			process.exit(14);
+			break;
+		}
 		default:
 			usage();
 			process.exit(cmd ? 14 : 0);