@dizzlkheinz/ynab-mcpb 0.16.0 → 0.17.0

package/.code/agents/94a0ddf3-a304-4ec3-913e-3cceef509948/error.txt

@@ -0,0 +1 @@
+Failed to spawn sandboxed agent: batch file arguments are invalid

package/.code/agents/e2c752b7-711d-423a-af57-f53c809deb84/result.txt

@@ -0,0 +1,160 @@
+Here’s a concise blueprint for Phase 1 that matches the factory pattern doc and repo conventions.
+
+**Module layout (production-ready, minimal)**
+- `src/types/toolRegistration.ts`: canonical types/interfaces for tool definitions and adapters.
+- `src/tools/adapters/index.ts`: adapter factory functions for the five categories (adapt, adaptNoInput, adaptWithDelta, adaptWrite, inline); export typed helpers.
+- `src/tools/schemas/common.ts`: shared zod schemas for inputs/outputs/memo/delta, reusable across tools.
+- `src/tools/index.ts`: re-export adapters and shared schemas (and future tool registrations).
+- Tests: `src/__tests__/tools/adapters.test.ts` (unit, Vitest).
+
+**Core types (toolRegistration.ts)**
+```ts
+import { z } from 'zod';
+
+export type ToolKind =
+  | 'adapt'          // input schema -> handler(args) -> output
+  | 'adaptNoInput'   // no input -> handler() -> output
+  | 'adaptWithDelta' // input + delta/metadata -> output + delta?
+  | 'adaptWrite'     // input triggers mutation; output includes status
+  | 'inline';        // small inline tools (no registration factory)
+
+export interface ToolContext {
+  logger?: { debug?: (...args: any[]) => void; info?: (...args: any[]) => void; error?: (...args: any[]) => void };
+  now?: () => Date;
+  // extend later with cache, env, config
+}
+
+export type ToolHandler<Input, Output> = (args: {
+  input: Input;
+  context?: ToolContext;
+}) => Promise<Output> | Output;
+
+export type ToolHandlerNoInput<Output> = (args?: { context?: ToolContext }) => Promise<Output> | Output;
+
+export interface ToolRegistration<Input, Output> {
+  id: string; // kebab-case tool id
+  description: string;
+  inputSchema: z.ZodType<Input>;
+  outputSchema?: z.ZodType<Output>;
+  handler: ToolHandler<Input, Output>;
+  kind?: ToolKind; // optional hint for tooling/metrics
+}
+
+export interface ToolRegistrationNoInput<Output>
+  extends Omit<ToolRegistration<undefined, Output>, 'inputSchema' | 'handler'> {
+  handler: ToolHandlerNoInput<Output>;
+}
+```
+
+**Shared schemas (schemas/common.ts)**
+```ts
+import { z } from 'zod';
+
+export const memoSchema = z.string().max(500).optional();
+export const baseInputSchema = z.object({ memo: memoSchema }).strip();
+export const deltaSchema = z.object({
+  deltaToken: z.string(),
+  revision: z.number().int().nonnegative(),
+});
+export const statusSchema = z.object({
+  ok: z.boolean(),
+  message: z.string().optional(),
+});
+```
+
+**Adapters (tools/adapters/index.ts)**
+```ts
+import { z } from 'zod';
+import {
+  ToolRegistration,
+  ToolRegistrationNoInput,
+  ToolHandler,
+  ToolHandlerNoInput,
+} from '../../types/toolRegistration';
+
+type AdapterResult<Input, Output> = ToolRegistration<Input, Output>;
+
+export function adapt<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adapt' };
+}
+
+export function adaptNoInput<Output>(
+  config: Omit<ToolRegistrationNoInput<Output>, 'kind' | 'inputSchema'>,
+): AdapterResult<undefined, Output> {
+  return {
+    ...config,
+    inputSchema: z.void(),
+    kind: 'adaptNoInput',
+  };
+}
+
+export function adaptWithDelta<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adaptWithDelta' };
+}
+
+export function adaptWrite<Input, Output>(
+  config: Omit<ToolRegistration<Input, Output>, 'kind'>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'adaptWrite' };
+}
+
+// inline: kept simple; bypasses factory if needed, but helper for consistency
+export function inline<Input, Output>(
+  config: ToolRegistration<Input, Output>,
+): AdapterResult<Input, Output> {
+  return { ...config, kind: 'inline' };
+}
+
+export type {
+  ToolRegistration,
+  ToolRegistrationNoInput,
+  ToolHandler,
+  ToolHandlerNoInput,
+};
+```
+
+**Exports (src/tools/index.ts)**
+```ts
+export * from './adapters';
+export * as commonSchemas from './schemas/common';
+```
+
+**Unit test plan (src/__tests__/tools/adapters.test.ts)**
+- `adapt`: returns config with `kind: 'adapt'`, preserves handler and schema identity, and is type-safe for input/output.
+- `adaptNoInput`: sets `inputSchema` to `z.void()`, `kind: 'adaptNoInput'`, handler invoked without input, rejects passing unexpected input at runtime (zod parse).
+- `adaptWithDelta`: attaches `kind: 'adaptWithDelta'`, works with a schema that includes delta fields (e.g., merged input + `deltaSchema`).
+- `adaptWrite`: sets `kind: 'adaptWrite'`, supports output schema with status; ensure no mutation to original config.
+- `inline`: passes through config and sets `kind: 'inline'`.
+- Shared behaviors: returned objects are new instances (no mutation), required fields (`id`, `description`, `handler`) are preserved.
+- Validation snapshots: optional quick zod parse test per adapter (when schema is provided) to prove wiring.
+
+**Test scaffolding snippet**
+```ts
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  adapt,
+  adaptNoInput,
+  adaptWithDelta,
+  adaptWrite,
+  inline,
+} from '../../tools/adapters';
+import { deltaSchema, statusSchema } from '../../tools/schemas/common';
+
+describe('tool adapters', () => {
+  it('adapt sets kind and preserves config', async () => { /* ... */ });
+  it('adaptNoInput sets z.void and kind', async () => { /* ... */ });
+  it('adaptWithDelta supports delta schema', async () => { /* ... */ });
+  it('adaptWrite marks kind adaptWrite', async () => { /* ... */ });
+  it('inline marks kind inline', async () => { /* ... */ });
+});
+```
+
+**Notes**
+- Keep adapters thin; no side effects. `kind` supports metrics/routing; callers can branch on it.
+- Shared schemas stay minimal; expand as new tools land.
+- Maintain kebab-case `id` per repo guidance; single export surface via `src/tools/index.ts`.

