@m6d/cortex-cli 0.20.0 → 0.21.0

package/src/contracts/manifest/index.ts

@@ -2,10 +2,11 @@ import { z } from "zod";
 import { datasetIdentifierSchema } from "../datasets/index";
 import { canCarrySecret } from "../egress-policy/index";
 import {
-    agentSlugSchema,
+    displayNameSchema,
     EVENT_HEADER,
     identifierSchema,
     localeSchema,
+    nameSchema,
     SERVER_EVENTS,
     refuseBlockedApprovalTitle,
     serverToolSchema,
@@ -25,7 +26,7 @@ import {
  * A manifest: the agents and components a code-first deployment declares,
  * written by hand (`cortex.manifest.ts` or JSON) and applied in one
  * transaction. Everything it points at, it names: a server, a model
- * provider, a service by its key, an agent by its slug, and a stored secret
+ * provider, a service, an agent, and a stored secret
  * or credential by the noun of what it names (`secret: "signing-key"`,
  * `credential: "petstore"`). A tool input field's `x-source` is the one
  * exception: `inputSchema` is the JSON Schema the tool stores, verbatim, so
@@ -187,11 +188,6 @@ function overridable<const TField extends string>(fields: readonly [TField, ...T
         .default([]);
 }
 
-/** Consumer-facing slugs: the manifest id, service keys, skill names and trigger names share it. */
-export const SLUG_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-export const SLUG_MAX_LENGTH = 64;
-const slugSchema = z.string().regex(SLUG_PATTERN).max(SLUG_MAX_LENGTH);
-
 /** A DNS host name in lower case, the way `URL` reports one: dot-separated labels of letters, digits and inner hyphens. */
 export const HOSTNAME_PATTERN =
     /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/;
@@ -477,11 +473,6 @@ function repeatedHeaders(entries: ReadonlyArray<{ header: string }>) {
     });
 }
 
-/** The longest name Cortex holds a server, model provider, credential or secret under. */
-export const NAME_MAX_LENGTH = 120;
-/** A server, model provider, credential or secret, by the name Cortex holds it under. */
-const nameSchema = z.string().trim().min(1).max(NAME_MAX_LENGTH);
-
 const presentedHeaderSchema = headerNameSchema.refine(
     (name) => !transportOwnedHeaders.has(name.toLowerCase()),
     "a header the transport sets",
@@ -518,7 +509,10 @@ const variableSourceSchema = z.object({
 });
 
 /** A credential Cortex holds or acquires, by name. */
-const credentialSourceSchema = z.object({ kind: z.literal("credential"), name: nameSchema });
+const credentialSourceSchema = z.object({
+    kind: z.literal("credential"),
+    name: nameSchema,
+});
 
 /** A value written as is. */
 const constantHeaderSourceSchema = z.object({
@@ -883,15 +877,15 @@ const objectSchema = objectJsonSchemaOf();
 
 const EMPTY_OBJECT = { type: "object" } as const satisfies z.input<typeof objectSchema>;
 
-/** Who a component reaches: every agent, every agent on one server, or the agents listed by slug. */
+/** Who a component reaches: every agent, every agent on one server, or the agents listed by name. */
 const audienceSchema = z.union([
     z.literal("all"),
     z.strictObject({ server: nameSchema }),
     z.strictObject({
         agents: z
-            .array(agentSlugSchema)
+            .array(nameSchema)
             .min(1)
-            .refine((slugs) => new Set(slugs).size === slugs.length, "an agent repeats"),
+            .refine((names) => new Set(names).size === names.length, "an agent repeats"),
     }),
 ]);
 
@@ -905,14 +899,9 @@ const modelSchema = z.strictObject({
     effort: z.string().trim().min(1).max(64).optional(),
 });
 
-/** A service's name and description, in characters per locale. The console caps its editor at the same lengths. */
-export const SERVICE_LIMITS = { nameLength: 120, descriptionLength: 4_000 } as const;
+/** A service's description, in characters per locale. The console caps its editor at the same length. */
+export const SERVICE_LIMITS = { descriptionLength: 4_000 } as const;
 
-/** One line per locale, trimmed. */
-const localizedLineSchema = z.record(
-    localeSchema,
-    z.string().trim().min(1).max(SERVICE_LIMITS.nameLength),
-);
 const localizedTextSchema = z.record(
     localeSchema,
     z.string().trim().min(1).max(SERVICE_LIMITS.descriptionLength),
@@ -932,6 +921,7 @@ function toolInputSchemaOf(type: (typeof TOOL_TYPE_NAMES)[number]) {
 
 /** What a live write may change on a manifest's tool, and keep through the next apply. */
 const TOOL_OVERRIDABLES = [
+    "displayName",
     "description",
     "timeoutMs",
     "maxResponseBytes",
@@ -946,6 +936,7 @@ const CALLED_TOOL_OVERRIDABLES = [...TOOL_OVERRIDABLES, "headers"] as const;
 /** Shared by every tool type; a tool that calls nothing (`client`) has no endpoint, headers, approval or bound fields. */
 const toolBaseSchema = z.strictObject({
     ...serverToolSchema.pick({ name: true, description: true }).shape,
+    displayName: displayNameSchema.default({}),
     inputSchema: toolInputSchemaOf("client"),
     outputSchema: objectSchema.default(EMPTY_OBJECT),
     timeoutMs: setting(toolBounds.timeoutMs),
@@ -1050,15 +1041,15 @@ const manifestOpenApiSchema = z.strictObject({
 });
 export type ManifestOpenApi = z.input<typeof manifestOpenApiSchema>;
 
-/** Identified by its `key`, which skills and collections scope themselves by; `name` is its label. */
+/** Skills and collections scope themselves by a service's `name`. */
 const manifestServiceSchema = z.strictObject({
-    /** What consumers parameterize their tools with; fixed once published. */
-    key: slugSchema,
-    name: localizedLineSchema,
+    /** What consumers parameterize their tools with. */
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     /** Rich text: it may mention tools and skills. */
     description: localizedTextSchema,
     audience: audienceSchema,
-    overridable: overridable(["description"]),
+    overridable: overridable(["displayName", "description"]),
 });
 export type ManifestService = z.input<typeof manifestServiceSchema>;
 
@@ -1066,14 +1057,15 @@ export type ManifestService = z.input<typeof manifestServiceSchema>;
 export const SKILL_LIMITS = { descriptionLength: 500 } as const;
 
 const manifestSkillSchema = z.strictObject({
-    name: slugSchema,
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().min(1).max(SKILL_LIMITS.descriptionLength),
     /** Rich text: it may mention tools, skills and datasets, and read `{{variables}}`. */
     body: z.string().trim().min(1),
-    /** The key of the service the skill renders inside; fixed once created. */
-    service: slugSchema.optional(),
+    /** The name of the service the skill renders inside; fixed once created. */
+    service: nameSchema.optional(),
     audience: audienceSchema,
-    overridable: overridable(["description", "body"]),
+    overridable: overridable(["displayName", "description", "body"]),
 });
 export type ManifestSkill = z.input<typeof manifestSkillSchema>;
 
@@ -1100,7 +1092,8 @@ export const TRIGGER_LIMITS = { descriptionLength: 500, instructionsLength: 20_0
 /** Fired with its secret, which the apply that creates it answers once and no manifest holds. */
 const manifestTriggerSchema = z.strictObject({
     /** `message` is the built-in trigger every agent has. */
-    name: slugSchema.refine((name) => name !== MESSAGE_TRIGGER_NAME, "the built-in trigger's name"),
+    name: nameSchema.refine((name) => name !== MESSAGE_TRIGGER_NAME, "the built-in trigger's name"),
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().min(1).max(TRIGGER_LIMITS.descriptionLength),
     inputSchema: objectSchema.default(EMPTY_OBJECT),
     /** The shape the run answers in; absent, the run answers in free text. */
@@ -1125,6 +1118,7 @@ const manifestTriggerSchema = z.strictObject({
     model: modelSchema.optional(),
     audience: audienceSchema,
     overridable: overridable([
+        "displayName",
         "description",
         "instructions",
         "threadPolicy",
@@ -1147,6 +1141,7 @@ export function unexposedPins(host: {
 const manifestDatasetHostSchema = z
     .strictObject({
         name: datasetIdentifierSchema,
+        displayName: displayNameSchema.default({}),
         url: upstreamUrlSchema,
         headers: headersSchema,
         timeoutMs: setting(SETTING_BOUNDS.datasetHost.timeoutMs),
@@ -1175,7 +1170,7 @@ const manifestDatasetHostSchema = z
         /** Among those, the ones listed in every turn, whatever the question. */
         pinned: z.array(datasetIdentifierSchema).max(50).default([]),
         audience: audienceSchema,
-        overridable: overridable(["timeoutMs", "rateLimits", "headers"]),
+        overridable: overridable(["displayName", "timeoutMs", "rateLimits", "headers"]),
     })
     .superRefine((host, context) => {
         const unexposed = unexposedPins(host);
@@ -1204,6 +1199,7 @@ export const mcpToolNamesSchema = z
 const manifestMcpServerSchema = z.strictObject({
     /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
     name: identifierSchema,
+    displayName: displayNameSchema.default({}),
     url: upstreamUrlSchema,
     headers: declaredHeadersSchema(
         presentedHeaderSchema.refine(
@@ -1216,7 +1212,7 @@ const manifestMcpServerSchema = z.strictObject({
     include: mcpToolNamesSchema.default([]),
     exclude: mcpToolNamesSchema.default([]),
     audience: audienceSchema,
-    overridable: overridable(["include", "exclude", "headers"]),
+    overridable: overridable(["displayName", "include", "exclude", "headers"]),
 });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
@@ -1226,7 +1222,8 @@ export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
  * travels under the header that names the event.
  */
 const manifestWebhookSchema = z.strictObject({
-    name: slugSchema,
+    name: nameSchema,
+    displayName: displayNameSchema.default({}),
     description: z.string().trim().max(500).default(""),
     event: z.enum(SERVER_EVENTS),
     url: upstreamUrlSchema,
@@ -1239,19 +1236,15 @@ const manifestWebhookSchema = z.strictObject({
     ),
     timeoutMs: setting(SETTING_BOUNDS.webhook.timeoutMs),
     audience: audienceSchema,
-    overridable: overridable(["description", "timeoutMs", "headers"]),
+    overridable: overridable(["displayName", "description", "timeoutMs", "headers"]),
 });
 export type ManifestWebhook = z.input<typeof manifestWebhookSchema>;
 
 /**
- * A collection's name and description in characters, and how many documents
- * a manifest lists in one. The console caps its editor at the same.
+ * A collection's description in characters, and how many documents a
+ * manifest lists in one. The console caps its editor at the same.
  */
-export const COLLECTION_LIMITS = {
-    nameLength: 80,
-    descriptionLength: 2_000,
-    documents: 100,
-} as const;
+export const COLLECTION_LIMITS = { descriptionLength: 2_000, documents: 100 } as const;
 
 /** A knowledge document's name in characters and its size in bytes, however it arrives. */
 export const DOCUMENT_LIMITS = { nameLength: 255, bytes: 10 * 1024 * 1024 } as const;
@@ -1377,15 +1370,16 @@ function collectionSchema<TDocument extends z.ZodType<Parameters<typeof document
     document: TDocument,
 ) {
     return z.strictObject({
-        name: z.string().trim().min(1).max(COLLECTION_LIMITS.nameLength),
+        name: nameSchema,
+        displayName: displayNameSchema.default({}),
         description: z.string().trim().max(COLLECTION_LIMITS.descriptionLength).default(""),
-        /** The key of the service every document in the collection belongs to. */
-        service: slugSchema.optional(),
+        /** The name of the service every document in the collection belongs to. */
+        service: nameSchema.optional(),
         /** Whether answers may name its documents; false keeps their names, sections and pages from the model. */
         citable: z.boolean().default(true),
         documents: documentsSchema(document),
         audience: audienceSchema,
-        overridable: overridable(["description", "documents"]),
+        overridable: overridable(["displayName", "description", "documents"]),
     });
 }
 
@@ -1497,13 +1491,10 @@ export const agentSettingsSchema = z.strictObject({
         .prefault({}),
 });
 
-/** 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),
+        name: nameSchema,
+        displayName: displayNameSchema.default({}),
         /**
          * 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,
@@ -1545,7 +1536,7 @@ const manifestAgentSchema = z
         suggestions: suggestionsSchema.default(() => byLocale(() => [])),
         greeting: greetingSchema.default(() => byLocale(() => "")),
         overridable: overridable([
-            "name",
+            "displayName",
             "prompt",
             "models",
             "settings",
@@ -1592,31 +1583,14 @@ export const MANIFEST_KINDS = [
 export type ManifestKind = (typeof MANIFEST_KINDS)[number];
 
 /**
- * The field each kind's entries go by, which its row's name holds: an
- * agent's slug, a service's key, any other entry's name. A list holds each
- * once, so one entry means one row.
+ * A list of entries, each going by the name its row holds, refusing a name
+ * they repeat: one entry means one row.
  */
-export const MANIFEST_NAME_FIELDS = {
-    agents: "slug",
-    tools: "name",
-    services: "key",
-    skills: "name",
-    triggers: "name",
-    datasetHosts: "name",
-    mcpServers: "name",
-    webhooks: "name",
-    collections: "name",
-} as const satisfies Record<ManifestKind, string>;
-
-/** A list of entries named by their `field`, refusing a name they repeat. */
-function listOf<TField extends string, TEntry extends z.ZodType<Record<TField, string>>>(
-    field: TField,
-    entry: TEntry,
-) {
+function listOf<TEntry extends z.ZodType<{ name: string }>>(entry: TEntry) {
     return z
         .array(entry)
         .refine(
-            (entries) => new Set(entries.map((value) => value[field])).size === entries.length,
+            (entries) => new Set(entries.map((value) => value.name)).size === entries.length,
             "a name repeats",
         )
         .default([]);
@@ -1634,17 +1608,17 @@ export const CORTEX_MANIFEST_ID = "cortex";
  */
 export const manifestSchema = z.strictObject({
     /** Fixed for the deployment it describes: the rows an apply owns carry it. */
-    id: slugSchema,
-    agents: listOf(MANIFEST_NAME_FIELDS.agents, manifestAgentSchema),
-    tools: listOf(MANIFEST_NAME_FIELDS.tools, manifestToolSchema),
-    openapi: listOf("name", manifestOpenApiSchema),
-    services: listOf(MANIFEST_NAME_FIELDS.services, manifestServiceSchema),
-    skills: listOf(MANIFEST_NAME_FIELDS.skills, manifestSkillSchema),
-    triggers: listOf(MANIFEST_NAME_FIELDS.triggers, manifestTriggerSchema),
-    datasetHosts: listOf(MANIFEST_NAME_FIELDS.datasetHosts, manifestDatasetHostSchema),
-    mcpServers: listOf(MANIFEST_NAME_FIELDS.mcpServers, manifestMcpServerSchema),
-    webhooks: listOf(MANIFEST_NAME_FIELDS.webhooks, manifestWebhookSchema),
-    collections: listOf(MANIFEST_NAME_FIELDS.collections, manifestCollectionSchema),
+    id: nameSchema,
+    agents: listOf(manifestAgentSchema),
+    tools: listOf(manifestToolSchema),
+    openapi: listOf(manifestOpenApiSchema),
+    services: listOf(manifestServiceSchema),
+    skills: listOf(manifestSkillSchema),
+    triggers: listOf(manifestTriggerSchema),
+    datasetHosts: listOf(manifestDatasetHostSchema),
+    mcpServers: listOf(manifestMcpServerSchema),
+    webhooks: listOf(manifestWebhookSchema),
+    collections: listOf(manifestCollectionSchema),
 } satisfies Record<ManifestKind | "id" | "openapi", z.ZodType>);
 /** A manifest as written: every field with a default may be left out. */
 export type Manifest = z.input<typeof manifestSchema>;
@@ -1655,15 +1629,12 @@ export type Manifest = z.input<typeof manifestSchema>;
  * beside it.
  */
 export const resolvedManifestSchema = manifestSchema.extend({
-    collections: listOf(MANIFEST_NAME_FIELDS.collections, resolvedCollectionSchema),
+    collections: listOf(resolvedCollectionSchema),
 });
 
 const manifestKindSchema = z.enum(MANIFEST_KINDS);
 
-/**
- * Entry names per kind, each by its `MANIFEST_NAME_FIELDS` field. An OpenAPI
- * source's operations are counted among `tools`.
- */
+/** Entry names per kind. An OpenAPI source's operations are counted among `tools`. */
 const namesByKindSchema = z.record(manifestKindSchema, z.array(z.string()));
 
 /** What an apply creates, updates and deletes, kind by kind; a preview answers the same without doing it. */

package/src/contracts/server/index.ts

@@ -18,10 +18,6 @@ import { APPROVAL_TITLE_FIELD, LOCALES } from "../wire/index";
 /** The run's end-user token, which Cortex forwards verbatim to a tool's backend, a dataset host or the agent's server. */
 export const END_USER_TOKEN_HEADER = "X-End-User-Token";
 
-/** The agent slug Cortex's routes name an agent by. */
-export const AGENT_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
-export const agentSlugSchema = z.string().regex(AGENT_SLUG_PATTERN);
-
 /** The longest end-user id Cortex stores. */
 export const USER_ID_MAX_LENGTH = 255;
 
@@ -40,9 +36,35 @@ export const IDENTIFIER_MAX_LENGTH = 64;
 
 export const identifierSchema = z.string().regex(IDENTIFIER_PATTERN).max(IDENTIFIER_MAX_LENGTH);
 
+/**
+ * A kebab name: lowercase letters and digits in words joined by single
+ * hyphens. What the manifest id and every name Cortex holds must be, save a
+ * tool's, an MCP server's and a dataset host's, and what its routes name an
+ * agent by.
+ */
+export const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** The longest kebab name Cortex stores. */
+export const NAME_MAX_LENGTH = 64;
+
+export const nameSchema = z.string().regex(NAME_PATTERN).max(NAME_MAX_LENGTH);
+
 /** A localized value's key. */
 export const localeSchema = z.enum(LOCALES);
 
+/** The longest display name Cortex stores, in any locale. */
+export const DISPLAY_NAME_MAX_LENGTH = 120;
+
+/**
+ * What a console shows an entity as, per locale; a locale without one falls
+ * back as `localized` says, and an entity with none goes by its name. Each
+ * value is trimmed, and a blank one is dropped as absent.
+ */
+export const displayNameSchema = z
+    .partialRecord(localeSchema, z.string().trim().max(DISPLAY_NAME_MAX_LENGTH))
+    .transform((value) => Object.fromEntries(Object.entries(value).filter(([, text]) => text)))
+    .pipe(z.partialRecord(localeSchema, z.string()));
+
 /** How many variables and tools a server's manifest declares at most, and how long each of their texts runs. */
 export const SERVER_MANIFEST_LIMITS = {
     variables: 100,
@@ -146,12 +168,14 @@ export type ServerVariable = z.infer<typeof serverVariableSchema>;
 
 /**
  * A tool the server runs. Its input is an object, the `input` its calls
- * carry. `requiresApproval` parks every call for the end user's approval;
- * such a tool's input cannot declare `APPROVAL_TITLE_FIELD`, which the
- * model fills for the approval card.
+ * carry. `displayName` is what the console shows it as; the model only ever
+ * sees its name. `requiresApproval` parks every call for the end user's
+ * approval; such a tool's input cannot declare `APPROVAL_TITLE_FIELD`, which
+ * the model fills for the approval card.
  */
 export const serverToolSchema = z.object({
     name: declaredToolNameSchema,
+    displayName: displayNameSchema.optional(),
     description: z.string().trim().min(1).max(SERVER_MANIFEST_LIMITS.description),
     inputSchema: jsonSchemaSchema.refine(
         (schema) => schema.type === "object",
@@ -179,7 +203,7 @@ export const EVENT_HEADER = "X-Cortex-Event";
  */
 export const approvalRequestedEventSchema = z.object({
     event: z.literal("approval_requested"),
-    agentSlug: agentSlugSchema,
+    agentName: nameSchema,
     agentId: z.uuid(),
     threadId: z.string(),
     runId: z.string(),
@@ -285,7 +309,7 @@ export const serverManifestSchema = z.object({
 export type ServerManifest = z.infer<typeof serverManifestSchema>;
 
 /** The agent a call is for. */
-const agentSchema = z.object({ id: z.uuid(), slug: agentSlugSchema });
+const agentSchema = z.object({ id: z.uuid(), name: nameSchema });
 
 /** The end user a run acts for, as their token was verified; null for a trigger's run. */
 const serverUserSchema = z

package/src/contracts/triggers/index.ts

@@ -6,7 +6,7 @@ import { TRIGGER_DROP_REASONS, TRIGGER_REASONS } from "../wire/index";
  * Triggers: named entry points on an agent. A firing is one invocation with a
  * payload and starts at most one run. The end user's message is the built-in
  * `message` trigger; every other trigger is fired by a caller over
- * `POST /agents/:agentSlug/triggers/:name` with the trigger's secret as its
+ * `POST /agents/:agentName/triggers/:name` with the trigger's secret as its
  * bearer. These are the shapes Cortex answers that caller with.
  */
 
@@ -26,14 +26,14 @@ export const TRIGGER_OUTCOMES = [
 ] as const;
 export type TriggerOutcome = (typeof TRIGGER_OUTCOMES)[number];
 
-/** The engine route of agent `agentSlug`, which the widget chats with and its triggers sit under. */
-export function agentRoute(agentSlug: string) {
-    return `/agents/${encodeURIComponent(agentSlug)}`;
+/** The engine route of agent `agentName`, which the widget chats with and its triggers sit under. */
+export function agentRoute(agentName: string) {
+    return `/agents/${encodeURIComponent(agentName)}`;
 }
 
-/** The engine route a trigger is fired at on agent `agentSlug`; its firings are read and answered under it. */
-export function triggerRoute(agentSlug: string, name: string) {
-    return `${agentRoute(agentSlug)}/triggers/${encodeURIComponent(name)}`;
+/** The engine route a trigger is fired at on agent `agentName`; its firings are read and answered under it. */
+export function triggerRoute(agentName: string, name: string) {
+    return `${agentRoute(agentName)}/triggers/${encodeURIComponent(name)}`;
 }
 
 /** One server tool call a parked run waits on; `POST .../firings/:id/answer` decides it. */
@@ -88,7 +88,7 @@ export const triggerFiringResponseSchema = z.discriminatedUnion("outcome", [
 export type TriggerFiringResponse = z.infer<typeof triggerFiringResponseSchema>;
 
 /**
- * `POST /agents/:agentSlug/triggers/:name/firings/:id/answer`: the decision on one parked call.
+ * `POST /agents/:agentName/triggers/:name/firings/:id/answer`: the decision on one parked call.
  * A call id is as long as the model provider made it (some carry a signature), so only the
  * request's body limit bounds it.
  */
@@ -98,7 +98,7 @@ export const triggerFiringAnswerSchema = z.object({
 });
 export type TriggerFiringAnswer = z.infer<typeof triggerFiringAnswerSchema>;
 
-/** One row of `GET /agents/:agentSlug/triggers/:name/firings`, and the answer of `.../firings/:id`. */
+/** One row of `GET /agents/:agentName/triggers/:name/firings`, and the answer of `.../firings/:id`. */
 export const triggerFiringRecordSchema = z.object({
     id: z.uuid(),
     triggerName: z.string(),

package/src/contracts/wire/index.ts

@@ -169,6 +169,8 @@ export type ClientToolBinding = {
  * The widget hides UI for anything absent; Cortex enforces each.
  */
 export type AgentCapabilities = {
+    /** The agent's display name per locale, which titles a new chat; `{}` for an agent without one. */
+    displayName: Partial<LocalizedText>;
     attachments: boolean;
     /**
      * False when this caller may not send to the chat: the agent's `message`
@@ -214,6 +216,15 @@ export type Greeting = Record<Locale, string>;
 /** Author-written copy the widget shows verbatim, one string per locale. */
 export type LocalizedText = Record<Locale, string>;
 
+/**
+ * Resolves a per-locale value against `locale`: exact match, then English,
+ * then any entry, so a sparse map still renders something. An entity's
+ * label is `localized(entity.displayName, locale) ?? entity.name`.
+ */
+export function localized<T>(value: Partial<Record<Locale, T>>, locale: Locale) {
+    return value[locale] ?? value.en ?? Object.values(value)[0];
+}
+
 /**
  * Cortex's own tools whose input carries `status`: the model's one-line
  * statement of the call, which the widget draws in place of a generic label.

package/src/scaffold/files.ts

@@ -8,8 +8,6 @@
  * a standalone scaffold has no workspace.
  */
 
-import { NAME_MAX_LENGTH } from "@cortex/contracts/manifest";
-
 import pkg from "../../package.json";
 import serverTs from "@/scaffold/templates/server.ts.txt";
 import setupTs from "@/scaffold/templates/setup.ts.txt";
@@ -30,7 +28,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.19.0";
+const CORTEX_VERSION = "0.20.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";
@@ -40,9 +38,9 @@ const SERVER_URL = `http://${DOCKER_HOST}:{{port.server}}`;
 
 /**
  * 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.
+ * Not `assistant`: Cortex holds that name for its console's own assistant.
  */
-export const AGENT_SLUG = "helper";
+export const AGENT_NAME = "helper";
 
 /**
  * The embedding model the stack asks for, and the dimension the image's
@@ -111,7 +109,7 @@ function runAll(runner: "mprocs" | "concurrently", processes: Record<string, str
     return `${runner} --names ${Object.keys(processes).join(",")} ${commands.join(" ")}`;
 }
 
-/** The name as the manifest `id` takes it: lowercase words and hyphens. */
+/** The name as the manifest `id` and the server's name take it: lowercase words and hyphens. */
 export function manifestIdOf(name: string) {
     return name
         .replace(/[^a-z0-9]+/g, "-")
@@ -149,7 +147,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.7.0",
+                "@m6d/cortex": "~0.8.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",
@@ -218,8 +216,8 @@ export default defineManifest({
     id: ${JSON.stringify(manifestIdOf(name))},
     agents: [
         {
-            slug: "${AGENT_SLUG}",
-            name: "Helper",
+            name: "${AGENT_NAME}",
+            displayName: { en: "Helper" },
             server,
             prompt: "You are a helpful assistant. Address the user as {{userName}}.",
             // No identity provider yet: each browser is a visitor of its own.
@@ -460,7 +458,7 @@ 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
+in \`.env\`, and applies the manifest. Then it prints where to chat with \`${AGENT_NAME}\`, 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:
@@ -487,7 +485,7 @@ A backend for Cortex agents, and Cortex itself to run them on.
           ? "\n- `datasets.ts` serves an `orders` table as a dataset host, for agents to ask grouped\n  questions of."
           : ""
   }
-- \`cortex.manifest.ts\` declares the \`${AGENT_SLUG}\` agent on this server${
+- \`cortex.manifest.ts\` declares the \`${AGENT_NAME}\` 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.
@@ -507,7 +505,7 @@ bun run dev
 
 ${gettingStarted}
 
-Then chat with \`${AGENT_SLUG}\` on the console's **Playground** page. Edit \`cortex.manifest.ts\` and run
+Then chat with \`${AGENT_NAME}\` 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.
@@ -538,7 +536,7 @@ pre-commit hook or CI job should run. Each is also available on its own: \`forma
  * are drawn by the caller.
  */
 export function scaffoldFiles(input: Input) {
-    const project = { ...input, server: input.name.slice(0, NAME_MAX_LENGTH) };
+    const project = { ...input, server: manifestIdOf(input.name) };
     const files = {
         "server.ts": serverTs,
         "setup.ts": setupTs,