fix(mode): explain stale cloud storage migration

bin/knowledge-mcp.js

@@ -16360,7 +16360,7 @@ function resolveKnowledgeModeSelection(env = process.env) {
       normalized = normalizeStorageMode3(value);
     } catch (error51) {
       const message = error51 instanceof Error ? error51.message : String(error51);
-      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message}`);
+      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message} ` + `Unset ${name} to use the default sqlite backend, or set ${name}=sqlite or ${name}=postgres.`);
     }
     const warnings = [];
     if (name !== canonicalModeKey) {

dist/index.js

@@ -16458,7 +16458,7 @@ function resolveKnowledgeModeSelection(env = process.env) {
       normalized = normalizeStorageMode3(value);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message}`);
+      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message} ` + `Unset ${name} to use the default sqlite backend, or set ${name}=sqlite or ${name}=postgres.`);
     }
     const warnings = [];
     if (name !== canonicalModeKey) {

dist/storage.js

@@ -1588,7 +1588,7 @@ function resolveKnowledgeModeSelection(env = process.env) {
       normalized = normalizeStorageMode3(value);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message}`);
+      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message} ` + `Unset ${name} to use the default sqlite backend, or set ${name}=sqlite or ${name}=postgres.`);
     }
     const warnings = [];
     if (name !== canonicalModeKey) {

src/knowledge-mode.ts

@@ -122,7 +122,10 @@ export function resolveKnowledgeModeSelection(env: NodeJS.ProcessEnv = process.e
       normalized = normalizeVendoredMode(value);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`knowledge: ${name}=${value} is not a valid mode. ${message}`);
+      throw new Error(
+        `knowledge: ${name}=${value} is not a valid mode. ${message} `
+          + `Unset ${name} to use the default sqlite backend, or set ${name}=sqlite or ${name}=postgres.`,
+      );
     }
     const warnings: string[] = [];
     if (name !== canonicalModeKey) {

tests/cli.test.ts

@@ -3778,6 +3778,38 @@ describe('a half-configured CLI fails loudly instead of reading the wrong store'
     expect(combined).not.toContain(FAKE_API_URL);
   });
 
+  test('REGRESSION: a removed cloud mode names the unset migration path', () => {
+    const result = runCliNoMode(
+      ['list', '--tag', 'convention', '--limit', '40', '--sort', 'created', '--desc', '--json'],
+      {
+        ...sandboxHome(),
+        HASNA_KNOWLEDGE_STORAGE_MODE: 'cloud',
+      },
+    );
+    const stderr = decode(result.stderr);
+
+    expect(result.exitCode).not.toBe(0);
+    expect(stderr).toContain('HASNA_KNOWLEDGE_STORAGE_MODE=cloud');
+    expect(stderr).toContain('Unset HASNA_KNOWLEDGE_STORAGE_MODE');
+  });
+
+  test('the exact convention read defaults to sqlite after the removed mode is absent', () => {
+    const args = ['list', '--tag', 'convention', '--limit', '40', '--sort', 'created', '--desc', '--json'];
+    const result = runCliNoMode(args, sandboxHome());
+    expect(result.exitCode).toBe(0);
+    expect((JSON.parse(decode(result.stdout)) as { ok: boolean }).ok).toBe(true);
+  });
+
+  test('the exact convention read still succeeds with explicit sqlite', () => {
+    const args = ['list', '--tag', 'convention', '--limit', '40', '--sort', 'created', '--desc', '--json'];
+    const result = runCliNoMode(args, {
+      ...sandboxHome(),
+      HASNA_KNOWLEDGE_STORAGE_MODE: 'sqlite',
+    });
+    expect(result.exitCode).toBe(0);
+    expect((JSON.parse(decode(result.stdout)) as { ok: boolean }).ok).toBe(true);
+  });
+
   test('`mode` still answers in the environment the guard rejects', () => {
     // The command whose entire job is explaining this state must survive it,
     // or the error message points at a diagnostic that also fails.