create-ragen-app 0.2.0 → 0.4.0

package/dist/config-template.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILENAME = void 0;
+exports.renderRagenConfig = renderRagenConfig;
+/**
+ * The whole `ragen.config.ts`, rendered.
+ *
+ * This replaced patching a marked region in the cloned file, after that
+ * approach produced four separate defects in a day: a substring search that
+ * matched the end marker inside the start marker, a marker line that carried
+ * explanatory prose and so matched nothing once the search was tightened, and
+ * two duplicate-region layouts that each mangled the file in a different way.
+ * Every one was a case of locating a region inside arbitrary text, and the
+ * space of ways that goes wrong is not something a fixture can be trusted to
+ * explore — the third defect reached CI precisely because every fixture
+ * agreed with the others and none agreed with the file being shipped.
+ *
+ * Rendering the whole file removes the operation entirely. There is nothing
+ * to find, nothing to preserve, and no malformed input: the installer writes
+ * what it means.
+ *
+ * The cost is that this template must carry the groups the wizard never asks
+ * about, and could drift from the file the repository ships. It cannot:
+ * `ragen.config.ts` at the repository root **is generated from this function**
+ * (`npm run config:template`), and
+ * `tests/architecture/ragen-config-is-generated.test.ts` compares them. One
+ * source, one artifact, checked — the same arrangement as the published
+ * configuration reference.
+ */
+exports.CONFIG_FILENAME = 'ragen.config.ts';
+/**
+ * A required field is typed `string`, so `process.env.X` alone does not
+ * compile — it is `string | undefined`. The fallback is a blank rather than a
+ * non-null assertion because a blank is *true*: the variable may genuinely be
+ * missing, and every reader in `@ragenai/env` treats blank as unset, so the
+ * boot-time check reports it instead of a `!` hiding it until something
+ * dereferences undefined.
+ */
+function renderField({ field, envVar, required }) {
+    const value = required
+        ? `process.env.${envVar} ?? ''`
+        : `process.env.${envVar}`;
+    return `    ${field}: ${value},`;
+}
+function renderGroup(group, provider, fields, comment) {
+    return [
+        `  ${group}: {`,
+        ...(comment ? [`    // ${comment}`] : []),
+        `    provider: '${provider}',`,
+        ...fields.map(renderField),
+        '  },',
+    ];
+}
+const HEADER = `import { defineConfig } from '@ragenai/env';
+
+/**
+ * The configuration this deployment was created with.
+ *
+ * Generated by \`create-ragen-app\`, which writes it once when the project is
+ * scaffolded and never again — so in a scaffolded project this is yours to
+ * edit.
+ *
+ * In the Ragen repository itself it is an artifact: regenerate it with
+ * \`npm run config:template\` and make changes in
+ * \`packages/create-ragen-app/src/config-template.ts\`, or the next scaffold
+ * discards them.
+ *
+ * ADR-37 declined a \`ragen.config.ts\` the apps would *read* instead of the
+ * environment, and that still holds: a secret does not belong in git, and
+ * compose, the Dockerfiles and Railway only speak environment variables.
+ * **Nothing reads this file at runtime.** It is the structure and the
+ * defaulting, with every value still resolved from \`process.env\` — which is
+ * why a fresh clone works with the minimum \`.env.local\` AGENTS.md documents,
+ * and why the fallbacks below are the same ones the code already applies.
+ *
+ * What it is for: choosing a provider makes that provider's variables
+ * mandatory *in the editor*. \`storage: { provider: 's3' }\` with no bucket does
+ * not compile. \`npm run typecheck:config\` is what makes that real — without
+ * it this file would be checked by nothing, since the repository has no root
+ * \`tsconfig.json\`.
+ *
+ * The shapes come from \`packages/env/src/provider-seams.ts\` and
+ * \`config-groups.ts\`, the same tables the boot-time check reads.
+ */
+export default defineConfig({
+  database: {
+    url:
+      process.env.DATABASE_URL ??
+      'postgresql://postgres:pass123@localhost:55432/ragen',
+  },
+
+  gateway: {
+    // Every model call goes through LiteLLM (ADR-04).
+    url: process.env.LITELLM_PROXY_URL ?? 'http://localhost:4000',
+    masterKey: process.env.LITELLM_MASTER_KEY,
+  },
+
+  vectorStore: {
+    // Qdrant is the only supported vector store (ADR-31).
+    url: process.env.QDRANT_URL ?? 'http://localhost:6333',
+    apiKey: process.env.QDRANT_API_KEY,
+  },
+
+  models: {
+    chat: process.env.DEFAULT_MODEL ?? 'gemini-3-flash-preview',
+    // Do not upgrade without approval — see AGENTS.md, "Model Defaults".
+    rephrase: process.env.REPHRASE_MODEL ?? 'gemini-2.5-flash',
+    summary: process.env.SUMMARY_MODEL ?? 'gemini-2.5-flash',
+    embeddings: process.env.EMBEDDINGS_MODEL,
+    // Changing this after documents exist invalidates the collection.
+    vectorSize: process.env.VECTOR_SIZE,
+  },
+
+`;
+function renderRagenConfig(storage, encryption) {
+    const lines = [
+        ...renderGroup('storage', storage.provider, storage.configFields, storage.provider === 'local'
+            ? 'ADR-27: local by default, so a fresh clone runs without a cloud account.'
+            : undefined),
+    ];
+    if (encryption.provider !== 'none') {
+        lines.push('', ...renderGroup('encryption', encryption.provider, encryption.configFields));
+    }
+    return `${HEADER}${lines.join('\n')}\n});\n`;
+}
+//# sourceMappingURL=config-template.js.map

