@savvy-web/mcp 1.7.5 → 1.8.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@savvy-web%2Fmcp?label=npm&color=cb3837)](https://www.npmjs.com/package/@savvy-web/mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
 
-The `savvy-mcp` [Model Context Protocol](https://modelcontextprotocol.io/) server. It serves [Silk Suite](https://github.com/savvy-web/systems) tooling to coding agents as structured tools, so an agent can read workspace facts and run Silk checks instead of parsing console output or guessing. It is a tools-only server — eight tools, no resources.
+The `savvy-mcp` [Model Context Protocol](https://modelcontextprotocol.io/) server. It serves [Silk Suite](https://github.com/savvy-web/systems) tooling to coding agents as structured tools, so an agent can read workspace facts and run Silk checks instead of parsing console output or guessing. It is a tools-only server — ten tools, no resources.
 
 ## Install
 
@@ -49,6 +49,8 @@ npx @modelcontextprotocol/inspector savvy-mcp .
 - `changeset_deps_detect` — read-only preview of the cumulative dependency diff (merge-base to working tree): one entry per affected workspace package with its resolved dependency-table rows, `catalog:`/`workspace:` specifiers resolved to concrete versions. It never writes a changeset. Backed by `silk-effects`' `Changesets.DepsRegen.plan`.
 - `changeset_deps_regen` — regenerates pure-dependency changesets: deletes stale ones and writes fresh single-package, patch-bump changesets from the cumulative dependency diff. Mutating unless `dryRun` is set, in which case it reports what it would delete and write without touching the filesystem. Backed by `silk-effects`' `Changesets.DepsRegen`.
 - `biome_check` — run Biome over a path and get structured diagnostics back: `mode=check` (lint, format and organize-imports) or `mode=lint`. Unlike most of the other tools it can mutate — pass `write` for safe fixes or `unsafe` for unsafe ones (both git-reversible) — so it returns the same diagnostics the Biome LSP surfaces for files you have edited.
+- `repos_inspect` — read-only inspection of vendored repositories: `mode=status` reports per-repo presence, the gitlink commit, working-tree dirtiness, and stale note ids; `mode=config` surfaces the validated `.repos/config.json` manifest and its entries. Returns markdown-escaped output since vendored-repo content is untrusted input. Backed by the same `silk-effects` `Repos` services the `savvy` CLI uses.
+- `repos_manage` — manages vendored repositories (mutating counterpart to repos_inspect): `action=sync` initializes any missing submodules (`git submodule update --init --depth 1`), applies sparse-checkout from the manifest, and clears stale git locks; `action=pin` fetches and checks out the new ref, staging the updated gitlink and manifest; `action=add` adds a new repo entry; `action=note` appends a short note to a repo. Pin and add stage git changes for the caller to commit. Backed by the same `silk-effects` `Repos` services the `savvy` CLI uses.
 
 ## License
 

package/index.d.ts

@@ -1,11 +1,11 @@
-import { Changesets, SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
+import { Changesets, Repos, SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
 import { Layer, ManagedRuntime } from "effect";
 import { WorkspaceDiscoveryError, WorkspaceRoot } from "workspaces-effect";
 import "@modelcontextprotocol/sdk/server/mcp.js";
 //#region src/context.d.ts
 /** The long-lived runtime and the project working directory. */
 interface McpContext {
-  readonly runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.ReleasePlanner | Changesets.DepsRegen, WorkspaceDiscoveryError>;
+  readonly runtime: ManagedRuntime.ManagedRuntime<SilkWorkspaceAnalyzer | WorkspaceRoot | Turbo.TurboInspector | Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.ReleasePlanner | Changesets.DepsRegen | Repos.ReposManager | Repos.ReposConfigStore, WorkspaceDiscoveryError>;
   readonly cwd: string;
 }
 //#endregion
@@ -13,16 +13,17 @@ interface McpContext {
 /**
  * The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`,
  * `Turbo.TurboInspector`, `Changesets.BranchAnalyzer`,
- * `Changesets.ConfigInspector`, `Changesets.ReleasePlanner`, and
- * `Changesets.DepsRegen`; requires `CommandExecutor` + `FileSystem` + `Path`
- * from the host's platform layer (`NodeContext.layer` in bin.ts).
+ * `Changesets.ConfigInspector`, `Changesets.ReleasePlanner`,
+ * `Changesets.DepsRegen`, `Repos.ReposManager`, and `Repos.ReposConfigStore`;
+ * requires `CommandExecutor` + `FileSystem` + `Path` from the host's platform
+ * layer (`NodeContext.layer` in bin.ts).
  *
  * `TurboInspectorLive` is fed its own `ToolDiscoveryLive`, whose
  * `PackageManagerDetector` + `WorkspaceRoot` requirements are satisfied by
  * {@link DepsLive}; the leftover `CommandExecutor` + `FileSystem` flow up to the
  * host platform layer.
  */
-declare const SilkRuntimeLive: Layer.Layer<Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.DepsRegen | Changesets.ReleasePlanner | import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | Turbo.TurboInspector | import("workspaces-effect").WorkspaceRoot, import("workspaces-effect").WorkspaceDiscoveryError, import("@effect/platform/CommandExecutor").CommandExecutor | import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path>;
+declare const SilkRuntimeLive: Layer.Layer<Changesets.BranchAnalyzer | Changesets.ConfigInspector | Changesets.DepsRegen | Changesets.ReleasePlanner | Repos.ReposConfigStore | Repos.ReposManager | import("@savvy-web/silk-effects").SilkWorkspaceAnalyzer | Turbo.TurboInspector | import("workspaces-effect").WorkspaceRoot, import("workspaces-effect").WorkspaceDiscoveryError, import("@effect/platform/CommandExecutor").CommandExecutor | import("@effect/platform/FileSystem").FileSystem | import("@effect/platform/Path").Path>;
 //#endregion
 //#region src/server.d.ts
 /** Build the server and connect it over stdio. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "1.7.5",
+	"version": "1.8.0",
 	"private": false,
 	"description": "The savvy MCP server — Silk Suite tooling and library knowledge for coding agents",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/mcp",
@@ -38,7 +38,7 @@
 		"@effect/sql": "^0.51.1",
 		"@effect/workflow": "^0.18.2",
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@savvy-web/silk-effects": "3.2.4",
+		"@savvy-web/silk-effects": "3.3.0",
 		"effect": "^3.21.4",
 		"workspaces-effect": "^2.0.3",
 		"zod": "^4.4.3"

package/runtime.js

@@ -1,4 +1,4 @@
-import { ChangesetConfigLive, ChangesetConfigReaderLive, Changesets, SilkWorkspaceAnalyzerLive, TagStrategyLive, ToolDiscoveryLive, Turbo, VersioningStrategyLive } from "@savvy-web/silk-effects";
+import { ChangesetConfigLive, ChangesetConfigReaderLive, Changesets, Repos, SilkWorkspaceAnalyzerLive, TagStrategyLive, ToolDiscoveryLive, Turbo, VersioningStrategyLive } from "@savvy-web/silk-effects";
 import { Layer } from "effect";
 import { PointInTimeWorkspaceLive, WorkspaceRootLive, WorkspacesLive } from "workspaces-effect";
 
@@ -43,18 +43,29 @@ const InspectorAndAnalyzerLive = Changesets.BranchAnalyzerLive.pipe(Layer.provid
 */
 const DepsRegenGroupLive = Changesets.DepsRegenLive.pipe(Layer.provide(InspectorAndAnalyzerLive), Layer.provide(PointInTimeWorkspaceLive), Layer.provide(ChangesetConfigLive.pipe(Layer.provide(ChangesetConfigReaderLive))));
 /**
+* `Repos.ReposManager` + `Repos.ReposConfigStore`, both exposed on the
+* runtime. `ReposManagerLive` requires `ReposConfigStore`, so it is given its
+* own `ReposConfigStoreLive` reference here (`Layer.mergeAll` does not
+* cross-feed sibling layers); `ReposConfigStore` is ALSO merged in directly so
+* `repos_inspect`'s config mode can resolve it on its own. The remaining
+* `CommandExecutor` + `FileSystem` + `Path` requirements flow up to the host
+* platform layer (`NodeContext.layer` in bin.ts).
+*/
+const ReposGroupLive = Layer.mergeAll(Repos.ReposConfigStoreLive, Repos.ReposManagerLive.pipe(Layer.provide(Repos.ReposConfigStoreLive)));
+/**
 * The MCP runtime layer. Provides `SilkWorkspaceAnalyzer`, `WorkspaceRoot`,
 * `Turbo.TurboInspector`, `Changesets.BranchAnalyzer`,
-* `Changesets.ConfigInspector`, `Changesets.ReleasePlanner`, and
-* `Changesets.DepsRegen`; requires `CommandExecutor` + `FileSystem` + `Path`
-* from the host's platform layer (`NodeContext.layer` in bin.ts).
+* `Changesets.ConfigInspector`, `Changesets.ReleasePlanner`,
+* `Changesets.DepsRegen`, `Repos.ReposManager`, and `Repos.ReposConfigStore`;
+* requires `CommandExecutor` + `FileSystem` + `Path` from the host's platform
+* layer (`NodeContext.layer` in bin.ts).
 *
 * `TurboInspectorLive` is fed its own `ToolDiscoveryLive`, whose
 * `PackageManagerDetector` + `WorkspaceRoot` requirements are satisfied by
 * {@link DepsLive}; the leftover `CommandExecutor` + `FileSystem` flow up to the
 * host platform layer.
 */
-const SilkRuntimeLive = Layer.mergeAll(SilkWorkspaceAnalyzerLive, WorkspaceRootLive, Turbo.TurboInspectorLive.pipe(Layer.provide(ToolDiscoveryLive)), InspectorAndAnalyzerLive, DepsRegenGroupLive).pipe(Layer.provide(DepsLive));
+const SilkRuntimeLive = Layer.mergeAll(SilkWorkspaceAnalyzerLive, WorkspaceRootLive, Turbo.TurboInspectorLive.pipe(Layer.provide(ToolDiscoveryLive)), InspectorAndAnalyzerLive, DepsRegenGroupLive, ReposGroupLive).pipe(Layer.provide(DepsLive));
 
 //#endregion
 export { SilkRuntimeLive };

package/server.js

@@ -5,6 +5,8 @@ import { ChangesetDepsRegenAsMarkdown, ChangesetDepsRegenResult, changesetDepsRe
 import { ChangesetInspectAsMarkdown, ChangesetInspectResult, changesetInspect } from "./tools/changeset-inspect.js";
 import { ChangesetPreviewAsMarkdown, ChangesetPreviewResult, changesetPreview } from "./tools/changeset-preview.js";
 import { ChangesetValidateAsMarkdown, ChangesetValidateResult, changesetValidate } from "./tools/changeset-validate.js";
+import { ReposInspectAsMarkdown, ReposInspectResult, reposInspect } from "./tools/repos-inspect.js";
+import { ReposManageAsMarkdown, ReposManageResult, reposManage } from "./tools/repos-manage.js";
 import { TurboInspectAsMarkdown, TurboInspectResult, turboInspect } from "./tools/turbo-inspect.js";
 import { WorkspaceInfoAsMarkdown, WorkspaceInfoResult, workspaceInfo } from "./tools/workspace-info.js";
 import { CURRENT_MCP_VERSION } from "./version.js";
@@ -141,6 +143,55 @@ function buildServer(ctx) {
 		const text = Schema.decodeSync(ChangesetDepsRegenAsMarkdown)(data);
 		return structuredResult(text, data);
 	});
+	server.registerTool("repos_inspect", {
+		title: "Inspect vendored repos",
+		description: "Read-only: drift report or parsed .repos/config.json manifest with orientation and notes.",
+		inputSchema: {
+			mode: z.enum(["status", "config"]).describe("status = drift report; config = the full agent brief."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(ReposInspectResult),
+		annotations: { readOnlyHint: true }
+	}, async (args) => {
+		const data = await ctx.runtime.runPromise(reposInspect(args, ctx.cwd));
+		const text = Schema.decodeSync(ReposInspectAsMarkdown)(data);
+		return structuredResult(text, data);
+	});
+	server.registerTool("repos_manage", {
+		title: "Manage vendored repos",
+		description: "Mutating: sync (initialize/reconcile submodules per the manifest), pin (re-pin a repo to a new ref), add (vendor a new repo), or note (add/remove/promote an agent note). Pass action plus the fields that action needs: pin needs name+ref; add needs url+ref+purpose (name/sparse optional); note needs name+op, plus note (op=add), id (op=remove), or id+into (op=promote). A decode failure names the missing field. The pin result's markdown surfaces commitMessage and staleNoteIds — review and commit after pinning.",
+		inputSchema: {
+			action: z.enum([
+				"sync",
+				"pin",
+				"add",
+				"note"
+			]).describe("Which mutation to perform."),
+			name: z.optional(z.string()).describe("Repo name (pin, note; optional override for add)."),
+			ref: z.optional(z.string()).describe("Git ref to pin/vendor to (pin, add)."),
+			url: z.optional(z.string()).describe("Repo URL to vendor (add)."),
+			purpose: z.optional(z.string()).describe("One-line purpose for the manifest (add)."),
+			sparse: z.optional(z.array(z.string())).describe("Sparse-checkout patterns (add)."),
+			op: z.optional(z.enum([
+				"add",
+				"remove",
+				"promote"
+			])).describe("Note operation (note)."),
+			note: z.optional(z.string()).describe("Note text (note, op=add)."),
+			id: z.optional(z.string()).describe("Note id (note, op=remove|promote)."),
+			into: z.optional(z.enum(["layout", "startHere"])).describe("Orientation target (note, op=promote)."),
+			cwd: z.optional(z.string()).describe("Directory to resolve the workspace root from.")
+		},
+		outputSchema: effectToZodSchema(ReposManageResult),
+		annotations: {
+			destructiveHint: true,
+			idempotentHint: false
+		}
+	}, async (args) => {
+		const data = await ctx.runtime.runPromise(reposManage(args, ctx.cwd));
+		const text = Schema.decodeSync(ReposManageAsMarkdown)(data);
+		return structuredResult(text, data);
+	});
 	server.registerTool("biome_check", {
 		description: "Run Biome over a path and get structured diagnostics back. mode=check (default; lint + format + organize-imports) or mode=lint. Set write=true to apply safe fixes (--write), unsafe=true for unsafe fixes (--write --unsafe). Severities match the project's Biome config (what `biome check` reports); set strict=true to surface project warnings as errors, each marked with its originalSeverity. Prefer this over shelling out to biome; the LSP already covers files you've edited. Returns markdown in content[] and a typed object in structuredContent. NOTE: with write/unsafe this tool MUTATES files (git-reversible).",
 		inputSchema: {

package/tools/md-inline.js

@@ -0,0 +1,22 @@
+//#region src/tools/md-inline.ts
+/**
+* Render a repo-derived value as an inert markdown code span. Backslash
+* escaping does NOT work inside code spans (CommonMark treats backslashes
+* literally there), so this uses the delimiter-run rule instead: wrap the
+* value in a backtick run strictly longer than any backtick run it contains,
+* padding with spaces when the value starts or ends with a backtick. This
+* keeps vendored-repo content (names, refs, purposes, orientation values,
+* commit messages, note text) — the definition of untrusted input — from
+* injecting markdown structure into the transcript an agent reads.
+*
+* Shared by every tool that interpolates untrusted repo content into a
+* markdown transcript so the escaping rule has exactly one implementation.
+*/
+const mdInline = (value) => {
+	const runs = value.match(/`+/g) ?? [];
+	const delimiter = "`".repeat(Math.max(1, ...runs.map((run) => run.length + 1)));
+	return `${delimiter}${value.startsWith("`") || value.endsWith("`") ? ` ${value} ` : value}${delimiter}`;
+};
+
+//#endregion
+export { mdInline };

package/tools/repos-inspect.js

@@ -0,0 +1,104 @@
+import { mdInline } from "./md-inline.js";
+import { Repos } from "@savvy-web/silk-effects";
+import { Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+
+//#region src/tools/repos-inspect.ts
+/**
+* The `repos_inspect` MCP tool: a discriminated-union result keyed by `mode`
+* (status | config), each variant embedding the corresponding resolved-output
+* schema from silk-effects' Repos namespace, plus a one-way markdown
+* transform. Read-only.
+*
+* @packageDocumentation
+*/
+/** Status-report variant. */
+const ReposStatusResult = Schema.Struct({
+	mode: Schema.Literal("status"),
+	result: Repos.ReposStatusReport
+}).annotations({ identifier: "ReposStatusResult" });
+/** Manifest-config variant. */
+const ReposConfigResult = Schema.Struct({
+	mode: Schema.Literal("config"),
+	result: Repos.ReposManifestFile
+}).annotations({ identifier: "ReposConfigResult" });
+/** The `repos_inspect` tool result — a discriminated union keyed by `mode`. */
+const ReposInspectResult = Schema.Union(ReposStatusResult, ReposConfigResult).annotations({
+	identifier: "ReposInspectResult",
+	title: "repos_inspect result",
+	description: "Drift report (status) or the parsed manifest with purposes, orientation, and notes (config)."
+});
+/** Render the structured result as a markdown transcript. */
+const renderMarkdown = (data) => {
+	switch (data.mode) {
+		case "status": {
+			const r = data.result;
+			const lines = [
+				`# repos status`,
+				``,
+				`clean: ${r.clean}`,
+				``,
+				`## Repos`
+			];
+			for (const entry of r.repos) {
+				lines.push(`### ${mdInline(entry.name)}`, `- ref: ${mdInline(entry.ref)}`, `- purpose: ${mdInline(entry.purpose)}`, `- present: ${entry.present}`, `- commit: ${entry.commit ? mdInline(entry.commit) : "(none)"}`, `- dirty: ${entry.dirty}`);
+				if (entry.staleNoteIds.length > 0) lines.push(`- staleNoteIds: ${entry.staleNoteIds.map(mdInline).join(", ")}`);
+			}
+			if (r.repos.length === 0) lines.push("(none)");
+			return lines.join("\n");
+		}
+		case "config": {
+			const r = data.result;
+			const lines = [
+				`# repos config`,
+				``,
+				`## Repos`
+			];
+			for (const [name, entry] of Object.entries(r.repos)) {
+				lines.push(`### ${mdInline(name)}`, `- url: ${mdInline(entry.url)}`, `- ref: ${mdInline(entry.ref)}`, `- purpose: ${mdInline(entry.purpose)}`);
+				if (entry.sparse && entry.sparse.length > 0) lines.push(`- sparse: ${entry.sparse.map(mdInline).join(", ")}`);
+				if (entry.orientation) {
+					const o = entry.orientation;
+					if (o.layout) lines.push(`- layout: ${mdInline(o.layout)}`);
+					if (o.startHere) lines.push(`- startHere: ${mdInline(o.startHere)}`);
+					if (o.keyPaths) {
+						lines.push(`- keyPaths:`);
+						for (const [key, value] of Object.entries(o.keyPaths)) lines.push(`  - ${mdInline(key)}: ${mdInline(value)}`);
+					}
+				}
+				if (entry.notes && entry.notes.length > 0) {
+					lines.push(`- notes:`);
+					for (const note of entry.notes) lines.push(`  - ${mdInline(note.id)} (${mdInline(note.date)}, ref ${mdInline(note.ref)}): ${mdInline(note.note)}`);
+				}
+			}
+			if (Object.keys(r.repos).length === 0) lines.push("(none)");
+			return lines.join("\n");
+		}
+	}
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const ReposInspectAsMarkdown = Schema.transformOrFail(ReposInspectResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "ReposInspectAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root, then dispatch to the matching
+* Repos service keyed by `mode`. Mirrors `changesetInspect`.
+*/
+const reposInspect = (args, fallbackCwd) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
+	switch (args.mode) {
+		case "status": return {
+			mode: "status",
+			result: yield* (yield* Repos.ReposManager).status(root)
+		};
+		case "config": return {
+			mode: "config",
+			result: yield* (yield* Repos.ReposConfigStore).read(root)
+		};
+	}
+});
+
+//#endregion
+export { ReposConfigResult, ReposInspectAsMarkdown, ReposInspectResult, ReposStatusResult, reposInspect };

package/tools/repos-manage.js

@@ -0,0 +1,195 @@
+import { mdInline } from "./md-inline.js";
+import { Repos } from "@savvy-web/silk-effects";
+import { Effect, ParseResult, Schema } from "effect";
+import { WorkspaceRoot } from "workspaces-effect";
+
+//#region src/tools/repos-manage.ts
+/**
+* The `repos_manage` MCP tool: one action-discriminated mutating tool
+* covering `sync`, `pin`, `add`, and `note` against the vendored `.repos/`
+* submodules. The wire schema is flat (no `oneOf`); the handler maps it into
+* an internal `Schema.TaggedStruct` request union that names the missing
+* field per action on decode failure. Mutating — no `readOnlyHint`.
+*
+* @packageDocumentation
+*/
+/** `sync` has no extra fields. */
+const SyncRequest = Schema.TaggedStruct("sync", {});
+/** `pin` requires both `name` and `ref`. */
+const PinRequest = Schema.TaggedStruct("pin", {
+	name: Schema.String,
+	ref: Schema.String
+});
+/** `add` requires `url`/`ref`/`purpose`; `name` and `sparse` are optional. */
+const AddRequest = Schema.TaggedStruct("add", {
+	url: Schema.String,
+	ref: Schema.String,
+	purpose: Schema.String,
+	name: Schema.optional(Schema.String),
+	sparse: Schema.optional(Schema.Array(Schema.String))
+});
+/**
+* `note` requires `name` and `op`; the fields required beyond that depend on
+* `op` — enforced by the trailing filter so the decode error names exactly
+* what's missing for the chosen op.
+*/
+const NoteRequest = Schema.TaggedStruct("note", {
+	name: Schema.String,
+	op: Schema.Literal("add", "remove", "promote"),
+	note: Schema.optional(Schema.String),
+	id: Schema.optional(Schema.String),
+	into: Schema.optional(Schema.Literal("layout", "startHere"))
+}).pipe(Schema.filter((request) => {
+	if (request.op === "add" && request.note === void 0) return "note op \"add\" requires `note`";
+	if (request.op === "remove" && request.id === void 0) return "note op \"remove\" requires `id`";
+	if (request.op === "promote" && (request.id === void 0 || request.into === void 0)) return "note op \"promote\" requires both `id` and `into`";
+	return true;
+}));
+/** Internal tagged-union request the flat wire args decode into. */
+const ReposManageRequest = Schema.Union(SyncRequest, PinRequest, AddRequest, NoteRequest);
+/** `sync` result variant. */
+const ReposManageSyncResult = Schema.Struct({
+	action: Schema.Literal("sync"),
+	result: Repos.ReposSyncReport
+}).annotations({ identifier: "ReposManageSyncResult" });
+/** `pin` result variant. */
+const ReposManagePinResult = Schema.Struct({
+	action: Schema.Literal("pin"),
+	result: Repos.ReposPinResult
+}).annotations({ identifier: "ReposManagePinResult" });
+/** `add` result variant. */
+const ReposManageAddResult = Schema.Struct({
+	action: Schema.Literal("add"),
+	result: Repos.ReposAddResult
+}).annotations({ identifier: "ReposManageAddResult" });
+/** `note` result variant. */
+const ReposManageNoteResult = Schema.Struct({
+	action: Schema.Literal("note"),
+	result: Repos.ReposNoteResult
+}).annotations({ identifier: "ReposManageNoteResult" });
+/** The `repos_manage` tool result — a discriminated union keyed by `action`. */
+const ReposManageResult = Schema.Union(ReposManageSyncResult, ReposManagePinResult, ReposManageAddResult, ReposManageNoteResult).annotations({
+	identifier: "ReposManageResult",
+	title: "repos_manage result",
+	description: "Result of a mutating repos action: sync, pin, add, or note."
+});
+/** Render the structured result as a markdown transcript. */
+const renderMarkdown = (data) => {
+	switch (data.action) {
+		case "sync": {
+			const r = data.result;
+			const section = (title, names) => [`## ${title}`, ...names.length > 0 ? names.map((name) => `- ${mdInline(name)}`) : ["(none)"]];
+			return [
+				`# repos sync`,
+				``,
+				...section("Initialized", r.initialized),
+				``,
+				...section("Sparse applied", r.sparseApplied),
+				``,
+				...section("Up to date", r.upToDate),
+				``,
+				...section("Cleared locks", r.clearedLocks)
+			].join("\n");
+		}
+		case "pin": {
+			const r = data.result;
+			const lines = [
+				`# repos pin — ${mdInline(r.name)}`,
+				``,
+				`ref: ${mdInline(r.ref)}`,
+				`oldCommit: ${r.oldCommit ? mdInline(r.oldCommit) : "(none)"}`,
+				`newCommit: ${mdInline(r.newCommit)}`,
+				``,
+				`## Commit message`,
+				``,
+				mdInline(r.commitMessage),
+				``,
+				`## Stale notes`,
+				``
+			];
+			if (r.staleNoteIds.length > 0) lines.push(`These notes reference a ref other than the new pin and should be reviewed before committing:`, ...r.staleNoteIds.map((id) => `- ${mdInline(id)}`));
+			else lines.push("(none)");
+			lines.push(``, `REVIEW AND COMMIT: stage the updated manifest and submodule gitlink, then commit using the message above.`);
+			return lines.join("\n");
+		}
+		case "add": {
+			const r = data.result;
+			return [
+				`# repos add — ${mdInline(r.name)}`,
+				``,
+				`ref: ${mdInline(r.ref)}`,
+				`path: ${mdInline(r.path)}`
+			].join("\n");
+		}
+		case "note": {
+			const r = data.result;
+			return [
+				`# repos note — ${mdInline(r.name)}`,
+				``,
+				`op: ${mdInline(r.op)}`,
+				`id: ${mdInline(r.id)}`,
+				`noteCount: ${r.noteCount}`
+			].join("\n");
+		}
+	}
+};
+/** One-way transform: result to markdown. Encoding back is forbidden. */
+const ReposManageAsMarkdown = Schema.transformOrFail(ReposManageResult, Schema.String, {
+	strict: true,
+	decode: (data) => ParseResult.succeed(renderMarkdown(data)),
+	encode: (text, _options, ast) => ParseResult.fail(new ParseResult.Forbidden(ast, text, "ReposManageAsMarkdown is one-way: markdown cannot be parsed back."))
+});
+/**
+* Effect handler: resolve the workspace root, decode the flat wire args into
+* the internal per-action request (naming the missing field on failure), then
+* dispatch to the matching `ReposManager` method.
+*/
+const reposManage = (args, fallbackCwd) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
+	const manager = yield* Repos.ReposManager;
+	const { action, cwd: _cwd, ...rest } = args;
+	const request = yield* Schema.decodeUnknown(ReposManageRequest)({
+		_tag: action,
+		...rest
+	});
+	switch (request._tag) {
+		case "sync": return {
+			action: "sync",
+			result: yield* manager.sync(root)
+		};
+		case "pin": return {
+			action: "pin",
+			result: yield* manager.pin(root, request.name, request.ref)
+		};
+		case "add": return {
+			action: "add",
+			result: yield* manager.add(root, {
+				url: request.url,
+				ref: request.ref,
+				purpose: request.purpose,
+				...request.name !== void 0 ? { name: request.name } : {},
+				...request.sparse !== void 0 ? { sparse: request.sparse } : {}
+			})
+		};
+		case "note": {
+			const noteOp = request.op === "add" ? {
+				op: "add",
+				note: request.note
+			} : request.op === "remove" ? {
+				op: "remove",
+				id: request.id
+			} : {
+				op: "promote",
+				id: request.id,
+				into: request.into
+			};
+			return {
+				action: "note",
+				result: yield* manager.note(root, request.name, noteOp)
+			};
+		}
+	}
+});
+
+//#endregion
+export { ReposManageAddResult, ReposManageAsMarkdown, ReposManageNoteResult, ReposManagePinResult, ReposManageResult, ReposManageSyncResult, reposManage };