diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9edf6bf
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,53 @@
+# Decky agent notes
+
+## Project
+
+- The active app is `app/`: Tauri 2 + Svelte 5 + TypeScript. The older .NET
+  projects under `src/` and `tests/` are reference code, not the product.
+- Decky is a compact, Nextcloud-inspired desktop client for Nextcloud Deck.
+  Preserve its dark native title bar, horizontal/vertical views, drag-and-drop,
+  compact cards, collapsible sidebar, and footer-free layout.
+- Background sync begins after 10 seconds idle and repeats every 30 seconds. It
+  must pause during edits, drags, loading, modals, and while the window is hidden.
+- Never store or commit Nextcloud credentials. Use an app password and the OS
+  credential store. Live-instance tests require the user to enter credentials.
+
+## Nextcloud API compatibility
+
+- Client code and tests are in `app/src/lib/deck-api.ts` and
+  `app/src/lib/deck-api.test.ts`.
+- Support both documented `index.php/apps/deck/api/v1.0/` and rewrite-friendly
+  `apps/deck/api/v1.0/` paths.
+- Preserve complete card fields on updates, including color and object/string
+  owner handling. Keep the tested cross-stack card-move fallback.
+- Stack reorder uses Deck's OCS reorder endpoint and verifies persisted order.
+- Respect board permissions before exposing edit/manage/delete controls.
+
+## Validation
+
+From `app/`, run `npm ci`, `npm run check`, `npm test`, and `npm run build`.
+Build Windows installers on this Windows machine; the Unraid Forgejo Docker
+runner only validates the web client via `.forgejo/workflows/validate.yml`.
+
+## Versions and releases
+
+- Installed apps update from signed Forgejo Release assets, never from Git.
+- A released version/tag is immutable. Always increment the semantic version;
+  never republish or replace assets for an existing version.
+- Use `scripts/Set-Version.ps1` to synchronize npm, Cargo, Tauri, and the browser
+  fallback. Commit and push source to `main` before publishing the release.
+- Build/sign with `scripts/Prepare-Release.ps1`. Generated files live under
+  `artifacts/release/vX.Y.Z/` and stay out of Git.
+- Publish by double-clicking `scripts/Publish-DeckyRelease.cmd` or by invoking
+  `scripts/Publish-ForgejoRelease.ps1`. The publisher creates the tag/release,
+  uploads the installer/signature, and commits `releases/latest.json` to `main`.
+- Publishing creates a new remote metadata commit. Fetch/rebase or pull before
+  the next push; a non-fast-forward rejection usually means this commit is
+  missing locally. LF-to-CRLF messages on Windows are warnings, not failures.
+- Forgejo: `https://git.elijahkuntz.com/Elijah/Decky`. A publishing PAT needs
+  `write:repository`; never commit or print it.
+- The permanent Tauri updater key is outside the repository at
+  `%USERPROFILE%\.tauri\decky.key` with its password beside it. Never expose,
+  replace, or regenerate this key after releases have shipped.
+
+See `app/UPDATES.md` for the complete release procedure.