package/.code/agents/e6601719-c31f-4a0e-8c71-d70787d0ab71/status.txt

@@ -0,0 +1 @@
+Agent cancelled

package/.code/agents/f250b7ed-5bd5-4036-aa8c-ce63caee7d61/result.txt

@@ -0,0 +1,20 @@
+**MCP Tool Catalogue**
+- **Budgets** (`src/server/YNABMCPServer.ts:467-540`): `list_budgets` (delta adapter; input inline `emptyObjectSchema`; output `ListBudgetsOutputSchema`), `get_budget` (read adapter; input `GetBudgetSchema` from `src/tools/budgetTools.ts`; output `GetBudgetOutputSchema`), `set_default_budget` (inline server write; input inline `setDefaultBudgetSchema`; output `SetDefaultBudgetOutputSchema`), `get_default_budget` (inline server read; input inline `emptyObjectSchema`; output `GetDefaultBudgetOutputSchema`).
+- **Accounts** (`src/server/YNABMCPServer.ts:573-615`): `list_accounts` (delta; input `ListAccountsSchema`; output `ListAccountsOutputSchema`), `get_account` (read; input `GetAccountSchema`; output `GetAccountOutputSchema`), `create_account` (write; input `CreateAccountSchema`; output inline `LooseObjectSchema`).
+- **Transactions – read/delta** (`src/server/YNABMCPServer.ts:618-692`): `list_transactions` (delta; input `ListTransactionsSchema`; output `LooseObjectSchema`), `export_transactions` (read; input `ExportTransactionsSchema`; output `ExportTransactionsOutputSchema`), `compare_transactions` (read; input `CompareTransactionsSchema`; output `CompareTransactionsOutputSchema`), `reconcile_account` (delta; input `ReconcileAccountSchema`; output `LooseObjectSchema`), `get_transaction` (read; input `GetTransactionSchema`; output `GetTransactionOutputSchema`).
+- **Transactions – write** (`src/server/YNABMCPServer.ts:694-785`): `create_transaction`, `create_transactions`, `create_receipt_split_transaction` (all write adapters; inputs `CreateTransactionSchema`/`CreateTransactionsSchema`/`CreateReceiptSplitTransactionSchema`; outputs `LooseObjectSchema`), `update_transaction`, `update_transactions` (write; inputs `UpdateTransactionSchema`/`UpdateTransactionsSchema`; outputs `LooseObjectSchema`), `delete_transaction` (write; input `DeleteTransactionSchema`; output `LooseObjectSchema`).
+- **Categories** (`src/server/YNABMCPServer.ts:787-830`): `list_categories` (delta; input `ListCategoriesSchema`; output `ListCategoriesOutputSchema`), `get_category` (read; input `GetCategorySchema`; output `GetCategoryOutputSchema`), `update_category` (write; input `UpdateCategorySchema`; output `LooseObjectSchema`).
+- **Payees** (`src/server/YNABMCPServer.ts:832-860`): `list_payees` (delta; input `ListPayeesSchema`; output `ListPayeesOutputSchema`), `get_payee` (read; input `GetPayeeSchema`; output `GetPayeeOutputSchema`).
+- **Months** (`src/server/YNABMCPServer.ts:862-889`): `get_month` (read; input `GetMonthSchema`; output `GetMonthOutputSchema`), `list_months` (delta; input `ListMonthsSchema`; output `ListMonthsOutputSchema`).
+- **Utilities/Local** (`src/server/YNABMCPServer.ts:892-998`): `get_user` (no-input adapter; input inline `emptyObjectSchema`; output `GetUserOutputSchema`), `convert_amount` (inline local handler; input `ConvertAmountSchema` from `src/tools/utilityTools.ts`; output `ConvertAmountOutputSchema`), `diagnostic_info` (inline server; input inline `diagnosticInfoSchema`; output `DiagnosticInfoOutputSchema`), `clear_cache` (inline server; input inline `emptyObjectSchema`; output `ClearCacheOutputSchema`), `set_output_format` (inline server; input inline `setOutputFormatSchema`; output `SetOutputFormatOutputSchema`).
+
+**Inline Schema Observations**
+- Inline definitions in `src/server/YNABMCPServer.ts:446-465` (`emptyObjectSchema`, `LooseObjectSchema`, `setDefaultBudgetSchema`, `diagnosticInfoSchema`, `setOutputFormatSchema`) are reused across tools and could move to a shared schema module (e.g., `src/tools/schemas/common.ts`) to reduce duplication and keep registrations declarative.
+- Most tools already pull input/output schemas from feature modules (`src/tools/*` and `src/tools/schemas/outputs/index.ts`); only the inline schemas above break that pattern.
+
+**Server-Owned Inline Tools to Keep Inline**
+- `set_default_budget`, `get_default_budget`, `diagnostic_info`, `clear_cache`, and `set_output_format` rely on server state (default budget cache warming, diagnostic manager, cache manager, response formatter) and likely stay in `YNABMCPServer` even if their schemas are centralized.
+
+**Notes for Migration**
+- Budget-aware tools share `defaultArgumentResolver` to inject `budget_id`; keep this resolver available wherever registrations move.
+- `LooseObjectSchema` is the permissive output for many write/delta tools—consider replacing with explicit output schemas in `src/tools/schemas/outputs` if stability is desired.

