diff --git a/AGENTS.md b/AGENTS.md
index 9be0018..4945f21 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,6 +13,56 @@ This project is a Nostr client application built with React 18.x, TailwindCSS 3.
 - **TanStack Query**: For data fetching, caching, and state management
 - **TypeScript**: For type-safe JavaScript development
 
+## Local Dev Environment, Build & Release (project-specific — read first)
+
+Machine-specific, verified operational notes. Use these instead of re-deriving workflows from scratch.
+
+### Where things are
+- **Dev root / repo**: `/home/sovereignsk8/SkateSpots` — the clone whose `origin` is the `nostr://` remote.
+- **origin**: `nostr://npub1yrnuj56rnen08zp2h9h7p74ghgjx6ma39spmpj6w9hzxywutevsst7k5cx/git.shakespeare.diy/SkateSpots` (browsable at nostrhub.io).
+- **Live site**: https://skate-spots.org — served by **Netlify**, deployed via **shakespeare.diy** (which also hosts the git server).
+- **Backups**: `~/.backups/` (nested clone, old lockfiles, keystore copies).
+
+### Toolchain (already installed on this machine)
+Node 22 + npm 10 · Bun 1.3 · Java 21 · Android SDK at `~/Android/Sdk` · `ngit` 3.0.3 (`~/.cargo/bin`) · `zsp` (`~/.local/bin`).
+
+### Run & validate
+- `npm run dev` → http://localhost:8080. Note the script runs `npm i` first (see lockfile caveat).
+- `npm test` = `npm i` + `tsc` + `eslint` + `vitest` + `vite build`. **Must pass before committing.**
+
+### ⚠️ Lockfile caveat (important)
+The committed `package-lock.json` (from commit `f25fc2b`) had entries stripped of `dependencies`/`bin` metadata, so transitive packages were silently missing. Repaired in `eb23ebc` (654 → 902 packages).
+- **Regression symptoms**: `npx cap` → "could not determine executable to run"; `tsc` → "Module '@nostrify/nostrify' has no exported member NostrEvent"; Vite → "Could not resolve @std/encoding/hex".
+- **Do NOT regenerate the lock blindly** — a fresh resolve bumps ~300 packages incl. major `@babel` 7→8 and `esbuild` 0.25→0.28. Prefer `npm ci`. If broken, repair each entry's `dependencies`/`bin` from the installed `node_modules/*/package.json`, then `npm install` to fill only the gaps.
+
+### Android release build
+- `npm run android:build` → `android/app/build/outputs/apk/release/app-release.apk`.
+- **Versioning**: `package.json` `version` is the single source of truth; `scripts/sync-android-version.mjs` syncs it to `versionName`/`versionCode` (e.g. `1.4.5` → `10405`) during the build. Bump **only** `package.json`.
+- **Signing**: secrets live in the gitignored `keystore.properties`; `scripts/inject-signing-config.mjs` injects a managed block into `android/app/build.gradle` (runs in `android:init`/`android:sync`/`android:build`). The authoritative keystore is **`/home/sovereignsk8/skatespots-release.jks`** (alias `skatespots`). An older repo-root copy had a wrong password and was retired to `~/.backups/keystore/`.
+- `android/` is **generated and gitignored**; recreate with `npm run android:init`.
+- Preflight: `cd android && ./gradlew :app:signingReport` confirms the signing config resolves.
+
+### Version bump + release notes
+1. Bump `package.json` `version` (Zapstore rejects an already-published version).
+2. Update the **top** section of `release-notes.txt` (format: `vX.Y.Z`, blank line, notes, then `---` before older versions).
+
+### Deploy
+- **Web**: `npm run build` produces the web `dist/` (with `_headers`/`_redirects`); deploy via shakespeare.diy (preferred) or drag `dist/` to the Netlify site's Deploys tab.
+- **Zapstore (Android)**, from the repo root: `SIGN_WITH='bunker://...' zsp publish zapstore.yaml`
+  - `zsp publish --wizard` is **broken for this app** (the wizard can't parse a nostrhub web `repository` — it supports only GitHub/GitLab/Gitea/F-Droid/local). Always pass `zapstore.yaml`.
+  - No NIP-07 browser extension is installed, so `SIGN_WITH=browser` fails. Use `bunker://…` (Amber) or `nsec1…`.
+  - `zapstore.yaml` sets `release_source` → local APK, `release_notes` → `release-notes.txt`, `icon` → `public/images/icon-1024.png`.
+  - Dry run (no upload): `SIGN_WITH='<signer>' zsp publish --offline zapstore.yaml`.
+
+### Git / ngit publishing
+- Push: `git push origin main` (handled by `git-remote-nostr`; publishes a signed repo-state event).
+- Login (once): `ngit account login --interactive` → scan the QR in Amber ("Add a new application → Connect app"). Plain `ngit account login` errors; the `--interactive` flag is required.
+- The NIP-65 write list contains a dead relay (`wss://wotr.relatr.xyz`), which makes `ngit repo edit` fail unless run with `--repo-relay-only`. Local git config `nostr.repo-relay-only true` is set as a workaround. Fully fix by removing that relay in the app (Settings → Relays).
+- `git push` may print a benign `cannot lock ref ... incorrect old value provided` retry warning; verify with `git fetch origin && git rev-list --left-right --count origin/main...HEAD`.
+
+### Secrets — never commit or paste
+`keystore.properties`, `*.jks`, `.env*`, and `android/` are gitignored. Never paste the nsec or keystore password into chat, logs, or command history — keep them in a password manager.
+
 ## Project Structure
 
 - `/skills/`: Specialized implementation guides for specific features - each skill has a comprehensive `SKILL.md` file with complete patterns, code examples, and best practices. See the Skills Directory section below for details on available skills.