@m6d/cortex-cli 0.1.0

package/src/graph/validate.ts

@@ -0,0 +1,78 @@
+import type { ConceptDef, DomainDef, RuleDef } from "@cortex/contracts/graph";
+
+/**
+ * Checks a domain for the two mistakes that survive the type system: a name used
+ * twice, and an entity nothing points at.
+ *
+ * Cross-domain references are allowed — a concept, endpoint or service may be
+ * defined in another module — so local membership is deliberately not enforced.
+ */
+export function validateDomain(data: DomainDef) {
+    const referenced = collectReferences(data);
+
+    return [
+        ...duplicateNames(data.concepts, "concept"),
+        ...duplicateNames(data.endpoints, "endpoint"),
+        ...duplicateNames(data.services, "service"),
+        ...duplicateNames(data.rules, "rule"),
+        ...unreferenced(
+            data.concepts,
+            referenced.concepts,
+            (name) => `Concept "${name}" is never referenced by any endpoint or service`,
+        ),
+        ...unreferenced(
+            data.rules,
+            referenced.rules,
+            (name) => `Rule "${name}" is never referenced by any endpoint, service, or concept`,
+        ),
+    ];
+}
+
+function duplicateNames(items: { name: string }[] | undefined, kind: string) {
+    const seen = new Set<string>();
+
+    return (items ?? []).flatMap((item) => {
+        const duplicate = seen.has(item.name);
+        seen.add(item.name);
+
+        return duplicate ? [`Duplicate ${kind} name: "${item.name}"`] : [];
+    });
+}
+
+function unreferenced(
+    items: { name: string }[] | undefined,
+    referenced: Set<string>,
+    message: (name: string) => string,
+) {
+    return (items ?? [])
+        .filter((item) => !referenced.has(item.name))
+        .map((item) => message(item.name));
+}
+
+/** Gathers every name pointed at from anywhere in the domain. */
+function collectReferences(data: DomainDef) {
+    const concepts = new Set<string>();
+    const rules = new Set<string>();
+    const addRules = (governedBy: RuleDef[] | undefined) =>
+        governedBy?.forEach((rule) => rules.add(rule.name));
+    const addConcept = (concept: ConceptDef | undefined) => concept && concepts.add(concept.name);
+
+    for (const endpoint of data.endpoints ?? []) {
+        endpoint.queries?.forEach(addConcept);
+        endpoint.mutates?.forEach(addConcept);
+        endpoint.returns?.forEach((returned) => addConcept(returned.concept));
+        addRules(endpoint.governedBy);
+    }
+
+    for (const service of data.services ?? []) {
+        addConcept(service.belongsTo);
+        addRules(service.governedBy);
+    }
+
+    for (const concept of data.concepts ?? []) {
+        addConcept(concept.parentConcept);
+        addRules(concept.governedBy);
+    }
+
+    return { concepts, rules };
+}

package/src/scaffold/features.ts

