@okfit/mcp 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,21 +1,735 @@
-//#region src/index.d.ts
+import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
+import { AppDirs, Xdg } from "@effected/xdg";
+import { LoadedConcept } from "@okfit/core";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { Toolkit } from "effect/unstable/ai";
+//#region src/errors.d.ts
+/** What a caller should do next about a failed tool call. @public */
+export declare const Remediation: Schema.Struct<{
+  readonly hint: Schema.String;
+  readonly suggestedTool: Schema.optionalKey<Schema.String>;
+}>;
+/** @public */
+export type Remediation = typeof Remediation.Type;
 /**
- * Model Context Protocol server for okfit.
+ * Compose a self-contained wire message from a raw cause message and its
+ * remediation: the human message, then the hint, then `Try <suggestedTool>.`
+ * when one is present. Every `McpToolError` member's `message` field is
+ * built through this at construction — under `failureMode: "error"` (the
+ * only mode this contract's tools use), `McpServer`'s own `registerToolkit`
+ * collapses a caught typed failure to
+ * `{ isError: true, content: [{ type: "text", text: error.message }] }`
+ * and never surfaces `structuredContent` for it
+ * (`.repos/effect/packages/effect/src/unstable/ai/McpServer.ts:1502-1506,1576-1584`,
+ * confirmed empirically in Task B1's own build). `remediation` itself is
+ * left on the schema unchanged, both for anything that inspects the typed
+ * error directly (a defect handler, a future in-process caller) and
+ * because it is what this function reads to build `message`.
  *
- * @packageDocumentation
+ * @public
+ */
+export declare const composeRemediatedMessage: (message: string, remediation: Remediation) => string;
+/**
+ * Truncate a caller-supplied value before it is echoed back inside an
+ * error's `message` — the only field a `failureMode: "error"` failure
+ * actually delivers to the wire (see {@link composeRemediatedMessage}'s
+ * doc comment). Without this, a pathological argument (a multi-megabyte
+ * `id`, say) is echoed once in the response's `content[0].text` and once
+ * more in the corresponding log line, wasting an agent's context on what
+ * is usually a pure typo (final whole-branch review, Minor finding 5).
+ *
+ * @public
+ */
+export declare const truncateEchoed: (value: string, limit?: number) => string;
+declare const ConfigError_base: Schema.Class<ConfigError, Schema.TaggedStruct<"ConfigError", {
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Config discovery, parsing, or validation failed. `message` is composed
+ * through {@link composeRemediatedMessage} at construction, so it is what
+ * reaches the wire as `tools/call`'s `content[0].text` (see that
+ * function's doc comment for why). @public
+ */
+export declare class ConfigError extends ConfigError_base {}
+declare const BundleNotFound_base: Schema.Class<BundleNotFound, Schema.TaggedStruct<"BundleNotFound", {
+  readonly root: Schema.String;
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The configured bundle root does not exist or could not be read.
+ * `message` is composed through {@link composeRemediatedMessage} at
+ * construction, so it is what reaches the wire as `tools/call`'s
+ * `content[0].text`. @public
+ */
+export declare class BundleNotFound extends BundleNotFound_base {}
+declare const ConceptNotFound_base: Schema.Class<ConceptNotFound, Schema.TaggedStruct<"ConceptNotFound", {
+  readonly id: Schema.String;
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * No concept in the bundle has the requested id. `message` is composed
+ * through {@link composeRemediatedMessage} at construction, so it is what
+ * reaches the wire as `tools/call`'s `content[0].text`. @public
+ */
+export declare class ConceptNotFound extends ConceptNotFound_base {}
+declare const UnknownVocabulary_base: Schema.Class<UnknownVocabulary, Schema.TaggedStruct<"UnknownVocabulary", {
+  readonly kind: Schema.Literals<readonly ["type", "tag"]>;
+  readonly requested: Schema.String;
+  readonly valid: Schema.$Array<Schema.String>;
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A requested type or tag name is not declared in the resolved config.
+ * `message` is composed through {@link composeRemediatedMessage} at
+ * construction, so it is what reaches the wire as `tools/call`'s
+ * `content[0].text`. @public
+ */
+export declare class UnknownVocabulary extends UnknownVocabulary_base {}
+declare const InvalidArgument_base: Schema.Class<InvalidArgument, Schema.TaggedStruct<"InvalidArgument", {
+  readonly argument: Schema.String;
+  readonly message: Schema.String;
+  readonly remediation: Schema.Struct<{
+    readonly hint: Schema.String;
+    readonly suggestedTool: Schema.optionalKey<Schema.String>;
+  }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A tool argument was structurally acceptable but semantically invalid.
+ * `message` is composed through {@link composeRemediatedMessage} at
+ * construction, so it is what reaches the wire as `tools/call`'s
+ * `content[0].text`. @public
+ */
+export declare class InvalidArgument extends InvalidArgument_base {}
+/** The one failure schema every tool declares (N-14). @public */
+export declare const McpToolError: Schema.Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+/** @public */
+export type McpToolError = typeof McpToolError.Type;
+//#endregion
+//#region src/resources/conceptResource.d.ts
+/**
+ * `okf://concept/<id>` — one static resource per concept in the bundle,
+ * built once at server start.
+ *
+ * Amends N-19 and contract §6.1 (Ruling, task C4): a `McpServer.resource`
+ * URI **template** routes a `McpSchema.param` through a single path
+ * segment only — `FindMyWay`'s parametric matcher stops a param at the
+ * next `/` (`.repos/effect/packages/effect/src/unstable/http/FindMyWay/internal/router.ts:355-360`),
+ * and every non-root OKF concept id nests under a type directory (D-12),
+ * e.g. `metrics/revenue`. A templated `okf://concept/{id}` therefore never
+ * routes a real bundle id. Static per-concept resources sidestep the
+ * router entirely: each concept gets its own literal `uri`, so there is
+ * no segment-spanning to fail.
+ *
+ * The list is fixed at server start (`loadToolContext` runs once, inside
+ * `Layer.unwrap`, not per read): a concept added after boot is not listed
+ * until the server restarts, though editing an already-listed concept's
+ * file is picked up live, since `content` re-reads the file from disk on
+ * every read (same complete text `get_concept`'s `raw` field returns).
+ *
+ * If the bundle fails to load at boot (bad config, missing bundle root),
+ * one line is logged and this layer contributes no resources — the
+ * six tools stay usable; only `okf://index` remains, since it is
+ * registered independently and re-resolves the bundle on every read.
+ *
+ * `content` builds the full `ReadResourceResult` itself, `mimeType`
+ * included, rather than returning a bare string: verified against source
+ * (`resolveResourceContent`, `unstable/ai/McpServer.ts:2324-2343`), a bare
+ * string is wrapped as `{ contents: [{ uri, text }] }` with no `mimeType`
+ * at all — the declared `mimeType` option only documents the resource in
+ * `resources/list`, it is never merged into a `resources/read` response.
+ *
+ * @public
+ */
+export declare const ConceptResources: (projectRoot: string) => Layer.Layer<never, never, FileSystem.FileSystem | Path.Path | AppDirs | Xdg>;
+//#endregion
+//#region src/resources/indexResource.d.ts
+/**
+ * `okf://index` — the bundle's root `index.md`, read from disk.
+ *
+ * This reads the file from disk, deliberately (J-7): `IndexDocument`
+ * carries only `{ path, dir, okfVersion?, sections }` — no raw-source
+ * field at all — so `bundle.indexes.get("")` cannot supply the raw
+ * markdown N-19 asks for. Reading the file also means a root `index.md`
+ * that failed to parse is still served, which is the more useful
+ * behaviour for an agent trying to fix it.
+ *
+ * A missing `index.md` fails the read rather than returning placeholder
+ * text (J-8): a resource that silently returns prose instead of the file
+ * it names is indistinguishable, to a model, from a bundle whose index
+ * really says that; §6.1 already fails an unknown id through the same
+ * channel.
+ *
+ * `content` builds the full `ReadResourceResult` itself, `mimeType`
+ * included, rather than returning a bare string: verified against source
+ * (`resolveResourceContent`, `unstable/ai/McpServer.ts:2324-2343`), a bare
+ * string is wrapped as `{ contents: [{ uri, text }] }` with no `mimeType`
+ * at all — the declared `mimeType` option only documents the resource in
+ * `resources/list`, it is never merged into a `resources/read` response.
+ *
+ * @public
+ */
+export declare const IndexResource: (projectRoot: string) => import("effect/Layer").Layer<never, never, import("@effected/xdg").AppDirs | FileSystem.FileSystem | Path.Path | import("@effected/xdg").Xdg>;
+//#endregion
+//#region src/schema/ConceptSummary.d.ts
+/** The seven-field shape every list-like tool result carries (N-16). @public */
+export declare const ConceptSummary: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly type: Schema.String;
+  readonly title: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+  readonly tags: Schema.$Array<Schema.String>;
+  readonly path: Schema.String;
+}>;
+/** @public */
+export type ConceptSummary = typeof ConceptSummary.Type;
+/** Project one loaded concept into its summary. @public */
+export declare const toConceptSummary: (concept: LoadedConcept) => ConceptSummary;
+//#endregion
+//#region src/schema/tools.d.ts
+/** `describe_vocabulary`'s result (§5.2). @public */
+export declare const DescribeVocabularySuccess: Schema.Struct<{
+  readonly project_root: Schema.String;
+  readonly bundle_root: Schema.String;
+  readonly config_path: Schema.NullOr<Schema.String>;
+  readonly profile: Schema.NullOr<Schema.String>;
+  readonly profile_requested: Schema.NullOr<Schema.String>;
+  readonly agent: Schema.NullOr<Schema.String>;
+  readonly types: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly guidance: Schema.NullOr<Schema.String>;
+  }>>;
+  readonly tags: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+  }>>;
+}>;
+/** @public */
+export type DescribeVocabularySuccess = typeof DescribeVocabularySuccess.Type;
+/** `list_concepts`' arguments (§5.3). @public */
+export declare const ListConceptsParams: Schema.Struct<{
+  readonly type: Schema.optionalKey<Schema.String>;
+  readonly tags: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly status: Schema.optionalKey<Schema.Literals<readonly ["draft", "stable", "deprecated"]>>;
+  readonly limit: Schema.optionalKey<Schema.Int>;
+  readonly offset: Schema.optionalKey<Schema.Int>;
+}>;
+/** @public */
+export type ListConceptsParams = typeof ListConceptsParams.Type;
+/** `list_concepts`' result: the page, plus the match count before paging. @public */
+export declare const ListConceptsSuccess: Schema.Struct<{
+  readonly items: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly type: Schema.String;
+    readonly title: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly path: Schema.String;
+  }>>;
+  readonly total: Schema.Int;
+}>;
+/** @public */
+export type ListConceptsSuccess = typeof ListConceptsSuccess.Type;
+/** `get_concept`'s result (§5.4). @public */
+export declare const GetConceptSuccess: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly type: Schema.String;
+  readonly title: Schema.String;
+  readonly description: Schema.NullOr<Schema.String>;
+  readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+  readonly tags: Schema.$Array<Schema.String>;
+  readonly path: Schema.String;
+  readonly frontmatter: Schema.$Record<Schema.String, Schema.Unknown>;
+  readonly raw: Schema.String;
+  readonly links: Schema.$Array<Schema.Struct<{
+    readonly to: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+    readonly source: Schema.Literals<readonly ["body", "frontmatter"]>;
+    readonly field: Schema.optionalKey<Schema.String>;
+  }>>;
+}>;
+/** @public */
+export type GetConceptSuccess = typeof GetConceptSuccess.Type;
+/** One graph neighbour: flat, with a nullable summary (J-4). @public */
+export declare const Neighbor: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+  readonly summary: Schema.NullOr<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly type: Schema.String;
+    readonly title: Schema.String;
+    readonly description: Schema.NullOr<Schema.String>;
+    readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+    readonly tags: Schema.$Array<Schema.String>;
+    readonly path: Schema.String;
+  }>>;
+}>;
+/** @public */
+export type Neighbor = typeof Neighbor.Type;
+/** `concept_neighbors`' result (§5.5). @public */
+export declare const ConceptNeighborsSuccess: Schema.Struct<{
+  readonly outgoing: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+    readonly summary: Schema.NullOr<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly type: Schema.String;
+      readonly title: Schema.String;
+      readonly description: Schema.NullOr<Schema.String>;
+      readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: Schema.$Array<Schema.String>;
+      readonly path: Schema.String;
+    }>>;
+  }>>;
+  readonly incoming: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["concept", "file", "missing"]>;
+    readonly summary: Schema.NullOr<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly type: Schema.String;
+      readonly title: Schema.String;
+      readonly description: Schema.NullOr<Schema.String>;
+      readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: Schema.$Array<Schema.String>;
+      readonly path: Schema.String;
+    }>>;
+  }>>;
+}>;
+/** @public */
+export type ConceptNeighborsSuccess = typeof ConceptNeighborsSuccess.Type;
+/** `stale_report`'s arguments: an optional ISO instant, decoded in the handler (J-5). @public */
+export declare const StaleReportParams: Schema.Struct<{
+  readonly now: Schema.optionalKey<Schema.String>;
+}>;
+/** @public */
+export type StaleReportParams = typeof StaleReportParams.Type;
+/** `stale_report`'s result (§5.6). @public */
+export declare const StaleReportSuccess: Schema.Struct<{
+  readonly as_of: Schema.String;
+  readonly items: Schema.$Array<Schema.Struct<{
+    readonly summary: Schema.Struct<{
+      readonly id: Schema.String;
+      readonly type: Schema.String;
+      readonly title: Schema.String;
+      readonly description: Schema.NullOr<Schema.String>;
+      readonly status: Schema.Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: Schema.$Array<Schema.String>;
+      readonly path: Schema.String;
+    }>;
+    readonly stale_after: Schema.String;
+    readonly days_past: Schema.Int;
+  }>>;
+}>;
+/** @public */
+export type StaleReportSuccess = typeof StaleReportSuccess.Type;
+/** `validate_bundle`'s arguments: the same shape and decode path as stale_report. @public */
+export declare const ValidateBundleParams: Schema.Struct<{
+  readonly now: Schema.optionalKey<Schema.String>;
+}>;
+/** @public */
+export type ValidateBundleParams = typeof ValidateBundleParams.Type;
+//#endregion
+//#region src/server.d.ts
+/**
+ * Everything `ServerLayer` still needs from the platform: the four services
+ * `describe_vocabulary`'s declared `Tool.make` dependencies pull through
+ * `McpServer.toolkit`'s own `Tool.HandlerServices<Tools>` requirement, plus
+ * `Stdio`, which `McpServer.layerStdio` itself requires
+ * (`unstable/ai/McpServer.ts:1207-1216`) and which the brief's own
+ * `PlatformServices` literal omitted.
+ *
+ * `ChildProcessSpawner` is new (contract §10.3, S-16): `validate_bundle`'s
+ * `Git`/`GitHistory` dependencies (`tools/validateBundle.ts`) are
+ * discharged right here, below, by `Layer.mergeAll(Git.layer, GitHistory.layer)`
+ * — both need only `ChildProcessSpawner` (`GitHistory.layer` itself provides
+ * `Git.layer` internally, `packages/profiles/src/GitHistory.ts:136`), which
+ * `bin.ts`'s untouched `PlatformLayer` already supplies via
+ * `NodeServices.layer`. This type widening is the only thing that changes
+ * at that boundary — `bin.ts` itself is not touched by this task.
+ *
+ * @public
  */
