new file mode 100644
index 0000000..a628a95
@@ -0,0 +1,133 @@
+---
+visibility: public
+---
+
+# AGENTS.md — picortex
+
+Operational instructions for coding agents (Codex CLI, Claude Code, Cursor, Amp, etc.). Prepended to every conversation — keep this file lean. For any detail beyond the essentials, link out and let the agent fetch on demand.
+
+## Project overview
+
+**picortex** is a personal variant of [Cortex](https://cortex.ideaflow.app) for iMessage + group texting through the [Linq](https://linq.so) partner API. It spawns Claude Code sessions per chat, isolated by Linux user + filesystem permissions (not Docker), with a mobile-first web UI for monitoring, file browsing, and live terminal attach.
+
+*Name is provisional.*
+
+## Status
+
+**Planning phase (2026-04-23).** The project has PRD, plan, ADRs, specs, and an LLM wiki — but **no code yet**. The first implementation stage is **S1** in [docs/plans/2026-04-23-initial-roadmap.md](docs/plans/2026-04-23-initial-roadmap.md).
+
+## Primary doc pointers (progressive disclosure)
+
+Don't inline content from these — link and let the reader fetch:
+
+- **PRD:** [docs/prd/001-picortex-v1.md](docs/prd/001-picortex-v1.md)
+- **Roadmap:** [docs/plans/2026-04-23-initial-roadmap.md](docs/plans/2026-04-23-initial-roadmap.md)
+- **Architecture:** [docs/wiki/architecture.md](docs/wiki/architecture.md)
+- **Cortex inheritance map:** [docs/wiki/cortex-inheritance.md](docs/wiki/cortex-inheritance.md)
+- **ADRs:** [docs/adrs/](docs/adrs/)
+- **Specs:** [docs/specs/](docs/specs/)
+- **LLM wiki (Karpathy-style):** [docs/wiki/index.md](docs/wiki/index.md)
+
+## Dev environment
+
+- Node 20+, tmux 3.3+, ripgrep, sudo, SQLite 3.40+
+- `npm install`
+- `cp .env.example .env` then fill in `LINQ_API_KEY`, `LINQ_WEBHOOK_SECRET`, `ANTHROPIC_API_KEY` (or rely on `claude` CLI auth)
+- `npm run dev` — backend (7823) + frontend (7824) + linq-sim orchestrator
+
+## Stack
+
+- **Backend:** Node.js + Fastify (TypeScript, strict mode)
+- **Frontend:** Vite + React + Tailwind (mobile-first)
+- **Terminal:** xterm.js (client), `node-pty` + `tmux` (server)
+- **Storage:** SQLite (canonical message log, per-chat config); per-chat filesystem workspaces at `/srv/picortex/chats/<chat_id>/`
+- **Auth (web UI):** Noos OAuth SSO; the iMessage/Linq path does not require UI auth
+- **Observability:** `pino` JSON logs, `X-Request-ID` middleware, `/api/frontend-log` browser error forwarder
+
+## Ports
+
+- Dev backend: **7823**
+- Dev frontend: **7824**
+- linq-sim (from Cortex): **8447**
+- Never use 3000/5000/8080/8000. See Jacob's `~/.claude/rules/dev-patterns.md`.
+
+## Code style
+
+- TypeScript strict. No `any` without a comment justifying it.
+- Conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
+- One concern per PR. Reference beads ticket: `[picortex-xxx]`.
+- Line length: soft 100, hard 120.
+
+## Testing
+
+- **vitest** for unit + integration
+- E2E runs against **linq-sim**, not real Linq
+- `npm test` — unit
+- `npm run test:e2e` — E2E (starts a linq-sim instance)
+- A feature isn't done until: (a) tests pass, (b) a linq-sim scene demo exists, (c) beads ticket closed.
+
+## Security invariants
+
+1. **Canonical message log lives on backend** (SQLite). Per-chat workspace filesystem is a **cache**, never authoritative. ([Cortex R5.1](docs/wiki/cortex-inheritance.md#r5-backend-authority))
+2. **Every cross-chat op** (e.g. "import X from my personal chat into this group") requires an out-of-band challenge/response: the group agent DMs the user, the user's reply is the approval. ([Cortex R5.4-5.5](docs/wiki/cortex-inheritance.md#r5-backend-authority))
+3. **Linq inbound webhooks** verified with `HMAC-SHA256("{timestamp}.{raw_body}", LINQ_WEBHOOK_SECRET)`. Reject on bad signature, skew > 5 min, or replay.
+4. **No secrets in workspace FS.** Env vars stay in the backend process. Per-chat Unix users have no ambient credentials.
+5. **Per-chat Unix user can't see other chats' files** — enforced by POSIX permissions (owner-only home dirs, 0700). See [ADR-0002](docs/adrs/0002-linux-users-over-docker.md).
+6. **Never disable isolation for convenience.** If provisioning breaks, stop and ask; do not fall through to "run as shared user."
+
+## Commit / PR conventions
+
+- Branch: `<type>/<short-desc>` e.g. `feat/attention-discriminator`
+- PR body: **Summary**, **Test plan**, beads link
+- Squash merge preferred
+
+## Deployment
+
+TBD — candidates: Hetzner VPS, Fly.io, HMA (Mac Mini). See [docs/runbooks/deploy.md](docs/runbooks/deploy.md) once chosen.
+
+## Dev patterns (per Jacob's global rules)
+
+- **Version on screen:** display app version in user-menu footer (from `package.json`)
+- **Update-available indicator:** non-intrusive badge when a newer commit is on `main`
+- **Frontend error logging:** `POST /api/frontend-log` endpoint that forwards browser errors to the server's structured log
+- **Port conflict handling:** auto-increment if 7823/7824 are taken, display actual port
+- **System deps:** proactively detect `tmux`, `rg`, `sudo`, `sqlite3`; print `brew install …` hint if missing
+
+## Beads
+
+- Prefix: `picortex-`
+- Init: `bd init picortex` (done at project setup)
+- List open: `bd list --status=open`
+- Create: `bd create "Title" --type task|feature|bug|epic --priority 0-4`
+
+## Cortex inheritance rule
+
+Where Cortex already solved it, **inherit, don't re-derive**. See [docs/wiki/cortex-inheritance.md](docs/wiki/cortex-inheritance.md) for the requirement-by-requirement map.
+
+**Cortex research cutoff:** when ingesting Cortex for context, **ignore commits before `af3a76f5` (2026-01-26)** — the pre-container Piyush-era EC2/SSH/Vercel architecture that was replaced wholesale and teaches patterns that conflict with current picortex ADRs. Use `git -C ~/code/cortex log af3a76f5..HEAD` as the reachable set.
+
+## Landing the Plane (Session Completion)
+
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+
+**MANDATORY WORKFLOW:**
+
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+ ```bash
+ git pull --rebase
+ bd sync
+ git push
+ git status # MUST show "up to date with origin"
+ ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
+
+**CRITICAL RULES:**
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds
\ No newline at end of file