@@ -0,0 +1,190 @@
+/**
+ * The five features `cortex new` toggles. A feature is not a
+ * config key: it is a bundle of a `cortex.config.ts` fragment, a block of env
+ * keys, and sometimes a compose service. Fragments concatenate — there is no
+ * merge engine — so every field here is plain text that gets joined.
+ *
+ * The grouping is what the server code already enforces. `vision` is inert
+ * without `storage`, so attachments writes both; `seedGraph` throws unless it
+ * has all of `neo4j`, `embedding` and `knowledge.domains`, so knowledge writes
+ * all three plus the `src/domains/` tree the domainsDir convention assumes.
+ */
+
+export type Feature = "attachments" | "redis" | "auth" | "knowledge" | "controlCenter";
+
+type Definition = {
+    /** One line, shown in `--help` and next to the option in the multi-select. */
+    hint: string;
+    /** Sits above the fragment in the generated config, commented either way. */
+    note: string;
+    /**
+     * The `cortex.config.ts` fragment, written at zero indentation: the assembler
+     * indents it into the object literal, or comments it out for a feature that
+     * was not selected. Conditional spread throughout, so an unfilled env var
+     * leaves the section *absent* rather than present-and-undefined.
+     */
+    config: string;
+    /** The `.env` block, identical in `.env` and `.env.example`. */
+    env: string;
+    /** The `docker-compose.yml` service, indented under `services:`. */
+    compose?: string;
+    /** The named volume that service mounts. */
+    volume?: string;
+    /** What `cd`-then-edit has to fill in before the project boots. */
+    secrets?: string;
+};
+
+export const FEATURES: Record<Feature, Definition> = {
+    attachments: {
+        hint: "MinIO storage for uploads, described by a vision model",
+        note: "Attachments: an S3-compatible bucket for uploads, plus an image-capable\nmodel that describes them. Vision does nothing without storage, which is\nwhy one toggle writes both.",
+        config: `...(process.env["CORTEX_MINIO_ENDPOINT"]
+    ? {
+          storage: {
+              endPoint: process.env["CORTEX_MINIO_ENDPOINT"],
+              port: Number(process.env["CORTEX_MINIO_PORT"] ?? {{port.minio}}),
+              useSSL: process.env["CORTEX_MINIO_USE_SSL"] === "true",
+              accessKey: process.env["CORTEX_MINIO_ACCESS_KEY"]!,
+              secretKey: process.env["CORTEX_MINIO_SECRET_KEY"]!,
+          },
+          vision: {
+              baseURL: process.env["CORTEX_VISION_URL"]!,
+              apiKey: process.env["CORTEX_VISION_KEY"]!,
+              modelName: process.env["CORTEX_VISION_MODEL"]!,
+          },
+      }
+    : {}),`,
+        env: `# --- Attachments -------------------------------------------------------------
+# S3-compatible object storage. docker-compose.yml runs MinIO on these values.
+CORTEX_MINIO_ENDPOINT=localhost
+CORTEX_MINIO_PORT={{port.minio}}
+CORTEX_MINIO_USE_SSL=false
+CORTEX_MINIO_ACCESS_KEY=minio
+CORTEX_MINIO_SECRET_KEY=minio-secret-key
+
+# An image-capable, OpenAI-compatible model. It describes uploaded images so the
+# agent can read them.
+CORTEX_VISION_URL=https://api.openai.com/v1
+CORTEX_VISION_KEY=your-vision-api-key
+CORTEX_VISION_MODEL=your-vision-model`,
+        compose: `    minio:
+        image: minio/minio:RELEASE.2025-04-22T22-12-26Z
+        command: server /data --console-address ":9001"
+        environment:
+            MINIO_ROOT_USER: minio
+            MINIO_ROOT_PASSWORD: minio-secret-key
+        ports:
+            - "{{port.minio}}:9000"
+            - "{{port.minioConsole}}:9001"
+        volumes:
+            - minio-data:/data`,
+        volume: "minio-data",
+        secrets: "CORTEX_VISION_*",
+    },
+
+    redis: {
+        hint: "resumable streams across restarts",
+        note: "Redis makes live runs survive a restart and reach every instance. Without\nit, an in-memory fallback covers this single process.",
+        config: `...(process.env["CORTEX_REDIS_URL"] ? { redis: { url: process.env["CORTEX_REDIS_URL"] } } : {}),`,
+        env: `# --- Redis -------------------------------------------------------------------
+# Resumable streams. docker-compose.yml runs one on this URL.
+CORTEX_REDIS_URL=redis://localhost:{{port.redis}}`,
+        compose: `    redis:
+        image: redis:7-alpine
+        ports:
+            - "{{port.redis}}:6379"`,
+    },
+
+    auth: {
+        hint: "JWT verification via JWKS",
+        note: "Bearer tokens verified against an identity provider's JWKS endpoint. The\nprovider is external, so there is no service for it.",
+        config: `...(process.env["CORTEX_AUTH_JWKS_URI"]
+    ? {
+          auth: {
+              kind: "jwks" as const,
+              jwksUri: process.env["CORTEX_AUTH_JWKS_URI"],
+              issuer: process.env["CORTEX_AUTH_ISSUER"]!,
+          },
+      }
+    : {}),`,
+        env: `# --- Auth --------------------------------------------------------------------
+# Your identity provider's JWKS endpoint, and the issuer it stamps on tokens.
+CORTEX_AUTH_JWKS_URI=https://your-idp.example.com/.well-known/jwks.json
+CORTEX_AUTH_ISSUER=https://your-idp.example.com/`,
+        secrets: "CORTEX_AUTH_*",
+    },
+
+    knowledge: {
+        hint: "Swagger + domains + Neo4j",
+        note: "The knowledge graph, which is three keys rather than one: Neo4j stores it,\nthe embedding endpoint makes it searchable, and the domain definitions under\nsrc/domains/ are what `cortex graph seed` loads into it.",
+        config: `...(process.env["CORTEX_NEO4J_URL"]
+    ? {
+          neo4j: {
+              url: process.env["CORTEX_NEO4J_URL"],
+              user: process.env["CORTEX_NEO4J_USER"]!,
+              password: process.env["CORTEX_NEO4J_PASSWORD"]!,
+          },
+          embedding: {
+              baseURL: process.env["CORTEX_EMBEDDING_URL"]!,
+              apiKey: process.env["CORTEX_EMBEDDING_KEY"]!,
+              modelName: process.env["CORTEX_EMBEDDING_MODEL"]!,
+              dimension: Number(process.env["CORTEX_EMBEDDING_DIMENSION"] ?? 1024),
+          },
+          knowledge: {
+              // swagger: { url: "https://api.example.com/swagger/v1/swagger.json" },
+              // Import the domains you write under src/domains/ and list them here.
+              domains: {},
+          },
+      }
+    : {}),`,
+        env: `# --- Knowledge graph ---------------------------------------------------------
+# Neo4j. docker-compose.yml runs one with exactly these credentials. The URL is
+# the HTTP endpoint, not the bolt one: the server talks to Neo4j over its HTTP
+# transaction API.
+CORTEX_NEO4J_URL=http://localhost:{{port.neo4j}}
+CORTEX_NEO4J_USER=neo4j
+CORTEX_NEO4J_PASSWORD=cortex-dev-password
+
+# An OpenAI-compatible embeddings endpoint — external, like the main model.
+# CORTEX_EMBEDDING_DIMENSION has to match what the model returns.
+CORTEX_EMBEDDING_URL=https://api.openai.com/v1
+CORTEX_EMBEDDING_KEY=your-embedding-api-key
+CORTEX_EMBEDDING_MODEL=your-embedding-model
+CORTEX_EMBEDDING_DIMENSION=1024`,
+        compose: `    neo4j:
+        image: neo4j:5-community
+        environment:
+            NEO4J_AUTH: neo4j/cortex-dev-password
+            # Neo4j Browser, served on the HTTP port, opens bolt at whatever this
+            # advertises. Without it the browser would offer 7687, which is the
+            # container's port and not the one published below.
+            NEO4J_server_bolt_advertised__address: ":{{port.neo4jBolt}}"
+        ports:
+            - "{{port.neo4j}}:7474"
+            - "{{port.neo4jBolt}}:7687"
+        volumes:
+            - neo4j-data:/data`,
+        volume: "neo4j-data",
+        secrets: "CORTEX_EMBEDDING_*",
+    },
+
+    controlCenter: {
+        hint: "serve agents published on a Control Center instance",
+        note: "The Control Center you point this server at. External, so no service here.",
+        config: `...(process.env["CORTEX_CONTROL_CENTER_URL"]
+    ? {
+          controlCenter: {
+              url: process.env["CORTEX_CONTROL_CENTER_URL"],
+              apiKey: process.env["CORTEX_CONTROL_CENTER_API_KEY"]!,
+          },
+      }
+    : {}),`,
+        env: `# --- Control Center ----------------------------------------------------------
+CORTEX_CONTROL_CENTER_URL=http://localhost:20000
+CORTEX_CONTROL_CENTER_API_KEY=cc_live_...`,
+        secrets: "CORTEX_CONTROL_CENTER_API_KEY",
+    },
+};
+
+/** Catalogue order, which is the order every generated file lists them in. */
+export const FEATURE_NAMES = Object.keys(FEATURES) as Feature[];

