archgraph-argo 0.23.0 → 0.24.1

package/README.md

@@ -57,12 +57,15 @@ Everything works out of the box except **semantic (Graph RAG) queries**, which n
 - **Embedding / vector engine** — powers semantic Graph RAG retrieval. Configure
   `ARGO_EMBEDDING_BASE_URL`, `ARGO_EMBEDDING_MODEL`, `ARGO_EMBEDDING_PROVIDER`,
   `ARGO_EMBEDDING_MODEL_VERSION`, `ARGO_EMBEDDING_DIMENSIONS`, plus the API key `QWEN_KEY`.
+  It points at **any OpenAI-compatible embedding endpoint** — a cloud provider, or a self-hosted
+  server for offline / intranet / private deployments via `ARGO_EMBEDDING_PROFILE=openai-compatible`
+  (see the [self-hosted embedding guide](docs/self-hosted-embedding-deployment.md)).
 
 Where do the values come from? The Neo4j credentials come from the Neo4j instance you own or
 provision (URI, username, password). The embedding configuration and `QWEN_KEY` come from your
-embedding provider's dashboard — for example Alibaba DashScope. `argo-deploy` walks you through the
-prompt (existing non-empty values in `~/.argo/.env` are kept); you can also edit the file afterwards
-and re-run.
+embedding provider's dashboard — for example Alibaba DashScope — or from a self-hosted
+OpenAI-compatible server. `argo-deploy` walks you through the prompt (existing non-empty values in
+`~/.argo/.env` are kept); you can also edit the file afterwards and re-run.
 
 ## How to use
 

package/argo/.env.example

@@ -19,6 +19,10 @@
 # -----------------------------------------------------------------------------
 
 # --- Embedding provider (required) — powers vector semantic retrieval -------
+# Provider profile: "approved" (default) = the human-approved cloud profile
+# below; "openai-compatible" = a self-hosted OpenAI-compatible endpoint
+# (intranet/offline) whose URL/model/label/dimension are read verbatim.
+ARGO_EMBEDDING_PROFILE=
 # OpenAI-compatible embedding endpoint base URL (no trailing slash).
 ARGO_EMBEDDING_BASE_URL=
 # Embedding model id (e.g. qwen3.7-text-embedding).
@@ -27,8 +31,17 @@ ARGO_EMBEDDING_MODEL=
 ARGO_EMBEDDING_PROVIDER=
 # Model version / qualification label (recorded evidence only).
 ARGO_EMBEDDING_MODEL_VERSION=
-# Embedding vector dimension; must match the model (current profiles: 1536).
+# Embedding vector dimension; must match the model and the vector index
+# (current profiles: 1536).
 ARGO_EMBEDDING_DIMENSIONS=
+# Query-side instruction prefix for instruction-tuned embedding models (e.g.
+# gte-Qwen2: "Instruct: <task>\nQuery: "). Empty = no prefix. Documents are
+# never prefixed; only the query side is.
+ARGO_EMBEDDING_QUERY_INSTRUCTION=
+# Optional embedding API key. SECRET: overrides QWEN_KEY as the Bearer token for
+# the embeddings call when set (useful for a self-hosted endpoint). Leave empty
+# to use QWEN_KEY.
+ARGO_EMBEDDING_API_KEY=
 
 # --- Neo4j (required) — structural projection + vector/full-text store ------
 # Neo4j connection URI (e.g. neo4j://127.0.0.1:7687).

package/argo/scripts/graph-rag/ARCHITECTURE.md

