diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ecd9c20
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,42 @@
+# Ten31Portal
+
+Ten31's internal system of record for entities, holdings, positions, valuations,
+investor capital accounts, and documents. The backend is FastAPI, SQLModel, and
+SQLite. The frontend is React and Vite. `deploy/` packages the application for
+StartOS.
+
+## Structure and checks
+
+- `backend/ten31portal/`: API, models, importers, storage, authentication, and CLI.
+- `backend/tests/`: pytest coverage for permissions, imports, NAV, and rollups.
+- `frontend/src/`: internal and investor-facing interfaces.
+- `deploy/`: StartOS package, migrations, and service image build.
+- Backend tests: `cd backend && python -m pytest`.
+- Frontend checks: `cd frontend && npm run lint && npm run build`.
+- StartOS type check: `cd deploy && npm run check`.
+
+## Durable gotchas
+
+- This repo handles confidential fund and investor information. Real databases,
+  uploaded documents, credentials, and source spreadsheets never enter git.
+- Financial data changes on the live service use application code and migrations,
+  followed by a sideload. Never edit the live SQLite database over SSH.
+- Bump the StartOS version or revision before every package build. Keep the
+  current version module and `deploy/package.json` aligned.
+- `frontend/src/version.ts` is a separate visible build marker. If it lags the
+  package version, the interface can display an old version even when the newer
+  package is installed.
+- `ROADMAP.md` contains an old current-state section. This file's `## Current
+  state` is the current snapshot; the roadmap should be pruned before using it as
+  an active work queue.
+
+## Current state
+
+- Work is on `investor-access`; its existing application history through
+  `34842cd` is on private Gitea, verified with `ls-remote` on 2026-09-04.
+- The StartOS version is 0.2.48:0 and matches the version recorded live in
+  `../FLEET.md` on 2026-09-02.
+- Recent work imports credit-fund loans into NAV and supports queued re-imports
+  for already-signed rounds.
+- `frontend/src/version.ts` still reports 0.2.46 while the package is 0.2.48.
+- Next: reconcile the visible frontend version marker and stale roadmap status.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file