diff --git a/CLAUDE.md b/CLAUDE.md
index 432419d..a68d274 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -32,16 +32,24 @@ You are world-class NodeJS developer, senior engineer with a vast experience in
 ## Project Structure
 ```
 ├── src/                   # MCP server source code
-│   ├── main.ts            # Server entry point and tool registration
-│   ├── bear-urls.ts       # Bear app URL scheme handlers
-│   ├── database.ts        # SQLite database connection
-│   ├── notes.ts           # Note operations (search, content)
-│   ├── tags.ts            # Tag operations (list, hierarchy)
-│   ├── note-conventions.ts # Tag placement conventions for new notes
+│   ├── main.ts            # Server entry point
 │   ├── config.ts          # Configuration management
+│   ├── logging.ts         # Logging setup
 │   ├── types.ts           # Type definitions
-│   ├── utils.ts           # Shared utilities
-│   └── *.test.ts          # Unit tests (co-located with source files)
+│   ├── infra/             # Infrastructure layer
+│   │   ├── bear-urls.ts   # Bear app URL scheme handlers
+│   │   ├── database.ts    # SQLite database connection
+│   │   └── *.test.ts      # Unit tests (co-located with source files)
+│   ├── operations/        # Business logic layer
+│   │   ├── bear-encoding.ts # Bear encoding/decoding utilities
+│   │   ├── notes.ts       # Note operations (search, content)
+│   │   ├── note-conventions.ts # Tag placement conventions for new notes
+│   │   ├── tags.ts        # Tag operations (list, hierarchy)
+│   │   └── *.test.ts      # Unit tests (co-located with source files)
+│   └── tools/             # MCP tool handlers
+│       ├── note-tools.ts  # Note tool registrations and handlers
+│       ├── tag-tools.ts   # Tag tool registrations and handlers
+│       └── responses.ts   # Tool response helpers
 ├── tests/
 │   ├── fixtures/          # Test fixtures (sample notes, images)
 │   └── system/            # System tests (require Bear app running)
diff --git a/docs/dev/SPECIFICATION.md b/docs/dev/SPECIFICATION.md
index d887399..ef90fa3 100644
--- a/docs/dev/SPECIFICATION.md
+++ b/docs/dev/SPECIFICATION.md
@@ -62,7 +62,7 @@ There is no delete tool. Too destructive for AI-assisted workflows — a misiden
 
 Bear uses Core Data with SQLite. The schema is undocumented — our understanding comes from reverse-engineering (see `BEAR_DATABASE_SCHEMA.md`). The database path is hardcoded to Bear's app group container at `~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite` (overridable via `BEAR_DB_PATH` env var for tests). Key fragility points:
 
-- Tag name decoding logic exists in two places (SQL expression in `notes.ts` and TypeScript function in `tags.ts`) — these must produce identical results. Bidirectional comments link them.
+- Tag name decoding logic exists in two places (SQL expression in `notes.ts` and TypeScript function in `bear-encoding.ts`) — these must produce identical results. Bidirectional comments link them.
 - Tag hierarchy is not stored relationally — it's reconstructed at query time by splitting slash-delimited paths.
 - All queries exclude trashed, archived, and encrypted notes to match what Bear's UI shows.