package/AGENTS.md

@@ -1,36 +1 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-
-`src/` hosts all TypeScript modules: `server/` wires the MCP host, `tools/` defines tool handlers, `utils/` shares primitives, and `index.ts` is the entry point.
-Tests live in `src/__tests__` (unit, integration, e2e, performance) with sanitized fixtures in `test-exports/` and artifacts in `test-results/`.
-Documentation stays in `docs/`, automation in `scripts/`, and compiled output in `dist/` plus `dist/bundle/`; never edit generated files directly.
-
-## Build, Test, and Development Commands
-
-- `npm run dev` - incremental TypeScript build while coding.
-- `npm run build` - clean `dist/`, compile, then esbuild-bundle.
-- `npm run build:prod` / `npm run package:mcpb` - production bundle with verification and MCPB packing.
-- `npm start` or `npm run start:mcp` - launch compiled server with `.env`.
-- `npm run validate-env` - confirm required secrets before tool runs.
-
-## Coding Style & Naming Conventions
-
-Prettier enforces 2-space indent, 100-char width, single quotes, and semicolons; verify with `npm run format:check`.
-ESLint (`npm run lint`) must pass before commits; prefer `npm run lint:fix` for safe rewrites.
-Name files after their capability (`budgetService.ts`, `create-account.tool.ts`) and keep MCP tool identifiers kebab-case with ES modules and explicit dependency injection.
-
-## Testing Guidelines
-
-Vitest powers the suite: `npm test` runs everything then filters failures into `test-results.json`, while `test:unit`, `test:integration`, `test:e2e`, `test:performance`, and `test:coverage` target specific goals.
-Use `test:comprehensive` (tsx runner) for orchestration flows, mirror test filenames to the feature, and update fixtures only with scrubbed data.
-
-## Commit & Pull Request Guidelines
-
-History follows Conventional Commits (`docs:`, `fix:`, `refactor:`); keep patches focused and note verification commands in every PR.
-Run `npm run pr:description` to refresh `.pr-description.md` before `gh pr create`, link issues, and attach screenshots or sample JSON for user-facing changes.
-
-## Environment & Security Tips
-
-Clone `.env` from `.env.example`, set `YNAB_ACCESS_TOKEN` plus cache settings, then rerun `npm run validate-env` after edits.
-Avoid logging secrets, prefer sample budgets when demonstrating behaviors, and delete stray exports from `test-exports/` before pushing.
+CLAUDE.md

