@m6d/cortex-cli 1.0.0

package/src/graph/generate-cypher.ts

@@ -0,0 +1,201 @@
+/**
+ * Transforms declarative DomainDef into idempotent MERGE-based Cypher.
+ *
+ * Returns two phases:
+ *   - `nodes`  -- MERGE statements that create/update Domain, Concept, Endpoint,
+ *                 Service, and Rule nodes.
+ *   - `edges`  -- MATCH+MERGE statements that wire up relationships between nodes.
+ *
+ * The caller MUST run all `nodes` from every module before running any `edges`,
+ * because edges may reference nodes defined in a different module (e.g. a Rule
+ * in the leaves module that GOVERNS a Concept created by the servicing module).
+ *
+ * Every label, relationship type and property name comes from the `GraphSchema`
+ * the caller passes in — the project's own copy, so what this writes is by
+ * construction what that project's resolver reads back.
+ */
+
+import type {
+    ConceptDef,
+    DomainDef,
+    EndpointDef,
+    GraphSchema,
+    RuleDef,
+    ServiceDef,
+} from "@cortex/contracts/graph";
+
+export type GeneratedCypher = {
+    nodes: string[];
+    edges: string[];
+};
+
+export function generateCypher(data: DomainDef, s: GraphSchema) {
+    const nodes: string[] = [domainNode(data, s)];
+    const edges: string[] = [];
+
+    for (const concept of data.concepts ?? []) {
+        nodes.push(conceptNode(concept, s));
+        edges.push(...conceptEdges(concept, data.name, s));
+    }
+
+    for (const endpoint of data.endpoints ?? []) {
+        nodes.push(endpointNode(endpoint, s));
+        edges.push(...endpointEdges(endpoint, s));
+    }
+
+    for (const service of data.services ?? []) {
+        nodes.push(serviceNode(service, s));
+        edges.push(...serviceEdges(service, s));
+    }
+
+    for (const rule of data.rules ?? []) {
+        nodes.push(ruleNode(rule, s));
+    }
+
+    return { nodes, edges } satisfies GeneratedCypher;
+}
+
+function domainNode(data: DomainDef, s: GraphSchema) {
+    return `MERGE (d:${s.label.domain} {${s.prop.name}: '${esc(data.name)}'})
+        SET d.${s.prop.description} = '${esc(data.description)}'${metadataClause("d", data.metadata, s)}`;
+}
+
+function conceptNode(concept: ConceptDef, s: GraphSchema) {
+    const aliases =
+        concept.aliases && concept.aliases.length > 0
+            ? `, c.${s.prop.aliases} = [${concept.aliases.map((alias) => `'${esc(alias)}'`).join(", ")}]`
+            : "";
+
+    return `MERGE (c:${s.label.concept} {${s.prop.name}: '${esc(concept.name)}'})
+            SET c.${s.prop.description} = '${esc(concept.description)}'${aliases}${metadataClause("c", concept.metadata, s)}`;
+}
+
+function conceptEdges(concept: ConceptDef, domainName: string, s: GraphSchema) {
+    const edges = [
+        `MATCH (c:${conceptRef(concept, s)})
+            MATCH (d:${s.label.domain} {${s.prop.name}: '${esc(domainName)}'})
+            MERGE (c)-[:${s.rel.belongsTo}]->(d)`,
+    ];
+
+    if (concept.parentConcept) {
+        edges.push(
+            `MATCH (child:${conceptRef(concept, s)})
+                MATCH (parent:${conceptRef(concept.parentConcept, s)})
+                MERGE (child)-[:${s.rel.specializes}]->(parent)`,
+        );
+    }
+
+    edges.push(...governedByEdges(concept.governedBy, conceptRef(concept, s), s));
+
+    return edges;
+}
+
+function endpointNode(endpoint: EndpointDef, s: GraphSchema) {
+    return `MERGE (e:${endpointRef(endpoint, s)})
+            SET e.${s.prop.name} = '${esc(endpoint.name)}',
+                e.${s.prop.description} = '${esc(endpoint.description)}',
+                e.${s.prop.params} = '${jsonStr(endpoint.params)}',
+                e.${s.prop.body} = '${jsonStr(endpoint.body)}',
+                e.${s.prop.response} = '${jsonStr(endpoint.response)}',
+                e.${s.prop.propertiesDescriptions} = '${jsonStr(endpoint.propertiesDescriptions)}',
+                e.${s.prop.successStatus} = ${endpoint.successStatus},
+                e.${s.prop.errorStatuses} = [${endpoint.errorStatuses.join(", ")}]${metadataClause("e", endpoint.metadata, s)}`;
+}
+
+function endpointEdges(endpoint: EndpointDef, s: GraphSchema) {
+    const edges: string[] = [];
+    const self = endpointRef(endpoint, s);
+
+    for (const [concepts, relationship] of [
+        [endpoint.queries, s.rel.queriedVia],
+        [endpoint.mutates, s.rel.mutatedVia],
+    ] as const) {
+        for (const concept of concepts ?? []) {
+            edges.push(
+                `MATCH (c:${conceptRef(concept, s)})
+                MATCH (e:${self})
+                MERGE (c)-[:${relationship}]->(e)`,
+            );
+        }
+    }
+
+    for (const returned of endpoint.returns ?? []) {
+        // The field says which part of the response carries the concept; without
+        // one the whole body is the concept.
+        const field = returned.field ? ` SET r.${s.prop.field} = '${esc(returned.field)}'` : "";
+        edges.push(
+            `MATCH (e:${self})
+                MATCH (c:${conceptRef(returned.concept, s)})
+                MERGE (e)-[r:${s.rel.returns}]->(c)${field}`,
+        );
+    }
+
+    edges.push(...governedByEdges(endpoint.governedBy, self, s));
+
+    for (const dependency of endpoint.dependsOn ?? []) {
+        edges.push(
+            `MATCH (e:${self})
+                MATCH (dep:${endpointRef(dependency.endpoint, s)})
+                MERGE (e)-[d:${s.rel.dependsOn}]->(dep)
+                SET d.${s.prop.paramName} = '${esc(dependency.paramName)}', d.${s.prop.fromField} = '${esc(dependency.fromField)}'`,
+        );
+    }
+
+    return edges;
+}
+
+function serviceNode(service: ServiceDef, s: GraphSchema) {
+    return `MERGE (s:${serviceRef(service, s)})
+            SET s.${s.prop.name} = '${esc(service.name)}',
+            s.${s.prop.description} = '${esc(service.description)}'${metadataClause("s", service.metadata, s)}`;
+}
+
+function serviceEdges(service: ServiceDef, s: GraphSchema) {
+    return [
+        `MATCH (c:${conceptRef(service.belongsTo, s)})
+            MATCH (s:${serviceRef(service, s)})
+            MERGE (c)-[:${s.rel.requestedVia}]->(s)`,
+        ...governedByEdges(service.governedBy, serviceRef(service, s), s),
+    ];
+}
+
+function ruleNode(rule: RuleDef, s: GraphSchema) {
+    return `MERGE (r:${s.label.rule} {${s.prop.name}: '${esc(rule.name)}'})
+            SET r.${s.prop.description} = '${esc(rule.description)}'${metadataClause("r", rule.metadata, s)}`;
+}
+
+/** Rules govern concepts, endpoints and services identically; only the target differs. */
+function governedByEdges(rules: RuleDef[] | undefined, targetRef: string, s: GraphSchema) {
+    return (rules ?? []).map(
+        (rule) => `MATCH (r:${s.label.rule} {${s.prop.name}: '${esc(rule.name)}'})
+                MATCH (t:${targetRef})
+                MERGE (r)-[:${s.rel.governs}]->(t)`,
+    );
+}
+
+/** Endpoints are keyed on path plus method, so both must appear in every match. */
+function endpointRef(endpoint: Pick<EndpointDef, "path" | "method">, s: GraphSchema) {
+    return `${s.label.endpoint} {${s.prop.path}: '${esc(endpoint.path)}', ${s.prop.method}: '${endpoint.method}'}`;
+}
+
+function conceptRef(concept: Pick<ConceptDef, "name">, s: GraphSchema) {
+    return `${s.label.concept} {${s.prop.name}: '${esc(concept.name)}'}`;
+}
+
+function serviceRef(service: Pick<ServiceDef, "builtInId">, s: GraphSchema) {
+    return `${s.label.service} {${s.prop.builtInId}: '${esc(service.builtInId)}'}`;
+}
+
+/** Omitted entirely when absent — an empty assignment is not valid Cypher. */
+function metadataClause(alias: string, metadata: unknown, s: GraphSchema) {
+    return metadata ? `, ${alias}.${s.prop.metadata} = '${jsonStr(metadata)}'` : "";
+}
+
+/** Backslashes first, so escaping a quote cannot itself be escaped away. */
+function esc(value: string) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n");
+}
+
+function jsonStr(value: unknown) {
+    return esc(JSON.stringify(value));
+}

