@morsa/guidance-bank 0.2.0

package/dist/mcp/tools/registerCreateBankTool.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { createProjectBankManifest, } from "../../core/bank/project.js";
+import { buildCreateBankPrompt } from "../../core/projects/createBankPrompt.js";
+import { finalizeCreateBankExecution, resolveCreateBankFlowContext } from "../../core/projects/createBankFlow.js";
+import { discoverCurrentProjectBank } from "../../core/projects/discoverCurrentProjectBank.js";
+import { buildCreateBankIterationPrompt, buildReadyProjectBankPrompt, } from "../../core/projects/createBankIterationPrompt.js";
+import { getCreateFlowPhase } from "../../core/projects/createFlowPhases.js";
+import { applyCreateBankChanges } from "./createBankApply.js";
+import { buildCreateBankResponseText, getCreateBankApplyBlockedMessage, normalizeApplyDeletions, normalizeApplyWrites, shouldWarnAboutIterationMismatch, } from "./createBankToolRuntime.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+import { CreateBankArgsSchema, CreateBankInputShape, CreateBankOutputShape, } from "./createBankToolSchemas.js";
+const registerCreateLikeTool = (server, options, { toolName, title, description, }) => {
+    server.registerTool(toolName, {
+        title,
+        description,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+        inputSchema: CreateBankInputShape,
+        outputSchema: CreateBankOutputShape,
+    }, async (args) => {
+        const parsedArgs = CreateBankArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool ${toolName}: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        const requestedIteration = parsedArgs.data.iteration ?? 0;
+        const flowContext = await resolveCreateBankFlowContext({
+            repository: options.repository,
+            projectPath: parsedArgs.data.projectPath,
+            requestedIteration,
+            stepCompleted: parsedArgs.data.stepCompleted ?? false,
+            hasApply: parsedArgs.data.apply !== undefined,
+            stepOutcome: parsedArgs.data.stepOutcome ?? null,
+            stepOutcomeNote: parsedArgs.data.stepOutcomeNote ?? null,
+            ...(parsedArgs.data.sourceReviewDecision ? { sourceReviewDecision: parsedArgs.data.sourceReviewDecision } : {}),
+            ...(parsedArgs.data.referenceProjectIds ? { referenceProjectIds: parsedArgs.data.referenceProjectIds } : {}),
+        });
+        if (flowContext.unknownReferenceIds.length > 0) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown reference project ids for tool ${toolName}: ${flowContext.unknownReferenceIds.join(", ")}`,
+                    },
+                ],
+            };
+        }
+        const { identity, projectContext, existingManifest, existingState, selectedReferenceProjects, existingBankUpdatedAt, existingBankUpdatedDaysAgo, effectiveIteration, stepCompletionRequired, sourceStrategyRequired, stepOutcomeRequired, syncRequired, improvementEntryPoint, extendedContext, confirmedSourceStrategies, } = flowContext;
+        if (existingState !== null &&
+            shouldWarnAboutIterationMismatch(existingState.createIteration, requestedIteration, effectiveIteration, stepCompletionRequired, sourceStrategyRequired, stepOutcomeRequired)) {
+            console.warn(`create_bank iteration mismatch for project ${identity.projectId}: stored=${existingState.createIteration}, requested=${requestedIteration}, effective=${effectiveIteration}. Overwriting stored iteration.`);
+        }
+        const applyBlockedMessage = getCreateBankApplyBlockedMessage({
+            hasApply: parsedArgs.data.apply !== undefined,
+            syncRequired,
+            improvementEntryPoint,
+            phase: syncRequired
+                ? "sync_required"
+                : improvementEntryPoint
+                    ? "ready_to_improve"
+                    : getCreateFlowPhase(effectiveIteration),
+            hasDiscoveredSources: extendedContext.discoveredSources.length > 0,
+            stepCompletionRequired,
+            sourceStrategyRequired,
+            stepOutcomeRequired,
+        });
+        if (applyBlockedMessage !== null) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: applyBlockedMessage,
+                    },
+                ],
+            };
+        }
+        if (existingManifest === null) {
+            await options.repository.ensureProjectStructure(identity.projectId);
+            await options.repository.writeProjectManifest(identity.projectId, createProjectBankManifest(identity.projectId, identity.projectName, identity.projectPath, projectContext.detectedStacks));
+        }
+        const projectBankPath = options.repository.paths.projectDirectory(identity.projectId);
+        const rulesDirectory = options.repository.paths.projectRulesDirectory(identity.projectId);
+        const skillsDirectory = options.repository.paths.projectSkillsDirectory(identity.projectId);
+        let currentBankSnapshot = existingManifest === null
+            ? {
+                ...extendedContext.currentBankSnapshot,
+                exists: true,
+            }
+            : extendedContext.currentBankSnapshot;
+        const applyResults = parsedArgs.data.apply
+            ? await applyCreateBankChanges({
+                repository: options.repository,
+                auditLogger: options.auditLogger,
+                projectId: identity.projectId,
+                projectPath: identity.projectPath,
+                sessionRef: parsedArgs.data.sessionRef ?? null,
+                writes: normalizeApplyWrites(parsedArgs.data.apply.writes),
+                deletions: normalizeApplyDeletions(parsedArgs.data.apply.deletions),
+            })
+            : {
+                writes: [],
+                deletions: [],
+            };
+        if (parsedArgs.data.apply) {
+            currentBankSnapshot = await discoverCurrentProjectBank(options.repository, identity.projectId, true);
+        }
+        const { effectiveIteration: finalEffectiveIteration, phase: finalPhase, stepCompletionRequired: finalStepCompletionRequired, stepOutcomeRequired: finalStepOutcomeRequired, mustContinue: finalMustContinue, nextIteration: finalNextIteration, completedFlowThisCall: finalCompletedFlowThisCall, nextState, } = finalizeCreateBankExecution({
+            flowContext,
+            requestedIteration,
+            stepCompleted: parsedArgs.data.stepCompleted ?? false,
+            stepOutcome: parsedArgs.data.stepOutcome ?? null,
+            stepOutcomeNote: parsedArgs.data.stepOutcomeNote ?? null,
+            applyResults,
+        });
+        await options.repository.writeProjectState(identity.projectId, nextState);
+        const prompt = syncRequired
+            ? "Project AI Guidance Bank already exists for this repository and requires synchronization before reuse. Sync only reconciles the existing bank with the current AI Guidance Bank storage version; it does not create or improve project content. Ask the user whether to synchronize it now or postpone it. After that, call `resolve_context` again."
+            : improvementEntryPoint
+                ? buildReadyProjectBankPrompt({
+                    updatedAt: existingBankUpdatedAt,
+                    updatedDaysAgo: existingBankUpdatedDaysAgo,
+                })
+                : finalMustContinue || finalCompletedFlowThisCall
+                    ? buildCreateBankIterationPrompt({
+                        iteration: finalEffectiveIteration,
+                        projectName: identity.projectName,
+                        projectPath: identity.projectPath,
+                        projectBankPath,
+                        rulesDirectory,
+                        skillsDirectory,
+                        detectedStacks: projectContext.detectedStacks,
+                        selectedReferenceProjects,
+                        discoveredSources: extendedContext.discoveredSources,
+                        confirmedSourceStrategies,
+                        currentBankSnapshot,
+                        hasExistingProjectBank: existingManifest !== null,
+                    })
+                    : "Project AI Guidance Bank already exists for this repository and is ready.";
+        const creationPrompt = finalEffectiveIteration === 0
+            ? buildCreateBankPrompt({
+                projectName: identity.projectName,
+                projectPath: identity.projectPath,
+                projectBankPath,
+                rulesDirectory,
+                skillsDirectory,
+                detectedStacks: projectContext.detectedStacks,
+                selectedReferenceProjects,
+            })
+            : null;
+        const payload = {
+            status: existingManifest === null ? "created" : "already_exists",
+            syncRequired,
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            projectBankPath,
+            rulesDirectory,
+            skillsDirectory,
+            detectedStacks: projectContext.detectedStacks,
+            phase: finalPhase,
+            iteration: finalEffectiveIteration,
+            discoveredSources: extendedContext.discoveredSources,
+            currentBankSnapshot,
+            selectedReferenceProjects,
+            creationState: nextState.creationState,
+            confirmedSourceStrategies,
+            stepCompletionRequired: finalStepCompletionRequired,
+            sourceStrategyRequired,
+            stepOutcomeRequired: finalStepOutcomeRequired,
+            mustContinue: finalMustContinue,
+            nextIteration: finalNextIteration,
+            existingBankUpdatedAt,
+            existingBankUpdatedDaysAgo,
+            applyResults,
+            prompt,
+            creationPrompt,
+            text: buildCreateBankResponseText({
+                syncRequired,
+                applyResults,
+                stepCompletionRequired: finalStepCompletionRequired,
+                sourceStrategyRequired,
+                stepOutcomeRequired: finalStepOutcomeRequired,
+                nextIteration: finalNextIteration,
+                improvementEntryPoint,
+                mustContinue: finalMustContinue,
+                completedFlowThisCall: finalCompletedFlowThisCall,
+                phase: finalPhase,
+            }),
+        };
+        await writeToolAuditEvent({
+            auditLogger: options.auditLogger,
+            sessionRef: parsedArgs.data.sessionRef,
+            tool: toolName,
+            action: "create_flow",
+            projectId: identity.projectId,
+            projectPath: identity.projectPath,
+            details: {
+                phase: finalPhase,
+                iteration: finalEffectiveIteration,
+                creationState: nextState.creationState,
+                syncRequired,
+                mustContinue: finalMustContinue,
+                applyWrites: applyResults.writes.length,
+                applyDeletions: applyResults.deletions.length,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+            structuredContent: payload,
+        };
+    });
+};
+export const registerCreateBankTool = (server, options) => {
+    registerCreateLikeTool(server, options, {
+        toolName: "create_bank",
+        title: "Create Project AI Guidance Bank",
+        description: "Create the canonical project AI Guidance Bank under the user-level AI Guidance Bank storage. AI Guidance Bank is the durable rules-and-skills layer for the project, not conversational memory.",
+    });
+    registerCreateLikeTool(server, options, {
+        toolName: "improve_bank",
+        title: "Improve Project AI Guidance Bank",
+        description: "Review and improve an existing project AI Guidance Bank through the guided flow. Use this when the project already has a durable rules-and-skills layer that needs refinement or expansion.",
+    });
+};

package/dist/mcp/tools/registerDeleteEntryTool.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { ENTRY_KINDS, ENTRY_SCOPES } from "../../core/bank/types.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeEntryAuditEvent } from "./auditUtils.js";
+import { buildInvalidToolArgsResult, buildStructuredToolResult, readEntryBeforeMutation, resolveScopedMutationContext, } from "./entryMutationHelpers.js";
+const DeleteEntryArgsSchema = z
+    .object({
+    scope: z.enum(ENTRY_SCOPES).describe("Delete target: shared user-level entries or project-specific entries."),
+    kind: z.enum(ENTRY_KINDS).describe("Whether to delete a thematic rule file or a skill folder."),
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+    path: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Rule file path or skill folder path relative to the selected layer."),
+})
+    .strict();
+export const registerDeleteEntryTool = (server, options) => {
+    server.registerTool("delete_entry", {
+        title: "Delete AI Guidance Bank Entry",
+        description: "Delete a rule file or skill folder from the shared or project AI Guidance Bank layer. Use with care and only after the user explicitly wants the entry removed.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+        inputSchema: {
+            scope: z.enum(ENTRY_SCOPES).describe("Delete target: shared user-level entries or project-specific entries."),
+            kind: z.enum(ENTRY_KINDS).describe("Whether to delete a thematic rule file or a skill folder."),
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+            path: z
+                .string()
+                .trim()
+                .min(1)
+                .describe("Rule file path or skill folder path relative to the selected layer."),
+        },
+        outputSchema: {
+            status: z.enum(["deleted", "not_found"]),
+            scope: z.enum(ENTRY_SCOPES),
+            kind: z.enum(ENTRY_KINDS),
+            projectId: z.string(),
+            projectName: z.string(),
+            projectPath: z.string(),
+            path: z.string(),
+        },
+    }, async (args) => {
+        const parsedArgs = DeleteEntryArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return buildInvalidToolArgsResult("delete_entry", parsedArgs.error);
+        }
+        const mutationContext = await resolveScopedMutationContext({
+            repository: options.repository,
+            projectPath: parsedArgs.data.projectPath,
+            scope: parsedArgs.data.scope,
+            missingProjectMessage: "Project AI Guidance Bank does not exist yet. Call create_bank before deleting project-scoped entries.",
+        });
+        if ("isError" in mutationContext) {
+            return mutationContext;
+        }
+        const { identity, projectId } = mutationContext;
+        const beforeContent = await readEntryBeforeMutation({
+            repository: options.repository,
+            scope: parsedArgs.data.scope,
+            kind: parsedArgs.data.kind,
+            path: parsedArgs.data.path,
+            ...(projectId ? { projectId } : {}),
+        });
+        const result = parsedArgs.data.kind === "rules"
+            ? await options.repository.deleteRule(parsedArgs.data.scope, parsedArgs.data.path, projectId)
+            : await options.repository.deleteSkill(parsedArgs.data.scope, parsedArgs.data.path, projectId);
+        if (result.status === "deleted") {
+            await writeEntryAuditEvent({
+                auditLogger: options.auditLogger,
+                sessionRef: parsedArgs.data.sessionRef,
+                tool: "delete_entry",
+                action: "delete",
+                scope: parsedArgs.data.scope,
+                kind: parsedArgs.data.kind,
+                projectId: identity.projectId,
+                projectPath: identity.projectPath,
+                path: result.path,
+                beforeContent,
+                afterContent: null,
+            });
+        }
+        const payload = {
+            status: result.status,
+            scope: parsedArgs.data.scope,
+            kind: parsedArgs.data.kind,
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            path: result.path,
+        };
+        return buildStructuredToolResult(payload);
+    });
+};

package/dist/mcp/tools/registerDeleteGuidanceSourceTool.js

@@ -0,0 +1,120 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { discoverExistingGuidance } from "../../core/projects/discoverExistingGuidance.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { ValidationError } from "../../shared/errors.js";
+import { AbsoluteProjectPathSchema, SessionRefSchema } from "./sharedSchemas.js";
+import { writeToolAuditEvent } from "./auditUtils.js";
+import { buildInvalidToolArgsResult, buildStructuredToolResult } from "./entryMutationHelpers.js";
+const DeleteGuidanceSourceArgsSchema = z
+    .object({
+    projectPath: AbsoluteProjectPathSchema,
+    sessionRef: SessionRefSchema,
+    sourcePath: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Absolute path to a discovered repository-local or provider-project guidance source."),
+})
+    .strict();
+const deleteGuidancePath = async (targetPath) => {
+    try {
+        const stats = await fs.lstat(targetPath);
+        if (stats.isSymbolicLink()) {
+            throw new ValidationError(`Guidance source cannot be a symbolic link: ${targetPath}`);
+        }
+        if (stats.isDirectory()) {
+            await fs.rm(targetPath, { recursive: true, force: false });
+            return "deleted";
+        }
+        if (stats.isFile()) {
+            await fs.unlink(targetPath);
+            return "deleted";
+        }
+        throw new ValidationError(`Unsupported guidance source path type: ${targetPath}`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return "not_found";
+        }
+        throw error;
+    }
+};
+export const registerDeleteGuidanceSourceTool = (server, options) => {
+    server.registerTool("delete_guidance_source", {
+        title: "Delete External Guidance Source",
+        description: "Delete a discovered repository-local or provider-project guidance source after the user explicitly chose a move-to-Memory-Bank strategy.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+        inputSchema: {
+            projectPath: AbsoluteProjectPathSchema,
+            sessionRef: SessionRefSchema,
+            sourcePath: z
+                .string()
+                .trim()
+                .min(1)
+                .describe("Absolute path to a discovered repository-local or provider-project guidance source."),
+        },
+        outputSchema: {
+            status: z.enum(["deleted", "not_found"]),
+            projectId: z.string(),
+            projectName: z.string(),
+            projectPath: z.string(),
+            sourcePath: z.string(),
+            relativePath: z.string(),
+            kind: z.string(),
+            scope: z.enum(["repository-local", "provider-project"]),
+            provider: z.enum(["codex", "cursor", "claude"]).nullable(),
+        },
+    }, async (args) => {
+        const parsedArgs = DeleteGuidanceSourceArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return buildInvalidToolArgsResult("delete_guidance_source", parsedArgs.error);
+        }
+        const identity = resolveProjectIdentity(parsedArgs.data.projectPath);
+        const discoveredSources = await discoverExistingGuidance(identity.projectPath);
+        const targetPath = path.resolve(parsedArgs.data.sourcePath);
+        const source = discoveredSources.find((candidate) => path.resolve(candidate.path) === targetPath);
+        if (!source) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Guidance source is not currently discoverable for this project: ${targetPath}`,
+                    },
+                ],
+            };
+        }
+        const status = await deleteGuidancePath(targetPath);
+        await writeToolAuditEvent({
+            auditLogger: options.auditLogger,
+            sessionRef: parsedArgs.data.sessionRef,
+            tool: "delete_guidance_source",
+            action: "delete_guidance",
+            projectId: identity.projectId,
+            projectPath: identity.projectPath,
+            details: {
+                status,
+                sourcePath: targetPath,
+                relativePath: source.relativePath,
+                scope: source.scope,
+                provider: source.provider,
+            },
+        });
+        return buildStructuredToolResult({
+            status,
+            projectId: identity.projectId,
+            projectName: identity.projectName,
+            projectPath: identity.projectPath,
+            sourcePath: targetPath,
+            relativePath: source.relativePath,
+            kind: source.kind,
+            scope: source.scope,
+            provider: source.provider,
+        });
+    });
+};