package/src/scaffold/files.ts

@@ -0,0 +1,411 @@
+/**
+ * Every file `cortex new` writes, as one pure function. Files with nothing to
+ * fill in are verbatim text under templates/; the ones that vary with the
+ * selection are assembled here. The tooling configs are inlined rather than
+ * pulled from `@m6d/eslint-config`, `@m6d/prettier-config` and `@m6d/tsconfig`:
+ * those are `private: true` at `0.0.0` and resolvable only through this
+ * workspace, and a standalone scaffold has no workspace.
+ */
+
+import { FEATURE_NAMES, FEATURES, type Feature } from "@/scaffold/features";
+import indexTs from "@/scaffold/templates/index.ts.txt";
+import domainsReadme from "@/scaffold/templates/domains-README.md.txt";
+import tsconfigJson from "@/scaffold/templates/tsconfig.json.txt";
+import gitignoreText from "@/scaffold/templates/gitignore.txt";
+import eslintConfig from "@/scaffold/templates/eslint.config.mjs.txt";
+import prettierConfig from "@/scaffold/templates/prettier.config.mjs.txt";
+import fallowrc from "@/scaffold/templates/fallowrc.jsonc.txt";
+import { applyPorts, type Ports } from "@/scaffold/ports";
+
+export type Database = "postgres" | "mssql";
+
+// The generated project depends on these directly, not transitively: its own code
+// imports `zod` for tool schemas and `hono` for extra routes on `server.app`.
+// The ranges are packages/cortex-server's own peers, which is the compatibility
+// statement the server itself publishes, and a server range pinned to its
+// current minor, since a minor bump is where the server breaks; the release
+// sync (scripts/sync-package-versions.ts) restamps it and files.test.ts holds
+// them to that.
+export const DEPENDENCIES = {
+    "@m6d/cortex-server": "~0.1.0",
+    "@tanstack/ai": "^0.55.0",
+    "@tanstack/ai-openai": "^0.22.8",
+    hono: "^4.12.3",
+    jose: "^6.1.3",
+    openai: "^6",
+    zod: "^4.1.8",
+};
+
+const DEV_DEPENDENCIES = {
+    "@types/bun": "latest",
+    cspell: "^9.6.4",
+    eslint: "^9",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    fallow: "^3.9.1",
+    prettier: "^3.6.2",
+    typescript: "^5",
+    "typescript-eslint": "^8.65.0",
+};
+
+// Postgres is the one we run, so it gets a scaffolded port. MSSQL is normally an
+// existing instance nobody moved, which is why it keeps 1433 and has no service.
+const CONNECTION_STRING: Record<Database, string> = {
+    postgres: "postgres://postgres:postgres@localhost:{{port.postgres}}/cortex",
+    mssql: "Server=localhost,1433;Database=cortex;User Id=sa;Password=your-password;Encrypt=false",
+};
+
+function packageJson(name: string) {
+    return `${JSON.stringify(
+        {
+            name,
+            version: "0.1.0",
+            private: true,
+            type: "module",
+            scripts: {
+                // Not `fallow audit`: it scopes itself to files changed against a
+                // base branch, and a project on line one has no commits and no
+                // remote to derive one from. Bare `fallow` runs the same three
+                // analyses — dead code, duplication, complexity — over everything.
+                audit: "fallow",
+                check: "tsc --noEmit",
+                dev: "bun run --hot index.ts",
+                format: "prettier --write .",
+                "format:check": "prettier --check .",
+                lint: "eslint",
+                spellcheck: 'cspell "**/*.{ts,mjs,json,md}"',
+                verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
+            },
+            dependencies: DEPENDENCIES,
+            devDependencies: DEV_DEPENDENCIES,
+        },
+        null,
+        4,
+    )}\n`;
+}
+
+/**
+ * Never toggled, so they only ever appear commented out: `context` is fully
+ * defaulted, and the other two are what you reach for once a real problem shows
+ * up — noisy graph retrieval, a cheap-model path — not on day one.
+ */
+const NEVER_SCAFFOLDED: [note: string, config: string][] = [
+    [
+        "A cheaper, faster model for auxiliary passes. Same shape as `model`.",
+        `fastModel: {
+    baseURL: process.env["CORTEX_FAST_MODEL_URL"]!,
+    apiKey: process.env["CORTEX_FAST_MODEL_KEY"]!,
+    modelName: process.env["CORTEX_FAST_MODEL_NAME"]!,
+},`,
+    ],
+    [
+        "Re-ranks knowledge-graph retrieval when it comes back noisy.",
+        `reranker: {
+    url: process.env["CORTEX_RERANKER_URL"]!,
+    apiKey: process.env["CORTEX_RERANKER_KEY"]!,
+},`,
+    ],
+    [
+        "Context-window tuning. Every field is defaulted, so override only what you\nhave measured a reason to change.",
+        `context: {
+    maxContextTokens: 120_000,
+    recentMessagesToKeep: 6,
+},`,
+    ],
+];
+
+/** Fragments are authored at zero indentation and placed by these two. */
+function indented(block: string) {
+    return block.replace(/^(?!$)/gm, "    ");
+}
+
+function commented(block: string) {
+    return block.replace(/^(?!$)/gm, "    // ");
+}
+
+/** A note, then its fragment — written live, or written disabled. */
+function block(note: string, config: string, enabled: boolean) {
+    return `\n${commented(note)}\n${enabled ? indented(config) : commented(config)}\n`;
+}
+
+function cortexConfig(database: Database, features: Feature[]) {
+    const fragment = (feature: Feature) =>
+        block(FEATURES[feature].note, FEATURES[feature].config, features.includes(feature));
+
+    const on = FEATURE_NAMES.filter((feature) => features.includes(feature))
+        .map(fragment)
+        .join("");
+    const off = FEATURE_NAMES.filter((feature) => !features.includes(feature))
+        .map(fragment)
+        .join("");
+    const never = NEVER_SCAFFOLDED.map(([note, config]) => block(note, config, false)).join("");
+
+    // cspell.json ships an empty word list on purpose, so the Cortex jargon the
+    // config names teaches the checker from the file that uses it.
+    return `import { defineAgent } from "@m6d/cortex-server";
+import type { CortexConfig } from "@m6d/cortex-server";
+
+// cspell:words reranker
+
+/**
+ * Inert on purpose: this file default-exports data and nothing else, so importing
+ * it never opens a connection or binds a port. Construction lives in index.ts,
+ * which is what lets tooling read this config without booting the server.
+ */
+export default {
+    port: 3331,
+    database: {
+        type: "${database}",
+        connectionString: process.env["CORTEX_DATABASE_URL"]!,
+    },
+    model: {
+        baseURL: process.env["CORTEX_MODEL_URL"]!,
+        apiKey: process.env["CORTEX_MODEL_KEY"]!,
+        modelName: process.env["CORTEX_MODEL_NAME"]!,
+    },
+${on === "" ? "" : `${on}\n`}    agents: {
+        assistant: defineAgent({
+            systemPrompt: "You are a helpful assistant.",
+            // Applications that serve datasets for grouped questions (see the
+            // README's "Dataset hosts"): the host applies its own access rules,
+            // the agent only picks which datasets to expose and pin.
+            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", pinned: ["orders"] }],
+        }),
+    },
+
+    // Everything below is off, written out so the file documents what else the
+    // server does. Uncomment a block and fill in its keys in .env to enable it.
+${off}${never}} satisfies CortexConfig;
+`;
+}
+
+/**
+ * Whether this selection runs anything of its own — which is the same question as
+ * "did any port get chosen", since a chosen port is always some service's.
+ */
+function hasServices(database: Database, features: Feature[]) {
+    return (
+        database === "postgres" ||
+        features.some((feature) => FEATURES[feature].compose !== undefined)
+    );
+}
+
+function env(database: Database, features: Feature[]) {
+    const blocks = FEATURE_NAMES.filter((feature) => features.includes(feature)).map(
+        (feature) => `\n${FEATURES[feature].env}\n`,
+    );
+
+    // Only the URLs pointing at scaffolded services carry a chosen port, and those
+    // are exactly the ones docker-compose.yml publishes.
+    const note = hasServices(database, features)
+        ? `#
+# The service ports below are not the canonical ones. They were picked when this
+# project was scaffolded, from what was free on the machine, so it does not
+# collide with anything else you run. Change them freely — in step with
+# docker-compose.yml.
+`
+        : "";
+
+    return `# Environment for this Cortex server. Bun loads this file from the directory you
+# run in, so it has to sit next to cortex.config.ts.
+#
+# .env.example is the committed copy. Keep the two in step; keep secrets in .env.
+${note}
+# --- Model -------------------------------------------------------------------
+# Any OpenAI-compatible endpoint: base URL, key, and model name.
+CORTEX_MODEL_URL=https://api.openai.com/v1
+CORTEX_MODEL_KEY=your-model-api-key
+CORTEX_MODEL_NAME=your-model-name
+
+# --- Database ----------------------------------------------------------------
+# The dialect is ${database}, set in cortex.config.ts. Change it there, not here.
+CORTEX_DATABASE_URL=${CONNECTION_STRING[database]}
+${blocks.join("")}`;
+}
+
+/**
+ * Services the selections actually need, and nothing else. `auth` and the
+ * Control Center are external, the embedding endpoint is a URL like the main
+ * model, and MSSQL is normally an existing instance — so with `--yes --database
+ * mssql` there is no service at all, and no file is written.
+ */
+function dockerCompose(name: string, database: Database, features: Feature[]) {
+    const services: string[] = [];
+    const volumes: string[] = [];
+
+    if (database === "postgres") {
+        services.push(`    postgres:
+        image: postgres:17-alpine
+        environment:
+            POSTGRES_USER: postgres
+            POSTGRES_PASSWORD: postgres
+            POSTGRES_DB: cortex
+        ports:
+            - "{{port.postgres}}:5432"
+        volumes:
+            - postgres-data:/var/lib/postgresql/data`);
+        volumes.push("postgres-data");
+    }
+
+    for (const feature of FEATURE_NAMES.filter((feature) => features.includes(feature))) {
+        const { compose, volume } = FEATURES[feature];
+        if (compose === undefined) continue;
+        services.push(compose);
+        if (volume !== undefined) volumes.push(volume);
+    }
+
+    if (services.length === 0) return undefined;
+
+    const volumeBlock =
+        volumes.length === 0
+            ? ""
+            : `\nvolumes:\n${volumes.map((name) => `    ${name}:\n`).join("")}`;
+
+    return `# Local infrastructure for this project. The .env this was scaffolded with
+# already points at these, so \`docker compose up -d\` is enough.
+#
+# The host ports were picked at scaffold time from what was free on the machine —
+# the container ports next to them are the canonical ones and should stay put.
+# Move a host port and .env has to follow.
+
+# Explicit so the project never collides with another checkout whose directory
+# happens to share this one's name (Compose defaults to the directory name, and
+# a name clash silently replaces the other project's containers and volumes).
+name: ${name}-cortex-server
+
+services:
+${services.join("\n\n")}
+${volumeBlock}`;
+}
+
+/**
+ * `--knowledge` scaffolds the directory `domainsDir` defaults to, which is what
+ * makes the convention true by construction: `cortex swagger sync` finds it with
+ * no config key.
+ */
+
+function cspellConfig() {
+    return `${JSON.stringify(
+        {
+            version: "0.2",
+            language: "en",
+            // Yours to fill in. Project jargon belongs here; nothing is seeded,
+            // because a stranger's vocabulary is noise in your repo.
+            words: [],
+            ignorePaths: [
+                "node_modules/**",
+                "out/**",
+                "build/**",
+                "**/dist/**",
+                "coverage/**",
+                "*.tsbuildinfo",
+                "bun.lock",
+                "package-lock.json",
+                "pnpm-lock.yaml",
+                "yarn.lock",
+                "*.db",
+                "*.sqlite",
+                "scratch.*",
+                ".env*",
+                "**/*.min.js",
+                "**/*.min.css",
+                "**/db/migrations/**",
+                "**/i18n/**",
+                "docs",
+                ".claude",
+                ".angular",
+                ".vercel/**",
+                "vendor/**",
+                ".gitignore",
+                "**/domains/**/*.concept.ts",
+            ],
+            dictionaries: [
+                "typescript",
+                "node",
+                "npm",
+                "html",
+                "css",
+                "bash",
+                "companies",
+                "softwareTerms",
+            ],
+        },
+        null,
+        4,
+    )}\n`;
+}
+
+function readme(name: string, database: Database, features: Feature[], compose: boolean) {
+    const enabled = FEATURE_NAMES.filter((feature) => features.includes(feature));
+
+    return `# ${name}
+
+A Cortex server: one agent, a ${database} database, and an OpenAI-compatible model.${
+        enabled.length === 0 ? "" : ` Also on: ${enabled.join(", ")}.`
+    }
+
+## Getting started
+
+\`\`\`sh
+bun install
+${compose ? "docker compose up -d\n" : ""}# fill in CORTEX_MODEL_* in .env
+bun run dev
+\`\`\`
+
+The server listens on http://localhost:3331. Change \`port\` in \`cortex.config.ts\` to move it.${
+        compose
+            ? `
+
+The service ports in \`docker-compose.yml\` are not the canonical ones: they were picked at scaffold
+time from what was free on this machine, so this project does not fight whatever else you run.
+\`.env\` already points at them.`
+            : ""
+    }
+
+## Layout
+
+- \`cortex.config.ts\` — inert data. It default-exports a \`CortexConfig\` and never constructs
+  anything, so tooling can import it without booting a server.
+- \`index.ts\` — construction. It reads the config, calls \`createCortex\`, serves, and is where your
+  own routes go.
+- \`.env\` — local secrets, loaded by Bun from the directory you run in. \`.env.example\` is the
+  committed copy.
+
+Commented-out sections in \`cortex.config.ts\` document what else the server can do.
+
+## Checks
+
+\`bun run verify\` runs formatting, lint, spelling, types, and the fallow audit — the same set a
+pre-commit hook or CI job should run. Each is also available on its own: \`format:check\`, \`lint\`,
+\`spellcheck\`, \`check\`, \`audit\`.
+`;
+}
+
+/** Relative path → contents. Nothing here touches the filesystem. */
+export function scaffoldFiles(name: string, database: Database, features: Feature[], ports: Ports) {
+    const envFile = env(database, features);
+    const compose = dockerCompose(name, database, features);
+
+    const files: Record<string, string> = {
+        "cortex.config.ts": cortexConfig(database, features),
+        "index.ts": indexTs,
+        "package.json": packageJson(name),
+        "tsconfig.json": tsconfigJson,
+        ".env": envFile,
+        ".env.example": envFile,
+        ".gitignore": gitignoreText,
+        "README.md": readme(name, database, features, compose !== undefined),
+        "eslint.config.mjs": eslintConfig,
+        "prettier.config.mjs": prettierConfig,
+        "cspell.json": cspellConfig(),
+        ".fallowrc.jsonc": fallowrc,
+        ...(compose === undefined ? {} : { "docker-compose.yml": compose }),
+        ...(features.includes("knowledge") ? { "src/domains/README.md": domainsReadme } : {}),
+    };
+
+    // One pass at the end, over everything: no generator holds a port number of
+    // its own, so compose, .env and the README cannot disagree about one.
+    return Object.fromEntries(
+        Object.entries(files).map(([path, contents]) => [path, applyPorts(contents, ports)]),
+    );
+}