package/dist/config-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-template.js","sourceRoot":"","sources":["../src/config-template.ts"],"names":[],"mappings":";;;AA2HA,8CA2BC;AAnJD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEU,QAAA,eAAe,GAAG,iBAAiB,CAAC;AAEjD;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAe;IAC3D,MAAM,KAAK,GAAG,QAAQ;QACpB,CAAC,CAAC,eAAe,MAAM,QAAQ;QAC/B,CAAC,CAAC,eAAe,MAAM,EAAE,CAAC;IAC5B,OAAO,OAAO,KAAK,KAAK,KAAK,GAAG,CAAC;AACnC,CAAC;AAED,SAAS,WAAW,CAClB,KAAa,EACb,QAAgB,EAChB,MAAqB,EACrB,OAAgB;IAEhB,OAAO;QACL,KAAK,KAAK,KAAK;QACf,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,kBAAkB,QAAQ,IAAI;QAC9B,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC;QAC1B,MAAM;KACP,CAAC;AACJ,CAAC;AAED,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4Dd,CAAC;AAEF,SAAgB,iBAAiB,CAC/B,OAAyB,EACzB,UAA+B;IAE/B,MAAM,KAAK,GAAG;QACZ,GAAG,WAAW,CACZ,SAAS,EACT,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,YAAY,EACpB,OAAO,CAAC,QAAQ,KAAK,OAAO;YAC1B,CAAC,CAAC,0EAA0E;YAC5E,CAAC,CAAC,SAAS,CACd;KACF,CAAC;IAEF,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CACR,EAAE,EACF,GAAG,WAAW,CACZ,YAAY,EACZ,UAAU,CAAC,QAAQ,EACnB,UAAU,CAAC,YAAY,CACxB,CACF,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;AAC/C,CAAC"}

package/dist/encryption-provider.d.ts

@@ -0,0 +1,35 @@
+import type { ConfigField } from './storage-provider';
+/**
+ * Encryption at rest for thread messages and PII (ADR-02, ADR-06).
+ *
+ * The wizard skipped this too, and the cost of skipping is asymmetric:
+ * turning encryption *on* later leaves everything written before it in
+ * plaintext, because nothing re-encrypts history. So the one moment it is
+ * free to decide is the moment the install is created.
+ *
+ * `local` is offered first because it costs the user nothing —
+ * `generateSecret()` already produces a 64-character hex string, which is
+ * exactly what `parseMasterKey` in `@ragenai/crypto` accepts. No account, no
+ * console, no copy-paste.
+ *
+ * The variable names mirror `ENCRYPTION_SEAM` in `@ragenai/env`, copied rather
+ * than imported for the reason given in `storage-provider.ts`, and held to the
+ * original by `tests/architecture/create-ragen-app-knows-the-provider-seams.test.ts`.
+ */
+export type EncryptionChoice = 'none' | 'local' | 'scaleway' | 'kms';
+export declare const ENCRYPTION_LABELS: Record<EncryptionChoice, string>;
+export interface EncryptionAnswers {
+    /** Scaleway: Key Manager key id. KMS: the key id or ARN. */
+    keyId: string;
+    /** Scaleway only. */
+    apiKey: string;
+}
+export interface EncryptionSelection {
+    provider: EncryptionChoice;
+    envUpdates: Record<string, string>;
+    configFields: ConfigField[];
+    /** True when the wizard minted the key, so the CLI can say where it went. */
+    generatedKey: boolean;
+}
+export declare function resolveEncryptionSelection(provider: EncryptionChoice, answers?: EncryptionAnswers): EncryptionSelection;
+//# sourceMappingURL=encryption-provider.d.ts.map

package/dist/encryption-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-provider.d.ts","sourceRoot":"","sources":["../src/encryption-provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,CAAC;AAErE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAK9D,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,YAAY,EAAE,OAAO,CAAC;CACvB;AAOD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,mBAAmB,CAkDrB"}

