@m6d/cortex-cli 0.19.0 → 0.20.0

package/README.md

@@ -38,7 +38,7 @@ Scaffolds `./<name>`: a backend for Cortex agents, and Cortex itself to run them
 - `bun run dev` starts Cortex (`docker compose up`), the backend and `bun cortex setup --wait --yes` in
   an mprocs dashboard. `bun run dev:agent` runs the same through `concurrently`, one labelled log for
   coding agents and CI.
-- eslint, prettier, cspell, fallow and tsconfig are inlined, so `bun run verify` works standalone.
+- oxlint, prettier, cspell, fallow and tsconfig are inlined, so `bun run verify` works standalone.
 
 It then runs `bun install`, and `git init` unless the target is already inside a work tree. An
 existing non-empty directory is an error. So is a name like `cortex` or `cortex.`, since the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.19.0",
+    "version": "0.20.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",
@@ -29,8 +29,8 @@
     },
     "devDependencies": {
         "@cortex/contracts": "workspace:*",
-        "@types/bun": "1.3.14",
-        "typescript": "~6.0.3"
+        "@types/bun": "1.4.4",
+        "typescript": "npm:@typescript/typescript6@^6.0.2"
     },
     "publishConfig": {
         "access": "public"

package/src/contracts/datasets/dataset-sql.ts

@@ -1030,7 +1030,7 @@ class Parser {
     }
 
     /** `a + b * (c - 1)`: `*` and `/` bind before `+` and `-`; a date plus or minus an INTERVAL folds to the date it names. */
-    // eslint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with factor and unit
+    // oxlint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with factor and unit
     private term(message: string): Term {
         let left = this.factor(message);
         while (this.peekPunct("+") || this.peekPunct("-")) {

package/src/contracts/management/index.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import { isRecord } from "../json/index";
+import { TIMEZONE_HEADER } from "../wire/index";
 import { managementProcedureKinds } from "./procedures.generated";
 import type { ManagementProcedures } from "./procedures.generated";
 
@@ -75,10 +76,19 @@ export class ManagementClientError extends Error {
     }
 }
 
-/** Where management calls go: a console's origin and a management key (`cortex_mgmt_…`); a test hands in its own `fetch`. */
+/**
+ * Where management calls go: a console's origin and a management key
+ * (`cortex_mgmt_…`); a test hands in its own `fetch`. `locale` (`ar`) and
+ * `timeZone` (an IANA zone, `Asia/Dubai`) are the caller's, sent as
+ * `Accept-Language` and `X-Cortex-Timezone`: Cortex words its refusals in
+ * the one and reads a day range in the other, else English and UTC days. A
+ * host acting for many users builds a client per request.
+ */
 export type ManagementTarget = {
     url: string;
     key: string;
+    locale?: string;
+    timeZone?: string;
     fetch?: (url: string, init: RequestInit) => Promise<Response>;
 };
 
@@ -100,6 +110,8 @@ export async function callManagement(
         headers: {
             Authorization: `Bearer ${target.key}`,
             ...(method === "post" ? { "Content-Type": "application/json" } : {}),
+            ...(target.locale ? { "Accept-Language": target.locale } : {}),
+            ...(target.timeZone ? { [TIMEZONE_HEADER]: target.timeZone } : {}),
         },
         body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
         signal,

package/src/contracts/management/procedures.generated.ts

@@ -206,10 +206,13 @@ export type StoredSchemaFieldRow = {
 
 /** Whether each procedure is a query (GET) or a mutation (POST). */
 export const managementProcedureKinds = {
+  "agents.addAlias": "mutation",
   "agents.create": "mutation",
   "agents.delete": "mutation",
+  "agents.deleteAlias": "mutation",
   "agents.get": "query",
   "agents.list": "query",
+  "agents.listAliases": "query",
   "agents.options": "query",
   "agents.publishPrompt": "mutation",
   "agents.rollbackPrompt": "mutation",
@@ -298,12 +301,9 @@ export const managementProcedureKinds = {
   "secrets.set": "mutation",
   "servers.create": "mutation",
   "servers.delete": "mutation",
-  "servers.deleteAlias": "mutation",
   "servers.get": "query",
   "servers.list": "query",
-  "servers.listAliases": "query",
   "servers.options": "query",
-  "servers.setAlias": "mutation",
   "servers.sync": "mutation",
   "servers.update": "mutation",
   "services.create": "mutation",
@@ -379,12 +379,25 @@ export const managementProcedureKinds = {
 
 /** Each procedure's input, as it is sent, and output, as JSON carries it. */
 export type ManagementProcedures = {
-  /** Create an agent on a registered server. The draft has no prompt yet; save one with agents.savePrompt before publishing. */
+  /** Give an agent an alias: a second slug it answers to wherever a slug is resolved. Refused (slug_taken) when an agent's slug or another alias holds the name; to move an alias, delete it and add it to the other agent. */
+  "agents.addAlias": {
+    input: {
+      alias: string;
+      agentId: string;
+    };
+    output: {
+      alias: string;
+      agentId: string;
+      createdAt: string;
+      updatedAt: string;
+    };
+  };
+  /** Create an agent on a registered server, or on none (`serverId` null), fixed for good either way. An agent with no server has no native tools, no server variables and no server auth, and publishes only on a chat model of its own. The draft has no prompt yet; save one with agents.savePrompt before publishing. */
   "agents.create": {
     input: {
       slug: string;
       name: string;
-      serverId: string;
+      serverId: string | null;
     };
     output: {
       id: string;
@@ -393,7 +406,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -438,7 +451,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -470,6 +483,18 @@ export type ManagementProcedures = {
       updatedAt: string;
     };
   };
+  /** Remove an alias. */
+  "agents.deleteAlias": {
+    input: {
+      alias: string;
+    };
+    output: {
+      alias: string;
+      agentId: string;
+      createdAt: string;
+      updatedAt: string;
+    };
+  };
   /** One agent by id, including its draft prompt and settings. */
   "agents.get": {
     input: {
@@ -482,7 +507,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -510,7 +535,7 @@ export type ManagementProcedures = {
       summarizationModel: string | null;
       context: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
       limits: string | number | boolean | null | Record<string, unknown> | Array<unknown>;
-      serverName: string;
+      serverName: string | null;
       serverVerifies: boolean;
       variables: Array<{
         name: string;
@@ -547,7 +572,7 @@ export type ManagementProcedures = {
         source: "direct" | "manifest" | "server";
         sourceId: string | null;
         overridable: Array<string>;
-        serverName: string;
+        serverName: string | null;
         published: boolean;
         toolCount: number;
         serviceCount: number;
@@ -560,6 +585,27 @@ export type ManagementProcedures = {
       filteredCount: number;
     };
   };
+  /** List an agent's aliases (second slugs, unique across the deployment beside every agent's own), with pagination. */
+  "agents.listAliases": {
+    input: {
+      pageIndex?: number;
+      pageSize?: number;
+      q?: string;
+      agentId: string;
+    };
+    output: {
+      items: Array<{
+        alias: string;
+        agentId: string;
+        createdAt: string;
+        updatedAt: string;
+      }>;
+      /** Every row the caller may see, ignoring the search and filters. */
+      count: number;
+      /** The rows matching the search and filters, over all pages: the total to report. */
+      filteredCount: number;
+    };
+  };
   /** Agent id, slug, and name pairs for selectors. */
   "agents.options": {
     input: undefined;
@@ -567,7 +613,7 @@ export type ManagementProcedures = {
       id: string;
       slug: string;
       name: string;
-      serverId: string;
+      serverId: string | null;
     }>;
   };
   /** Publish the agent's current draft prompt and settings so Cortex serves them. Refused as `auth_required` while the agent's end-user authentication is unchosen, and as `chat_model_required` when neither the agent nor its server picks a chat model. `warnings` says what the publish went ahead despite: published tools the prompt names without an @-mention (neither pinned nor mentioned by a skill it mentions), which the agent usually cannot see. */
@@ -621,7 +667,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -731,7 +777,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -776,7 +822,7 @@ export type ManagementProcedures = {
       overridable: Array<string>;
       applied: string | number | boolean | null | Record<string, unknown> | Array<unknown> | null;
       slug: string;
-      serverId: string;
+      serverId: string | null;
       name: string;
       promptDraft: string;
       ragEnabled: boolean;
@@ -1633,7 +1679,7 @@ export type ManagementProcedures = {
       agents?: Array<{
         slug: string;
         name: string;
-        server: string;
+        server?: string;
         prompt: string;
         auth: {
           kind: "jwks";
@@ -2158,7 +2204,7 @@ export type ManagementProcedures = {
       agents?: Array<{
         slug: string;
         name: string;
-        server: string;
+        server?: string;
         prompt: string;
         auth: {
           kind: "jwks";
@@ -3117,7 +3163,7 @@ export type ManagementProcedures = {
       outcome: "started" | "awaiting_approval" | "completed" | "failed" | "rejected" | "dropped";
       reason: "busy" | "approval_pending" | "budget" | "rate_limited" | "invalid_payload" | "missing_thread_key" | "no_turn" | "no_output" | "invalid_output" | null;
       output: unknown;
-      serverName: string;
+      serverName: string | null;
       agentSlug: string;
       agentName: string;
       threadTitle: string | null;
@@ -3153,8 +3199,8 @@ export type ManagementProcedures = {
         activeUsers: number;
       };
       perUser: Array<{
-        serverId: string;
-        serverName: string;
+        scopeId: string;
+        scopeName: string;
         userId: string;
         triggerName: string | null;
         threads: number;
@@ -3166,8 +3212,8 @@ export type ManagementProcedures = {
         messages: number;
       }>;
       perServer: Array<{
-        serverId: string;
-        serverName: string;
+        serverId: string | null;
+        serverName: string | null;
         totalTokens: number;
       }>;
       perAgent: Array<{
@@ -3205,7 +3251,7 @@ export type ManagementProcedures = {
         detail: string | null;
         threadId: string;
         createdAt: string;
-        serverName: string;
+        serverName: string | null;
         agentSlug: string;
         agentName: string;
         threadTitle: string | null;
@@ -3387,7 +3433,7 @@ export type ManagementProcedures = {
         outcome: "started" | "awaiting_approval" | "completed" | "failed" | "rejected" | "dropped";
         reason: "busy" | "approval_pending" | "budget" | "rate_limited" | "invalid_payload" | "missing_thread_key" | "no_turn" | "no_output" | "invalid_output" | null;
         output: unknown;
-        serverName: string;
+        serverName: string | null;
         agentSlug: string;
         agentName: string;
         threadTitle: string | null;
@@ -3702,18 +3748,6 @@ export type ManagementProcedures = {
       updatedAt: string;
     };
   };
-  /** Remove an alias. */
-  "servers.deleteAlias": {
-    input: {
-      alias: string;
-    };
-    output: {
-      alias: string;
-      agentId: string;
-      createdAt: string;
-      updatedAt: string;
-    };
-  };
   /** One server by id with its declared variables and the components whose audience is the server. */
   "servers.get": {
     input: {
@@ -3776,27 +3810,6 @@ export type ManagementProcedures = {
       filteredCount: number;
     };
   };
-  /** List the aliases (second slugs, unique across the deployment beside every agent's own) of a server's agents, with pagination. */
-  "servers.listAliases": {
-    input: {
-      pageIndex?: number;
-      pageSize?: number;
-      q?: string;
-      serverId: string;
-    };
-    output: {
-      items: Array<{
-        alias: string;
-        agentId: string;
-        agentName: string;
-        agentSlug: string;
-      }>;
-      /** Every row the caller may see, ignoring the search and filters. */
-      count: number;
-      /** The rows matching the search and filters, over all pages: the total to report. */
-      filteredCount: number;
-    };
-  };
   /** Server id and name pairs for selectors. Cortex's own system server is left out unless `includeSystem` asks for it, as a filter over its threads does. */
   "servers.options": {
     input: {
@@ -3807,17 +3820,6 @@ export type ManagementProcedures = {
       name: string;
     }>;
   };
-  /** Point an alias at an agent, creating it or moving it among the agents of one server. Refused (slug_taken) when an agent goes by the name or it is an alias of another server's agent. */
-  "servers.setAlias": {
-    input: {
-      alias: string;
-      agentId: string;
-    };
-    output: {
-      alias: string;
-      agentId: string;
-    };
-  };
   /** Read the server's manifest now and apply its variables and native tools; a refused manifest leaves the previous one in place. */
   "servers.sync": {
     input: {
@@ -4361,8 +4363,8 @@ export type ManagementProcedures = {
       triggerName: string | null;
       createdAt: string;
       updatedAt: string;
-      serverId: string;
-      serverName: string;
+      serverId: string | null;
+      serverName: string | null;
       agentSlug: string;
       agentId: string;
       agentName: string;
@@ -4400,8 +4402,8 @@ export type ManagementProcedures = {
         triggerName: string | null;
         createdAt: string;
         updatedAt: string;
-        serverId: string;
-        serverName: string;
+        serverId: string | null;
+        serverName: string | null;
         agentSlug: string;
       }>;
       /** Every row the caller may see, ignoring the search and filters. */

package/src/contracts/manifest/index.ts

@@ -1500,55 +1500,77 @@ export const agentSettingsSchema = z.strictObject({
 /** An agent's name in characters. The console caps its editor at the same. */
 export const AGENT_LIMITS = { nameLength: 120 } as const;
 
-const manifestAgentSchema = z.strictObject({
-    slug: agentSlugSchema,
-    name: z.string().trim().min(1).max(AGENT_LIMITS.nameLength),
-    /** The server it belongs to, by name; a manifest never creates one. */
-    server: nameSchema,
-    /** Rich text: it may mention tools and skills, and read `{{variables}}`. */
-    prompt: z.string().trim().min(1),
-    auth: agentAuthSchema,
-    /**
-     * `chat` left out runs on the server's pick; `vision` and
-     * `summarization` left out use none of their own.
-     */
-    models: z
-        .strictObject({
-            chat: modelSchema.optional(),
-            vision: modelSchema.omit({ effort: true }).optional(),
-            summarization: modelSchema.omit({ effort: true }).optional(),
-        })
-        .default({}),
-    settings: agentSettingsSchema.prefault({}),
-    /** Messages a minute and model tokens a UTC day, for all users together and for each; null, no limit. */
-    rateLimits: z
-        .strictObject({
-            allUsers: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
-                })
-                .prefault({}),
-            perUser: z
-                .strictObject({
-                    messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
-                    tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
-                })
-                .prefault({}),
-        })
-        .prefault({}),
-    suggestions: suggestionsSchema.default(() => byLocale(() => [])),
-    greeting: greetingSchema.default(() => byLocale(() => "")),
-    overridable: overridable([
-        "name",
-        "prompt",
-        "models",
-        "settings",
-        "rateLimits",
-        "suggestions",
-        "greeting",
-    ]),
-});
+const manifestAgentSchema = z
+    .strictObject({
+        slug: agentSlugSchema,
+        name: z.string().trim().min(1).max(AGENT_LIMITS.nameLength),
+        /**
+         * The server it belongs to, by name; a manifest never creates one. Left
+         * out, the agent has no server: no native tools, no server variables,
+         * no `server` auth, and no model to inherit, so it names its own `chat`.
+         */
+        server: nameSchema.optional(),
+        /** Rich text: it may mention tools and skills, and read `{{variables}}`. */
+        prompt: z.string().trim().min(1),
+        auth: agentAuthSchema,
+        /**
+         * `chat` left out runs on the server's pick; `vision` and
+         * `summarization` left out use none of their own.
+         */
+        models: z
+            .strictObject({
+                chat: modelSchema.optional(),
+                vision: modelSchema.omit({ effort: true }).optional(),
+                summarization: modelSchema.omit({ effort: true }).optional(),
+            })
+            .default({}),
+        settings: agentSettingsSchema.prefault({}),
+        /** Messages a minute and model tokens a UTC day, for all users together and for each; null, no limit. */
+        rateLimits: z
+            .strictObject({
+                allUsers: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "allUsers"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "allUsers"),
+                    })
+                    .prefault({}),
+                perUser: z
+                    .strictObject({
+                        messagesPerMinute: rateLimit(agentRateLimits.messagesPerMinute, "perUser"),
+                        tokensPerDay: rateLimit(agentRateLimits.tokensPerDay, "perUser"),
+                    })
+                    .prefault({}),
+            })
+            .prefault({}),
+        suggestions: suggestionsSchema.default(() => byLocale(() => [])),
+        greeting: greetingSchema.default(() => byLocale(() => "")),
+        overridable: overridable([
+            "name",
+            "prompt",
+            "models",
+            "settings",
+            "rateLimits",
+            "suggestions",
+            "greeting",
+        ]),
+    })
+    .superRefine((agent, context) => {
+        if (agent.server !== undefined) return;
+        if (agent.auth.kind === "server") {
+            context.addIssue({
+                code: "custom",
+                path: ["auth"],
+                message: "server auth needs a server",
+            });
+        }
+        if (agent.models.chat === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: ["models", "chat"],
+                message: "an agent with no server names its own chat model",
+            });
+        }
+    });
 export type ManifestAgent = z.input<typeof manifestAgentSchema>;
 
 /**

package/src/management/client.ts

@@ -166,6 +166,8 @@ export function inputSchemaOf(operation: OpenApiOperation) {
 export function managementTarget(profile: { url: string; key: string }) {
     return {
         ...profile,
+        // Every day range a command takes is this machine's days.
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
         fetch: (url: string, init: RequestInit) =>
             fetch(url, init).catch((error: unknown) => {
                 throw new UnreachableError(error);

package/src/scaffold/files.ts

@@ -2,9 +2,10 @@
  * 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
  * project 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.
+ * pulled from `@m6d/prettier-config`, `@m6d/tsconfig` and the root
+ * `.oxlintrc.json`: those are `private: true` at `0.0.0` (the lint config
+ * loads `@m6d/oxlint-plugin`) and resolvable only through this workspace, and
+ * a standalone scaffold has no workspace.
  */
 
 import { NAME_MAX_LENGTH } from "@cortex/contracts/manifest";
@@ -16,11 +17,11 @@ import datasetsTs from "@/scaffold/templates/datasets.ts.txt";
 import tsconfigJson from "@/scaffold/templates/tsconfig.json.txt";
 import gitignoreText from "@/scaffold/templates/gitignore.txt";
 import dockerignoreText from "@/scaffold/templates/dockerignore.txt";
-import eslintConfig from "@/scaffold/templates/eslint.config.mjs.txt";
+import oxlintrc from "@/scaffold/templates/oxlintrc.json.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.
+// Project jargon is the project's to add. Only the tool names its own
+// package.json carries are 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";
 
@@ -29,7 +30,7 @@ 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.18.0";
+const CORTEX_VERSION = "0.19.0";
 
 /** 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";
@@ -54,18 +55,16 @@ export const EMBEDDING = { model: "text-embedding-3-small", dimension: 768 } as
 const DEV_DEPENDENCIES = {
     // `cortex apply`, `cortex setup` and the management commands, at the release that wrote the project.
     "@m6d/cortex-cli": `~${pkg.version}`,
-    "@types/bun": "1.3.14",
+    "@types/bun": "1.4.4",
     // 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",
+    oxlint: "^1.90.0",
+    "oxlint-tsgolint": "^7.0.2005",
     prettier: "^3.8.1",
-    typescript: "~6.0.3",
-    "typescript-eslint": "^8.65.0",
+    typescript: "^7.0.2",
 };
 
 /**
@@ -145,12 +144,12 @@ function packageJson({ name, datasets, setup }: Project) {
                 postinstall: "bun run --if-present setup.ts",
                 format: "prettier --write .",
                 "format:check": "prettier --check .",
-                lint: "eslint",
+                lint: "oxlint",
                 spellcheck: 'cspell "**/*.{ts,mjs,json,md}"',
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.6.0",
+                "@m6d/cortex": "~0.7.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",
@@ -249,9 +248,11 @@ COMPOSE_PROJECT_NAME=
 DEFAULT_ADMIN_EMAIL=admin@example.com
 DEFAULT_ADMIN_PASSWORD=
 BOOTSTRAP_MANAGEMENT_KEY=
-# Session signing, and the key the secrets store is encrypted with.
+# Session signing, the key the secrets store is encrypted with, and object
+# storage's password (storage is published on this machine for uploads).
 BETTER_AUTH_SECRET=
 SECRETS_MASTER_KEY=
+S3_SECRET_ACCESS_KEY=
 # Any OpenAI-compatible embeddings endpoint and model. Tool search and
 # knowledge collections embed with it, and stay off while the key is blank.
 EMBEDDING_BASE_URL=https://api.openai.com/v1
@@ -288,17 +289,14 @@ MODEL_PROVIDER_MODEL=
 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. \`bun run dev\`
-# starts it; .env holds its secrets.
+# http://localhost:{{port.engine}}, storage the console uploads to at
+# http://localhost:{{port.storage}}, and the stores they keep state in.
+# \`bun run dev\` starts it; .env holds its secrets.
 #
 # 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
-# S3_ENDPOINT, which only this stack resolves. Point it at storage the
-# browser reaches too before relying on them.
 
 # The stack runs as .env's COMPOSE_PROJECT_NAME, drawn for each checkout by
 # setup.ts, so no two checkouts share containers or volumes, whatever their
@@ -316,9 +314,13 @@ x-cortex: &cortex
         DATABASE_URL: postgres://postgres:postgres@postgres:5432/cortex
         REDIS_URL: redis://redis:6379
         S3_ENDPOINT: http://minio:9000
+        # The console's uploads go straight to storage, from the browser.
+        S3_PUBLIC_ENDPOINT: http://localhost:{{port.storage}}
         S3_REGION: us-east-1
         S3_ACCESS_KEY_ID: minio
-        S3_SECRET_ACCESS_KEY: minio-secret-key
+        # Interpolated like storage's own, so both read the one value even when the
+        # shell exports another.
+        S3_SECRET_ACCESS_KEY: \${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}
         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.
@@ -366,9 +368,13 @@ services:
         command: server /data
         environment:
             MINIO_ROOT_USER: minio
-            MINIO_ROOT_PASSWORD: minio-secret-key
+            MINIO_ROOT_PASSWORD: \${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}
+            # The console's uploads come from its origin alone.
+            MINIO_API_CORS_ALLOW_ORIGIN: http://localhost:{{port.cortex}},http://127.0.0.1:{{port.cortex}}
         volumes:
             - minio-data:/data
+        ports:
+            - "127.0.0.1:{{port.storage}}:9000"
         healthcheck:
             test: ["CMD", "bash", "-c", "</dev/tcp/127.0.0.1/9000"]
             interval: 5s
@@ -381,7 +387,7 @@ services:
             minio:
                 condition: service_healthy
         environment:
-            MC_HOST_local: http://minio:minio-secret-key@minio:9000
+            MC_HOST_local: http://minio:\${S3_SECRET_ACCESS_KEY:?run bun install to generate .env}@minio:9000
         command: ["mb", "--ignore-existing", "local/cortex"]
 
     # One-shot: migrate the database, then create the first admin and its key.
@@ -547,7 +553,7 @@ export function scaffoldFiles(input: Input) {
         ".gitignore": gitignoreText,
         ".dockerignore": dockerignoreText,
         "README.md": readme(project),
-        "eslint.config.mjs": eslintConfig,
+        ".oxlintrc.json": oxlintrc,
         "prettier.config.mjs": prettierConfig,
         "cspell.json": cspellJson,
         ".fallowrc.jsonc": fallowrc,

package/src/scaffold/ports.ts

@@ -2,9 +2,10 @@
  * Host ports for the Cortex stack a generated project runs, chosen once at
  * scaffold time.
  *
- * 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. The backend listens on the third. Fixed ports would collide with
+ * The app, the engine and storage are published: the browser and this
+ * project's callers reach them (storage through the upload links Cortex
+ * signs), and nothing outside the stack reaches its databases. The backend
+ * listens on the fourth. Fixed ports would collide with
  * the next project scaffolded on the same machine, so each project draws its
  * own. Container ports stay canonical.
  *
@@ -60,7 +61,7 @@ export function allocatePorts() {
         return port;
     }
 
-    return { cortex: next(), engine: next(), server: next() };
+    return { cortex: next(), engine: next(), storage: next(), server: next() };
 }
 
 export type Ports = ReturnType<typeof allocatePorts>;

package/src/scaffold/templates/cspell.json.txt

@@ -1,7 +1,7 @@
 {
     "version": "0.2",
     "language": "en",
-    "words": ["mprocs"],
+    "words": ["mprocs", "oxlint", "tsgolint"],
     "ignorePaths": [
         "node_modules/**",
         "out/**",

package/src/scaffold/templates/oxlintrc.json.txt

@@ -0,0 +1,67 @@
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    // typescript-eslint's recommended type-checked set; nothing else runs.
+    "categories": {
+        "correctness": "off"
+    },
+    "options": {
+        "typeAware": true,
+        "reportUnusedDisableDirectives": "warn"
+    },
+    "ignorePatterns": ["**/node_modules/**", "**/dist/**", "**/.fallow/**"],
+    "overrides": [
+        {
+            "files": ["**/*.ts"],
+            "plugins": ["typescript"],
+            "rules": {
+                "no-var": "error",
+                "prefer-const": "error",
+                "prefer-rest-params": "error",
+                "prefer-spread": "error",
+                "no-array-constructor": "error",
+                "no-unused-expressions": "error",
+                "no-unused-vars": "error",
+                "typescript/await-thenable": "error",
+                "typescript/ban-ts-comment": "error",
+                "typescript/no-array-delete": "error",
+                "typescript/no-base-to-string": "error",
+                "typescript/no-duplicate-enum-values": "error",
+                "typescript/no-duplicate-type-constituents": "error",
+                "typescript/no-empty-object-type": "error",
+                "typescript/no-explicit-any": "error",
+                "typescript/no-extra-non-null-assertion": "error",
+                "typescript/no-floating-promises": "error",
+                "typescript/no-for-in-array": "error",
+                "typescript/no-implied-eval": "error",
+                "typescript/no-misused-new": "error",
+                "typescript/no-misused-promises": "error",
+                "typescript/no-namespace": "error",
+                "typescript/no-non-null-asserted-optional-chain": "error",
+                "typescript/no-redundant-type-constituents": "error",
+                "typescript/no-require-imports": "error",
+                "typescript/no-this-alias": "error",
+                "typescript/no-unnecessary-type-assertion": "error",
+                "typescript/no-unnecessary-type-constraint": "error",
+                "typescript/no-unsafe-argument": "error",
+                "typescript/no-unsafe-assignment": "error",
+                "typescript/no-unsafe-call": "error",
+                "typescript/no-unsafe-declaration-merging": "error",
+                "typescript/no-unsafe-enum-comparison": "error",
+                "typescript/no-unsafe-function-type": "error",
+                "typescript/no-unsafe-member-access": "error",
+                "typescript/no-unsafe-return": "error",
+                "typescript/no-unsafe-unary-minus": "error",
+                "typescript/no-wrapper-object-types": "error",
+                "typescript/only-throw-error": "error",
+                "typescript/prefer-as-const": "error",
+                "typescript/prefer-namespace-keyword": "error",
+                "typescript/prefer-promise-reject-errors": "error",
+                "typescript/require-await": "error",
+                "typescript/restrict-plus-operands": "error",
+                "typescript/restrict-template-expressions": "error",
+                "typescript/triple-slash-reference": "error",
+                "typescript/unbound-method": "error"
+            }
+        }
+    ]
+}

package/src/scaffold/templates/setup.ts.txt

@@ -30,6 +30,7 @@ const GENERATED = [
     ["BOOTSTRAP_MANAGEMENT_KEY", () => `cortex_mgmt_${token()}`],
     ["BETTER_AUTH_SECRET", key],
     ["SECRETS_MASTER_KEY", key],
+    ["S3_SECRET_ACCESS_KEY", token],
 ] as const;
 
 const source = existsSync(".env") ? ".env" : ".env.example";

package/src/scaffold/templates/eslint.config.mjs.txt

@@ -1,20 +0,0 @@
-import { defineConfig, globalIgnores } from "eslint/config";
-import prettierConfig from "eslint-config-prettier";
-import prettierPlugin from "eslint-plugin-prettier";
-import tseslint from "typescript-eslint";
-
-export default defineConfig([
-    globalIgnores(["**/node_modules/**", "**/dist/**", "**/.fallow/**"]),
-    prettierConfig,
-    {
-        plugins: { prettier: prettierPlugin },
-        rules: { "prettier/prettier": "error" },
-    },
-    {
-        files: ["**/*.ts"],
-        extends: [tseslint.configs.recommendedTypeChecked],
-        languageOptions: {
-            parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
-        },
-    },
-]);