@@ -137,7 +137,7 @@ Successful query evidence identifies `nodejs` as runtime, `neo4j-native` as retr
 - Frozen accepted source fixtures supply all five `ARGO_EMBEDDING_*` keys, `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and both secret keys from process-only, file-only, or matching dual sources. Every rejected fixture starts from that complete profile and mutates only its named rejection dimension; no implicit default may satisfy normalization.
 - Loader provenance rejects root/alternate/tracked files, CLI, literal/default/fallback, alias, destructured, generated, or indirect secret sources.
 - The resolver validates every trace before consuming its value using its private composition capability: trace/alias-chain immutability, exact field set with no extras, field types, issued-object identity, requested-key equality, exact requested file path, source-kind/path/operation correlation, and a one-element alias chain equal to the requested key for approved direct reads. Trusted test composition can deliberately issue key/path mismatch, missing/extra-field, or wrong-type traces; each must fail exactly `SOURCE_TRACE_INVALID`. The same value with CLI/literal operation methods, fallback/indirect operation methods, or alias methods remains prohibited.
-- The approved live profile is provider `alibaba-cloud-model-studio-openai-compatible-cn-beijing`, endpoint `https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`, model `qwen3.7-text-embedding`, qualification `qualification-2026-07-25`, dimensions `1024`.
+- The approved live profile is provider `alibaba-cloud-model-studio-openai-compatible-cn-beijing`, endpoint `https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`, model `qwen3.7-text-embedding`, qualification `qualification-2026-07-25`, dimensions `1536`. The embedding backend is profile-selectable via `ARGO_EMBEDDING_PROFILE`: `approved` (default) enforces those values byte-for-byte; `openai-compatible` reads a self-hosted OpenAI-compatible endpoint verbatim but still fails closed on a missing key or an invalid dimension, with the vector-index dimension driven by `ARGO_EMBEDDING_DIMENSIONS`. `ARGO_EMBEDDING_QUERY_INSTRUCTION` prefixes the query side only (instruction-tuned models), never stored documents; `ARGO_EMBEDDING_API_KEY` (optional secret) overrides `QWEN_KEY` as the embeddings Bearer token.
 - Live network access requires explicit opt-in through the approved configuration source, normally the ignored/untracked `.argo/.env` containing `ARGO_LIVE_PROVIDER_E2E=1` and, for W3.1, `ARGO_W31_LIVE_MUTATION_VECTOR_E2E=1`; controlled process injection is allowed only through the same provenance-checked resolver. Default/offline CI remains deterministic but never substitutes fake evidence for a live pass.
 - Redaction verification includes a synthetic-success recording boundary that captures full Cypher text/parameter and graph-evidence values, detects canaries in neutral fields, and clears all in-memory persistence before inspecting generated artifacts.
 - The controlled Neo4j test boundary uses `ARGO_NEO4J_DATABASE_URL`, `ARGO_NEO4J_DATABASE_USERNAME`, and `ARGO_NEO4J_DATABASE_PASSWORD`; the password flows only to `neo4j.auth.basic`, never to Cypher or evidence.

package/argo/scripts/graph-rag/defaultSemanticRetrieval.js

@@ -35,6 +35,9 @@ const {
 const {
   markPhase,
 } = require('./mcpCrashDiagnostics.js');
+const {
+  composeQueryEmbeddingInput,
+} = require('./embeddingProviderProfile.js');
 
 const APPROVED_SOURCE_KEYS = Object.freeze([
   'ARGO_EMBEDDING_BASE_URL',
@@ -165,6 +168,7 @@ function createDefaultSemanticRetrieval(dependencies = {}) {
           composition,
           canonicalGraph,
           activeReadinessBoundary,
+          expectedEmbeddingQualification(configurationEvidence.configuration),
         );
         if (!evidence.alignment.aligned) {
           await attemptAutomaticAlignment({
@@ -176,6 +180,7 @@ function createDefaultSemanticRetrieval(dependencies = {}) {
             composition,
             canonicalGraph,
             activeReadinessBoundary,
+            expectedEmbeddingQualification(configurationEvidence.configuration),
           );
           if (!evidence.alignment.aligned) {
             throw semanticAutomaticAlignmentFailed(evidence.alignment);
@@ -219,11 +224,12 @@ function createDefaultSemanticRetrieval(dependencies = {}) {
           && activeTestComposition.useReadinessBoundary !== true
           ? undefined
           : readinessBoundary;
-        await composition.resolveConfiguration();
+        const configurationEvidence = await composition.resolveConfiguration();
         const evidence = await readAndEvaluatePersistentReadiness(
           composition,
           canonicalGraph,
           activeReadinessBoundary,
+          expectedEmbeddingQualification(configurationEvidence.configuration),
         );
         return publicReadinessOutcome(evidence.alignment);
       } finally {
@@ -255,9 +261,12 @@ async function executeWpP2Retrieval({
     transport: composition.transport,
   });
   markPhase('retrieval:embed:start');
-  const vector = await provider.embed(request.intent);
+  const vector = await provider.embed(composeQueryEmbeddingInput(
+    request.intent,
+    configurationEvidence.configuration.embeddingQueryInstruction,
+  ));
   markPhase('retrieval:embed:done');
-  requireQualifiedVector(vector);
+  requireQualifiedVector(vector, configurationEvidence.configuration.embeddingDimensions);
   const purpose = request && typeof request.purpose === 'string' ? request.purpose : '';
   const strict = AUDIT_PURPOSES.has(purpose);
   const topK = Number.isInteger(request.topK) && request.topK > 0 ? request.topK : resolveTopK();
@@ -652,7 +661,7 @@ async function readPersistentReadiness(neo4jDriver, readinessBoundary) {
   return { readiness, requireQualification: false };
 }
 
-function evaluatePersistentReadiness(readiness, canonicalGraph, requireQualification = false) {
+function evaluatePersistentReadiness(readiness, canonicalGraph, requireQualification = false, expectedQualification = APPROVED_PROFILE) {
   const expectedCanonicalVersion = deriveCanonicalVersion(canonicalGraph);
   const records = new Map((Array.isArray(readiness.channels) ? readiness.channels : [])
     .map(record => [record.channel, record]));
@@ -669,10 +678,10 @@ function evaluatePersistentReadiness(readiness, canonicalGraph, requireQualifica
       || record.contentVersion !== readiness.contentVersion
       || record.indexVersion !== readiness.indexVersion
       || (requireQualification && (
-        record.provider !== APPROVED_PROFILE.provider
-        || record.model !== APPROVED_PROFILE.model
-        || record.modelVersion !== APPROVED_PROFILE.version
-        || record.dimensions !== APPROVED_PROFILE.dimensions
+        record.provider !== expectedQualification.provider
+        || record.model !== expectedQualification.model
+        || record.modelVersion !== expectedQualification.version
+        || record.dimensions !== expectedQualification.dimensions
         || record.queryable !== true
         || record.coherent !== true
       ))
@@ -720,17 +729,27 @@ function arrayEvidence(value, fallback = []) {
     : fallback;
 }
 
-async function readAndEvaluatePersistentReadiness(composition, canonicalGraph, readinessBoundary) {
+async function readAndEvaluatePersistentReadiness(composition, canonicalGraph, readinessBoundary, expectedQualification) {
   const persistent = await readPersistentReadiness(composition.neo4jDriver, readinessBoundary);
   const readiness = persistent.readiness;
   const alignment = evaluatePersistentReadiness(
     readiness,
     canonicalGraph,
     persistent.requireQualification,
+    expectedQualification,
   );
   return { composition, readiness, alignment };
 }
 
+function expectedEmbeddingQualification(configuration) {
+  return {
+    provider: configuration.embeddingProvider,
+    model: configuration.embeddingModel,
+    version: configuration.embeddingModelVersion,
+    dimensions: configuration.embeddingDimensions,
+  };
+}
+
 function publicFailureEvidence(readiness) {
   const categories = new Set([
     'APPROVED_SECRET_REQUIRED',
@@ -929,10 +948,10 @@ async function completeSemanticResult({
     canonicalGraph,
     embeddingQualification: {
       approvedByHuman: true,
-      provider: APPROVED_PROFILE.provider,
-      model: APPROVED_PROFILE.model,
-      version: APPROVED_PROFILE.version,
-      dimensions: APPROVED_PROFILE.dimensions,
+      provider: configurationEvidence.configuration.embeddingProvider,
+      model: configurationEvidence.configuration.embeddingModel,
+      version: configurationEvidence.configuration.embeddingModelVersion,
+      dimensions: configurationEvidence.configuration.embeddingDimensions,
     },
     neo4jRetrievalBoundary: {
       async retrieve() {
@@ -967,10 +986,10 @@ async function completeSemanticResult({
     seedsByType: Object.freeze(seedsByType),
     configurationEvidence: Object.freeze({
       attribution: configurationEvidence.attribution,
-      provider: APPROVED_PROFILE.provider,
-      model: APPROVED_PROFILE.model,
-      modelVersion: APPROVED_PROFILE.version,
-      dimensions: APPROVED_PROFILE.dimensions,
+      provider: configurationEvidence.configuration.embeddingProvider,
+      model: configurationEvidence.configuration.embeddingModel,
+      modelVersion: configurationEvidence.configuration.embeddingModelVersion,
+      dimensions: configurationEvidence.configuration.embeddingDimensions,
     }),
     canonicalVersion: versions.canonicalVersion,
     contentVersion: versions.contentVersion,
@@ -1159,10 +1178,10 @@ function semanticAutomaticAlignmentFailed(alignment, sourceError) {
   return error;
 }
 
-function requireQualifiedVector(vector) {
+function requireQualifiedVector(vector, dimensions = APPROVED_PROFILE.dimensions) {
   if (
     !Array.isArray(vector)
-    || vector.length !== APPROVED_PROFILE.dimensions
+    || vector.length !== dimensions
     || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
   ) {
     throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');

package/argo/scripts/graph-rag/embeddingProviderProfile.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// Embedding provider profile (ArchGraph ARGO).
+//
+// The semantic-retrieval embedding backend is either the human-approved cloud
+// profile (`approved`, the default, byte-for-byte unchanged) or a self-hosted
+// OpenAI-compatible endpoint (`openai-compatible`) for intranet / offline
+// deployments. This module owns the profile vocabulary, the dimension contract,
+// and the query-side instruction composition so the live configuration resolver
+// and the retrieval runtime share one implementation.
+
+const PROFILE_KEY = 'ARGO_EMBEDDING_PROFILE';
+const QUERY_INSTRUCTION_KEY = 'ARGO_EMBEDDING_QUERY_INSTRUCTION';
+const API_KEY = 'ARGO_EMBEDDING_API_KEY';
+const PROFILE_APPROVED = 'approved';
+const PROFILE_OPENAI_COMPATIBLE = 'openai-compatible';
+const SUPPORTED_EMBEDDING_PROFILES = Object.freeze([PROFILE_APPROVED, PROFILE_OPENAI_COMPATIBLE]);
+const DEFAULT_EMBEDDING_DIMENSIONS = 1536;
+
+function resolveEmbeddingProfile(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return normalized === '' ? PROFILE_APPROVED : normalized;
+}
+
+function isApprovedEmbeddingProfile(value) {
+  return resolveEmbeddingProfile(value) === PROFILE_APPROVED;
+}
+
+function requireSupportedEmbeddingProfile(value) {
+  const profile = resolveEmbeddingProfile(value);
+  if (!SUPPORTED_EMBEDDING_PROFILES.includes(profile)) {
+    throw profileError('EMBEDDING_PROFILE_UNSUPPORTED');
+  }
+  return profile;
+}
+
+function resolveEmbeddingDimensions(value, fallback = DEFAULT_EMBEDDING_DIMENSIONS) {
+  const parsed = typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function requireEmbeddingDimensions(value) {
+  const parsed = typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw profileError('EMBEDDING_DIMENSIONS_INVALID');
+  }
+  return parsed;
+}
+
+// The query-side input may carry an instruction prefix (e.g. gte-Qwen2's
+// "Instruct: <task>\nQuery: <query>"); document-side input stays raw so stored
+// vectors are never polluted by a query-only prefix. The prefix commonly comes
+// from a single-line `.env` value, so `\n`/`\r`/`\t` escapes are decoded here.
+function normalizeInstruction(instruction) {
+  if (typeof instruction !== 'string') return '';
+  return instruction
+    .replace(/\\r\\n/g, '\n')
+    .replace(/\\n/g, '\n')
+    .replace(/\\r/g, '\r')
+    .replace(/\\t/g, '\t');
+}
+
+function composeQueryEmbeddingInput(text, instruction) {
+  const query = text == null ? '' : String(text);
+  const prefix = normalizeInstruction(instruction);
+  return prefix === '' ? query : `${prefix}${query}`;
+}
+
+function profileError(category) {
+  const error = new Error(category);
+  error.category = category;
+  return error;
+}
+
+module.exports = {
+  PROFILE_KEY,
+  QUERY_INSTRUCTION_KEY,
+  API_KEY,
+  PROFILE_APPROVED,
+  PROFILE_OPENAI_COMPATIBLE,
+  SUPPORTED_EMBEDDING_PROFILES,
+  DEFAULT_EMBEDDING_DIMENSIONS,
+  resolveEmbeddingProfile,
+  isApprovedEmbeddingProfile,
+  requireSupportedEmbeddingProfile,
+  resolveEmbeddingDimensions,
+  requireEmbeddingDimensions,
+  composeQueryEmbeddingInput,
+};

package/argo/scripts/graph-rag/liveEmbeddingIndexGate.js

@@ -46,7 +46,7 @@ function createLiveEmbeddingIndexGate(dependencies = {}) {
       requireInput(input);
       const vector = await client.embed(input.input);
       if (
-        vector.length !== 1536
+        vector.length !== configuration.embeddingDimensions
         || vector.some(value => typeof value !== 'number' || !Number.isFinite(value))
       ) {
         throw safeError('LIVE_PROVIDER_RESPONSE_INVALID');
@@ -79,7 +79,6 @@ function requireApprovedConfiguration(configuration, qualification) {
     || qualification.model !== configuration.embeddingModel
     || qualification.version !== configuration.embeddingModelVersion
     || qualification.dimensions !== configuration.embeddingDimensions
-    || qualification.dimensions !== 1536
   ) {
     throw safeError('LIVE_PROVIDER_INDEX_WRITE_PROHIBITED');
   }

package/argo/scripts/graph-rag/liveEmbeddingProviderClient.js

@@ -11,7 +11,7 @@ function createLiveEmbeddingProviderClient({ configuration, transport }) {
           {
             method: 'POST',
             headers: {
-              Authorization: `Bearer ${configuration.qwenKey}`,
+              Authorization: `Bearer ${configuration.embeddingApiKey || configuration.qwenKey}`,
               'Content-Type': 'application/json',
             },
             body: JSON.stringify({

package/argo/scripts/graph-rag/liveEmbeddingProviderConfig.js

@@ -6,6 +6,14 @@ const {
 const {
   getArgoEnvPath,
 } = require('../argo-paths.js');
+const {
+  PROFILE_KEY,
+  QUERY_INSTRUCTION_KEY,
+  API_KEY: EMBEDDING_API_KEY_KEY,
+  PROFILE_APPROVED,
+  requireSupportedEmbeddingProfile,
+  requireEmbeddingDimensions,
+} = require('./embeddingProviderProfile.js');
 
 const CONFIG_KEYS = Object.freeze([
   'ARGO_EMBEDDING_BASE_URL',
@@ -63,11 +71,35 @@ const READABLE_KEYS = Object.freeze([
   ...CONFIG_KEYS,
   ...OPTIONAL_CONFIG_KEYS,
   ...RETRIEVAL_TUNING_KEYS,
+  PROFILE_KEY,
+  QUERY_INSTRUCTION_KEY,
+  EMBEDDING_API_KEY_KEY,
   ...Object.keys(OPT_IN_KEYS),
 ]);
 const LEGACY_KEYS = Object.freeze(['ARGO_NEO4J_URI', 'ARGO_NEO4J_USERNAME', 'ARGO_NEO4J_PASSWORD']);
+// Host / process-level keys: read from the environment at launch, but NOT
+// accepted inside the .env file (see argo/.env.example Part 2). Kept explicit so
+// the coverage test (tests/env-key-coverage.test.js) can prove every env key
+// referenced by argo/scripts is classified — either a .env key, a host-only key,
+// or a legacy alias. This is what prevents "a key the code already uses is still
+// rejected as unknown".
+const HOST_ONLY_ENV_KEYS = Object.freeze([
+  'ARGO_ENV_FILE',
+  'ARGO_REPO_ROOT',
+  'ARGO_EA_QEA',
+  'ARGO_WORKSPACE_ROOTS',
+  'ARGO_SERVER_PATH',
+  'GRAPH_MCP_URL',
+  'EA_QEA_DEBUG',
+  'WORKSPACE_FOLDER',
+  'ARGO_TEST_TIMEOUT_MS',
+  'ARGO_MCP_MUTATION_RESPONSE_DEBUG',
+  'ARGO_MCP_SEMANTIC_DEDUP',
+  'ARGO_MCP_SEMANTIC_DEDUP_THRESHOLD',
+  'ARGO_SEMANTIC_DEDUP_THRESHOLD',
+]);
 const PROHIBITED_RUNTIME_FIELD_KEYS = Object.freeze(['neo4jUri', 'embeddingCredential']);
-const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY', 'ARGO_RERANK_API_KEY']);
+const SECRET_KEYS = new Set(['ARGO_NEO4J_DATABASE_PASSWORD', 'QWEN_KEY', 'ARGO_RERANK_API_KEY', EMBEDDING_API_KEY_KEY]);
 const APPROVED = Object.freeze({
   ARGO_EMBEDDING_BASE_URL: 'https://llm-clids9mqc5o1mbvb.cn-beijing.maas.aliyuncs.com/compatible-mode/v1',
   ARGO_EMBEDDING_MODEL: 'qwen3.7-text-embedding',
@@ -194,15 +226,16 @@ async function resolveTrusted({
     }
     attribution[key] = present(processValue) ? 'process' : 'file';
   }
-  for (const [key, expected] of Object.entries(APPROVED)) {
-    if (normalized[key] !== expected) throw safeError('LIVE_PROVIDER_CONFIGURATION_REQUIRED');
-  }
+  const profile = requireSupportedEmbeddingProfile(
+    selectOptional(processValues, fileValues, PROFILE_KEY),
+  );
+  const profileConfiguration = buildProfileConfiguration(normalized, profile);
+  const embeddingQueryInstruction = selectOptional(processValues, fileValues, QUERY_INSTRUCTION_KEY);
+  const explicitEmbeddingApiKey = selectOptional(processValues, fileValues, EMBEDDING_API_KEY_KEY);
   const configuration = Object.freeze({
-    embeddingBaseUrl: normalized.ARGO_EMBEDDING_BASE_URL,
-    embeddingModel: normalized.ARGO_EMBEDDING_MODEL,
-    embeddingProvider: normalized.ARGO_EMBEDDING_PROVIDER,
-    embeddingModelVersion: normalized.ARGO_EMBEDDING_MODEL_VERSION,
-    embeddingDimensions: 1536,
+    ...profileConfiguration,
+    embeddingQueryInstruction,
+    embeddingApiKey: explicitEmbeddingApiKey || normalized.QWEN_KEY,
     neo4jDatabaseUrl: normalized.ARGO_NEO4J_DATABASE_URL,
     neo4jDatabaseUsername: normalized.ARGO_NEO4J_DATABASE_USERNAME,
     neo4jDatabasePassword: normalized.ARGO_NEO4J_DATABASE_PASSWORD,
@@ -216,6 +249,52 @@ async function resolveTrusted({
   });
 }
 
+// Profile-aware embedding identity. `approved` (the default) enforces the
+// human-approved cloud values byte-for-byte; `openai-compatible` accepts the
+// configured self-hosted endpoint verbatim but still fails closed on any missing
+// key or invalid dimension (no implicit default).
+function buildProfileConfiguration(normalized, profileValue) {
+  const profile = requireSupportedEmbeddingProfile(profileValue);
+  for (const key of [
+    'ARGO_EMBEDDING_BASE_URL',
+    'ARGO_EMBEDDING_MODEL',
+    'ARGO_EMBEDDING_PROVIDER',
+    'ARGO_EMBEDDING_MODEL_VERSION',
+  ]) {
+    if (!present(normalized[key])) {
+      const error = safeError('LIVE_PROVIDER_CONFIGURATION_REQUIRED');
+      error.field = key;
+      throw error;
+    }
+  }
+  if (profile === PROFILE_APPROVED) {
+    for (const [key, expected] of Object.entries(APPROVED)) {
+      if (normalized[key] !== expected) throw safeError('LIVE_PROVIDER_CONFIGURATION_REQUIRED');
+    }
+  }
+  return Object.freeze({
+    embeddingProfile: profile,
+    embeddingBaseUrl: normalized.ARGO_EMBEDDING_BASE_URL,
+    embeddingModel: normalized.ARGO_EMBEDDING_MODEL,
+    embeddingProvider: normalized.ARGO_EMBEDDING_PROVIDER,
+    embeddingModelVersion: normalized.ARGO_EMBEDDING_MODEL_VERSION,
+    embeddingDimensions: requireEmbeddingDimensions(normalized.ARGO_EMBEDDING_DIMENSIONS),
+  });
+}
+
+function selectOptional(processValues, fileValues, key) {
+  const processValue = processValues.get(key);
+  const fileValue = fileValues.get(key);
+  if (present(processValue) && present(fileValue) && processValue !== fileValue) {
+    throw safeError(SECRET_KEYS.has(key)
+      ? 'SECRET_SOURCE_CONFLICT'
+      : 'LIVE_PROVIDER_CONFIGURATION_CONFLICT');
+  }
+  if (present(processValue)) return processValue;
+  if (present(fileValue)) return fileValue;
+  return '';
+}
+
 function optionalDatabaseName(value, repositoryRoot) {
   if (present(value)) return String(value).trim();
   const repoName = path.basename(repositoryRoot);
@@ -534,10 +613,14 @@ module.exports = {
   resolveApprovedLiveConfiguration,
   withApprovedLiveConfigurationTestComposition,
   posixModeIsSecretSafe,
+  buildProfileConfiguration,
+  APPROVED_EMBEDDING_VALUES: APPROVED,
   // The authoritative set of keys an approved `.env` file may carry. The
   // committed `.env.example` must document exactly this set (see
   // tests/env-example.test.js); SECRET_KEYS marks the subset that must be
   // preflighted as secrets.
   ENV_FILE_KEYS: READABLE_KEYS,
   ENV_FILE_SECRET_KEYS: Object.freeze(Array.from(SECRET_KEYS)),
+  HOST_ONLY_ENV_KEYS,
+  ENV_FILE_LEGACY_KEYS: LEGACY_KEYS,
 };

package/argo/scripts/graph-rag/semantic-persistence/productionSemanticNeo4jAdapter.js

@@ -29,7 +29,7 @@ function createProductionSemanticNeo4jAdapter(dependencies = {}) {
         }));
       }
       return withSession(driver, dependencies.configuration, async session => {
-        await ensureVectorIndexes(session);
+        await ensureVectorIndexes(session, resolveEmbeddingDimensions(dependencies.configuration));
         await ensureFulltextIndexes(session);
         const results = [];
         for (const [channel, definition] of Object.entries(CHANNEL_INDEXES)) {
@@ -93,11 +93,16 @@ function createProductionSemanticNeo4jAdapter(dependencies = {}) {
 
 const EMBEDDING_DIMENSIONS = 1536;
 
-async function ensureVectorIndexes(session) {
+function resolveEmbeddingDimensions(configuration) {
+  const value = configuration && configuration.embeddingDimensions;
+  return Number.isInteger(value) && value > 0 ? value : EMBEDDING_DIMENSIONS;
+}
+
+async function ensureVectorIndexes(session, dimensions = EMBEDDING_DIMENSIONS) {
   for (const definition of Object.values(CHANNEL_INDEXES)) {
     // CREATE ... IF NOT EXISTS cannot change an existing index's dimensions, so
-    // when the approved embedding dimension changes (e.g. 1024 -> 1536) drop the
-    // stale index first and recreate it at the approved dimension.
+    // when the configured embedding dimension changes (e.g. 1024 -> 1536) drop
+    // the stale index first and recreate it at the configured dimension.
     const existing = await executeRead(
       session,
       'SHOW INDEXES YIELD name, type, options WHERE type = \'VECTOR\' AND name = $name RETURN name, options',
@@ -106,7 +111,7 @@ async function ensureVectorIndexes(session) {
     if (existing.records.length > 0) {
       const options = existing.records[0].get('options');
       const dim = options && options.indexConfig && options.indexConfig['vector.dimensions'];
-      if (dim !== EMBEDDING_DIMENSIONS) {
+      if (dim !== dimensions) {
         await executeWrite(session, `DROP INDEX ${definition.indexName} IF EXISTS`, {});
       }
     }
@@ -115,7 +120,7 @@ async function ensureVectorIndexes(session) {
       [
         `CREATE VECTOR INDEX ${definition.indexName} IF NOT EXISTS`,
         `FOR (semantic:${definition.label}) ON (semantic.vector)`,
-        `OPTIONS { indexConfig: { \`vector.dimensions\`: ${EMBEDDING_DIMENSIONS}, \`vector.similarity_function\`: "cosine" } }`,
+        `OPTIONS { indexConfig: { \`vector.dimensions\`: ${dimensions}, \`vector.similarity_function\`: "cosine" } }`,
       ].join('\n'),
       {},
     );