package/dist/encryption-provider.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENCRYPTION_LABELS = void 0;
+exports.resolveEncryptionSelection = resolveEncryptionSelection;
+const secrets_1 = require("./secrets");
+exports.ENCRYPTION_LABELS = {
+    local: 'Yes — generate a key for me (recommended)',
+    scaleway: 'Yes — Scaleway Key Manager (I have a key id)',
+    kms: 'Yes — AWS KMS (I have a key id)',
+    none: 'No — store messages and documents in plaintext',
+};
+const NOTHING = {
+    envUpdates: {},
+    configFields: [],
+};
+function resolveEncryptionSelection(provider, answers) {
+    if (provider === 'none') {
+        // Deliberately writes nothing rather than `ENCRYPTION_PROVIDER=none`:
+        // there is no such provider, and `@ragenai/crypto` decides by looking for
+        // credentials. An unset variable is the honest way to say "not
+        // configured", and it is what a deployed environment refuses to start on.
+        return { provider, ...NOTHING, generatedKey: false };
+    }
+    if (provider === 'local') {
+        return {
+            provider,
+            envUpdates: {
+                ENCRYPTION_PROVIDER: 'local',
+                ENCRYPTION_MASTER_KEY: (0, secrets_1.generateSecret)(),
+            },
+            configFields: [
+                { field: 'masterKey', envVar: 'ENCRYPTION_MASTER_KEY', required: true },
+            ],
+            generatedKey: true,
+        };
+    }
+    const keyId = answers?.keyId.trim() ?? '';
+    const apiKey = answers?.apiKey.trim() ?? '';
+    if (provider === 'kms') {
+        return {
+            provider,
+            envUpdates: { ENCRYPTION_PROVIDER: 'kms', AWS_KMS_KEY_ID: keyId },
+            configFields: [
+                { field: 'keyId', envVar: 'AWS_KMS_KEY_ID', required: true },
+            ],
+            generatedKey: false,
+        };
+    }
+    return {
+        provider: 'scaleway',
+        envUpdates: {
+            ENCRYPTION_PROVIDER: 'scaleway',
+            SCW_KEY_MANAGER_KEY_ID: keyId,
+            SCW_API_KEY: apiKey,
+        },
+        configFields: [
+            { field: 'keyId', envVar: 'SCW_KEY_MANAGER_KEY_ID', required: true },
+            { field: 'apiKey', envVar: 'SCW_API_KEY', required: true },
+        ],
+        generatedKey: false,
+    };
+}
+//# sourceMappingURL=encryption-provider.js.map

package/dist/encryption-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption-provider.js","sourceRoot":"","sources":["../src/encryption-provider.ts"],"names":[],"mappings":";;;AAkDA,gEAqDC;AAvGD,uCAA2C;AAuB9B,QAAA,iBAAiB,GAAqC;IACjE,KAAK,EAAE,2CAA2C;IAClD,QAAQ,EAAE,8CAA8C;IACxD,GAAG,EAAE,iCAAiC;IACtC,IAAI,EAAE,gDAAgD;CACvD,CAAC;AAiBF,MAAM,OAAO,GAA6D;IACxE,UAAU,EAAE,EAAE;IACd,YAAY,EAAE,EAAE;CACjB,CAAC;AAEF,SAAgB,0BAA0B,CACxC,QAA0B,EAC1B,OAA2B;IAE3B,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,sEAAsE;QACtE,0EAA0E;QAC1E,+DAA+D;QAC/D,0EAA0E;QAC1E,OAAO,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IAED,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO;YACL,QAAQ;YACR,UAAU,EAAE;gBACV,mBAAmB,EAAE,OAAO;gBAC5B,qBAAqB,EAAE,IAAA,wBAAc,GAAE;aACxC;YACD,YAAY,EAAE;gBACZ,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,uBAAuB,EAAE,QAAQ,EAAE,IAAI,EAAE;aACxE;YACD,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAE5C,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACvB,OAAO;YACL,QAAQ;YACR,UAAU,EAAE,EAAE,mBAAmB,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE;YACjE,YAAY,EAAE;gBACZ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC7D;YACD,YAAY,EAAE,KAAK;SACpB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,UAAU;QACpB,UAAU,EAAE;YACV,mBAAmB,EAAE,UAAU;YAC/B,sBAAsB,EAAE,KAAK;YAC7B,WAAW,EAAE,MAAM;SACpB;QACD,YAAY,EAAE;YACZ,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE;YACpE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC3D;QACD,YAAY,EAAE,KAAK;KACpB,CAAC;AACJ,CAAC"}

package/dist/llm-provider.d.ts

@@ -1,4 +1,5 @@
 import type { LiteLLMModelEntry } from './litellm-config';
+import type { RouteTableEntry } from './route-table';
 /**
  * The `infra/litellm/config.yaml` shipped in the repo only wires Azure
  * OpenAI, AWS Bedrock, Google Vertex and Scaleway — none of which a new
@@ -9,6 +10,8 @@ export type LlmProviderChoice = 'openai' | 'anthropic';
 export interface LlmEmbeddingsConfig {
     modelName: string;
     litellmModel: string;
+    /** The upstream's own name, for the route table. */
+    upstreamModel: string;
     /** Output dimensionality — must match `VECTOR_SIZE`, see rag-core's vector contract. */
     vectorSize: number;
 }
@@ -17,6 +20,15 @@ export interface LlmProviderConfig {
     apiKeyEnvVar: string;
     modelName: string;
     litellmModel: string;
+    /**
+     * The `@ragenai/llm-gateway` provider that serves this key directly, and the
+     * upstream's own name for the model. Both providers the wizard offers have
+     * one, so a scaffolded install calls the provider itself — the same default
+     * every other deployment gets — rather than routing through a proxy it only
+     * runs because the wizard configured one.
+     */
+    gatewayProvider: string;
+    upstreamModel: string;
     /**
      * Undefined for a provider with no embeddings API of its own. Chat still
      * works; the knowledge base does not, because retrieval has nothing to
@@ -30,6 +42,11 @@ export declare const LLM_PROVIDERS: Record<LlmProviderChoice, LlmProviderConfig>
 export interface LlmProviderChoiceResult {
     envUpdates: Record<string, string>;
     liteLLMEntries: LiteLLMModelEntry[];
+    /**
+     * The route table this installation gets. Written over the one shipped in
+     * the repository, which names providers a new install has no keys for.
+     */
+    routes: RouteTableEntry[];
     /** False when the picked provider cannot serve embeddings — the caller warns. */
     embeddingsConfigured: boolean;
 }