package/dist/mcp/tools/registerListEntriesTool.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { ENTRY_KINDS, ENTRY_SCOPES } from "../../core/bank/types.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { AbsoluteProjectPathSchema } from "./sharedSchemas.js";
+const ListEntriesArgsSchema = z
+    .object({
+    scope: z.enum(ENTRY_SCOPES).optional().describe("Entry layer to query. Defaults to shared."),
+    kind: z.enum(ENTRY_KINDS).describe("Entry namespace to query. Allowed values: rules | skills."),
+    projectPath: AbsoluteProjectPathSchema.optional(),
+    group: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Optional subdirectory path inside the selected namespace."),
+})
+    .strict();
+export const registerListEntriesTool = (server, options) => {
+    server.registerTool("list_entries", {
+        title: "List AI Guidance Bank Entries",
+        description: "List rule or skill files from the local AI Guidance Bank.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            scope: z.enum(ENTRY_SCOPES).optional().describe("Entry layer to query. Defaults to shared."),
+            kind: z.enum(ENTRY_KINDS).describe("Entry namespace to query. Allowed values: rules | skills."),
+            projectPath: AbsoluteProjectPathSchema.optional(),
+            group: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("Optional subdirectory path inside the selected namespace."),
+        },
+        outputSchema: {
+            scope: z.enum(ENTRY_SCOPES),
+            kind: z.enum(ENTRY_KINDS),
+            projectPath: z.string().optional(),
+            group: z.string().optional(),
+            entries: z.array(z.object({
+                path: z.string(),
+            })),
+        },
+    }, async (args) => {
+        const parsedArgs = ListEntriesArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool list_entries: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        const scope = parsedArgs.data.scope ?? "shared";
+        if (scope === "project" && parsedArgs.data.projectPath === undefined) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "projectPath is required when scope is project.",
+                    },
+                ],
+            };
+        }
+        const projectId = scope === "project" && parsedArgs.data.projectPath
+            ? resolveProjectIdentity(parsedArgs.data.projectPath).projectId
+            : undefined;
+        const entries = scope === "project"
+            ? await options.repository.listLayerEntries("project", parsedArgs.data.kind, projectId, parsedArgs.data.group)
+            : await options.repository.listEntries(parsedArgs.data.kind, parsedArgs.data.group);
+        const payload = {
+            scope,
+            kind: parsedArgs.data.kind,
+            ...(parsedArgs.data.projectPath ? { projectPath: parsedArgs.data.projectPath } : {}),
+            ...(parsedArgs.data.group ? { group: parsedArgs.data.group } : {}),
+            entries,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(payload, null, 2),
+                },
+            ],
+            structuredContent: payload,
+        };
+    });
+};