@@ -177,4 +182,5 @@ function cloneRecord(record) {
 
 module.exports = {
   createProductionSemanticNeo4jAdapter,
+  resolveEmbeddingDimensions,
 };

package/argo/scripts/graph-rag/semanticInitConfiguration.js

@@ -0,0 +1,24 @@
+'use strict';
+
+// Maps profile-aware configuration evidence (from resolveApprovedLiveConfiguration)
+// into the shape the canonical semantic-init / backfill runtime consumes.
+//
+// This is the single place that turns "which embedding profile" into the init
+// backfill's configuration, so argo init embeds through the SAME provider the
+// retrieval path uses (approved cloud by default, or a self-hosted endpoint via
+// ARGO_EMBEDDING_PROFILE=openai-compatible) — instead of a hardcoded profile.
+
+function buildDefaultSemanticConfiguration(evidence) {
+  const configuration = evidence && typeof evidence === 'object' && evidence.configuration
+    ? evidence.configuration
+    : evidence;
+  if (!configuration || typeof configuration !== 'object') {
+    throw new TypeError('resolved configuration evidence is required');
+  }
+  return Object.freeze({
+    ...configuration,
+    embeddingCredential: configuration.embeddingApiKey || configuration.qwenKey,
+  });
+}
+
+module.exports = { buildDefaultSemanticConfiguration };

package/argo/scripts/systemarchitecture-mcp-server.js

@@ -144,12 +144,12 @@ const {
 const {
   semanticOperatorErrorResult,
 } = require('./graph-rag/semanticOperatorError.js');
-const {
-  resolveExternalProductionConfig,
-} = require('./graph-rag/externalProductionConfig.js');
 const {
   resolveApprovedLiveConfiguration,
 } = require('./graph-rag/liveEmbeddingProviderConfig.js');
+const {
+  buildDefaultSemanticConfiguration,
+} = require('./graph-rag/semanticInitConfiguration.js');
 const {
   createLiveEmbeddingProviderClient,
 } = require('./graph-rag/liveEmbeddingProviderClient.js');
@@ -4056,59 +4056,17 @@ async function createDefaultProductionSemanticRuntime(options = {}) {
   });
 }
 
