diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..64e388c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,73 @@
+# AGENTS.md — contributor / agent guide
+
+cortex-plugin is the OpenClaw client surface for Cortex (company-brain).
+Read `VISION.md` first — in particular the client/server boundary: the Cortex
+**server** is a separate repo (`electricsheephq/evaos-cortex`); this repo only
+exposes it as agent tools.
+
+## Repo map
+
+```
+src/index.ts                # plugin entrypoint — tool registration, config
+src/config.ts               # config schema / defaults
+src/__tests__/               # test suite (see below — run via dist, not ts-node)
+openclaw.plugin.json         # OpenClaw plugin manifest: id, tools[], configSchema
+docs/cortex-core-tools.md    # memory/entity/graph tool reference (read-only tools)
+docs/company-brain-tools.md  # Company Brain tool reference + owner-scoping rules
+scripts/
+  deploy-local-extension.sh   # rsync build output into ~/.openclaw/extensions/cortex
+  cortex-runtime-smoke.mjs     # read-only smoke against a live Cortex URL (npm run runtime:smoke)
+  company-brain-canary.mjs    # Company Brain canary check
+  check-deploy-parity.sh      # verify deployed extension matches built dist
+  sync-dist-manifest.mjs      # copies openclaw.plugin.json into dist/ at build time
+```
+
+`src/` is listed in `.gitignore` but is force-tracked in git (`git ls-files`
+shows it) — don't be surprised it's committed despite the ignore rule; that's
+intentional, not an accident to fix.
+
+## Setup / build / test
+
+Verified from `package.json` and `.github/workflows/ci.yml`:
+
+```bash
+npm ci             # or npm install
+npx tsc --noEmit   # typecheck (what CI runs)
+npm run build      # tsc && sync-dist-manifest.mjs
+npm test           # builds, then runs the compiled test files under dist/__tests__/
+```
+
+CI (`.github/workflows/ci.yml`) runs `npm ci`, `npx tsc --noEmit`, and
+`npm run build` on every push/PR to `main`. `.github/workflows/codeql.yml`
+runs CodeQL JS analysis on the same triggers. Dependabot
+(`.github/dependabot.yml`) watches npm + github-actions weekly.
+
+Before trusting a deployed runtime, run the read-only smoke test against a
+real Cortex server:
+
+```bash
+CORTEX_URL=https://your-cortex-server.example.com \
+CORTEX_API_KEY="$CORTEX_API_KEY" \
+npm run runtime:smoke
+```
+
+## Contribution guardrails
+
+- Branch, open a PR against `main`, keep CI (typecheck + build, CodeQL) green.
+- Keep the core-memory tools (`docs/cortex-core-tools.md`) and Company Brain
+  tools (`docs/company-brain-tools.md`) conceptually separate — different tool
+  sets, different owner-scoping rules. Don't blend them when adding a tool.
+- Don't implement server-side behavior here (retrieval ranking, embeddings,
+  connector ingestion) — that belongs in `evaos-cortex`. This repo wires tools
+  to the server's HTTP API.
+- `insufficient_evidence` from a Company Brain tool is a successful, honest
+  response — don't treat it as a tool failure in new code or tests.
+
+## Fleet context
+
+This plugin ships into customer VMs as part of the fleet. Before any
+fleet-affecting change (default config, auto-recall/auto-capture behavior,
+anything that runs unattended in every customer's agent loop), read
+`evaos-support-control/docs/fleet-contract.md` (canonical). This repo does not
+yet have its own `docs/fleet-contract.md` stub — if fleet-facing risk grows
+here, add one following the pattern in `evaos-ws-proxy` or `evaos-golden`.
diff --git a/VISION.md b/VISION.md
new file mode 100644
index 0000000..53b3a0b
--- /dev/null
+++ b/VISION.md
@@ -0,0 +1,33 @@
+# Vision
+
+cortex-plugin is the OpenClaw plugin that connects a customer's Eva agent to
+Cortex, the $995/mo company-brain product. It surfaces Cortex's remember/recall
+(personal memory: BM25 + vector + reranked retrieval, capture, contradictions,
+commitments, open loops) and Company Brain connector ingestion (Gmail via
+Pipedream, and the broader account/timeline/query surface) as agent tools
+inside the customer VM, so the agent can capture and query the customer's
+institutional memory in the middle of an ordinary conversation.
+
+It exists to make the company-brain **usable from inside the agent**, not just
+reachable via the Cortex HTTP API.
+
+## Boundary: this is the client, not the server
+
+**The Cortex server lives in a separate repo, `electricsheephq/evaos-cortex`.**
+This repo is the OpenClaw plugin — it calls the server's HTTP API
+(`cortexUrl`) and exposes the results as `cortex_*` / `company_brain_*` tools.
+It does not implement retrieval, storage, embeddings, or connector ingestion
+itself. If you're debugging a memory-quality or ingestion-correctness issue,
+you likely want the server repo; if you're debugging tool wiring, config, or
+what the agent sees in context, you're in the right place.
+
+## Why this matters
+
+- **One plugin surface, two products.** Personal memory (Cortex core) and
+  Company Brain (the $995/mo product) are both exposed here but are distinct
+  concerns with separate tool sets and owner-scoping rules — don't conflate
+  them when adding tools or docs.
+- **Hosted Cortex stays authoritative.** For hosted/JWT-authenticated
+  deployments, the server resolves the effective owner; this plugin's
+  `ownerId` config is a self-hosted/owner-bound-API-key affordance, not a way
+  to override auth.