package/src/graph/seed.ts

@@ -0,0 +1,227 @@
+/**
+ * Seed orchestrator for the knowledge graph.
+ *
+ * Validates domains, generates Cypher, executes against Neo4j,
+ * and generates concept embeddings. All configuration is passed
+ * explicitly — no environment variables or Convex dependencies.
+ */
+
+import type { DomainDef, EmbedFn, GraphSchema, Neo4jClient } from "@cortex/contracts/graph";
+
+import { expandDomains } from "./expand-domains";
+import { generateCypher, type GeneratedCypher } from "./generate-cypher";
+import { validateDomain } from "./validate";
+
+export type EmbeddingConfig = {
+    embed: EmbedFn;
+    dimension: number;
+};
+
+export type SeedGraphConfig = {
+    neo4j: Neo4jClient;
+    embedding: EmbeddingConfig;
+    /** `GRAPH_SCHEMA`, passed rather than imported so tests can drive a fake one. */
+    schema: GraphSchema;
+    /** Stamped onto the graph, so the server can refuse a shape it cannot read. */
+    schemaVersion: number;
+};
+
+export type StatementFailure = {
+    /** The Neo4j error code where there was one, its message otherwise. */
+    error: string;
+    /** The statement as generated, untruncated — the caller decides how much to show. */
+    statement: string;
+};
+
+export type DomainSeedResult = {
+    nodes: number;
+    edges: number;
+    failed: number;
+    failures: StatementFailure[];
+};
+
+export type SeedGraphResult = {
+    nodes: number;
+    edges: number;
+    failed: number;
+    /** Keyed by the same names the config declares under `knowledge.domains`. */
+    domains: Record<string, DomainSeedResult>;
+    embeddings: { concepts: number; dimension: number };
+};
+
+// Nodes for every domain run before any edge does, so a statement carries the
+// domain it came from rather than being attributed by the loop that runs it.
+type TaggedStatement = { domain: string; statement: string };
+
+// The client resolves query failures as {"error":true} JSON rather than
+// rejecting; unchecked, a failed statement would count as a success.
+async function runStatement(client: Neo4jClient, statement: string) {
+    try {
+        const parsed = JSON.parse(await client.query(statement)) as {
+            error?: boolean;
+            code?: string;
+            message?: string;
+        };
+        if (!parsed.error) return undefined;
+        return parsed.code ?? parsed.message ?? "Neo4j query failed";
+    } catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+
+// Maps, not objects: a domain is named by the user, and `constructor` is a legal
+// domain name that on a plain record reads back `Object.prototype.constructor` —
+// a function, so `?? 0` never fires and `.push` throws.
+async function runPhase(client: Neo4jClient, statements: TaggedStatement[]) {
+    const succeeded = new Map<string, number>();
+    const failures = new Map<string, StatementFailure[]>();
+
+    for (const { domain, statement } of statements) {
+        const error = await runStatement(client, statement);
+        if (error === undefined) {
+            succeeded.set(domain, (succeeded.get(domain) ?? 0) + 1);
+            continue;
+        }
+
+        const collected = failures.get(domain) ?? [];
+        collected.push({ error, statement });
+        failures.set(domain, collected);
+    }
+
+    return { succeeded, failures };
+}
+
+// Same reason as `runStatement`, but the embedding pass has no partial result to
+// report: a failure there is a thrown error, not a count.
+function assertOk(result: string) {
+    const parsed = JSON.parse(result) as { error?: boolean; message?: string };
+    if (parsed.error) throw new Error(parsed.message ?? "Neo4j query failed");
+}
+
+async function generateEmbeddings(
+    client: Neo4jClient,
+    embeddingConfig: EmbeddingConfig,
+    s: GraphSchema,
+) {
+    // 1. Create the vector index (idempotent)
+    assertOk(
+        await client.query(
+            `CREATE VECTOR INDEX ${s.conceptEmbeddingsIndex} IF NOT EXISTS
+             FOR (c:${s.label.concept}) ON (c.${s.prop.embedding})
+             OPTIONS {indexConfig: {
+                 \`vector.dimensions\`: ${embeddingConfig.dimension},
+                 \`vector.similarity_function\`: 'cosine'
+             }}`,
+        ),
+    );
+
+    // 2. Fetch all concepts
+    const conceptsRaw = await client.query(
+        `MATCH (c:${s.label.concept}) RETURN c.${s.prop.name} AS name, c.${s.prop.description} AS description`,
+    );
+    assertOk(conceptsRaw);
+    const concepts = JSON.parse(conceptsRaw) as { name: string; description: string }[];
+
+    if (!Array.isArray(concepts) || concepts.length === 0) {
+        return { concepts: 0, dimension: embeddingConfig.dimension };
+    }
+
+    // 3. Generate embeddings for every concept in one request
+    const embeddings = await embeddingConfig.embed(concepts.map((c) => c.description));
+
+    // 4. Store the embeddings in the graph
+    await Promise.all(
+        concepts.map(async (concept, idx) =>
+            assertOk(
+                await client.query(
+                    `MATCH (c:${s.label.concept} {${s.prop.name}: $name})
+                     SET c.${s.prop.embedding} = $embedding`,
+                    {
+                        name: concept.name,
+                        embedding: embeddings[idx]!,
+                    },
+                ),
+            ),
+        ),
+    );
+
+    return { concepts: concepts.length, dimension: embeddingConfig.dimension };
+}
+
+export async function seedGraph(config: SeedGraphConfig, domains: Record<string, DomainDef>) {
+    const expandedDomains = expandDomains(domains);
+
+    // Validate all domains
+    const validationErrors = Object.entries(expandedDomains).flatMap(([name, domain]) =>
+        validateDomain(domain).map((err) => `[${name}] ${err}`),
+    );
+
+    if (validationErrors.length) {
+        throw new Error(
+            `Validation failed with ${validationErrors.length} error(s):\n${validationErrors.join("\n")}`,
+        );
+    }
+
+    const client = config.neo4j;
+    const targets = Object.entries(expandedDomains);
+
+    // Generate Cypher for all target domains
+    const allCypher: [string, GeneratedCypher][] = targets.map(([name, data]) => [
+        name,
+        generateCypher(data, config.schema),
+    ]);
+
+    // Stamped before anything else is written, so an interrupted seed still
+    // leaves the graph labelled with the schema it was written against.
+    assertOk(
+        await client.query(
+            `MERGE (g:${config.schema.label.marker})
+             SET g.${config.schema.prop.version} = ${config.schemaVersion}`,
+        ),
+    );
+
+    // Phase 1: Create all nodes across every domain first.
+    // This ensures cross-domain references resolve correctly.
+    const allNodes = allCypher.flatMap(([domain, c]) => tag(domain, c.nodes));
+    const nodes = await runPhase(client, allNodes);
+
+    // Phase 2: Create all edges now that every node exists.
+    const allEdges = allCypher.flatMap(([domain, c]) => tag(domain, c.edges));
+    const edges = await runPhase(client, allEdges);
+
+    // Phase 3: Generate embeddings for concepts
+    const embeddings = await generateEmbeddings(client, config.embedding, config.schema);
+
+    const domainResults: Record<string, DomainSeedResult> = Object.fromEntries(
+        targets.map(([name]) => {
+            const failures = [
+                ...(nodes.failures.get(name) ?? []),
+                ...(edges.failures.get(name) ?? []),
+            ];
+            return [
+                name,
+                {
+                    nodes: nodes.succeeded.get(name) ?? 0,
+                    edges: edges.succeeded.get(name) ?? 0,
+                    failed: failures.length,
+                    failures,
+                },
+            ];
+        }),
+    );
+
+    // The aggregates stay the headline number; per-domain is the breakdown of it.
+    return Object.values(domainResults).reduce<SeedGraphResult>(
+        (total, domain) => ({
+            ...total,
+            nodes: total.nodes + domain.nodes,
+            edges: total.edges + domain.edges,
+            failed: total.failed + domain.failed,
+        }),
+        { nodes: 0, edges: 0, failed: 0, domains: domainResults, embeddings },
+    );
+}
+
+function tag(domain: string, statements: string[]) {
+    return statements.map((statement) => ({ domain, statement }) satisfies TaggedStatement);
+}

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,189 @@
+/**
+ * The five features `cortex new` toggles (design spec §7.1). 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=minioadmin
+CORTEX_MINIO_SECRET_KEY=minioadmin
+
+# 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: minioadmin
+            MINIO_ROOT_PASSWORD: minioadmin
+        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: {
+              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_KEY"]!,
+          },
+      }
+    : {}),`,
+        env: `# --- Control Center ----------------------------------------------------------
+CORTEX_CONTROL_CENTER_URL=http://localhost:4000
+CORTEX_CONTROL_CENTER_KEY=your-control-center-key`,
+        secrets: "CORTEX_CONTROL_CENTER_KEY",
+    },
+};
+
+/** Catalogue order, which is the order every generated file lists them in. */
+export const FEATURE_NAMES = Object.keys(FEATURES) as Feature[];