package/dist/mcp/tools/registerReadEntryTool.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { ENTRY_KINDS, ENTRY_SCOPES } from "../../core/bank/types.js";
+import { resolveProjectIdentity } from "../../core/projects/identity.js";
+import { ValidationError } from "../../shared/errors.js";
+import { AbsoluteProjectPathSchema } from "./sharedSchemas.js";
+const ReadEntryArgsSchema = z
+    .object({
+    scope: z.enum(ENTRY_SCOPES).optional().describe("Entry layer to query. Defaults to shared."),
+    kind: z.enum(ENTRY_KINDS).describe("Entry namespace to query. Allowed values: rules | skills."),
+    projectPath: AbsoluteProjectPathSchema.optional(),
+    path: z.string().trim().min(1).describe("Relative file path inside the selected namespace."),
+})
+    .strict();
+export const registerReadEntryTool = (server, options) => {
+    server.registerTool("read_entry", {
+        title: "Read AI Guidance Bank Entry",
+        description: "Read a rule or skill file from the local AI Guidance Bank.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+        inputSchema: {
+            scope: z.enum(ENTRY_SCOPES).optional().describe("Entry layer to query. Defaults to shared."),
+            kind: z.enum(ENTRY_KINDS).describe("Entry namespace to query. Allowed values: rules | skills."),
+            projectPath: AbsoluteProjectPathSchema.optional(),
+            path: z.string().trim().min(1).describe("Relative file path inside the selected namespace."),
+        },
+        outputSchema: {
+            scope: z.enum(ENTRY_SCOPES),
+            kind: z.enum(ENTRY_KINDS),
+            projectPath: z.string().optional(),
+            path: z.string(),
+            content: z.string(),
+        },
+    }, async (args) => {
+        const parsedArgs = ReadEntryArgsSchema.safeParse(args);
+        if (!parsedArgs.success) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid arguments for tool read_entry: ${z.prettifyError(parsedArgs.error)}`,
+                    },
+                ],
+            };
+        }
+        try {
+            const scope = parsedArgs.data.scope ?? "shared";
+            if (scope === "project" && parsedArgs.data.projectPath === undefined) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: "projectPath is required when scope is project.",
+                        },
+                    ],
+                };
+            }
+            const projectId = scope === "project" && parsedArgs.data.projectPath
+                ? resolveProjectIdentity(parsedArgs.data.projectPath).projectId
+                : undefined;
+            const content = scope === "project"
+                ? await options.repository.readLayerEntry("project", parsedArgs.data.kind, parsedArgs.data.path, projectId)
+                : await options.repository.readEntry(parsedArgs.data.kind, parsedArgs.data.path);
+            const payload = {
+                scope,
+                kind: parsedArgs.data.kind,
+                ...(parsedArgs.data.projectPath ? { projectPath: parsedArgs.data.projectPath } : {}),
+                path: parsedArgs.data.path,
+                content,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: content,
+                    },
+                ],
+                structuredContent: payload,
+            };
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: error.message,
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+};