Skip to content

A native macOS / windows / Linux database IDE built with Swift and AppKit. Connect to PostgreSQL, MySQL, SQLite, and Redis from a single app with a fast, keyboard-driven interface.

C++

docs(agents): macOS AGENTS.md catalog + CLAUDE.md import

Tobiaadf77cec73a
diff --git a/CLAUDE.md b/CLAUDE.md
index daced9b..84ccfc0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -63,3 +63,13 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+---
+
+## Platform-specific guidance
+
+When touching macOS code, the following file is auto-imported. It catalogs reusable
+contracts, services, UI components, and the Do/Don't lessons from real incidents —
+read it before adding helpers or patterns of your own.
+
+@macos/AGENTS.md
diff --git a/macos/AGENTS.md b/macos/AGENTS.md
new file mode 100644
index 0000000..631fc4b
--- /dev/null
+++ b/macos/AGENTS.md
@@ -0,0 +1,288 @@
+# AGENTS.md — Gridex macOS
+
+Guide for AI agents (Claude, Codex, Cline, …) working on the macOS Swift codebase. Scope: everything under [macos/](.). Windows and Linux ports have their own conventions.
+
+**Read order on every new task:**
+1. This file.
+2. [`CLAUDE.md`](../CLAUDE.md) at the repo root (project overview + behavioural guard-rails — `Think before coding`, `Surgical changes`, `Goal-driven execution`).
+3. The closest existing adapter/service to what you're touching — copy its shape before inventing your own.
+
+If anything in this file conflicts with `CLAUDE.md`, the root `CLAUDE.md` wins. This file is the **macOS-specific** layer on top.
+
+---
+
+## 0. Architecture invariants — non-negotiable
+
+These are load-bearing. Don't violate them without an explicit user instruction.
+
+- **5-layer Clean Architecture, dependencies point inward only.**
+ `Core ← Domain ← Data ← Services ← Presentation`. Core has zero dependencies. Data implements Domain. Presentation never imports Data directly.
+- **Single `DependencyContainer.shared`** at [`App/DependencyInjection/DependencyContainer.swift`](App/DependencyInjection/DependencyContainer.swift) is the only composition root. Don't `init` services elsewhere; ask the container.
+- **Thread-safe services are `actor`.** `ConnectionManager`, `QueryEngine`, `MCPServer`, `SSHTunnelService`, `SchemaInspectorService`, `ProviderRegistry`, `BackupService` are all actors. Cross-actor types must be `Sendable`.
+- **Domain models are plain Swift** (`struct`, `Codable`, `Sendable`). SwiftData `@Model` entities live only under [`Data/Persistence/Models/`](Data/Persistence/Models/) and round-trip via `toConfig()` / equivalent.
+- **Errors are `GridexError`.** Never throw raw `NSError` or driver errors out of an adapter. Wrap with the matching case.
+- **Credentials live in Keychain.** `KeychainService` (via `keychainService` on the container). Passwords are passed into adapters in-memory only; they are never on `ConnectionConfig`.
+- **No global mutable state besides `DependencyContainer.shared` and `AppState`.** Per-window state goes on `AppState`; global on the container.
+
+---
+
+## 1. Reusable surface — use these before writing new code
+
+Before introducing a new helper/protocol/model, scan this section. Hidden coupling notes in `[Coupling]` callouts.
+
+### 1.1 Core protocols — the contracts
+
+| Protocol | File | Conform when… |
+|---|---|---|
+| `DatabaseAdapter` | [Core/Protocols/Database/DatabaseAdapter.swift](Core/Protocols/Database/DatabaseAdapter.swift) | Adding a new database engine. ~50 methods covering connect/disconnect, execute (incl. parameterized), schema introspection, CRUD, pagination, transactions. |
+| `SchemaInspectable` | [Core/Protocols/Database/SchemaInspectable.swift](Core/Protocols/Database/SchemaInspectable.swift) | The new adapter can introspect schemas. Powers AI context + ER diagram. |
+| `LLMService` | [Core/Protocols/AI/LLMService.swift](Core/Protocols/AI/LLMService.swift) | Adding a new AI provider. Streaming-first, `AsyncThrowingStream`. |
+| `AIContextProvider` | [Core/Protocols/AI/AIContextProvider.swift](Core/Protocols/AI/AIContextProvider.swift) | You almost certainly don't need a new one — reuse `aiContextEngine` from the container. |
+| `MCPTool` | `Services/MCP/Tools/` | Adding a new MCP tool. Must declare permission tier + input schema. |
+
+### 1.2 Core models — the value types every layer exchanges
+
+| Model | File | Notes |
+|---|---|---|
+| `RowValue` | [Core/Models/Database/RowValue.swift](Core/Models/Database/RowValue.swift) | Unified cell type (null/string/int/double/bool/date/uuid/json/data/array). Always use; never leak driver-native types upward. |
+| `ConnectionConfig` | [Core/Models/Database/ConnectionConfig.swift](Core/Models/Database/ConnectionConfig.swift) | Canonical connection spec. Includes `mongoOptions: [String:String]?` (URI query params), SSH tunnel config, mTLS cert paths. **Password is NOT a field** — passed separately. |
+| `QueryResult` | [Core/Models/Query/QueryResult.swift](Core/Models/Query/QueryResult.swift) | Standard query output. `columns + rows + rowsAffected + executionTime + queryType`. |
+| `QueryParameter` | [Core/Models/Query/QueryParameter.swift](Core/Models/Query/QueryParameter.swift) | Wraps `RowValue` for parameterized execution. Adapters bind via dialect-specific placeholders. |
+| `FilterExpression` | [Core/Models/Query/FilterExpression.swift](Core/Models/Query/FilterExpression.swift) | Grid filter UI → SQL. `toSQL(dialect:)` builds the WHERE clause. **Use this; never concat WHERE strings by hand.** |
+| `QuerySortDescriptor` | [Core/Models/Query/SortDescriptor.swift](Core/Models/Query/SortDescriptor.swift) | Grid sort state → ORDER BY. |
+| `SchemaSnapshot`, `TableDescription`, `ColumnInfo`, `IndexInfo`, `ForeignKeyInfo`, `ViewInfo`, `TableInfo` | [Core/Models/Schema/](Core/Models/Schema/) | Schema introspection output. `TableDescription.toDDL(dialect:)` regenerates CREATE TABLE for export. |
+| `AIContext`, `LLMMessage`, `ChatMessage` | [Core/Models/AI/AIModels.swift](Core/Models/AI/AIModels.swift) | AI chat data model (token-budgeted context, role messages, persisted history with inlined SQL/results). |
+| `ProviderConfig` | [Core/Models/AI/ProviderConfig.swift](Core/Models/AI/ProviderConfig.swift) | Runtime AI provider config. API key is **not** a field — fetched from Keychain via `"ai.apikey.<uuid>"`. |
+
+### 1.3 Errors
+
+All in [`Core/Errors/GridexError.swift`](Core/Errors/GridexError.swift). Pick the closest case; don't add a new one without a real distinct meaning.
+
+| Case | Throw it when |
+|---|---|
+| `connectionFailed(underlying:)` | Adapter `connect()` fails. Wrap the driver error. |
+| `connectionTimeout` | Connection didn't respond within timeout. |
+| `authenticationFailed` | Credentials rejected. |
+| `sslRequired` | Server demands TLS but config disables it. |
+| `queryExecutionFailed(String)` | Query syntax/runtime error. **Wrap driver errors via the adapter's formatter** (see 1.6). |
+| `queryCancelled`, `queryTimeout` | Self-explanatory. |
+| `sshConnectionFailed`, `sshAuthenticationFailed`, `sshTunnelFailed` | SSH tunnel failure paths. |
+| `schemaLoadFailed(String)`, `tableNotFound(String)` | Schema introspection failed. |
+| `aiProviderError`, `aiAPIKeyMissing`, `aiTokenLimitExceeded`, `aiStreamingError` | LLM provider failures. |
+| `keychainError`, `persistenceError`, `importError`, `exportError` | I/O & persistence. |
+| `unsupportedOperation(String)`, `internalError(String)` | Last resort. Prefer a more specific case if one fits. |
+
+### 1.4 Key enums (verified — use exact case names)
+
+| Enum | File | Cases |
+|---|---|---|
+| `DatabaseType` | [Core/Enums/DatabaseType.swift](Core/Enums/DatabaseType.swift) | `.sqlite, .postgresql, .mysql, .redis, .mongodb, .mssql, .clickhouse` |
+| `SQLDialect` | [Core/Enums/SQLDialect.swift](Core/Enums/SQLDialect.swift) | one per `DatabaseType`; carries `quoteIdentifier`, `qualifiedIdentifier`, `parameterPlaceholder(_:)` |
+| `SSLMode` | [Core/Enums/SSLMode.swift](Core/Enums/SSLMode.swift) | `.preferred, .disabled, .required, .verifyCA, .verifyIdentity` (libpq semantics) |
+| `MCPConnectionMode` | [Core/Enums/MCPConnectionMode.swift](Core/Enums/MCPConnectionMode.swift) | `.locked, .readOnly, .readWrite` |
+| `ProviderType` | [Core/Enums/ProviderType.swift](Core/Enums/ProviderType.swift) | `.anthropic, .openai, .gemini, .ollama` |
+| `SSHAuthMethod`, `ColorTag`, `MCPPermissionTier`, `QueryType`, `FilterCombinator`, `FilterOperator`, `SortDirection` | [Core/Enums/](Core/Enums/) | Use directly in forms/UI/SQL builders. |
+
+### 1.5 SQL generation helpers
+
+`SQLDialect` is the single source of truth for dialect-specific SQL pieces:
+
+```swift
+let d = SQLDialect.postgresql
+d.quoteIdentifier("user table") // "user table" (PG: ""), MySQL: ``, MSSQL: []
+d.qualifiedIdentifier("users", schema: "auth") // "auth"."users"
+d.parameterPlaceholder(1) // PG: $1, MSSQL: @p1, MySQL/SQLite: ?
+```
+
+**Always** quote identifiers via `quoteIdentifier`. Never hardcode quote characters.
+
+`QueryBuilder` at [`Services/QueryEngine/QueryBuilder.swift`](Services/QueryEngine/QueryBuilder.swift) is the fluent SELECT builder — use it for grid pagination/filtering instead of string concat. No DML builder yet; INSERT/UPDATE/DELETE go through adapter methods (`insertRow`, `updateRow`, `deleteRow`).
+
+### 1.6 Adapter-shared helpers
+
+Each adapter has its own private decoder/error formatter. Don't cross-call.
+
+| Helper | Adapter | Visibility | Notes |
+|---|---|---|---|
+| `formatPostgresError(_:)` | PostgreSQL | `static`, callable | Extracts `message/detail/hint/position/sqlState` from `PSQLError`. Use it whenever you re-throw a PG error. |
+| `wrap(mongoError:)` | MongoDB | `private static` | Extracts `errmsg/codeName` from `MongoServerError`. Extract if you need it elsewhere. |
+| `decodeCell(_:dataType:)` | every adapter | private | Driver-specific. Output is `RowValue`. |
+| `executeParameterized(sql:params:)` | PostgreSQL | private | Bound `$1, $2, …` execution. Use in any new metadata query that takes user input. |
+| `inlineValue(_:)` / `buildInlineSQL(...)` | PostgreSQL | private | Last-resort SQL inlining for paths that can't bind. Prefer parameterised. |
+
+`[Coupling]` These helpers are file-private to the adapter. **Don't** call across adapters; if you need shared error formatting/decoding, extract first.
+
+`disableAutoSubstitutions()` on `NSTextView` ([`Core/Extensions/NSTextView+PlainText.swift`](Core/Extensions/NSTextView+PlainText.swift)) is the **shared** helper for any text input that must remain plain ASCII (SQL, JSON). See incident in §3.
+
+### 1.7 Services (`DependencyContainer` surface)
+
+Access these via `DependencyContainer.shared.<name>`:
+
+| Property | Type | Use for |
+|---|---|---|
+| `modelContainer` | `ModelContainer` | SwiftData root. Repositories own this; you rarely touch it. |
+| `keychainService` | `KeychainServiceProtocol` | All credential I/O. |
+| `connectionRepository` | `ConnectionRepository` | Saved-connection CRUD. |
+| `queryHistoryRepository` | `QueryHistoryRepository` | Persisted query history (favourites, search). |
+| `llmProviderRepository` | `LLMProviderRepository` | AI provider configs. |
+| `connectionManager` | `ConnectionManager` (actor) | `connect/disconnect/active connection` lifecycle. SSH tunnel routed internally. |
+| `queryEngine` | `QueryEngine` (actor) | Run queries; auto-logs to history. |
+| `schemaInspector` | `SchemaInspectorService` (actor) | Cached `SchemaSnapshot`s per connection. |
+| `aiContextEngine` | `AIContextEngine` | Token-budgeted prompts from a SchemaSnapshot. |
+| `mcpServer` | `MCPServer` (actor) | start/stop, per-connection mode. |
+| `providerRegistry` | `ProviderRegistry` (actor) | resolve LLM by name/type. |
+
+Bootstrap once in `WindowRoot`: `await container.bootstrapMCPServer()` + `await container.bootstrapProviderRegistry()`.
+
+### 1.8 Persistence: entity ↔ config round-trip
+
+Pattern: every persisted SwiftData entity exposes a `toConfig()` / `toEntry()` method. Business logic uses Domain models; entities stay inside the Data layer.
+
+| Entity | File | Round-trip |
+|---|---|---|
+| `SavedConnectionEntity` | [Data/Persistence/Models/SavedConnectionEntity.swift](Data/Persistence/Models/SavedConnectionEntity.swift) | `toConfig() -> ConnectionConfig`. **All new fields must be `Optional` for SwiftData lightweight migration.** |
+| `QueryHistoryEntity` | [Data/Persistence/Models/QueryHistoryEntity.swift](Data/Persistence/Models/QueryHistoryEntity.swift) | `toEntry() -> QueryHistoryEntry` |
+| `LLMProviderEntity` | [Data/Persistence/Models/LLMProviderEntity.swift](Data/Persistence/Models/LLMProviderEntity.swift) | `toConfig() -> ProviderConfig` |
+
+Repositories live under [`Domain/Repositories/`](Domain/Repositories/) (protocols) and [`Data/Persistence/Repositories/`](Data/Persistence/Repositories/) (impls).
+
+### 1.9 DI + per-window state
+
+- [`DependencyContainer`](App/DependencyInjection/DependencyContainer.swift) — global singleton. Composes everything.
+- [`AppState`](App/State/AppState.swift) — per-window `@MainActor ObservableObject`. Holds active connection, tabs, sidebar/AI panel visibility, pending edits, cached grid/editor state. **Hook into existing `@Published` props** (`activeConnectionId`, `tabs`, `sidebarVisible`, …) — don't add a parallel state store.
+- `AppState.active` returns the currently-focused window's state for use in command menu actions.
+
+`[Coupling]` Don't add `@Published` properties that nobody observes — they bloat the type and confuse future readers (see §3, the `showSettings` incident).
+
+### 1.10 Reusable SwiftUI / AppKit components
+
+| Component | File | Purpose |
+|---|---|---|
+| `TPRow<Content>` | [Presentation/Views/ConnectionForm/ConnectionFormView.swift](Presentation/Views/ConnectionForm/ConnectionFormView.swift) (line ~602) | Form row: label on left, content on right, fixed `labelWidth` (default 110). |
+| `TPTextField` | same file (line ~635) | `NSViewRepresentable` text field with `focusRingType = .none`. Has `isSecure` for passwords. |
+| `TPButton` | same file (line ~620) | Flat, `maxWidth` button. |
+| `TPFileButton` | same file (line ~671) | Opens `NSOpenPanel`, binds selected path. SSL keys, SQLite picker, etc. |
+| `ClickableModifier` | [Presentation/Views/Shared/ClickableModifier.swift](Presentation/Views/Shared/ClickableModifier.swift) | Hover + click decoration on arbitrary views. |
+| `PlainJSONTextEditor`, `SQLTextView` | Presentation/Views/{MongoDB,QueryEditor}/ | `NSTextView` wrappers that call `disableAutoSubstitutions()`. **Use these instead of SwiftUI `TextEditor` for SQL/JSON input** (see §3 smart-quotes incident). |
+
+`[Coupling]` `TP*` components are currently **defined inline** in `ConnectionFormView.swift` — not exported. If you need them in a new form, extract to `Presentation/Views/Shared/` first; don't duplicate.
+
+### 1.11 Notification.Name event bus
+
+Cross-cutting events flow through `NotificationCenter.default`. Constants are extension members on `Notification.Name` defined in [`App/Lifecycle/GridexApp.swift`](App/Lifecycle/GridexApp.swift):
+
+`.executeQuery`, `.executeSelection`, `.explainQuery`, `.formatSQL`, `.deleteSelectedRows`, `.commitChanges`, `.reloadData`, `.toggleFilterBar`.
+
+Adding a new app-wide command? Add it to that extension and post from a `CommandMenu`/`CommandGroup` in `GridexApp.swift`. Receivers should observe in `init` and tear down on deinit.
+
+---
+
+## 2. DO
+
+Concrete, codified patterns. Each one is an explicit "yes" — the inverse of a §3 incident.
+
+1. **Add new `ConnectionConfig` fields as `Optional?` with a sensible fallback at the read site.**
+ New SwiftData columns must also be optional. Old rows decoded without the field must keep working. `toConfig()` should `flatMap`/`??` to back-compat.
+
+2. **Use `executeParameterized` for any metadata query that takes user input.**
+ PostgreSQL adapter has `private executeParameterized(sql:params:)`. Write similar bound execution paths in new adapters.
+
+3. **Wrap driver errors via the adapter's formatter before throwing `GridexError.queryExecutionFailed`.**
+ `formatPostgresError`, `wrap(mongoError:)`. Bare `error.localizedDescription` loses the SQLSTATE / `errmsg` / detail / hint that users actually need.
+
+4. **Persist the full UI state, not its boolean shadow.**
+ If the picker has 5 modes, store the 5-mode enum, not `isOn: Bool`. The boolean form ignores user intent (SSL `verifyCA` ≠ "on", see §3).
+
+5. **Reach for the existing actor service.**
+ New connection lifecycle? Go through `ConnectionManager`, not a fresh `Adapter()`. New schema fetch? `SchemaInspectorService`. Don't bypass the cache.
+
+6. **Conform to `DatabaseAdapter` exhaustively.**
+ The grid, ER diagram, MCP tools, AI context all assume the full surface. A half-implemented adapter breaks features silently three layers up.
+
+7. **Use the parent role's catalog, not `information_schema.*`, for "list everything" queries.**
+ `pg_namespace` / `pg_class` / `pg_proc` are readable by all roles. `information_schema` is privilege-filtered (incident #34).
+
+8. **Use `@FocusedObject` for cross-window `AppState` in command menus.**
+ See `currentAppState` in `GridexApp.swift`. Falls back to `AppState.active` when no window is focused.
+
+9. **Validate identifiers from external clients (MCP).**
+ `MCPIdentifierValidator` ASCII-allowlists table/schema/column names. Use it for any new write tool.
+
+10. **Bump `Info.plist` version in a separate `chore(release): bump version to X.Y.Z` commit on the same branch.**
+ Convention is `CFBundleShortVersionString` + `CFBundleVersion` (integer) advanced together. macOS uses its own series independent of Windows/Linux.
+
+11. **Conventional Commits with scope.** `feat(postgres): …`, `fix(mcp): …`, `chore(release): …`, `docs(readme): …`. Keep subjects ≤ 72 chars; explain the *why* in the body.
+
+12. **One concern per PR.** A schema fix doesn't need a refactor. A version bump is its own commit, not folded into the feature commit.
+
+---
+
+## 3. DON'T (with concrete incident references)
+
+Each item maps to a real bug we shipped and then fixed. The commit hash is the receipt — read it before re-introducing the pattern.
+
+1. **Don't query `information_schema.*` for "show me everything" lists.** It's privilege-filtered per SQL standard. Use `pg_namespace` / `pg_class` / `pg_proc`. → `d6e51b3` *(fix #34, only `public` schema visible on Supabase)*.
+
+2. **Don't collapse a multi-state UI enum into a `Bool` when persisting.** SSL mode picker had 5 states; we stored only `sslEnabled: Bool`, so `REQUIRED` / `VERIFY_CA` / `VERIFY_IDENTITY` all degraded to `.prefer(tls)`. → `6a4aad0`.
+
+3. **Don't add a custom `CommandGroup(replacing: .appSettings)` while a SwiftUI `Settings { … }` scene exists.** They both render menu items, you get a duplicate "Settings…". → `813f365` *(fix #26)*.
+
+4. **Don't use SwiftUI `TextEditor` for SQL or JSON input.** macOS auto-substitution turns `"` into `“ ”` and breaks `JSONSerialization` / SQL parsers with an opaque error. Use an `NSViewRepresentable` calling `disableAutoSubstitutions()`. → `0c5644d`.
+
+5. **Don't drop URI query parameters when parsing connection strings.** A pasted `mongodb://...?authSource=admin&replicaSet=rs0` must round-trip through `ConnectionConfig.mongoOptions` to the adapter's `buildURI`. → `9466c55`.
+
+6. **Don't ship `@Published` state that no one observes.** It signals intent that doesn't exist and traps the next reader. The duplicated Settings menu's button wrote to `AppState.showSettings`, observed by nothing. → `813f365`.
+
+7. **Don't break the `Codable` contract on persisted value types.** Adding a non-optional field fails decoding for existing rows. Make it `Optional` and resolve at the read site. → `6a4aad0` *(sslMode added as `SSLMode?`)*.
+
+8. **Don't assume IPv4 reachability.** Supabase free-tier direct URLs (`db.<ref>.supabase.co:5432`) have only AAAA records; an IPv4-only network never connects. On connection failure, surface an actionable hint (try `ipv6OnlyHint(host:)`-style detection) instead of returning a generic timeout. → `6a4aad0`.
+
+9. **Don't surface raw `PSQLError` / `MongoError` to users.** Wrap with the adapter's formatter; otherwise they see `"operation couldn't be completed (… error 1.)"` instead of the actual `errmsg`. → `7042ecb`, `6a4aad0`.
+
+10. **Don't hand-roll WHERE / ORDER BY strings.** Use `FilterExpression.toSQL(dialect:)` and `QuerySortDescriptor.toSQL(dialect:)`. Manual construction loses dialect-specific quoting and value escaping.
+
+11. **Don't introduce driver-native types above the adapter.** `Postgres.Jsonb`, `MongoKitten.Document`, `MySQL.Variant` stop at the adapter boundary. Decode to `RowValue` (or a Core model) before returning.
+
+12. **Don't bypass `DependencyContainer`.** Construct services through the container, not direct `init`. Tests can swap the container; ad-hoc `init`s can't.
+
+13. **Don't `--no-verify` or `--no-gpg-sign` to push past a hook.** Investigate the hook failure. Same for `git push --force` on shared branches.
+
+14. **Don't merge unrelated work into an open PR.** When the user says "fix X", don't fold "while I'm here, also …" into the same commit/branch. Open a second branch.
+
+---
+
+## 4. Workflow
+
+### Branch + commit flow
+- Branch off `main`. Naming: `fix/<issue>-<short>`, `feat/<area>-<short>`, `chore/…`, `docs/…`.
+- Conventional Commits in subject. Body answers *why*. Reference issue numbers (`#34`).
+- Version bump in `Info.plist` is a **separate commit** (`chore(release): bump version to X.Y.Z`) on the same branch as the change that justifies it.
+- Open the PR with a clear title (≤ 70 chars), Summary + Test Plan in the body. Caveats and migration notes go in the Test Plan.
+
+### Build + verify
+- `swift build` from repo root. Must pass with no new warnings before commit.
+- `./scripts/build-app.sh` for the `.app` bundle.
+- `./scripts/release.sh` (or `release-all.sh`) for signed/notarized DMG.
+- Postgres-specific changes: spin up a local PG via `brew services start postgresql@16` (or initdb to a temp dir on a non-default port) and reproduce the user's failure mode before claiming a fix. The session that produced incident #34 verified by reproducing Supabase's role layout locally.
+
+### When the user reports a connection bug
+Order of suspicion (from incident base rate):
+1. Network layer (IPv6-only host, firewall, DNS).
+2. Auth (wrong user/role, missing `authSource` for Mongo).
+3. TLS mode mismatch.
+4. Driver-level edge case (URI parsing, parameter binding).
+
+Resolve DNS for the user's host before digging into TLS. If only AAAA exists and the user's network is v4-only, no SSL change will help — direct them to a pooler / IPv4 endpoint.
+
+---
+
+## 5. When you're stuck
+
+In order, before asking the user:
+
+1. **Read the closest sibling.** Adding a Postgres feature? `MySQLAdapter.swift` already solved the same shape. Adding an AI provider? Compare `AnthropicService.swift` ↔ `OpenAIService.swift`.
+2. **`git log --oneline -- <file>`** on the file you're editing. The last 5 commits often cover the gotchas.
+3. **`git log -G "<symbol>"`** to see when a symbol was introduced or refactored — the message usually explains the constraint.
+4. **Reproduce locally.** A Postgres bug? `initdb` + `pg_ctl` + `psql`. A SwiftUI bug? Run the dev build and click through.
+
+If after that you still have multiple plausible interpretations, **stop and ask the user**. Per `CLAUDE.md` rule 1: "If multiple interpretations exist, present them — don't pick silently." Better one extra round-trip than 200 lines on the wrong premise.