docs(agents): fix broken steps and de-duplicate the instruction files

AGENTS.md

@@ -1,26 +1,29 @@
 # mcp-wordpress-remote
 
-MCP proxy server between Codex and a WordPress backend.
+MCP proxy server between an MCP client and a WordPress backend.
 
-## Commit discipline
+## Commits
 
-**Every line in a commit must trace to the stated goal.** No drive-by cleanups, no unrelated "improvements." The 0.2.20 race condition was caused by a harmless-looking capabilities change (`tools: {}` → `tools: { listChanged: false }`) bundled with an unrelated SOCKS proxy fix. Review every changed line — if it isn't required for the task, remove it before committing.
+- Before committing, run `npm run check` and `npx jest tests/unit/ tests/integration/ --no-coverage`. CI runs the same steps on every PR (`.github/workflows/ci.yml`), so this only saves you the round trip — there is no pre-commit hook.
+- Keep every line in a commit traceable to its stated goal. A one-token capabilities change (`tools: {}` → `tools: { listChanged: false }`) once rode along with an unrelated fix and caused a transport race.
 
 ## Pre-publish release gate
 
 "Works in repo" is not enough. Gate on "works from packed artifact in clean environment."
 
 1. Build and pack: `npm ci && npm run build && npm pack`
-2. Install tarball in a clean temp dir, run `npx mcp-wordpress-remote --help`
+2. Install the tarball in a clean temp dir. Confirm `dist/proxy.js` is the tsup bundle (~2.4 MB single file), not per-file output — the binary has no `--help`, so it cannot be smoke-tested by invoking it bare
 3. Test against a healthy WordPress endpoint (normal init + tools/list flow)
 4. Test against a broken endpoint (fallback init, no malformed forwarding)
 5. Debug logs: verify no forwarded requests fire before init settles
-6. Publish canary first (`x.y.z-canary.1`), soak in real clients, then promote to latest
-7. Know the last good version — be ready for immediate dist-tag rollback
+
+## Version
+
+The version lives in two places that must move together: `version` in `package.json` and `MCP_WORDPRESS_REMOTE_VERSION` in `src/lib/config.ts`. Letting them drift once shipped a token directory literally named `wordpress-remote-undefined`. The token store is namespaced by version, so any bump forces every user to re-authenticate.
 
 ## Testing
 
-- Run all tests: `npx jest tests/unit/ --no-coverage`
+- Run all tests: `npx jest tests/unit/ tests/integration/ --no-coverage` (`tests/unit/` alone skips the integration suites)
 - Build: `npm run build`
 - ESM mocking pattern: set `process.env` vars BEFORE `jest.resetModules()` + dynamic imports (CONFIG caches at import time)
 - WordPress API endpoint in nock: `/?rest_route=/wp/v2/wpmcp` (not `/wp/v2/wpmcp`)

CLAUDE.md

@@ -1,32 +1 @@
-# mcp-wordpress-remote
-
-MCP proxy server between Claude Code and a WordPress backend.
-
-## Commit discipline
-
-**Every line in a commit must trace to the stated goal.** No drive-by cleanups, no unrelated "improvements." The 0.2.20 race condition was caused by a harmless-looking capabilities change (`tools: {}` → `tools: { listChanged: false }`) bundled with an unrelated SOCKS proxy fix. Review every changed line — if it isn't required for the task, remove it before committing.
-
-## Pre-publish release gate
-
-"Works in repo" is not enough. Gate on "works from packed artifact in clean environment."
-
-1. Build and pack: `npm ci && npm run build && npm pack`
-2. Install tarball in a clean temp dir, run `npx mcp-wordpress-remote --help`
-3. Test against a healthy WordPress endpoint (normal init + tools/list flow)
-4. Test against a broken endpoint (fallback init, no malformed forwarding)
-5. Debug logs: verify no forwarded requests fire before init settles
-6. Publish canary first (`x.y.z-canary.1`), soak in real clients, then promote to latest
-7. Know the last good version — be ready for immediate dist-tag rollback
-
-## Testing
-
-- Run all tests: `npx jest tests/unit/ --no-coverage`
-- Build: `npm run build`
-- ESM mocking pattern: set `process.env` vars BEFORE `jest.resetModules()` + dynamic imports (CONFIG caches at import time)
-- WordPress API endpoint in nock: `/?rest_route=/wp/v2/wpmcp` (not `/wp/v2/wpmcp`)
-
-## Architecture notes
-
-- Transport detection (JSON-RPC vs simple) runs during the `initialize` handler
-- `sessionContext.transportType` starts null — the init-ready gate (`waitForInit`) blocks all handlers until detection settles
-- `waitForInit` returns `InitResult` (`{ ready: true } | { ready: false; reason: 'failed' | 'timeout' }`)
+@AGENTS.md