@m6d/cortex-cli 0.13.0 → 0.15.0

package/src/contracts/wire/index.ts

@@ -131,12 +131,23 @@ export type ClientToolBinding = {
  */
 export type AgentCapabilities = {
     attachments: boolean;
-    /** False when the agent's `message` trigger is off: the widget hides its composer. */
+    /**
+     * False when this caller may not send to the chat: the agent's `message`
+     * trigger is off, or the caller only reads (`readOnly`). The widget hides
+     * its composer and answers no tool call.
+     */
     messages: boolean;
+    /** True when the caller only reads, as an operator inspecting a user's thread does. */
+    readOnly: boolean;
     /** Prompt chips on the blank-chat landing per locale; clicking one sends its `prompt` as the first message. */
     suggestions: Suggestions;
     /** Headline of the blank-chat landing per locale; "" falls back to the widget's built-in copy. */
     greeting: Greeting;
+    /**
+     * Whether this caller gets the debug view: tool inputs and outputs, reasoning,
+     * model calls. Cortex sends anyone else only what the widget's normal UI draws.
+     */
+    debug: boolean;
 };
 
 export type MessageMetadata = {
@@ -171,13 +182,25 @@ export type LocalizedText = Record<Locale, string>;
  */
 export const STATEMENT_TOOLS = ["executeCode", "queryDataset", "describeDataset"] as const;
 
+/**
+ * The input Cortex adds to every tool that waits for the end user's approval:
+ * the model writes what that one call will do, and the approval card shows it
+ * as its title. Cortex removes it before the call runs.
+ */
+export const APPROVAL_TITLE_FIELD = "approvalTitle";
+
+/** The title the model wrote into an approval call's input, or undefined while it has none. */
+export function approvalTitleOf(input: unknown) {
+    if (!input || typeof input !== "object" || !(APPROVAL_TITLE_FIELD in input)) return undefined;
+    const title: unknown = input[APPROVAL_TITLE_FIELD];
+    return typeof title === "string" && title.trim() ? title.trim() : undefined;
+}
+
 /**
  * What Cortex stamps on a tool call's `metadata.cortex` from its first chunk,
  * so the live part and the stored one agree.
  */
 export type ToolCallMetadata = {
-    /** The action the approval card names, in the author's words rather than the function's name. */
-    approval?: LocalizedText;
     /**
      * Set on every call the client answers: a client tool's, the consumer's own, or a built-in
      * input's. Cortex runs every other call, so only these take an output from a request.
@@ -326,3 +349,19 @@ export type WsEvent =
 
 /** The header the widget sends the browser's IANA time zone in; the turn reasons in that clock. */
 export const TIMEZONE_HEADER = "X-Cortex-Timezone";
+
+/**
+ * The console operator's short-lived token, sent by the playground and the
+ * thread inspector on every request to an agent and by the fire and answer
+ * calls Cortex makes to a trigger's route. A verified one makes the operator the caller unless the
+ * request also carries an end-user token to test as, and marks the threads it
+ * opens as test threads. A WebSocket upgrade carries it as `?operator=`.
+ */
+export const OPERATOR_HEADER = "X-Cortex-Operator";
+
+/**
+ * Beside the operator token, the id of a thread the operator inspects: the
+ * request then reads as that thread's owner, read-only, with the debug view.
+ * A WebSocket upgrade carries it as `?inspect=`.
+ */
+export const INSPECT_HEADER = "X-Cortex-Inspect";

package/src/management/client.ts

@@ -225,6 +225,8 @@ export async function callManagement(
             ...(method === "post" ? { "Content-Type": "application/json" } : {}),
         },
         body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
+    }).catch((error: unknown) => {
+        throw new UnreachableError(error);
     });
     const body: unknown = await response.json().catch(() => null);
     if (!response.ok) {
@@ -261,6 +263,18 @@ function queryString(input: Record<string, unknown>) {
     return encoded === "" ? "" : `?${encoded}`;
 }
 
+/**
+ * Cortex did not answer at all: refused, reset, unresolvable. `fetch` rejects
+ * only for these, with whatever its runtime throws (Bun's is a plain `Error`
+ * with a `code`), so `callManagement` names them once here.
+ */
+export class UnreachableError extends Error {
+    public constructor(cause: unknown) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = "UnreachableError";
+    }
+}
+
 /** A refusal; `detail` is what the refusal names, when it names something (an entry, the row holding a name). */
 export class ManagementError extends Error {
     public constructor(

package/src/management/profiles.ts

@@ -87,14 +87,16 @@ export function removeProfile(name: string) {
 }
 
 /**
- * The profile a management command runs against: `CORTEX_URL` + `CORTEX_KEY`
- * when both are set (CI, containers), else the named or current entry from
- * the file. `undefined` means nobody has logged in.
+ * The profile a management command runs against: the entry `name` picks from
+ * the file, else `CORTEX_URL` + `CORTEX_KEY` when both are set (CI, containers,
+ * a project's .env), else the current entry. A name always wins, so `-p prod`
+ * inside a project whose .env points at its own Cortex still reaches prod.
+ * `undefined` means nobody has logged in.
  */
 export function resolveProfile(name?: string) {
     const url = process.env["CORTEX_URL"];
     const key = process.env["CORTEX_KEY"];
-    if (url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
+    if (name === undefined && url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
     const store = readStore();
     const chosen = name ?? store.current;
     const profile = lookup(store, chosen);

package/src/scaffold/files.ts

@@ -17,6 +17,9 @@ import dockerignoreText from "@/scaffold/templates/dockerignore.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";
+// Project jargon is the project's to add. Only `mprocs`, which its own
+// package.json names, is seeded: a stranger's vocabulary is noise in a repo.
+import cspellJson from "@/scaffold/templates/cspell.json.txt";
 import { applyPorts, type Ports } from "@/scaffold/ports";
 
 /**
@@ -24,11 +27,13 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.13.0";
+const CORTEX_VERSION = "0.15.0";
 
-/** Where the backend listens, and how Cortex's containers reach it on this machine. */
-const SERVER_PORT = 3331;
-const SERVER_URL = `http://host.docker.internal:${SERVER_PORT}`;
+/** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
+export const DOCKER_HOST = "host.docker.internal";
+
+/** How Cortex's containers reach the backend on this machine, at the port drawn for it. */
+const SERVER_URL = `http://${DOCKER_HOST}:{{port.server}}`;
 
 /** The longest server name Cortex accepts. */
 const SERVER_NAME_MAX = 100;
@@ -37,27 +42,76 @@ const SERVER_NAME_MAX = 100;
  * The agent the manifest declares and the README sends you to chat with.
  * Not `assistant`: Cortex holds that slug for its console's own assistant.
  */
-const AGENT_SLUG = "helper";
+export const AGENT_SLUG = "helper";
+
+/**
+ * The embedding model the stack asks for, and the dimension the image's
+ * migrations give the vector columns. `cortex setup` probes a provider with
+ * the same pair before reusing it for embeddings.
+ */
+export const EMBEDDING = { model: "text-embedding-3-small", dimension: 768 } as const;
 
 const DEV_DEPENDENCIES = {
-    // `cortex apply` and the management commands, at the release that wrote the project.
+    // `cortex apply`, `cortex setup` and the management commands, at the release that wrote the project.
     "@m6d/cortex-cli": `~${pkg.version}`,
     "@types/bun": "latest",
+    // The two runners of `bun run dev` and `bun run dev:agent`.
+    concurrently: "^10.0.6",
     cspell: "^9.6.4",
     eslint: "^9",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.5",
     fallow: "^3.9.1",
+    mprocs: "^0.9.6",
     prettier: "^3.6.2",
     typescript: "^5",
     "typescript-eslint": "^8.65.0",
 };
 
-type Input = { name: string; datasets: boolean; ports: Ports };
+/**
+ * `setup` puts `cortex setup` among the processes `bun run dev` starts; `env`
+ * holds values `cortex new` was given for `.env`, such as the model provider,
+ * which is then written beside `.env.example` with them filled in.
+ */
+type Input = {
+    name: string;
+    datasets: boolean;
+    setup: boolean;
+    ports: Ports;
+    env?: Record<string, string>;
+};
 
 /** The input, and the name the backend is registered under in Cortex. */
 type Project = Input & { server: string };
 
+/**
+ * `text` with each `KEY=` line named in `values` set to its value, and every
+ * other line left as written. `cortex new` fills `.env` with it, and
+ * `cortex setup` the `.env` it asks the model provider for.
+ */
+export function withEnvValues(text: string, values: Record<string, string>) {
+    return Object.entries(values).reduce(
+        (filled, [key, value]) =>
+            filled.replace(new RegExp(`^${key}=.*$`, "m"), () => `${key}=${value}`),
+        text,
+    );
+}
+
+/** What `bun run dev` starts side by side, named as the runners label them. */
+function devProcesses(setup: boolean) {
+    return {
+        cortex: "docker compose up",
+        server: "bun run dev:server",
+        ...(setup ? { setup: "bun cortex setup --wait --yes" } : {}),
+    };
+}
+
+/** One runner's command line: the process names, then each command quoted. */
+function runAll(runner: "mprocs" | "concurrently", processes: Record<string, string>) {
+    const commands = Object.values(processes).map((command) => `"${command}"`);
+    return `${runner} --names ${Object.keys(processes).join(",")} ${commands.join(" ")}`;
+}
+
 /** The name as the manifest `id` takes it: lowercase words and hyphens. */
 export function manifestIdOf(name: string) {
     return name
@@ -66,7 +120,9 @@ export function manifestIdOf(name: string) {
         .replace(/^-+|-+$/g, "");
 }
 
-function packageJson({ name, datasets }: Project) {
+function packageJson({ name, datasets, setup }: Project) {
+    const processes = devProcesses(setup);
+
     return `${JSON.stringify(
         {
             name,
@@ -80,7 +136,11 @@ function packageJson({ name, datasets }: Project) {
                 // analyses — dead code, duplication, complexity — over everything.
                 audit: "fallow",
                 check: "tsc --noEmit",
-                dev: "bun run --hot index.ts",
+                // The same processes twice: a dashboard for people, and one
+                // labelled log for coding agents and CI.
+                dev: runAll("mprocs", processes),
+                "dev:agent": runAll("concurrently", processes),
+                "dev:server": "bun run --hot index.ts",
                 // A no-op where setup.ts is not copied in, as in an image build.
                 postinstall: "bun run --if-present setup.ts",
                 format: "prettier --write .",
@@ -90,7 +150,7 @@ function packageJson({ name, datasets }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.1.0",
+                "@m6d/cortex": "~0.3.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",
@@ -118,16 +178,20 @@ ${datasets ? `import { datasets } from "./datasets";\n` : ""}import { server } f
 const app = new Hono();
 app.route("/cortex", server);
 ${datasets ? `app.route("/datasets", datasets);\n` : ""}
-export default { port: ${SERVER_PORT}, fetch: app.fetch };
+export default { port: {{port.server}}, fetch: app.fetch };
 `;
 }
 
-function manifestTs({ name, server, datasets }: Project) {
-    const serverUrl = `
-/** Where Cortex reaches this backend, from .env. */
-const serverUrl = process.env["CORTEX_SERVER_URL"];
-if (!serverUrl) throw new Error("Set CORTEX_SERVER_URL in .env before applying this manifest.");
-`;
+function manifestTs({ name, datasets }: Project) {
+    const fromEnv = datasets
+        ? `/** The server this backend is registered as, and where Cortex reaches it, from .env. */
+const { CORTEX_SERVER_NAME: server, CORTEX_SERVER_URL: serverUrl } = process.env;
+if (!server || !serverUrl) {
+    throw new Error("Apply from this project: its .env names the server.");
+}`
+        : `/** The server this backend is registered as, from .env. */
+const server = process.env["CORTEX_SERVER_NAME"];
+if (!server) throw new Error("Apply from this project: its .env names the server.");`;
     const datasetHosts = `
     // The orders this backend serves (datasets.ts), for every agent on its server.
     datasetHosts: [
@@ -137,7 +201,7 @@ if (!serverUrl) throw new Error("Set CORTEX_SERVER_URL in .env before applying t
             credentials: [],
             expose: ["orders"],
             pinned: ["orders"],
-            audience: { server: ${JSON.stringify(server)} },
+            audience: { server },
         },
     ],`;
 
@@ -145,17 +209,19 @@ if (!serverUrl) throw new Error("Set CORTEX_SERVER_URL in .env before applying t
 
 /*
  * What this project declares in Cortex, which \`cortex apply\` makes Cortex
- * match. The agent runs on the server registered as ${JSON.stringify(server)}: this
- * backend, whose variable its prompt reads and whose native tool it calls.
+ * match. The agent runs on this backend's server, whose variable its prompt
+ * reads and whose native tool it calls.
  */
-${datasets ? serverUrl : ""}
+
+${fromEnv}
+
 export default defineManifest({
     id: ${JSON.stringify(manifestIdOf(name))},
     agents: [
         {
             slug: "${AGENT_SLUG}",
             name: "Helper",
-            server: ${JSON.stringify(server)},
+            server,
             prompt: "You are a helpful assistant. Address the user as {{userName}}.",
             // No identity provider yet: every caller is one shared identity.
             auth: { kind: "anonymous" },
@@ -165,35 +231,21 @@ export default defineManifest({
 `;
 }
 
-/** The backend's settings, which setup.ts copies into .env, generating the key. */
-const BACKEND_ENV = `# This backend's settings. Bun loads .env from the directory you run in, into
-# the backend (\`bun run dev\`) and into \`cortex apply\`. Cortex's own settings
-# are in cortex.env, which only docker compose reads.
+/** Every setting the project has, which setup.ts copies into .env, generating the secrets. */
+function envExample({ server }: Project) {
+    return `# Every setting this project has. Bun loads .env from the directory you run
+# in, into the backend and the \`cortex\` CLI; docker compose hands it to the
+# Cortex containers and reads COMPOSE_PROJECT_NAME from it.
 #
 # This is the committed copy. \`bun install\` writes .env from it, generating
-# the values it leaves blank, and never changes a value .env already holds.
+# the secrets it leaves blank, and never changes a value .env already holds.
 
 # The Compose project this checkout's Cortex stack runs as, drawn for each
 # checkout, so a clone never shares another checkout's containers or volumes.
 COMPOSE_PROJECT_NAME=
 
-# The key Cortex presents on every call to the server. Store the same value in
-# Cortex as the secret the server is registered with.
-CORTEX_SERVER_KEY=
-# Where Cortex reaches this backend from inside its containers.
-CORTEX_SERVER_URL=${SERVER_URL}
-`;
-
-/** Cortex's settings, which setup.ts copies into cortex.env, generating the secrets. */
-const CORTEX_ENV = `# Cortex's settings, which docker compose hands the Cortex containers in
-# docker-compose.yml. The backend never loads cortex.env.
-#
-# This is the committed copy. \`bun install\` writes cortex.env from it,
-# generating the secrets it leaves blank, and never changes a value
-# cortex.env already holds.
-
-# Cortex's first admin, created when the stack first starts, and
-# the management key \`cortex login\` takes.
+# Cortex's first admin, created when the stack first starts, and its
+# management key.
 DEFAULT_ADMIN_EMAIL=admin@example.com
 DEFAULT_ADMIN_PASSWORD=
 BOOTSTRAP_MANAGEMENT_KEY=
@@ -201,21 +253,47 @@ BOOTSTRAP_MANAGEMENT_KEY=
 BETTER_AUTH_SECRET=
 SECRETS_MASTER_KEY=
 # Any OpenAI-compatible embeddings endpoint and model. Tool search and
-# knowledge collections embed with it.
+# knowledge collections embed with it, and stay off while the key is blank.
 EMBEDDING_BASE_URL=https://api.openai.com/v1
-EMBEDDING_API_KEY=your-embedding-api-key
-EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_API_KEY=
+EMBEDDING_MODEL=${EMBEDDING.model}
+# The private hosts Cortex's containers may call, and send a secret to over
+# plain http, comma-separated: this machine, for the backend. A model provider
+# on a private network goes here too. The policy admits a host by name,
+# whatever the port: see README.md.
+EGRESS_ALLOWED_HOSTS=${DOCKER_HOST}
+
+# The Cortex \`cortex apply\` and \`cortex setup\` talk to: this checkout's,
+# under its management key, so neither needs \`cortex login\`. \`-p <profile>\`
+# still picks a saved one.
+CORTEX_URL=http://localhost:{{port.cortex}}
+CORTEX_KEY=\${BOOTSTRAP_MANAGEMENT_KEY}
+
+# This backend as Cortex registers it: its name, where Cortex's containers
+# reach it, and the key Cortex presents on every call to it.
+CORTEX_SERVER_NAME=${server}
+CORTEX_SERVER_URL=${SERVER_URL}
+CORTEX_SERVER_KEY=
+
+# The model provider \`cortex setup\` registers and the server's agents run on.
+# While these are blank, setup registers the server and applies nothing.
+MODEL_PROVIDER_NAME=
+MODEL_PROVIDER_URL=
+MODEL_PROVIDER_API_KEY=
+MODEL_PROVIDER_MODEL=
 `;
+}
 
 /** Cortex itself: its app, worker and engine, all on the one Cortex image, and their stores. */
 function dockerCompose() {
     return `# Cortex, for this project's agents to run on: the console at
 # http://localhost:{{port.cortex}}, the engine widgets and trigger callers reach at
-# http://localhost:{{port.engine}}, and the stores they keep state in. \`docker compose
-# up -d\` starts it; cortex.env holds its secrets.
+# http://localhost:{{port.engine}}, and the stores they keep state in. \`bun run dev\`
+# starts it; .env holds its secrets.
 #
-# The two host ports were picked at scaffold time from what was free on this
-# machine. Move one and the URLs that name it here and in README.md follow.
+# The host ports were picked at scaffold time from what was free on this
+# machine. Move one and the URLs that name it here, in .env and in README.md
+# follow.
 # CORTEX_VERSION, set in the shell, runs another release of the image.
 #
 # The console's browser uploads (knowledge documents) go straight to
@@ -229,8 +307,12 @@ function dockerCompose() {
 x-cortex: &cortex
     image: syscodeia/cortex:\${CORTEX_VERSION:-${CORTEX_VERSION}}
     working_dir: /repo/apps/cortex
-    env_file: cortex.env
+    # The whole .env, the backend's settings too. What \`environment\` sets
+    # wins over it, so nothing there can move these containers' ports or mode.
+    env_file: .env
     environment: &cortex-environment
+        NODE_ENV: production
+        PORT: "3000"
         DATABASE_URL: postgres://postgres:postgres@postgres:5432/cortex
         REDIS_URL: redis://redis:6379
         S3_ENDPOINT: http://minio:9000
@@ -240,15 +322,11 @@ x-cortex: &cortex
         S3_BUCKET: cortex
         BETTER_AUTH_ALLOWED_HOSTS: localhost:{{port.cortex}},127.0.0.1:{{port.cortex}}
         # The dimension the image's migrations give the vector columns.
-        EMBEDDING_DIMENSION: "768"
+        EMBEDDING_DIMENSION: "${EMBEDDING.dimension}"
         # The engine's public origin (browsers, trigger callers) and the
         # address the app reaches it at inside the stack.
         ENGINE_PUBLIC_URL: http://localhost:{{port.engine}}
         ENGINE_INTERNAL_URL: http://engine:3001
-        # This backend is a private address seen from the containers, and the
-        # server key travels to it over plain http. The policy admits a host
-        # by name, whatever the port: see README.md.
-        EGRESS_ALLOWED_HOSTS: host.docker.internal
     # Docker Desktop resolves host.docker.internal on its own; Linux needs this.
     extra_hosts:
         - host.docker.internal:host-gateway
@@ -353,6 +431,7 @@ services:
         command: ["bun", "src/engine/server.ts"]
         environment:
             <<: *cortex-environment
+            PORT: "3001"
             # Browser origins allowed to call the engine: the console's, for its playground and assistant.
             ENGINE_CORS_ORIGINS: http://localhost:{{port.cortex}},http://127.0.0.1:{{port.cortex}}
         ports:
@@ -369,57 +448,27 @@ volumes:
 `;
 }
 
-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",
-            ],
-            dictionaries: [
-                "typescript",
-                "node",
-                "npm",
-                "html",
-                "css",
-                "bash",
-                "companies",
-                "softwareTerms",
-            ],
-        },
-        null,
-        4,
-    )}\n`;
-}
+function readme({ name, server, datasets, setup }: Project) {
+    const gettingStarted = setup
+        ? `That starts Cortex (\`docker compose up\`), this backend, and \`cortex setup\` in one dashboard.
+Setup waits for Cortex, registers this backend as the server \`${server}\`, adds the model provider
+in \`.env\`, and applies the manifest. Then it prints where to chat with \`${AGENT_SLUG}\`, and the first
+time, how to sign in. It adds only what is missing, so every \`bun run dev\` runs it again.
+
+While \`MODEL_PROVIDER_*\` in \`.env\` is blank, setup registers the server and applies nothing:
+Cortex publishes no agent without a model. Run \`bun cortex setup\` in a terminal to be asked for
+one.`
+        : `That starts Cortex (\`docker compose up\`) and this backend in one dashboard. Then register the
+backend and apply the manifest, either way:
+
+- \`bun cortex setup\` in a terminal asks for a model provider, registers the server
+  \`${server}\`, and applies the manifest.
+- By hand: open the console at http://localhost:{{port.cortex}} and sign in with
+  \`DEFAULT_ADMIN_EMAIL\` and \`DEFAULT_ADMIN_PASSWORD\` from \`.env\`. Add a model provider on the
+  **Model providers** page, and store \`CORTEX_SERVER_KEY\` from \`.env\` on the **Secrets** page.
+  On the **Servers** page, add a server named \`${server}\` at \`${SERVER_URL}/cortex\` with that
+  secret as its key, and pick the model its agents run on. Then run \`bun cortex apply\`.`;
 
-function readme({ name, server, datasets }: Project) {
     return `# ${name}
 
 A backend for Cortex agents, and Cortex itself to run them on.
@@ -433,48 +482,38 @@ A backend for Cortex agents, and Cortex itself to run them on.
 - \`cortex.manifest.ts\` declares the \`${AGENT_SLUG}\` agent on this server${
         datasets ? " and the dataset host" : ""
     }. \`cortex apply\` makes Cortex match it.
-- \`docker-compose.yml\` runs Cortex: its app, worker and engine, and the stores they use, with
-  their secrets in \`cortex.env\`. \`.env\` holds the backend's own key.
-- \`setup.ts\` runs on every \`bun install\`: it writes \`.env\` and \`cortex.env\` from their committed
-  \`.example\` copies and generates each value they leave blank, so a fresh clone gets its own
-  secrets and its own Compose stack. It never changes a value already set. \`.dockerignore\` keeps
-  all four files out of any image built here.
+- \`docker-compose.yml\` runs Cortex: its app, worker and engine, and the stores they use.
+- \`.env\` holds every setting: Cortex's secrets, this backend's key, and the model provider.
+  \`setup.ts\` runs on every \`bun install\`: it writes \`.env\` from the committed \`.env.example\` and
+  generates each secret left blank, so a fresh clone gets its own secrets and its own Compose stack.
+  It never changes a value already set. \`.dockerignore\` keeps both files out of any image built
+  here.
 
 ## Getting started
 
-1. On a fresh clone, run \`bun install\` (\`cortex new\` already did). Then fill in
-   \`EMBEDDING_API_KEY\` in \`cortex.env\`.
-2. Start Cortex and this backend:
-
-    \`\`\`sh
-    docker compose up -d
-    bun run dev
-    \`\`\`
-
-3. Open the console at http://localhost:{{port.cortex}} and sign in with
-   \`DEFAULT_ADMIN_EMAIL\` and \`DEFAULT_ADMIN_PASSWORD\` from \`cortex.env\`.
-4. Register the server. Add a model provider on the **Model providers** page and store
-   \`CORTEX_SERVER_KEY\` from \`.env\` on the **Secrets** page. Then on the **Servers** page, add a
-   server named \`${server}\` at \`${SERVER_URL}/cortex\` with that secret as its key, and pick
-   the model its agents run on.
-5. Apply the manifest. \`cortex login\` asks for a management key: \`BOOTSTRAP_MANAGEMENT_KEY\` from
-   \`cortex.env\`.
-
-    \`\`\`sh
-    bun cortex login --url http://localhost:{{port.cortex}}
-    bun cortex apply
-    \`\`\`
-
-Then chat with \`${AGENT_SLUG}\` on the console's **Playground** page. Edit \`cortex.manifest.ts\` and
-apply again to change it; an apply changes only what the edit changed.
-
-The backend listens on http://localhost:${SERVER_PORT}. Move it in \`index.ts\`, and
+On a fresh clone, run \`bun install\` first (\`cortex new\` already did): it writes \`.env\`.
+
+\`\`\`sh
+bun run dev
+\`\`\`
+
+${gettingStarted}
+
+Then chat with \`${AGENT_SLUG}\` on the console's **Playground** page. Edit \`cortex.manifest.ts\` and run
+\`bun cortex apply\` to change it; an apply changes only what the edit changed. The CLI reaches this
+checkout's Cortex through \`CORTEX_URL\` and \`CORTEX_KEY\` in \`.env\`, so it needs no login, and
+\`-p <profile>\` picks a saved one instead.
+
+\`bun run dev:agent\` runs the same processes without the dashboard, each log line labelled with
+its process, for coding agents and CI.
+
+The backend listens on http://localhost:{{port.server}}. Move it in \`index.ts\`, and
 \`CORTEX_SERVER_URL\` and the server's URL in Cortex with it.
 
 ## Reaching this machine
 
 Cortex's containers reach the backend at \`host.docker.internal\`, which \`EGRESS_ALLOWED_HOSTS\` in
-\`docker-compose.yml\` admits. The policy admits a host by name, not by port, so every HTTP tool, MCP
+\`.env\` admits. The policy admits a host by name, not by port, so every HTTP tool, MCP
 server and credential you define in Cortex can reach any port this machine listens
 on, over plain http. Keep the stack on your own machine, and define only tools you trust.
 
@@ -501,14 +540,14 @@ export function scaffoldFiles(input: Input) {
         "docker-compose.yml": dockerCompose(),
         "package.json": packageJson(project),
         "tsconfig.json": tsconfigJson,
-        ".env.example": BACKEND_ENV,
-        "cortex.env.example": CORTEX_ENV,
+        ".env.example": envExample(project),
+        ...(project.env ? { ".env": withEnvValues(envExample(project), project.env) } : {}),
         ".gitignore": gitignoreText,
         ".dockerignore": dockerignoreText,
         "README.md": readme(project),
         "eslint.config.mjs": eslintConfig,
         "prettier.config.mjs": prettierConfig,
-        "cspell.json": cspellConfig(),
+        "cspell.json": cspellJson,
         ".fallowrc.jsonc": fallowrc,
     } satisfies Record<string, string>;
 

package/src/scaffold/ports.ts

@@ -4,10 +4,9 @@
  *
  * Only the app and the engine are published: the browser and this
  * project's callers reach them, and nothing outside the stack reaches its
- * databases. A fixed pair would collide with the next project scaffolded on
- * the same machine, so each project draws its own. Container ports stay
- * canonical. The backend's own port is not one of these: it is the project's
- * to choose, and stays the documented default.
+ * databases. The backend listens on the third. Fixed ports would collide with
+ * the next project scaffolded on the same machine, so each project draws its
+ * own. Container ports stay canonical.
  *
  * Every generated file spells its ports `{{port.<name>}}` and gets them filled in
  * by `applyPorts`. That is the point of the token: compose and the README
@@ -61,12 +60,12 @@ export function allocatePorts() {
         return port;
     }
 
-    return { cortex: next(), engine: next() };
+    return { cortex: next(), engine: next(), server: next() };
 }
 
 export type Ports = ReturnType<typeof allocatePorts>;
 
-/** Fills in `{{port.cortex}}` and `{{port.engine}}`. Applied to every file, once, at the end. */
+/** Fills in every `{{port.<name>}}`. Applied to every file, once, at the end. */
 export function applyPorts(contents: string, ports: Ports) {
     return Object.entries(ports).reduce(
         (text, [name, port]) => text.replaceAll(`{{port.${name}}}`, String(port)),