diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f0c088d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,122 @@
+# Repository Guidelines
+
+## Project Overview
+PodNotes is an Obsidian community plugin for listening to podcasts, tracking
+playback progress, creating podcast notes, capturing timestamps, downloading
+episodes, using local audio files, and exposing a small API for workflow plugins.
+
+## Project Structure
+Source code lives in `src/`. Core plugin registration and lifecycle wiring live
+in `src/main.ts`; public API code is under `src/API/`; parsing code is under
+`src/parser/`; stores and controllers are under `src/store*`; utility functions
+are under `src/utility/`; Svelte UI lives under `src/ui/`; shared types live in
+`src/types/`.
+
+Tests are colocated with source files as `*.test.ts` where practical. Shared
+test mocks live in `tests/mocks/`. User-facing documentation lives in `docs/`
+and is built with MkDocs.
+
+Generated plugin artifacts such as `main.js` and source maps are ignored by git
+and should not be hand-edited. Production builds write `main.js` at the repo
+root for release packaging; development builds write into `build/` and maintain
+root symlinks for local Obsidian loading.
+
+## Tooling
+- Use Node 22. The repo has `.nvmrc`, `.npmrc`, and `package.json` engines for
+  this.
+- Use npm for package management and scripts. Do not introduce another package
+  manager unless the migration is intentional and removes the old lockfile.
+- Use Conventional Commits (`feat:`, `fix:`, `test:`, `docs:`, `chore:`) so
+  semantic-release can determine versions.
+- If work resolves a GitHub issue, prefer an issue-linked branch workflow before
+  implementation.
+
+## Common Commands
+- `npm install`: install dependencies for local development.
+- `npm run dev`: watch-mode development build via Vite.
+- `npm run typecheck`: run `tsc --noEmit`.
+- `npm run lint`: run ESLint against TypeScript sources.
+- `npm run format:check`: run the configured Biome check.
+- `npm run check:a11y`: run `svelte-check --fail-on-warnings`.
+- `npm run test`: run Svelte checks and the Vitest suite.
+- `npm run build`: type-check and produce the production plugin bundle.
+- `npm run docs:build`: build the MkDocs documentation.
+- `npm run docs:deploy`: build docs and deploy `docs/site` to Cloudflare Pages.
+
+Before opening a PR or cutting a release, run the CI-equivalent checks locally:
+
+```bash
+npm run lint
+npm run format:check
+npm run typecheck
+npm run build
+npm run test
+npm run docs:build
+```
+
+## Testing
+Vitest runs in jsdom and aliases `obsidian` to `tests/mocks/obsidian.ts`.
+Prefer unit tests for pure utility, parser, store, API, and component behavior.
+Use Testing Library for Svelte component behavior instead of asserting on
+implementation details.
+
+When a bug depends on real Obsidian runtime behavior, reproduce it in Obsidian
+before changing code and verify it there after the fix. Timestamp links, URI
+handling, playback restore, downloaded/local media, file writes, settings
+migrations, and workspace/view behavior are runtime-sensitive and should not be
+trusted to jsdom alone.
+
+For runtime verification, record the exact Obsidian version, platform, vault
+setup, feed or local file used, command or URI invoked, console/runtime errors,
+and observed plugin state before and after the action.
+
+## Obsidian Runtime Workflow
+Use a dedicated development vault for manual or scripted Obsidian checks. Ensure
+the vault's PodNotes plugin folder points at this checkout's generated plugin
+artifacts before trusting runtime evidence.
+
+Typical local loop:
+
+```bash
+npm run dev
+# reload or re-enable PodNotes in the development vault
+# trigger the relevant command, UI flow, or obsidian://podnotes URI
+# inspect console/errors and plugin state
+```
+
+If using the `obsidian` CLI, pass the vault selector consistently and prefer
+scripted, repeatable checks for non-trivial flows. For bugs involving commands
+or URIs, test both the user-facing path and the direct command/URI path when
+possible.
+
+## Documentation
+Docs live in `docs/docs/` and are configured by `docs/mkdocs.yml`. Update docs
+with user-facing behavior changes, new commands, API changes, template syntax,
+transcript behavior, local-file behavior, or import/export changes.
+
+Use `npm run docs:build` to validate docs locally. The Cloudflare Pages output
+directory is `docs/site`, configured in `wrangler.jsonc`.
+
+## Release Notes
+The release setup is semantic-release based. `npm version` runs
+`version-bump.mjs`, which keeps `manifest.json` and `versions.json` in sync with
+the package version and Obsidian `minAppVersion`.
+
+Release assets are `main.js` and `manifest.json`. Keep version metadata changes
+generated by the release process with the release commit, and treat unexpected
+diffs in `package.json`, `package-lock.json`, `manifest.json`, or
+`versions.json` as blockers until understood.
+
+## PR Expectations
+Pull requests should include:
+- a concise summary of the user-facing change;
+- linked issues when relevant;
+- screenshots or short recordings for visible UI changes;
+- feed URLs, local file details, or transcript setup for podcast-specific fixes;
+- exact commands run and whether Obsidian runtime verification was performed;
+- release or migration impact, especially for settings, storage, API, or URI
+  behavior.
+
+Keep changes scoped to the touched behavior. Do not mix unrelated formatting,
+dependency churn, docs rewrites, or generated artifact changes into feature and
+bug-fix commits.
diff --git a/manifest.json b/manifest.json
index 785a9ec..916d96d 100644
--- a/manifest.json
+++ b/manifest.json
@@ -8,4 +8,4 @@
 	"authorUrl": "https://bagerbach.com",
 	"fundingUrl": "https://buymeacoffee.com/chhoumann",
 	"isDesktopOnly": false
-}
\ No newline at end of file
+}