package/dist/llm-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-provider.d.ts","sourceRoot":"","sources":["../src/llm-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,iBAAiB,EAAE,iBAAiB,CAyBtE,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC,iFAAiF;IACjF,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,GACb,uBAAuB,CAwCzB"}
+{"version":3,"file":"llm-provider.d.ts","sourceRoot":"","sources":["../src/llm-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,iBAAiB,EAAE,iBAAiB,CAiCtE,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,iBAAiB,EAAE,CAAC;IACpC;;;OAGG;IACH,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,iFAAiF;IACjF,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,GACb,uBAAuB,CA+DzB"}

package/dist/llm-provider.js

@@ -8,9 +8,12 @@ exports.LLM_PROVIDERS = {
         apiKeyEnvVar: 'OPENAI_API_KEY',
         modelName: 'gpt-4o-mini',
         litellmModel: 'openai/gpt-4o-mini',
+        gatewayProvider: 'openai',
+        upstreamModel: 'gpt-4o-mini',
         embeddings: {
             modelName: 'text-embedding-3-small',
             litellmModel: 'openai/text-embedding-3-small',
+            upstreamModel: 'text-embedding-3-small',
             vectorSize: 1536,
         },
     },
@@ -24,8 +27,13 @@ exports.LLM_PROVIDERS = {
         // Bedrock traffic under Bedrock's catalog metadata.
         modelName: 'claude-haiku-4-5-direct',
         litellmModel: 'anthropic/claude-haiku-4-5-20251001',
+        gatewayProvider: 'anthropic',
+        upstreamModel: 'claude-haiku-4-5-20251001',
         // Anthropic ships no embeddings endpoint, so there is nothing to point
-        // EMBEDDINGS_MODEL at with this key alone.
+        // EMBEDDINGS_MODEL at with this key alone. The gateway says the same
+        // thing in its own shape: `anthropic` has no entry in
+        // EMBEDDING_PROVIDER_FACTORIES, and a route pointing there raises
+        // EmbeddingsUnsupportedError rather than failing inside the AI SDK.
     },
 };
 function resolveLlmProviderChoice(choice, apiKey) {
@@ -33,6 +41,12 @@ function resolveLlmProviderChoice(choice, apiKey) {
     const envUpdates = {
         [config.apiKeyEnvVar]: apiKey,
         DEFAULT_MODEL: config.modelName,
+        // Overrides the manifest's `litellm`, which is the baseline for the one
+        // path that reaches neither branch here: "I'll configure LiteLLM myself".
+        LLM_GATEWAY: 'native',
+        // Not the gateway. This names the pricing namespace `AiUsage` writes
+        // against, where the whole catalogue lives under `litellm`; the provider
+        // that actually served a turn is recorded separately as `servedBy`.
         DEFAULT_MODEL_PROVIDER: 'litellm',
         // .env.example ships gemini-2.5-flash here, which needs Vertex
         // credentials. Multi-query expansion is on by default (ADR-15), so
@@ -47,6 +61,16 @@ function resolveLlmProviderChoice(choice, apiKey) {
             apiKeyEnvVar: config.apiKeyEnvVar,
         },
     ];
+    // Written as well as the route table, and deliberately: `docker compose up`
+    // starts LiteLLM whatever `LLM_GATEWAY` says, so configuring both makes
+    // `LLM_GATEWAY=litellm` a working rollback rather than a broken one.
+    const routes = [
+        {
+            modelName: config.modelName,
+            provider: config.gatewayProvider,
+            model: config.upstreamModel,
+        },
+    ];
     if (config.embeddings) {
         envUpdates.EMBEDDINGS_MODEL = config.embeddings.modelName;
         // VECTOR_SIZE and EMBEDDINGS_MODEL have to agree or Qdrant rejects every
@@ -58,10 +82,16 @@ function resolveLlmProviderChoice(choice, apiKey) {
             model: config.embeddings.litellmModel,
             apiKeyEnvVar: config.apiKeyEnvVar,
         });
+        routes.push({
+            modelName: config.embeddings.modelName,
+            provider: config.gatewayProvider,
+            model: config.embeddings.upstreamModel,
+        });
     }
     return {
         envUpdates,
         liteLLMEntries,
+        routes,
         embeddingsConfigured: Boolean(config.embeddings),
     };
 }