+// Resolve the canonical semantic-init/backfill configuration through the SAME
+// profile-aware resolver the retrieval path uses, so argo init embeds via the
+// configured provider (ARGO_EMBEDDING_PROFILE) instead of a hardcoded cloud
+// profile. `resolveApprovedLiveConfiguration` still fails closed when a required
+// key is missing or an unknown key is present in the .env file.
 async function resolveDefaultSemanticConfiguration(repositoryRoot) {
-  let external;
-  try {
-    external = resolveExternalProductionConfig({
-      neo4jUri: process.env.ARGO_NEO4J_DATABASE_URL,
-      neo4jUsername: process.env.ARGO_NEO4J_DATABASE_USERNAME,
-      neo4jPassword: process.env.ARGO_NEO4J_DATABASE_PASSWORD,
-      embeddingCredential: process.env.QWEN_KEY,
-      neo4jDatabase: process.env.ARGO_NEO4J_DATABASE || getDefaultSemanticNeo4jDatabaseName(repositoryRoot),
-    }, {
-      operation: 'semantic-backfill',
-      sourceKeys: new Map([
-        ['neo4jUri', 'ARGO_NEO4J_DATABASE_URL'],
-        ['neo4jUsername', 'ARGO_NEO4J_DATABASE_USERNAME'],
-        ['neo4jPassword', 'ARGO_NEO4J_DATABASE_PASSWORD'],
-        ['embeddingCredential', 'QWEN_KEY'],
-      ]),
-    });
-  } catch (error) {
-    if (error && error.category === 'EXTERNAL_CREDENTIALS_REQUIRED') {
-      const missing = new Error('EXTERNAL_CREDENTIALS_REQUIRED');
-      missing.category = 'EXTERNAL_CREDENTIALS_REQUIRED';
-      missing.field = error.field;
-      throw missing;
-    }
-    throw error;
-  }
-  return Object.freeze({
-    embeddingBaseUrl: W31_APPROVED_PROFILE.baseUrl,
-    embeddingModel: W31_APPROVED_PROFILE.model,
-    embeddingProvider: W31_APPROVED_PROFILE.provider,
-    embeddingModelVersion: W31_APPROVED_PROFILE.version,
-    embeddingDimensions: W31_APPROVED_PROFILE.dimensions,
-    neo4jDatabaseUrl: external.neo4jUri,
-    neo4jDatabaseUsername: external.neo4jUsername,
-    neo4jDatabasePassword: external.neo4jPassword,
-    qwenKey: external.embeddingCredential,
-    embeddingCredential: external.embeddingCredential,
-    ...(external.neo4jDatabase === undefined ? {} : { neo4jDatabase: external.neo4jDatabase }),
+  const evidence = await resolveApprovedLiveConfiguration({
+    repositoryRoot,
+    requiredOptIns: [LIVE_PROVIDER_OPT_IN, W31_LIVE_OPT_IN],
   });
-}
-
-function getDefaultSemanticNeo4jDatabaseName(repositoryRoot) {
-  const repoName = path.basename(repositoryRoot || resolveWorkspaceRoot());
-  const normalized = String(repoName)
-    .toLowerCase()
-    .replace(/[^a-z0-9.-]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .replace(/\.{2,}/g, '.')
-    .replace(/-{2,}/g, '-');
-  const safe = normalized || 'workspace';
-  const prefixed = /^[a-z]/.test(safe) ? safe : `db-${safe}`;
-  return prefixed.slice(0, 63);
+  return buildDefaultSemanticConfiguration(evidence);
 }
 
 function deriveSemanticCanonicalVersion(document) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {