Suggest edit — AGENTS

Title

Name

Note

---
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, post-pivot).** The project has PRD, plan, ADRs, specs, and an LLM wiki — but **no code yet**.

⚠️ **Don't start implementation at S1.** The initial roadmap (S1-S9) was built around Option 1 (tmux-centered single-host). Late in the planning session, Jacob reframed the product as "awesome texting experience" and reopened the architecture choice — see [docs/plans/2026-04-23-prototype-options.md](docs/plans/2026-04-23-prototype-options.md). The actual next action is **Q0** (`picortex-adb`) — define the success criteria that constrain the architecture choice. Then Q1-Q4 choose the option bundle, then `picortex-357` reconciles the docs with the chosen option, then a revised roadmap replaces S1-S9.

## 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 (revised 2026-04-23):** Don't *inherit* patterns from pre-`af3a76f5` Cortex (the Piyush-era EC2/SSH/Vercel design, 2026-01-20 → 2026-01-23), but *do* study it deliberately — several of its patterns (bot/workspace physical split, `claude -c -p` per turn) are exactly what the texting-first picortex wants. See `docs/wiki/piyush-era-design.md` and `docs/plans/2026-04-23-prototype-options.md` (Option 2).

## 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