package/dist/llm-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm-provider.js","sourceRoot":"","sources":["../src/llm-provider.ts"],"names":[],"mappings":";;;AAkEA,4DA2CC;AA7EY,QAAA,aAAa,GAAiD;IACzE,MAAM,EAAE;QACN,KAAK,EAAE,QAAQ;QACf,YAAY,EAAE,gBAAgB;QAC9B,SAAS,EAAE,aAAa;QACxB,YAAY,EAAE,oBAAoB;QAClC,UAAU,EAAE;YACV,SAAS,EAAE,wBAAwB;YACnC,YAAY,EAAE,+BAA+B;YAC7C,UAAU,EAAE,IAAI;SACjB;KACF;IACD,SAAS,EAAE;QACT,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,mBAAmB;QACjC,gFAAgF;QAChF,uEAAuE;QACvE,qEAAqE;QACrE,sEAAsE;QACtE,oDAAoD;QACpD,SAAS,EAAE,yBAAyB;QACpC,YAAY,EAAE,qCAAqC;QACnD,uEAAuE;QACvE,2CAA2C;KAC5C;CACF,CAAC;AASF,SAAgB,wBAAwB,CACtC,MAAyB,EACzB,MAAc;IAEd,MAAM,MAAM,GAAG,qBAAa,CAAC,MAAM,CAAC,CAAC;IAErC,MAAM,UAAU,GAA2B;QACzC,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM;QAC7B,aAAa,EAAE,MAAM,CAAC,SAAS;QAC/B,sBAAsB,EAAE,SAAS;QACjC,+DAA+D;QAC/D,mEAAmE;QACnE,uEAAuE;QACvE,kDAAkD;QAClD,cAAc,EAAE,MAAM,CAAC,SAAS;KACjC,CAAC;IAEF,MAAM,cAAc,GAAwB;QAC1C;YACE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK,EAAE,MAAM,CAAC,YAAY;YAC1B,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC;KACF,CAAC;IAEF,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,UAAU,CAAC,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1D,yEAAyE;QACzE,sEAAsE;QACtE,qDAAqD;QACrD,UAAU,CAAC,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC9D,cAAc,CAAC,IAAI,CAAC;YAClB,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS;YACtC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,YAAY;YACrC,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU;QACV,cAAc;QACd,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC;KACjD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"llm-provider.js","sourceRoot":"","sources":["../src/llm-provider.ts"],"names":[],"mappings":";;;AA2FA,4DAkEC;AAjHY,QAAA,aAAa,GAAiD;IACzE,MAAM,EAAE;QACN,KAAK,EAAE,QAAQ;QACf,YAAY,EAAE,gBAAgB;QAC9B,SAAS,EAAE,aAAa;QACxB,YAAY,EAAE,oBAAoB;QAClC,eAAe,EAAE,QAAQ;QACzB,aAAa,EAAE,aAAa;QAC5B,UAAU,EAAE;YACV,SAAS,EAAE,wBAAwB;YACnC,YAAY,EAAE,+BAA+B;YAC7C,aAAa,EAAE,wBAAwB;YACvC,UAAU,EAAE,IAAI;SACjB;KACF;IACD,SAAS,EAAE;QACT,KAAK,EAAE,WAAW;QAClB,YAAY,EAAE,mBAAmB;QACjC,gFAAgF;QAChF,uEAAuE;QACvE,qEAAqE;QACrE,sEAAsE;QACtE,oDAAoD;QACpD,SAAS,EAAE,yBAAyB;QACpC,YAAY,EAAE,qCAAqC;QACnD,eAAe,EAAE,WAAW;QAC5B,aAAa,EAAE,2BAA2B;QAC1C,uEAAuE;QACvE,qEAAqE;QACrE,sDAAsD;QACtD,kEAAkE;QAClE,oEAAoE;KACrE;CACF,CAAC;AAcF,SAAgB,wBAAwB,CACtC,MAAyB,EACzB,MAAc;IAEd,MAAM,MAAM,GAAG,qBAAa,CAAC,MAAM,CAAC,CAAC;IAErC,MAAM,UAAU,GAA2B;QACzC,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM;QAC7B,aAAa,EAAE,MAAM,CAAC,SAAS;QAC/B,wEAAwE;QACxE,0EAA0E;QAC1E,WAAW,EAAE,QAAQ;QACrB,qEAAqE;QACrE,yEAAyE;QACzE,oEAAoE;QACpE,sBAAsB,EAAE,SAAS;QACjC,+DAA+D;QAC/D,mEAAmE;QACnE,uEAAuE;QACvE,kDAAkD;QAClD,cAAc,EAAE,MAAM,CAAC,SAAS;KACjC,CAAC;IAEF,MAAM,cAAc,GAAwB;QAC1C;YACE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK,EAAE,MAAM,CAAC,YAAY;YAC1B,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC;KACF,CAAC;IAEF,4EAA4E;IAC5E,wEAAwE;IACxE,qEAAqE;IACrE,MAAM,MAAM,GAAsB;QAChC;YACE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,QAAQ,EAAE,MAAM,CAAC,eAAe;YAChC,KAAK,EAAE,MAAM,CAAC,aAAa;SAC5B;KACF,CAAC;IAEF,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,UAAU,CAAC,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1D,yEAAyE;QACzE,sEAAsE;QACtE,qDAAqD;QACrD,UAAU,CAAC,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC9D,cAAc,CAAC,IAAI,CAAC;YAClB,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS;YACtC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,YAAY;YACrC,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC;YACV,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS;YACtC,QAAQ,EAAE,MAAM,CAAC,eAAe;YAChC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,aAAa;SACvC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU;QACV,cAAc;QACd,MAAM;QACN,oBAAoB,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC;KACjD,CAAC;AACJ,CAAC"}

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAEpE,eAAO,MAAM,QAAQ,EAAE,aAAa,EAqEnC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,aAAa,EAAE,CAEnE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,eAAe,CAAC;IAC1B,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAEpE,eAAO,MAAM,QAAQ,EAAE,aAAa,EAuFnC,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,aAAa,EAAE,CAEnE"}

package/dist/manifest.js

