@gmickel/gno 1.12.3 → 1.13.0

package/src/pipeline/vsearch.ts

@@ -18,6 +18,7 @@ import { formatQueryForEmbedding } from "./contextual";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
 import { detectQueryLanguage } from "./query-language";
+import { attachSearchResultContexts } from "./result-context";
 import {
   resolveRecencyTimestamp,
   isWithinTemporalRange,
@@ -333,6 +334,7 @@ export async function searchVectorWithEmbedding(
   }
 
   const finalResults = results.slice(0, limit);
+  await attachSearchResultContexts(store, finalResults);
 
   return ok({
     results: finalResults,

package/src/sdk/client.ts

@@ -40,6 +40,7 @@ import type {
 } from "./types";
 
 import { decorateUriForIndex, getIndexDbPath } from "../app/constants";
+import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import {
   ConfigSchema,
   loadConfig,
@@ -1208,6 +1209,12 @@ class GnoClientImpl implements GnoClient {
 export async function createGnoClient(
   options: GnoClientInitOptions = {}
 ): Promise<GnoClient> {
+  if (options.indexName !== undefined && !isValidIndexName(options.indexName)) {
+    throw sdkError(
+      "VALIDATION",
+      `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`
+    );
+  }
   const state = await resolveClientState(options);
   return new GnoClientImpl(state);
 }

package/src/sdk/types.ts

@@ -46,6 +46,7 @@ export interface GnoClientInitOptions {
   config?: Config;
   configPath?: string;
   dbPath?: string;
+  /** Filesystem-safe index name: 1-64 Unicode letters/marks/numbers plus ` ._-`. */
   indexName?: string;
   cacheDir?: string;
   downloadPolicy?: DownloadPolicy;

package/src/serve/activation-health.ts

@@ -0,0 +1,91 @@
+/** UI-neutral health checks derived from the shared activation contract. */
+
+import type { ActivationStatus } from "../core/activation-status";
+import type { HealthCheck } from "./status-model";
+
+function countLabel(count: number, singular: string): string {
+  return `${count} ${count === 1 ? singular : `${singular}s`}`;
+}
+
+export function buildActivationCheck(
+  activation: ActivationStatus
+): HealthCheck {
+  if (activation.healthy) {
+    const semanticReasons = [
+      ...new Set(
+        activation.collections.map(
+          ({ semanticAvailability }) => semanticAvailability.code
+        )
+      ),
+    ];
+    return {
+      id: "retrieval-activation",
+      title: "Retrieval proof",
+      status: "ok",
+      summary: `${countLabel(activation.collections.length, "folder")} passed lexical retrieval`,
+      detail: `Lexical search is proven. Semantic availability is separate (${semanticReasons.join(", ")}).`,
+      actionLabel: "Run update",
+      actionKind: "sync",
+    };
+  }
+
+  const failed = activation.collections.filter(({ ready }) => !ready);
+  const first = failed[0];
+  const detail = first?.remediation
+    ? `${first.collection}: ${first.remediation.stage}/${first.remediation.code}. Run: ${first.remediation.command}`
+    : "Add and index a supported text collection, then check retrieval again.";
+  return {
+    id: "retrieval-activation",
+    title: "Retrieval proof",
+    status: activation.usable ? "warn" : "error",
+    summary: activation.usable
+      ? `${countLabel(failed.length, "folder")} failed lexical retrieval`
+      : "No folder passed lexical retrieval",
+    detail,
+    actionLabel: "Run update",
+    actionKind: "sync",
+  };
+}
+
+export function buildConnectorActivationCheck(
+  activation: ActivationStatus
+): HealthCheck | null {
+  const { projected, total, truncated } = activation.connectorProjection;
+  const omitted = total - projected;
+  const observed = activation.connectors.filter(
+    ({ code }) =>
+      code !== "connector_not_configured" &&
+      code !== "target_runtime_unverifiable"
+  );
+  if (observed.length === 0 && !truncated) {
+    return null;
+  }
+  const failed = observed.filter(({ status }) => status === "failed");
+  const incomplete = observed.filter(({ status }) => status !== "passed");
+  const first = failed[0] ?? incomplete[0] ?? observed[0];
+  const firstDetail = first
+    ? `${first.target} / ${first.collection}: ${first.status}${first.code ? `/${first.code}` : ""}${first.remediation ? `. ${first.remediation}` : ""}`
+    : null;
+  const projectionDetail = truncated
+    ? `${omitted} target/collection checks were omitted by the bounded status projection; no result is claimed for them.`
+    : null;
+  return {
+    id: "connector-activation",
+    title: "Connector proof",
+    status:
+      failed.length > 0
+        ? "error"
+        : incomplete.length > 0 || truncated
+          ? "warn"
+          : "ok",
+    summary:
+      failed.length > 0
+        ? `${countLabel(failed.length, "connector proof")} failed`
+        : incomplete.length > 0
+          ? `${countLabel(incomplete.length, "connector proof")} incomplete`
+          : truncated
+            ? `${projected} of ${total} connector target/collection checks projected`
+            : `${countLabel(observed.length, "connector proof")} passed`,
+    detail: [projectionDetail, firstDetail].filter(Boolean).join(" "),
+  };
+}

package/src/serve/background-runtime.ts

@@ -1,3 +1,6 @@
+// node:path resolve has no Bun equivalent for canonical process-relative paths.
+import { resolve } from "node:path";
+
 import type { Config } from "../config/types";
 import type { SyncResult } from "../ingestion";
 import type { DocumentEventBus } from "./doc-events";
@@ -9,6 +12,7 @@ import type {
 } from "./watch-service";
 
 import { getIndexDbPath } from "../app/constants";
+import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import {
   ensureDirectories,
   formatConfigWarnings,
@@ -89,6 +93,12 @@ export async function startBackgroundRuntime(
   options: BackgroundRuntimeOptions = {},
   deps: BackgroundRuntimeDeps = {}
 ): Promise<BackgroundRuntimeResult> {
+  if (options.index !== undefined && !isValidIndexName(options.index)) {
+    return {
+      success: false,
+      error: `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`,
+    };
+  }
   const syncAllService = deps.syncAllService
     ? (...args: Parameters<typeof defaultSyncService.syncAll>) =>
         deps.syncAllService!(...args)
@@ -123,7 +133,7 @@ export async function startBackgroundRuntime(
   const store = deps.storeFactory ? deps.storeFactory() : new SqliteAdapter();
   const dbPath = getIndexDbPath(options.index);
   const paths = (deps.getConfigPaths ?? getConfigPaths)();
-  const actualConfigPath = options.configPath ?? paths.configFile;
+  const actualConfigPath = resolve(options.configPath ?? paths.configFile);
   store.setConfigPath(actualConfigPath);
 
   const openResult = await store.open(dbPath, config.ftsTokenizer);

package/src/serve/connectors.ts

@@ -1,14 +1,27 @@
 import type { McpScope, McpTarget } from "../cli/commands/mcp/paths";
 import type { SkillScope, SkillTarget } from "../cli/commands/skill/paths";
+import type {
+  ConnectorVerifierOptions,
+  ConnectorVerificationTarget,
+} from "../core/connector-verifier";
+import type {
+  ActivationVerificationReceipt,
+  StorePort,
+  StoreResult,
+} from "../store/types";
 
 import { installMcpToTarget } from "../cli/commands/mcp/install";
 import {
   buildMcpServerEntry,
   getTargetDisplayName,
 } from "../cli/commands/mcp/paths";
-import { checkMcpTargetStatus } from "../cli/commands/mcp/status";
+import {
+  checkMcpTargetStatus,
+  toMcpConnectorVerificationTarget,
+} from "../cli/commands/mcp/status";
 import { installSkillToTarget } from "../cli/commands/skill/install";
 import { resolveSkillPaths } from "../cli/commands/skill/paths";
+import { verifyConnectorActivation } from "../core/connector-verifier";
 
 export interface ConnectorStatus {
   id: string;
@@ -47,6 +60,75 @@ interface McpConnectorDefinition {
 
 type ConnectorDefinition = SkillConnectorDefinition | McpConnectorDefinition;
 
+interface SkillInspection {
+  installed: boolean;
+  path: string;
+  unavailable: boolean;
+}
+
+interface ConnectorInstallContext {
+  cwd?: string;
+  homeDir?: string;
+  indexName?: string;
+  configPath?: string;
+}
+
+const SKILL_PATH_UNAVAILABLE_ERROR =
+  "Skill path configuration is invalid or unavailable.";
+
+function unresolvedSkillPath(target: SkillTarget): string {
+  return `unresolved-skill-path/${target}`;
+}
+
+async function inspectSkillConnector(
+  definition: SkillConnectorDefinition,
+  overrides?: { cwd?: string; homeDir?: string }
+): Promise<SkillInspection> {
+  try {
+    const paths = resolveSkillPaths({
+      scope: definition.scope,
+      target: definition.target,
+      ...overrides,
+    });
+    return {
+      installed: await Bun.file(`${paths.gnoDir}/SKILL.md`).exists(),
+      path: paths.gnoDir,
+      unavailable: false,
+    };
+  } catch {
+    return {
+      installed: false,
+      path: unresolvedSkillPath(definition.target),
+      unavailable: true,
+    };
+  }
+}
+
+function toSkillVerificationTarget(
+  definition: SkillConnectorDefinition,
+  inspection: SkillInspection
+): ConnectorVerificationTarget {
+  if (inspection.unavailable) {
+    return {
+      kind: "skill",
+      id: definition.id,
+      target: definition.target,
+      scope: definition.scope,
+      configPath: inspection.path,
+      installed: false,
+      configError: true,
+    };
+  }
+  return {
+    kind: "skill",
+    id: definition.id,
+    target: definition.target,
+    scope: definition.scope,
+    configPath: inspection.path,
+    installed: inspection.installed,
+  };
+}
+
 const CONNECTOR_DEFINITIONS: ConnectorDefinition[] = [
   {
     id: "claude-code-skill",
@@ -139,28 +221,29 @@ export async function getConnectorStatuses(overrides?: {
   const statuses = await Promise.all(
     CONNECTOR_DEFINITIONS.map(async (definition) => {
       if (definition.installKind === "skill") {
-        const paths = resolveSkillPaths({
-          scope: definition.scope,
-          target: definition.target,
-          ...overrides,
-        });
-        const skillMdPath = `${paths.gnoDir}/SKILL.md`;
-        const installed = await Bun.file(skillMdPath).exists();
+        const inspection = await inspectSkillConnector(definition, overrides);
         return {
           id: definition.id,
           appName: definition.appName,
           installKind: definition.installKind,
           target: definition.target,
           scope: definition.scope,
-          installed,
-          path: paths.gnoDir,
-          summary: installed
-            ? `${definition.appName} skill is installed.`
-            : `${definition.appName} skill is not installed yet.`,
-          nextAction: installed
-            ? "Restart the agent to reload the skill."
-            : "Install the skill from the app.",
+          installed: inspection.installed,
+          path: inspection.path,
+          summary: inspection.unavailable
+            ? `${definition.appName} skill path is unavailable.`
+            : inspection.installed
+              ? `${definition.appName} skill is installed.`
+              : `${definition.appName} skill is not installed yet.`,
+          nextAction: inspection.unavailable
+            ? "Fix the skill path configuration, then reload status."
+            : inspection.installed
+              ? "Restart the agent to reload the skill."
+              : "Install the skill from the app.",
           mode: definition.mode,
+          ...(inspection.unavailable
+            ? { error: SKILL_PATH_UNAVAILABLE_ERROR }
+            : {}),
         } satisfies ConnectorStatus;
       }
 
@@ -192,12 +275,34 @@ export async function getConnectorStatuses(overrides?: {
   return statuses;
 }
 
+/** Inspect current connector configs without starting any connector runtime. */
+export async function getConnectorVerificationTargets(overrides?: {
+  cwd?: string;
+  homeDir?: string;
+}): Promise<ConnectorVerificationTarget[]> {
+  return Promise.all(
+    CONNECTOR_DEFINITIONS.map(async (definition) => {
+      if (definition.installKind === "skill") {
+        const inspection = await inspectSkillConnector(definition, overrides);
+        return toSkillVerificationTarget(definition, inspection);
+      }
+
+      const status = await checkMcpTargetStatus(
+        definition.target,
+        definition.scope,
+        overrides ?? {}
+      );
+      return toMcpConnectorVerificationTarget(definition.id, status);
+    })
+  );
+}
+
 export async function installConnector(
   id: string,
   options?: {
     reinstall?: boolean;
   },
-  overrides?: { cwd?: string; homeDir?: string }
+  overrides?: ConnectorInstallContext
 ): Promise<ConnectorStatus> {
   const definition = CONNECTOR_DEFINITIONS.find((entry) => entry.id === id);
   if (!definition) {
@@ -220,14 +325,21 @@ export async function installConnector(
       overrides
     );
   } else {
+    const targetOverrides = overrides
+      ? { cwd: overrides.cwd, homeDir: overrides.homeDir }
+      : undefined;
     await installMcpToTarget(
       definition.target,
       definition.scope,
-      buildMcpServerEntry({ enableWrite: false }),
+      buildMcpServerEntry({
+        enableWrite: false,
+        indexName: overrides?.indexName,
+        configPath: overrides?.configPath,
+      }),
       {
         force: options?.reinstall ?? false,
         dryRun: false,
-        ...overrides,
+        ...targetOverrides,
       }
     );
   }
@@ -253,3 +365,36 @@ export function getConnectorDisplayName(id: string): string {
 
   return definition.appName;
 }
+
+/**
+ * Resolve and verify one connector without editing its client configuration.
+ * Kept separate from passive status listing because this starts a local MCP
+ * child and performs a real, collection-scoped retrieval smoke.
+ */
+export async function verifyInstalledConnector(
+  id: string,
+  store: StorePort,
+  collection: string,
+  options?: ConnectorVerifierOptions,
+  overrides?: { cwd?: string; homeDir?: string }
+): Promise<StoreResult<ActivationVerificationReceipt>> {
+  const definition = CONNECTOR_DEFINITIONS.find((entry) => entry.id === id);
+  if (!definition) {
+    throw new Error(`Unknown connector: ${id}`);
+  }
+
+  let target: ConnectorVerificationTarget;
+  if (definition.installKind === "skill") {
+    const inspection = await inspectSkillConnector(definition, overrides);
+    target = toSkillVerificationTarget(definition, inspection);
+  } else {
+    const status = await checkMcpTargetStatus(
+      definition.target,
+      definition.scope,
+      overrides ?? {}
+    );
+    target = toMcpConnectorVerificationTarget(definition.id, status);
+  }
+
+  return verifyConnectorActivation(store, collection, target, options);
+}

package/src/serve/public/components/BootstrapStatus.tsx

@@ -1,4 +1,6 @@
 import {
+  AlertCircleIcon,
+  CheckCircle2Icon,
   DownloadIcon,
   HardDriveIcon,
   PackageIcon,
@@ -7,6 +9,7 @@ import {
 
 import type { AppStatusResponse } from "../../status-model";
 
+import { buildConnectorActivationCheck } from "../../activation-health";
 import { Button } from "./ui/button";
 import {
   Card,
@@ -18,6 +21,7 @@ import {
 
 interface BootstrapStatusProps {
   bootstrap: AppStatusResponse["bootstrap"];
+  activation: AppStatusResponse["activation"];
   onDownloadModels: () => void;
 }
 
@@ -37,11 +41,21 @@ function formatRole(
 }
 
 export function BootstrapStatus({
+  activation,
   bootstrap,
   onDownloadModels,
 }: BootstrapStatusProps) {
   const missingModels =
     bootstrap.models.totalCount - bootstrap.models.cachedCount;
+  const displayedConnectorCount = Math.min(activation.connectors.length, 8);
+  const hiddenProjectedConnectorCount =
+    activation.connectorProjection.projected - displayedConnectorCount;
+  const omittedConnectorCount =
+    activation.connectorProjection.total -
+    activation.connectorProjection.projected;
+  const connectorHealth = buildConnectorActivationCheck(activation);
+  const connectorsHealthy =
+    connectorHealth === null || connectorHealth.status === "ok";
 
   return (
     <section className="space-y-4">
@@ -64,7 +78,7 @@ export function BootstrapStatus({
         )}
       </div>
 
-      <div className="grid gap-4 xl:grid-cols-3">
+      <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
         <Card className="border-border/60 bg-card/70">
           <CardHeader className="pb-3">
             <div className="flex items-center gap-2">
@@ -127,6 +141,85 @@ export function BootstrapStatus({
             </div>
           </CardContent>
         </Card>
+
+        <Card className="border-border/60 bg-card/70">
+          <CardHeader className="pb-3">
+            <div className="flex items-center gap-2">
+              {activation.healthy && connectorsHealthy ? (
+                <CheckCircle2Icon className="size-4 text-emerald-500" />
+              ) : activation.usable ? (
+                <ServerCogIcon className="size-4 text-amber-500" />
+              ) : (
+                <AlertCircleIcon className="size-4 text-destructive" />
+              )}
+              <CardTitle className="text-base">Retrieval proof</CardTitle>
+            </div>
+            <CardDescription>
+              {activation.healthy
+                ? "Lexical retrieval proven"
+                : activation.usable
+                  ? `Search usable in ${activation.collections.filter(({ ready }) => ready).length}/${activation.collections.length} folders`
+                  : "Retrieval proof failed"}
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-3 text-sm">
+            {activation.collections.length === 0 ? (
+              <p className="text-muted-foreground">
+                Add and index a text folder to prove retrieval.
+              </p>
+            ) : (
+              activation.collections.map((collection) => (
+                <div
+                  className="rounded-lg border border-border/50 px-3 py-2"
+                  key={collection.collection}
+                >
+                  <p className="font-medium">{collection.collection}</p>
+                  <p className="text-muted-foreground text-xs">
+                    {collection.ready
+                      ? `Lexical passed; semantic ${collection.semanticAvailability.code}`
+                      : `${collection.remediation?.stage ?? "index"}/${collection.remediation?.code ?? "index_query_failed"}`}
+                  </p>
+                  {collection.remediation && (
+                    <p className="mt-1 font-mono text-muted-foreground text-xs">
+                      {collection.remediation.command}
+                    </p>
+                  )}
+                </div>
+              ))
+            )}
+            {(activation.connectors.length > 0 ||
+              activation.connectorProjection.truncated) && (
+              <div className="space-y-2 border-border/50 border-t pt-3">
+                <p className="font-medium text-xs uppercase tracking-wide">
+                  Connector proof
+                </p>
+                {activation.connectors.slice(0, 8).map((connector) => (
+                  <div
+                    className="text-muted-foreground text-xs"
+                    key={`${connector.collection}-${connector.target}`}
+                  >
+                    <span className="font-medium text-foreground">
+                      {connector.target}
+                    </span>{" "}
+                    · {connector.collection} · {connector.status}
+                    {connector.code ? `/${connector.code}` : ""}
+                  </div>
+                ))}
+                {hiddenProjectedConnectorCount > 0 && (
+                  <p className="text-muted-foreground text-xs">
+                    +{hiddenProjectedConnectorCount} more projected checks
+                  </p>
+                )}
+                {activation.connectorProjection.truncated && (
+                  <p className="text-muted-foreground text-xs">
+                    {omittedConnectorCount} additional target/collection checks
+                    omitted from this bounded status view
+                  </p>
+                )}
+              </div>
+            )}
+          </CardContent>
+        </Card>
       </div>
     </section>
   );

package/src/serve/public/components/FirstRunWizard.tsx

@@ -204,10 +204,8 @@ export function FirstRunWizard({
   onboarding,
   onAddCollection,
   onDownloadModels,
-  onEmbed,
   onSync,
   onSyncComplete,
-  embedding = false,
   syncJobId = null,
   syncing = false,
 }: FirstRunWizardProps) {
@@ -238,27 +236,19 @@ export function FirstRunWizard({
       : null;
   const progressValue = getStepProgress(onboarding);
   const isShowingRecommended = activeStep?.id === recommendedStepId;
-  const indexingNeedsEmbeddings =
-    onboarding.stage === "indexing" &&
-    onboarding.detail.toLowerCase().includes("embedding");
-
   const runRecommendedAction = () => {
     if (!activeStep) {
       return;
     }
-    if (activeStep.id === "folders") {
+    if (activeStep.action === "add-collection") {
       onAddCollection();
       return;
     }
-    if (activeStep.id === "models") {
+    if (activeStep.action === "download-models") {
       onDownloadModels();
       return;
     }
-    if (activeStep.id === "indexing" && indexingNeedsEmbeddings && !embedding) {
-      onEmbed();
-      return;
-    }
-    if (activeStep.id === "indexing" && !syncing) {
+    if (activeStep.action === "sync" && !syncing) {
       onSync();
     }
   };
@@ -403,7 +393,7 @@ export function FirstRunWizard({
         <WizardPanel>
           <WizardPanelHeader
             badge={<Badge variant="outline">Safe to rerun</Badge>}
-            title="Finish first indexing"
+            title="Prove lexical retrieval"
           >
             <p className="max-w-2xl text-muted-foreground text-sm leading-6">
               {activeStep.detail}
@@ -419,31 +409,13 @@ export function FirstRunWizard({
 
         <WizardActionPanel
           action={
-            <Button
-              disabled={indexingNeedsEmbeddings ? embedding : syncing}
-              onClick={indexingNeedsEmbeddings ? onEmbed : onSync}
-              size="lg"
-            >
+            <Button disabled={syncing} onClick={onSync} size="lg">
               <RefreshCwIcon className="mr-2 size-4" />
-              {indexingNeedsEmbeddings
-                ? embedding
-                  ? "Embedding..."
-                  : "Finish embeddings"
-                : syncing
-                  ? "Syncing..."
-                  : "Run first sync"}
+              {syncing ? "Syncing..." : "Run first sync"}
             </Button>
           }
-          body={
-            indexingNeedsEmbeddings
-              ? "Your files are indexed. One more embedding pass will unlock semantic search and local answers."
-              : "Good last step before you move into normal use."
-          }
-          title={
-            indexingNeedsEmbeddings
-              ? "Finish semantic indexing"
-              : "Index the current workspace"
-          }
+          body="Builds the local lexical index and proves that this exact folder can return corpus-derived evidence."
+          title="Index and verify the current workspace"
         />
 
         {syncJobId && (
@@ -451,7 +423,7 @@ export function FirstRunWizard({
             <WizardPanelHeader title="Sync progress">
               <p className="max-w-2xl text-muted-foreground text-sm leading-6">
                 Your first indexing run is in progress. The wizard will advance
-                once the job finishes and embeddings catch up.
+                once the job finishes and lexical retrieval is proven.
               </p>
             </WizardPanelHeader>
             <div style={{ padding: "24px 28px" }}>
@@ -568,24 +540,14 @@ export function FirstRunWizard({
             </div>
             {activeStep && activeStep.id !== "preset" && (
               <Button
-                disabled={
-                  activeStep.id === "indexing"
-                    ? indexingNeedsEmbeddings
-                      ? embedding
-                      : syncing
-                    : false
-                }
+                disabled={activeStep.action === "sync" ? syncing : false}
                 onClick={runRecommendedAction}
                 size="sm"
                 variant={isShowingRecommended ? "default" : "outline"}
               >
-                {activeStep.id === "indexing" && indexingNeedsEmbeddings
-                  ? embedding
-                    ? "Embedding..."
-                    : "Finish embeddings"
-                  : activeStep.id === "indexing" && syncing
-                    ? "Syncing..."
-                    : getStepActionLabel(activeStep.id)}
+                {activeStep.action === "sync" && syncing
+                  ? "Syncing..."
+                  : getStepActionLabel(activeStep.id)}
               </Button>
             )}
           </div>