docs: clarify Python bridge runtime and test behavior

.memory/project.md

@@ -1,20 +1,47 @@
-{
-	"name": "kdbx-lib",
-	"packageManager": "bun@1.0.0",
-	"version": "0.1.0",
-	"private": true,
-	"type": "module",
-	"scripts": {
-		"example": "bun run src/example.ts",
-		"validate": "bun run test",
-		"test": "bun test",
-		"test:unit": "bun test",
-		"test:integration": "bun run src/test-integration.ts",
-		"setup:python": "python3 -m venv .venv && .venv/bin/pip install pykeepass"
-	},
-	"dependencies": {},
-	"devDependencies": {
-		"typescript": "^5.5.0",
-		"bun-types": "^1.1.0"
-	}
-}
+# Project
+
+## Goal
+Provide a small read-only TypeScript wrapper around KeePass `.kdbx` databases using a Python bridge powered by `pykeepass`.
+
+## Architecture
+- Public API is TypeScript.
+- `src/python/bridge.py` is the runtime backend and uses `pykeepass`.
+- TypeScript spawns a Python process per request; there is no persistent worker yet.
+- JSON is exchanged over stdin/stdout.
+- Bridge errors, empty output, invalid JSON, missing files, and backend exceptions are surfaced as TypeScript errors.
+
+## Public API
+- `openKeePassDatabase(path, options)`
+- `KeePassDatabase.listEntries()`
+- `KeePassDatabase.findEntries(query)`
+- `KeePassDatabase.listGroups()`
+- `KeePassDatabase.close()` is a no-op.
+
+## Types
+- Entries expose: `title`, `username`, `password`, `url`, `notes`, optional `groupPath`, optional `otp`.
+- Groups expose: `name`, `path`.
+- Open options support `password` and optional `keyFile`.
+- Find queries support partial matching on `title`, `username`, `url`, and `groupPath`.
+
+## Runtime details
+- Python path defaults to `.venv/bin/python3`.
+- It can be overridden with `PYTHON_PATH`.
+- `bun run setup:python` creates `.venv` if needed and installs `pykeepass`.
+- The bridge also works with an existing project-local virtual environment.
+
+## Fixtures and tests
+- Bundled fixtures: `tests/fixtures/data.kdbx` and `tests/fixtures/empty.kdbx`.
+- Companion JSON fixture: `tests/fixtures/data.kdbx.json` stores the password and expected content.
+- Unit tests in `tests/unit/` mock the child process and validate bridge parsing/error handling.
+- Integration tests in `tests/integration/` use `data.kdbx` to verify entries, groups, partial search, and OTP/TOTP output when `pykeepass` is installed.
+- The integration test runner checks for `pykeepass` and skips cleanly when it is unavailable.
+
+## Main scripts
+- `bun run test` / `bun test`
+- `bun run src/example.ts`
+- `bun run src/test-integration.ts`
+- `bun run setup:python`
+
+## Current direction
+Keep improving failure-path coverage and keep the API minimal unless a concrete need appears.
+