@@ -63,6 +63,22 @@ exports.MANIFEST = [
         targets: ['root', 'admin'],
     },
     // --- Local-dev defaults that correct a stale example value ---
+    {
+        // The baseline, and `resolveLlmProviderChoice` overrides it with `native`
+        // whenever a provider key is actually configured — which is both branches
+        // the wizard offers.
+        //
+        // What is left is the third path: "I'll configure LiteLLM myself". That
+        // one writes no route table, and the table shipped in the repository names
+        // Azure, Bedrock, Vertex and Scaleway — providers a fresh install has no
+        // credentials for. Inheriting the `native` default there would make every
+        // model call fail on the first question, so this pins the proxy the manual
+        // guide then tells them to configure.
+        key: 'LLM_GATEWAY',
+        strategy: 'local-default',
+        targets: ['root'],
+        value: 'litellm',
+    },
     {
         // Ships commented out, which leaves apps/web sending no Authorization
         // header while docker-compose.yml starts the proxy *with* a master key
@@ -82,10 +98,12 @@ exports.MANIFEST = [
         value: 'sk-litellm-dev-key',
     },
     {
-        // docker-compose.yml maps Postgres to host port 55432, not the 5432 that
-        // both .env.example files show — a native/other Postgres on 5432 would
-        // otherwise silently answer instead of the container. See
-        // docs/lessons.md.
+        // docker-compose.yml maps Postgres to host port 55432. A native or other
+        // Postgres on 5432 would otherwise silently answer instead of the
+        // container, and report success against the wrong database. The
+        // `.env.example` files used to disagree with this value; they no longer
+        // do, and `tests/architecture/docs-name-the-published-service-ports.test.ts`
+        // keeps it that way. See docs/lessons.md.
         key: 'DATABASE_URL',
         strategy: 'local-default',
         targets: ['root', 'admin'],

package/dist/manifest.js.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AA0FH,4CAEC;AAzEY,QAAA,QAAQ,GAAoB;IACvC,oDAAoD;IACpD,EAAE,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;IACrE,EAAE,GAAG,EAAE,oBAAoB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;IAC7E;QACE,GAAG,EAAE,0BAA0B;QAC/B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,GAAG,EAAE,qBAAqB;QAC1B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,6DAA6D;QAC7D,sEAAsE;QACtE,0DAA0D;QAC1D,GAAG,EAAE,mBAAmB;QACxB,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,OAAO,CAAC;KACnB;IAED,yDAAyD;IACzD;QACE,yEAAyE;QACzE,mDAAmD;QACnD,oEAAoE;QACpE,0EAA0E;QAC1E,0BAA0B;QAC1B,GAAG,EAAE,qBAAqB;QAC1B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;KAC3B;IAED,gEAAgE;IAChE;QACE,sEAAsE;QACtE,uEAAuE;QACvE,uEAAuE;QACvE,mEAAmE;QACnE,eAAe;QACf,EAAE;QACF,sEAAsE;QACtE,wEAAwE;QACxE,kEAAkE;QAClE,uEAAuE;QACvE,uEAAuE;QACvE,kEAAkE;QAClE,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,yEAAyE;QACzE,uEAAuE;QACvE,0DAA0D;QAC1D,mBAAmB;QACnB,GAAG,EAAE,cAAc;QACnB,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QAC1B,KAAK,EAAE,qDAAqD;KAC7D;CACF,CAAC;AAEF,SAAgB,gBAAgB,CAAC,MAAiB;IAChD,OAAO,gBAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AA4GH,4CAEC;AA3FY,QAAA,QAAQ,GAAoB;IACvC,oDAAoD;IACpD,EAAE,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;IACrE,EAAE,GAAG,EAAE,oBAAoB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE;IAC7E;QACE,GAAG,EAAE,0BAA0B;QAC/B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,GAAG,EAAE,qBAAqB;QAC1B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,6DAA6D;QAC7D,sEAAsE;QACtE,0DAA0D;QAC1D,GAAG,EAAE,mBAAmB;QACxB,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,CAAC;KAClB;IACD;QACE,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,OAAO,CAAC;KACnB;IAED,yDAAyD;IACzD;QACE,yEAAyE;QACzE,mDAAmD;QACnD,oEAAoE;QACpE,0EAA0E;QAC1E,0BAA0B;QAC1B,GAAG,EAAE,qBAAqB;QAC1B,QAAQ,EAAE,iBAAiB;QAC3B,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;KAC3B;IAED,gEAAgE;IAChE;QACE,0EAA0E;QAC1E,0EAA0E;QAC1E,qBAAqB;QACrB,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,yEAAyE;QACzE,0EAA0E;QAC1E,2EAA2E;QAC3E,sCAAsC;QACtC,GAAG,EAAE,aAAa;QAClB,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,SAAS;KACjB;IACD;QACE,sEAAsE;QACtE,uEAAuE;QACvE,uEAAuE;QACvE,mEAAmE;QACnE,eAAe;QACf,EAAE;QACF,sEAAsE;QACtE,wEAAwE;QACxE,kEAAkE;QAClE,uEAAuE;QACvE,uEAAuE;QACvE,kEAAkE;QAClE,GAAG,EAAE,oBAAoB;QACzB,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,oBAAoB;KAC5B;IACD;QACE,yEAAyE;QACzE,kEAAkE;QAClE,gEAAgE;QAChE,wEAAwE;QACxE,6EAA6E;QAC7E,0CAA0C;QAC1C,GAAG,EAAE,cAAc;QACnB,QAAQ,EAAE,eAAe;QACzB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;QAC1B,KAAK,EAAE,qDAAqD;KAC7D;CACF,CAAC;AAEF,SAAgB,gBAAgB,CAAC,MAAiB;IAChD,OAAO,gBAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AACpE,CAAC"}

package/dist/manual-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manual-setup.d.ts","sourceRoot":"","sources":["../src/manual-setup.ts"],"names":[],"mappings":"AAsEA,wBAAgB,0BAA0B,IAAI,MAAM,CAkCnD"}
+{"version":3,"file":"manual-setup.d.ts","sourceRoot":"","sources":["../src/manual-setup.ts"],"names":[],"mappings":"AAgJA,wBAAgB,0BAA0B,IAAI,MAAM,CAoCnD"}

package/dist/manual-setup.js

@@ -16,10 +16,18 @@ function providerSection(choice) {
     const config = llm_provider_1.LLM_PROVIDERS[choice];
     const envLines = [
         `${config.apiKeyEnvVar}=<your ${config.label} key>`,
+        // The wizard writes this, so the guide must too — otherwise following it
+        // by hand produces a proxy install where the wizard produces a direct one.
+        'LLM_GATEWAY=native',
         'DEFAULT_MODEL_PROVIDER=litellm',
         `DEFAULT_MODEL=${config.modelName}`,
         `REPHRASE_MODEL=${config.modelName}`,
     ];
+    const routeLines = [
+        `  ${config.modelName}:`,
+        `    provider: ${config.gatewayProvider}`,
+        `    model: ${config.upstreamModel}`,
+    ];
     const yamlLines = [
         `  - model_name: ${config.modelName}`,
         '    litellm_params:',
@@ -29,6 +37,7 @@ function providerSection(choice) {
     if (config.embeddings) {
         envLines.push(`EMBEDDINGS_MODEL=${config.embeddings.modelName}`, `VECTOR_SIZE=${config.embeddings.vectorSize}`);
         yamlLines.push(`  - model_name: ${config.embeddings.modelName}`, '    litellm_params:', `      model: ${config.embeddings.litellmModel}`, `      api_key: os.environ/${config.apiKeyEnvVar}`);
+        routeLines.push(`  ${config.embeddings.modelName}:`, `    provider: ${config.gatewayProvider}`, `    model: ${config.embeddings.upstreamModel}`);
     }
     return [
         `### ${config.label}`,
@@ -39,20 +48,78 @@ function providerSection(choice) {
         ...envLines,
         '```',
         '',
-        '`infra/litellm/config.yaml`, under the existing `model_list:` key:',
+        '`infra/llm-gateway/routes.yaml` — replace the `routes:` block with:',
+        '',
+        '```yaml',
+        'routes:',
+        ...routeLines,
+        '```',
+        '',
+        'The table shipped in the repository routes to Azure, Bedrock, Vertex and',
+        'Scaleway. Those entries are not wrong, they are simply not yours.',
+        '',
+        `<details><summary>Prefer to run a proxy instead?</summary>`,
+        '',
+        'Set `LLM_GATEWAY=litellm` rather than `native`, leave the route table',
+        'alone, and add this under the existing `model_list:` key in',
+        '`infra/litellm/config.yaml`:',
         '',
         '```yaml',
         ...yamlLines,
         '```',
-        ...(config.embeddings
-            ? []
-            : [
-                '',
-                `${config.label} has no embeddings API, so the knowledge base needs a`,
-                'second provider. Leave `EMBEDDINGS_MODEL` and `VECTOR_SIZE` alone and',
-                'add one (OpenAI, Scaleway or Cohere) before uploading documents.',
-            ]),
         '',
+        'Then `docker compose restart litellm`.',
+        '',
+        '</details>',
+        ...(config.embeddings ? [] : secondProviderForEmbeddings(config.label)),
+        '',
+    ];
+}
+/**
+ * What to add when the chosen provider serves chat and nothing else.
+ *
+ * Concrete rather than "add one (OpenAI, Scaleway or Cohere)", because the
+ * instructions above replace the whole `routes:` block — so the shipped
+ * `EMBEDDINGS_MODEL` default stops being routed at all, and the knowledge base
+ * fails on the first upload with a model id nothing serves. Telling someone to
+ * leave that variable alone was correct while a proxy served it and is wrong
+ * now.
+ *
+ * OpenAI rather than a choice, for the same reason the wizard picks defaults:
+ * one working recipe beats three that each need a decision. Derived from
+ * `LLM_PROVIDERS.openai` so the model name and its vector size cannot drift
+ * from what the wizard would have written.
+ */
+function secondProviderForEmbeddings(label) {
+    const openai = llm_provider_1.LLM_PROVIDERS.openai;
+    const embeddings = openai.embeddings;
+    if (!embeddings) {
+        return [];
+    }
+    return [
+        '',
+        `${label} publishes no embeddings API, so the knowledge base needs a`,
+        'second provider. Anything else with one will do; this is the shortest',
+        'working version.',
+        '',
+        'Add to `.env.local`:',
+        '',
+        '```',
+        `${openai.apiKeyEnvVar}=<your ${openai.label} key>`,
+        `EMBEDDINGS_MODEL=${embeddings.modelName}`,
+        `VECTOR_SIZE=${embeddings.vectorSize}`,
+        '```',
+        '',
+        'And a second entry under `routes:`, beside the chat one above:',
+        '',
+        '```yaml',
+        `  ${embeddings.modelName}:`,
+        `    provider: ${openai.gatewayProvider}`,
+        `    model: ${embeddings.upstreamModel}`,
+        '```',
+        '',
+        'Without both, uploads fail on a model id nothing serves — the route table',
+        'you wrote above replaced the one that used to carry a default.',
     ];
 }
 function manualLlmSetupInstructions() {
@@ -63,11 +130,9 @@ function manualLlmSetupInstructions() {
         'base will not work until one is configured. Nothing here needs to go',
         'through a CLI — edit the two files below yourself.',
         '',
-        'Pick one provider, apply both edits, then restart the proxy:',
-        '',
-        '```bash',
-        'docker compose restart litellm',
-        '```',
+        'Ragen calls providers directly by default, so the two files are your',
+        '`.env.local` and the route table. Pick one provider, apply both edits,',
+        'and restart the apps.',
         '',
         ...providerSection('openai'),
         ...providerSection('anthropic'),
@@ -80,11 +145,15 @@ function manualLlmSetupInstructions() {
         '',
         '## Check it worked',
         '',
+        'One real call per model this installation is configured to use:',
+        '',
         '```bash',
-        'curl -s -H "Authorization: Bearer $LITELLM_MASTER_KEY" \\',
-        '  http://localhost:4000/v1/models',
+        'npm run gateway:preflight -- --probe',
         '```',
         '',
+        'It resolves each model and calls it. "Configured" and "works" are',
+        'different questions, and only the second one matters here.',
+        '',
         `Anything else — S3 storage, encryption at rest, Stripe, email, MCP`,
         `connectors — is documented at ${SELF_HOSTING_DOCS}.`,
         '',

package/dist/manual-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"manual-setup.js","sourceRoot":"","sources":["../src/manual-setup.ts"],"names":[],"mappings":";;AAsEA,gEAkCC;AAxGD,iDAAuE;AAEvE;;;;;;;;GAQG;AAEH,MAAM,iBAAiB,GAAG,yCAAyC,CAAC;AAEpE,SAAS,eAAe,CAAC,MAAyB;IAChD,MAAM,MAAM,GAAG,4BAAa,CAAC,MAAM,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG;QACf,GAAG,MAAM,CAAC,YAAY,UAAU,MAAM,CAAC,KAAK,OAAO;QACnD,gCAAgC;QAChC,iBAAiB,MAAM,CAAC,SAAS,EAAE;QACnC,kBAAkB,MAAM,CAAC,SAAS,EAAE;KACrC,CAAC;IAEF,MAAM,SAAS,GAAG;QAChB,mBAAmB,MAAM,CAAC,SAAS,EAAE;QACrC,qBAAqB;QACrB,gBAAgB,MAAM,CAAC,YAAY,EAAE;QACrC,6BAA6B,MAAM,CAAC,YAAY,EAAE;KACnD,CAAC;IAEF,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,QAAQ,CAAC,IAAI,CACX,oBAAoB,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,EACjD,eAAe,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,CAC9C,CAAC;QACF,SAAS,CAAC,IAAI,CACZ,mBAAmB,MAAM,CAAC,UAAU,CAAC,SAAS,EAAE,EAChD,qBAAqB,EACrB,gBAAgB,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,EAChD,6BAA6B,MAAM,CAAC,YAAY,EAAE,CACnD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,MAAM,CAAC,KAAK,EAAE;QACrB,EAAE;QACF,iCAAiC;QACjC,EAAE;QACF,KAAK;QACL,GAAG,QAAQ;QACX,KAAK;QACL,EAAE;QACF,oEAAoE;QACpE,EAAE;QACF,SAAS;QACT,GAAG,SAAS;QACZ,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,UAAU;YACnB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,EAAE;gBACF,GAAG,MAAM,CAAC,KAAK,uDAAuD;gBACtE,uEAAuE;gBACvE,kEAAkE;aACnE,CAAC;QACN,EAAE;KACH,CAAC;AACJ,CAAC;AAED,SAAgB,0BAA0B;IACxC,OAAO;QACL,0BAA0B;QAC1B,EAAE;QACF,sEAAsE;QACtE,sEAAsE;QACtE,oDAAoD;QACpD,EAAE;QACF,8DAA8D;QAC9D,EAAE;QACF,SAAS;QACT,gCAAgC;QAChC,KAAK;QACL,EAAE;QACF,GAAG,eAAe,CAAC,QAAQ,CAAC;QAC5B,GAAG,eAAe,CAAC,WAAW,CAAC;QAC/B,+BAA+B;QAC/B,EAAE;QACF,mEAAmE;QACnE,yEAAyE;QACzE,qEAAqE;QACrE,yBAAyB;QACzB,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,SAAS;QACT,2DAA2D;QAC3D,mCAAmC;QACnC,KAAK;QACL,EAAE;QACF,oEAAoE;QACpE,iCAAiC,iBAAiB,GAAG;QACrD,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"manual-setup.js","sourceRoot":"","sources":["../src/manual-setup.ts"],"names":[],"mappings":"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"}