package/CLAUDE.md

@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a Model Context Protocol (MCP) server for YNAB (You Need A Budget) integration, enabling AI assistants to interact with YNAB budgets, accounts, transactions, and categories. The codebase uses TypeScript with a modular architecture introduced in v0.8.x.
+This is a Model Context Protocol (MCP) server for YNAB (You Need A Budget) integration, enabling AI assistants to interact with YNAB budgets, accounts, transactions, and categories. The codebase uses TypeScript with a modular, service-oriented architecture.
+
+**Current Version:** 0.17.0
 
 ## Essential Commands
 
@@ -18,22 +20,31 @@ npm run dev                # TypeScript watch mode for development
 npm run type-check         # Run TypeScript type checking without emitting files
 ```
 
-See [docs/development/BUILD.md](docs/development/BUILD.md) for detailed build information.
-
 ### Testing
 
 ```bash
-npm test                   # Run all unit tests + filter results
-npm run test:unit          # Unit tests only (fast, mocked dependencies)
-npm run test:integration   # Integration tests with mocked YNAB API
-npm run test:e2e           # End-to-end tests (requires real YNAB token)
-npm run test:performance   # Performance and load tests
-npm run test:coverage      # Generate coverage report (requires 80% coverage)
-npm run test:watch         # Watch mode for test development
+npm test                           # Run all unit tests + filter results
+npm run test:unit                  # Unit tests only (fast, mocked dependencies)
+npm run test:integration           # Integration tests (core only)
+npm run test:integration:core      # Core integration tests
+npm run test:integration:domain    # Domain-specific integration tests
+npm run test:integration:full      # Full integration test suite (throttled)
+npm run test:integration:budgets   # Budget-specific integration tests
+npm run test:integration:accounts  # Account-specific integration tests
+npm run test:integration:transactions  # Transaction-specific integration tests
+npm run test:integration:categories    # Category-specific integration tests
+npm run test:integration:payees    # Payee-specific integration tests
+npm run test:integration:months    # Month-specific integration tests
+npm run test:integration:delta     # Delta caching integration tests
+npm run test:integration:reconciliation  # Reconciliation integration tests
+npm run test:e2e                   # End-to-end tests (requires real YNAB token)
+npm run test:performance           # Performance and load tests
+npm run test:coverage              # Generate coverage report (requires 80% coverage)
+npm run test:watch                 # Watch mode for test development
+npm run test:comprehensive         # Run comprehensive test suite
+npm run test:all                   # Run all tests (unit, integration, e2e, performance)
 ```
 
-See [docs/guides/TESTING.md](docs/guides/TESTING.md) for comprehensive testing documentation.
-
 ### Code Quality
 
 ```bash