+type PlatformServices = FileSystem.FileSystem | Path.Path | AppDirs | Xdg | Stdio.Stdio | ChildProcessSpawner.ChildProcessSpawner;
 /**
- * Message the stub bin writes to stderr until the server exists.
+ * The whole server as one layer: the toolkit, one static resource per
+ * concept (`okf://concept/<id>`, built once at boot — see
+ * {@link ConceptResources}), and `okf://index` (re-read from disk on every
+ * call), over `McpServer.layerStdio`.
+ *
+ * `protocols` ships BOTH adapters, newest first (N-2). Array order is
+ * load-bearing: the protocol registry falls back to `protocols[0]` for an
+ * unrecognised client version, so a 2026-07-28 client is answered with
+ * 2025-11-25. Never reduce this to one entry.
+ *
+ * `Cause.IllegalArgumentError` in `layerStdio`'s signature is left
+ * unhandled: `protocols` is a static two-element literal, so it is an
+ * implementer-time defect, not a runtime condition.
  *
  * @public
  */
-declare const NOT_IMPLEMENTED_MESSAGE = "okfit-mcp: the MCP server is not implemented yet. Track progress at https://github.com/spencerbeggs/okfit.";
+export declare const ServerLayer: (projectRoot: string) => Layer.Layer<never, never, PlatformServices>;
+//#endregion
+//#region src/toolkit.d.ts
+/**
+ * The six read-only tools (N-10). Tasks C1, C2 and C3 each add two; the
+ * order here is the tool set's own order and is what
+ * `agents/okf-docs.md`'s `tools:` allowlist mirrors.
+ *
+ * @public
+ */
+export declare const OkfitToolkit: Toolkit.Toolkit<{
+  readonly concept_neighbors: import("effect/unstable/ai/Tool").Tool<"concept_neighbors", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly outgoing: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly summary: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>>;
+      }>>;
+      readonly incoming: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly summary: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly describe_vocabulary: import("effect/unstable/ai/Tool").Tool<"describe_vocabulary", {
+    readonly parameters: import("effect/unstable/ai/Tool").EmptyParams;
+    readonly success: import("effect/Schema").Struct<{
+      readonly project_root: import("effect/Schema").String;
+      readonly bundle_root: import("effect/Schema").String;
+      readonly config_path: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly profile_requested: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly agent: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly types: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+        readonly guidance: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      }>>;
+      readonly tags: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly get_concept: import("effect/unstable/ai/Tool").Tool<"get_concept", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+      readonly type: import("effect/Schema").String;
+      readonly title: import("effect/Schema").String;
+      readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+      readonly path: import("effect/Schema").String;
+      readonly frontmatter: import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>;
+      readonly raw: import("effect/Schema").String;
+      readonly links: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly to: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly source: import("effect/Schema").Literals<readonly ["body", "frontmatter"]>;
+        readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly list_concepts: import("effect/unstable/ai/Tool").Tool<"list_concepts", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly type: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+      readonly tags: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
+      readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>>;
+      readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+      readonly offset: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly items: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly type: import("effect/Schema").String;
+        readonly title: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+        readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+        readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+        readonly path: import("effect/Schema").String;
+      }>>;
+      readonly total: import("effect/Schema").Int;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly stale_report: import("effect/unstable/ai/Tool").Tool<"stale_report", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly as_of: import("effect/Schema").String;
+      readonly items: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly summary: import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>;
+        readonly stale_after: import("effect/Schema").String;
+        readonly days_past: import("effect/Schema").Int;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly validate_bundle: import("effect/unstable/ai/Tool").Tool<"validate_bundle", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly schema: import("effect/Schema").Literal<1>;
+      readonly okfit_version: import("effect/Schema").String;
+      readonly okf_version: import("effect/Schema").String;
+      readonly root: import("effect/Schema").String;
+      readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly exit_code: import("effect/Schema").Literals<readonly [0, 1, 2]>;
+      readonly summary: import("effect/Schema").Struct<{
+        readonly conformance_errors: import("effect/Schema").Number;
+        readonly lint_errors: import("effect/Schema").Number;
+        readonly lint_warnings: import("effect/Schema").Number;
+        readonly lint_info: import("effect/Schema").Number;
+        readonly profile_errors: import("effect/Schema").Number;
+        readonly concepts: import("effect/Schema").Number;
+      }>;
+      readonly diagnostics: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly source: import("effect/Schema").Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+        readonly file: import("effect/Schema").String;
+        readonly code: import("effect/Schema").String;
+        readonly severity: import("effect/Schema").Literals<readonly ["error", "warning", "info"]>;
+        readonly message: import("effect/Schema").String;
+        readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+}>;
+/**
+ * The handler layer. `projectRoot` is closed over from the bin (N-21);
+ * the bundle itself reloads on every call inside each handler (N-9).
+ *
+ * @public
+ */
+export declare const ToolsLayer: (projectRoot: string) => import("effect/Layer").Layer<import("effect/unstable/ai/Tool").HandlersFor<{
+  readonly concept_neighbors: import("effect/unstable/ai/Tool").Tool<"concept_neighbors", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly outgoing: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly summary: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>>;
+      }>>;
+      readonly incoming: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly summary: import("effect/Schema").NullOr<import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly describe_vocabulary: import("effect/unstable/ai/Tool").Tool<"describe_vocabulary", {
+    readonly parameters: import("effect/unstable/ai/Tool").EmptyParams;
+    readonly success: import("effect/Schema").Struct<{
+      readonly project_root: import("effect/Schema").String;
+      readonly bundle_root: import("effect/Schema").String;
+      readonly config_path: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly profile_requested: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly agent: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly types: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+        readonly guidance: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      }>>;
+      readonly tags: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly name: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly get_concept: import("effect/unstable/ai/Tool").Tool<"get_concept", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly id: import("effect/Schema").String;
+      readonly type: import("effect/Schema").String;
+      readonly title: import("effect/Schema").String;
+      readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+      readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+      readonly path: import("effect/Schema").String;
+      readonly frontmatter: import("effect/Schema").$Record<import("effect/Schema").String, import("effect/Schema").Unknown>;
+      readonly raw: import("effect/Schema").String;
+      readonly links: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly to: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").Literals<readonly ["concept", "file", "missing"]>;
+        readonly source: import("effect/Schema").Literals<readonly ["body", "frontmatter"]>;
+        readonly field: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly list_concepts: import("effect/unstable/ai/Tool").Tool<"list_concepts", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly type: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+      readonly tags: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
+      readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>>;
+      readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+      readonly offset: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly items: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly id: import("effect/Schema").String;
+        readonly type: import("effect/Schema").String;
+        readonly title: import("effect/Schema").String;
+        readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+        readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+        readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+        readonly path: import("effect/Schema").String;
+      }>>;
+      readonly total: import("effect/Schema").Int;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly stale_report: import("effect/unstable/ai/Tool").Tool<"stale_report", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly as_of: import("effect/Schema").String;
+      readonly items: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly summary: import("effect/Schema").Struct<{
+          readonly id: import("effect/Schema").String;
+          readonly type: import("effect/Schema").String;
+          readonly title: import("effect/Schema").String;
+          readonly description: import("effect/Schema").NullOr<import("effect/Schema").String>;
+          readonly status: import("effect/Schema").Literals<readonly ["draft", "stable", "deprecated"]>;
+          readonly tags: import("effect/Schema").$Array<import("effect/Schema").String>;
+          readonly path: import("effect/Schema").String;
+        }>;
+        readonly stale_after: import("effect/Schema").String;
+        readonly days_past: import("effect/Schema").Int;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+  readonly validate_bundle: import("effect/unstable/ai/Tool").Tool<"validate_bundle", {
+    readonly parameters: import("effect/Schema").Struct<{
+      readonly now: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+    }>;
+    readonly success: import("effect/Schema").Struct<{
+      readonly schema: import("effect/Schema").Literal<1>;
+      readonly okfit_version: import("effect/Schema").String;
+      readonly okf_version: import("effect/Schema").String;
+      readonly root: import("effect/Schema").String;
+      readonly profile: import("effect/Schema").NullOr<import("effect/Schema").String>;
+      readonly exit_code: import("effect/Schema").Literals<readonly [0, 1, 2]>;
+      readonly summary: import("effect/Schema").Struct<{
+        readonly conformance_errors: import("effect/Schema").Number;
+        readonly lint_errors: import("effect/Schema").Number;
+        readonly lint_warnings: import("effect/Schema").Number;
+        readonly lint_info: import("effect/Schema").Number;
+        readonly profile_errors: import("effect/Schema").Number;
+        readonly concepts: import("effect/Schema").Number;
+      }>;
+      readonly diagnostics: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+        readonly source: import("effect/Schema").Literals<readonly ["core.conformance", "core.lint", "profile"]>;
+        readonly file: import("effect/Schema").String;
+        readonly code: import("effect/Schema").String;
+        readonly severity: import("effect/Schema").Literals<readonly ["error", "warning", "info"]>;
+        readonly message: import("effect/Schema").String;
+        readonly range: import("effect/Schema").optionalKey<typeof import("@okfit/core").DiagnosticRange>;
+      }>>;
+    }>;
+    readonly failure: import("effect/Schema").Union<readonly [typeof ConfigError, typeof BundleNotFound, typeof ConceptNotFound, typeof UnknownVocabulary, typeof InvalidArgument]>;
+    readonly failureMode: "error";
+  }, import("@effected/xdg").AppDirs | import("effect/FileSystem").FileSystem | import("@effected/git").Git | import("@okfit/profiles").GitHistory | import("effect/Path").Path | import("@effected/xdg").Xdg>;
+}>, never, never>;
+//#endregion
+//#region src/version.d.ts
 /**
- * Exit code the stub bin uses.
+ * The version this server reports in `initialize`, read from its own
+ * manifest (K-32) so a release can never desync from the reported version.
  *
  * @public
  */
-declare const NOT_IMPLEMENTED_EXIT_CODE = 1;
+export declare const MCP_VERSION: string;
 //#endregion
-export { NOT_IMPLEMENTED_EXIT_CODE, NOT_IMPLEMENTED_MESSAGE };
+export type { PlatformServices };
 //# sourceMappingURL=index.d.ts.map