@@ -48,31 +59,43 @@ npm run format:check       # Check formatting without modifying files
 ```bash
 npm run package:mcpb        # Build production MCPB package for Claude Desktop
 npm run generate:mcpb       # Generate MCPB file from built bundle
-npm run bundle             # Bundle with esbuild (development)
-npm run bundle:prod        # Bundle with minification (production)
+npm run bundle              # Bundle with esbuild (development)
+npm run bundle:prod         # Bundle with minification (production)
+npm run prepare             # Prepare package for publication (runs build:prod)
+npm run prepublishOnly      # Pre-publish checks (runs tests + build)
 ```
 
-See [docs/guides/DEPLOYMENT.md](docs/guides/DEPLOYMENT.md) for deployment instructions.
-
 ## Architecture Overview
 
-The v0.8.x architecture is modular and service-oriented:
+The architecture is modular and service-oriented:
 
 ### Core Server Components (`src/server/`)
 
 - **YNABMCPServer.ts** - Main orchestration server, coordinates all services
 - **toolRegistry.ts** - Centralized tool metadata, validation, and execution
 - **cacheManager.ts** - Enhanced caching with LRU eviction, observability, and stale-while-revalidate
+- **deltaCache.ts** - Delta request management with server knowledge tracking and merge operations
+- **deltaCache.merge.ts** - Entity merging functions for delta responses (transactions, categories, accounts)
+- **serverKnowledgeStore.ts** - Tracks last known server_knowledge values per cache key for delta requests
 - **budgetResolver.ts** - Consistent budget ID resolution across all tools
 - **errorHandler.ts** - Centralized error handling with dependency injection
 - **config.ts** - Environment validation and server configuration
-- **resources.ts** - MCP resource definitions and handlers
+- **resources.ts** - MCP resource definitions and handlers (includes resource templates)
 - **prompts.ts** - MCP prompt definitions and handlers
 - **diagnostics.ts** - System diagnostics and health monitoring
 - **securityMiddleware.ts** - Security validation and wrapper functions
 - **responseFormatter.ts** - JSON response formatting (minification/pretty-print)
 - **rateLimiter.ts** - Rate limiting for YNAB API compliance
 - **requestLogger.ts** - Request/response logging middleware
+- **cacheKeys.ts** - Centralized cache key generation utilities
+
+### Tool Registration Pattern (2025-12)
+
+- `ToolContext` (`src/types/toolRegistration.ts`) centralizes shared deps (ynabAPI, deltaFetcher/cache, knowledge store, default budget accessors, cache/diagnostic managers).
+- Adapter helpers (`src/tools/adapters.ts`): `adapt`, `adaptNoInput`, `adaptWithDelta`, `adaptWrite`, and `createBudgetResolver` to inject default budget IDs; covered by unit tests in `src/tools/__tests__/adapters.test.ts`.
+- Domain factories (`register*Tools`) live in each tool file: budget, account, transaction, category, payee, month, utility, reconciliation. `setupToolRegistry` now delegates to these factories.
+- Shared schemas: `emptyObjectSchema`, `looseObjectSchema` in `src/tools/schemas/common.ts`.
+- Server-owned inline tools that stay in `YNABMCPServer`: `set_default_budget`, `get_default_budget`, `diagnostic_info`, `clear_cache`, `set_output_format` (they depend on server internals).
 
 ### Tool Implementation (`src/tools/`)
 
@@ -85,13 +108,29 @@ Tools are organized by domain with some using modular sub-directories:
 - **payeeTools.ts** - Payee listing and retrieval
 - **monthTools.ts** - Monthly budget data
 - **utilityTools.ts** - User info and amount conversion
+- **adapters.ts** - Tool adapter implementations
+- **toolCategories.ts** - Tool categorization utilities
+- **compareTransactions.ts** - Transaction comparison tool entry point
 - **exportTransactions.ts** - Transaction export to JSON files
-- **reconcileAccount.ts** - Comprehensive account reconciliation
+- **reconcileAdapter.ts** - Legacy adapter for reconciliation tool
+- **deltaFetcher.ts** - Delta request utilities for efficient API updates
+- **deltaSupport.ts** - Delta request support utilities and helpers
 
 **Modular Tool Directories:**
 
 - **compareTransactions/** - CSV comparison tools split into parser, matcher, formatter
-- **financialOverview/** - Financial analysis split into schemas, handlers, insights, trends, formatter
+- **reconciliation/** - Comprehensive account reconciliation system (v2 architecture)
+  - csvParser.ts - CSV parsing with bank presets (TD, RBC, Scotiabank, etc.)
+  - matcher.ts - Fuzzy matching engine with configurable scoring
+  - analyzer.ts - Transaction analysis and discrepancy detection
+  - executor.ts - Bulk transaction operations (create/update/unclear)
+  - recommendationEngine.ts - Smart reconciliation recommendations
+  - reportFormatter.ts - Human-readable reconciliation reports
+  - signDetector.ts - Auto-detection of debit/credit sign conventions
+  - payeeNormalizer.ts - Payee name normalization for matching
+  - ynabAdapter.ts - YNAB API integration layer
+- **schemas/** - Zod schemas for input/output validation
+  - outputs/ - Output schema definitions for all tools
 
 ### Type Definitions (`src/types/`)
 
@@ -119,7 +158,7 @@ registry.register({
 });
 ```
 
-### Enhanced Caching (v0.8.x)
+### Enhanced Caching with Delta Support
 
 Use `cacheManager.wrap()` for automatic caching with observability:
 
@@ -139,6 +178,30 @@ Cache TTL constants are defined in `cacheManager.ts`:
 - `CACHE_TTLS.SHORT` - 5 minutes (transactions)
 - `CACHE_TTLS.LONG` - 1 hour
 
+### Delta Caching Pattern
+
+The server supports YNAB delta requests to fetch only changed data since the last request:
+
+```typescript
+import { DeltaCache } from './server/deltaCache.js';
+import { ServerKnowledgeStore } from './server/serverKnowledgeStore.js';
+
+// Delta cache automatically manages server_knowledge tracking
+const result = await deltaCache.fetchWithDelta({
+  cacheKey: 'transactions:budget123',
+  fetchFn: (lastKnowledge) => api.getTransactions(budgetId, lastKnowledge),
+  mergeFn: DeltaCache.mergeTransactions, // Built-in merge functions available
+});
+```
+
+The delta cache system:
+
+- Tracks `server_knowledge` values per cache key via `ServerKnowledgeStore`
+- Automatically merges delta responses with cached snapshots
+- Provides built-in merge functions for transactions, categories, and accounts
+- Resets knowledge on server restart to ensure consistency
+- Handles large knowledge gaps and edge cases
+
 ### Budget Resolution Pattern
 
 Use `BudgetResolver` for consistent budget ID handling:
@@ -174,6 +237,20 @@ constructor(
 ) {}
 ```
 
+## MCP Resources
+
+The server provides MCP resources for dynamic data access:
+
+### Resource Templates
+
+Resource templates allow AI assistants to discover and access YNAB data using URI patterns:
+
+- `ynab://budgets/{budget_id}` - Get detailed budget information
+- `ynab://budgets/{budget_id}/accounts` - List accounts for a specific budget
+- `ynab://budgets/{budget_id}/accounts/{account_id}` - Get detailed account information
+
+Resources support full caching with configurable TTLs and return structured data that AI assistants can use for analysis and recommendations.
+
 ## Tool Annotations
 
 All tools include MCP-compliant annotations as advisory hints for AI clients. These annotations follow the Model Context Protocol specification and help AI assistants understand tool capabilities, safety characteristics, and expected behavior. The annotation system uses type-safe presets defined in `src/tools/toolCategories.ts` via the `ToolAnnotationPresets` constant.
@@ -236,17 +313,6 @@ All 30 tools are classified into the following categories:
 
 - `get_default_budget`, `convert_amount`, `diagnostic_info`, `clear_cache`, `set_output_format`
 
-### Expected Benefits
-
-The tool annotation system provides several advantages:
-
-- **Enhanced AI Client UX** - AI assistants like Claude can show warnings/confirmations for destructive tools
-- **Safer Workflows** - AI understands which tools are dangerous and can prompt for confirmation before execution
-- **Better Tool Discovery** - Annotations help AI clients understand tool capabilities and constraints
-- **Future-Proof Integration** - As more MCP clients emerge, they'll respect these standard annotations
-- **Self-Documenting API** - Metadata provides clear documentation of tool behavior without reading implementation
-- **Zero Breaking Changes** - Fully backward compatible, annotations are advisory only and don't affect tool execution
-
 ### Usage Example
 
 Tool annotations are applied during tool registration using preset patterns:
@@ -366,7 +432,7 @@ Strict mode enabled with extensive safety checks:
 3. Register tool in `YNABMCPServer.ts` using `ToolRegistry`
 4. Add unit tests in `src/tools/__tests__/myTools.test.ts`
 5. Add integration tests in `src/tools/__tests__/myTools.integration.test.ts`
-6. Update API documentation in `docs/API.md`
+6. Update API documentation in `docs/reference/API.md`
 
 ### Modifying Cache Behavior
 
@@ -381,34 +447,48 @@ Service modules (like diagnostics, resources, prompts) follow a pattern:
 3. Register in `YNABMCPServer` constructor
 4. Add tests in `src/server/__tests__/`
 
-## MCPB Packaging for Claude Desktop
+## Git Workflow
+
+- **Main branch**: `master`
+- **Commit style**: Conventional commits (feat:, fix:, chore:, refactor:, test:, docs:)
+- Run `npm test` and `npm run lint` before committing
+- PR titles should follow: `type: description` (e.g., `feat: add bulk transaction import`)
 
-The project builds a `.mcpb` file (MCP extension for Claude Desktop):
+## Reconciliation System
 
-```bash
-npm run package:mcpb
-```
+The reconciliation tool (`reconcile_account`) is a comprehensive account reconciliation system with advanced features:
 
-Output: `dist/ynab-mcp-server-<version>.mcpb`
+### Key Components
 
-The MCPB includes:
+- **CSV Parser** - Supports multiple bank formats with presets for Canadian banks (TD, RBC, Scotiabank, Wealthsimple, Tangerine)
+- **Fuzzy Matcher** - Uses token-set-ratio matching for merchant name variations
+- **Analyzer** - Detects discrepancies, duplicates, and missing transactions
+- **Executor** - Handles bulk create/update/unclear operations with comprehensive error handling
+- **Recommendation Engine** - Provides smart reconciliation suggestions
+- **Sign Detector** - Auto-detects debit/credit sign conventions from CSV data
 
-- Bundled Node.js code (single file, no node_modules)
-- Manifest with extension metadata
-- Environment variable configuration schema
+### Configuration
 
-## Git & Version Control
+- Amount tolerance: 1 cent (10 milliunits) by default
+- Date tolerance: 7 days (accommodates bank posting delays)
+- Scoring weights: amount 50%, payee 35%, date 15%
+- Auto-match threshold: 85%
 
-- **Main branch**: `master`
-- **Versioning**: Semantic versioning (currently 0.x.y - pre-1.0 API)
-- **Commit style**: Conventional commits encouraged (feat:, fix:, chore:, etc.)
+See `docs/technical/reconciliation-system-architecture.md` for detailed documentation.
+
+## Boundaries
+
+- ✅ **Always do**: Run `npm test` before commits, use milliunits for YNAB amounts, follow existing patterns
+- ✅ **Always do**: Use `.js` extensions in imports, validate inputs with Zod schemas
+- ⚠️ **Ask first**: Adding new dependencies, changing API response formats, modifying cache TTLs
+- 🚫 **Never do**: Commit `.env` or secrets, edit `dist/` or `node_modules/`, skip type checking
+- 🚫 **Never do**: Remove failing tests without fixing, use `any` type without justification
 
 ## Important Notes
 
-- **Backward Compatibility**: v0.8.x maintains 100% API compatibility with v0.7.x
-- **Cache Invalidation**: Write operations (create, update, delete) should invalidate related caches
+- **Amount Handling**: YNAB uses milliunits (1 dollar = 1000 milliunits) - always convert
 - **Date Format**: Always use ISO format `YYYY-MM-DD` for dates
 - **Budget ID Resolution**: Most tools auto-resolve budget_id from default budget if not provided
 - **Error Responses**: All errors return consistent JSON format via `ErrorHandler`
-- **Security**: Input validation via Zod schemas, security middleware wraps all tool executions
-- **Rate Limiting**: YNAB API has rate limits - use caching aggressively
+- **Cache Invalidation**: Write operations (create, update, delete) should invalidate related caches
+- **Rate Limiting**: YNAB API has rate limits - use delta caching and aggressive caching strategies

package/NUL

@@ -1 +0,0 @@
-dir: cannot access '/B': No such file or directory

package/README.md

@@ -60,7 +60,7 @@ Add this to your Claude Desktop MCP settings file:
   "mcpServers": {
     "ynab": {
       "command": "npx",
-      "args": ["-y", "@dizzlkheinz/ynab-mcpb"],
+      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
       "env": {
         "YNAB_ACCESS_TOKEN": "your-token-here"
       }
@@ -81,7 +81,7 @@ Add this to your Cline MCP settings:
   "mcpServers": {
     "ynab": {
       "command": "npx",
-      "args": ["-y", "@dizzlkheinz/ynab-mcpb"],
+      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
       "env": {
         "YNAB_ACCESS_TOKEN": "your-token-here"
       }
@@ -92,13 +92,28 @@ Add this to your Cline MCP settings:
 
 </details>
 
+<details>
+<summary><b>Codex</b></summary>
+
+Add this to your configuration file:
+
+```toml
+[mcp_servers.ynab-mcpb]
+command = "npx"
+args = ["-y", "@dizzlkheinz/ynab-mcpb@latest"]
+env = {"YNAB_ACCESS_TOKEN" = "your-token-here"}
+startup_timeout_sec = 120
+```
+
+</details>
+
 <details>
 <summary><b>Other MCP Clients</b></summary>
 
 For any MCP-compatible client, configure the server with:
 
 **Command:** `npx`
-**Arguments:** `["-y", "@dizzlkheinz/ynab-mcpb"]`
+**Arguments:** `["-y", "@dizzlkheinz/ynab-mcpb@latest"]`
 **Environment Variables:**
 
 - `YNAB_ACCESS_TOKEN`: Your YNAB Personal Access Token
@@ -133,7 +148,7 @@ Example:
   "mcpServers": {
     "ynab": {
       "command": "npx",
-      "args": ["-y", "@dizzlkheinz/ynab-mcpb"],
+      "args": ["-y", "@dizzlkheinz/ynab-mcpb@latest"],
       "env": {
         "YNAB_ACCESS_TOKEN": "your-token-here",
         "YNAB_EXPORT_PATH": "C:\\Users\\YourName\\Documents"
@@ -143,7 +158,7 @@ Example:
 }
 ```
 
-For advanced configuration options (caching, output formatting), see the [Configuration Guide](docs/getting-started/CONFIGURATION.md).
+For advanced configuration options (caching, output formatting), see the `.env.example` file in the repository.
 
 ## What's Available
 
@@ -168,12 +183,16 @@ The server gives Claude access to 30 tools organized by function. You don't need
 - Find missing transactions
 - Track budget performance
 
+## MCP Resources
+
+- Access budget and account data via URI patterns (e.g., `ynab://budgets/{id}`)
+- Static resources: `ynab://budgets`, `ynab://user`
+
 For the complete list with technical details, see the [API Reference](docs/reference/API.md).
 
 ## Need Help?
 
-- **[Troubleshooting Guide](docs/reference/TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Full Documentation](docs/README.md)** - Complete guides and API reference
+- **[API Reference](docs/reference/API.md)** - Complete tool documentation
 - **[GitHub Issues](https://github.com/dizzlkheinz/ynab-mcpb/issues)** - Report bugs or request features
 
 ## For Developers
@@ -214,12 +233,6 @@ Want to contribute or build from source?
    npm test
    ```
 
-### Additional Resources
-
-- **[Development Guide](docs/guides/DEVELOPMENT.md)** - Setup and best practices
-- **[Architecture Overview](docs/guides/ARCHITECTURE.md)** - How the code is organized
-- **[Testing Guide](docs/guides/TESTING.md)** - Running and writing tests
-
 ## Security & Privacy
 
 Your YNAB access token is stored securely and never logged. All communication with YNAB's API uses HTTPS, and the server validates all inputs to prevent errors and security issues.
@@ -233,7 +246,7 @@ Contributions welcome! Please:
 3. Add tests for new features
 4. Submit a pull request
 
-See the [Development Guide](docs/guides/DEVELOPMENT.md) for details.
+See `CLAUDE.md` for development details and architecture overview.
 
 ## License