docs: rewrite the README for new users and add a contributing guide

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to PodNotes
+
+Thanks for helping. This guide covers how to build PodNotes, run its checks, test it in Obsidian, and open a pull request. [AGENTS.md](AGENTS.md) has the full details on every tool mentioned here.
+
+## Set up
+
+PodNotes uses npm and the Node version in `.nvmrc` (Node 22). Switch to it first, for example with `nvm install` or `fnm use --install-if-missing`, which also install it if needed. npm refuses to install on a Node version before 22.22.2 or after 22.x. `npm ci` installs the exact versions in `package-lock.json`.
+
+```
+npm ci
+npm run build
+```
+
+`npm run build` type-checks PodNotes and writes the production `main.js` to the repository root. While you work, `npm run dev` rebuilds on every change. It keeps running until you stop it with `Ctrl+C`.
+
+## Try your build
+
+PodNotes tests against the Obsidian desktop app: `Obsidian.app` on macOS, and the `.deb` or tarball install at `/opt/Obsidian` on Linux. A Linux machine without a display also needs `xvfb` and `xauth`. The Flatpak and Snap builds do not work.
+
+The test tools drive Obsidian through its command line client, so set that up once. In Obsidian, open **Settings → General** and turn on **Command line interface** under **Advanced**. In the dialog that opens, select **Register**. If the setting is already on, turn it off and on again to open the dialog. On Linux, this puts the client in `~/.local/bin`, which must come before `/usr/bin` on your `PATH`.
+
+```
+npm run start:e2e-obsidian
+```
+
+This starts an isolated Obsidian with its own vault that loads this checkout's build. After a rebuild, run it again to reload PodNotes. `npm run stop:e2e-obsidian` stops it.
+
+To use your own test vault instead, link `main.js` and `manifest.json` from the repository root into the vault's `.obsidian/plugins/podnotes/` folder. After each rebuild, turn PodNotes off and on in **Settings → Community plugins**. Use a vault you do not mind breaking.
+
+## Run the checks
+
+Pull requests must pass these checks. Run them before you push:
+
+```
+npm run lint
+npm run format:check
+npm run typecheck
+npm run build
+npm run size
+npm run test -- --run
+npm run docs:build
+```
+
+`npm run format` fixes formatting. `npm run size` checks the bundle size budget. `npm run test` runs the Svelte checks and the unit tests, and `--run` stops it from watching for changes. `npm run docs:build` builds the documentation site and checks its links.
+
+Tests sit next to the code as `*.test.ts`. A test file that needs a DOM starts with `// @vitest-environment jsdom`.
+
+## Test in Obsidian
+
+Behavior such as playback, timestamp links, downloads, local files, and settings migrations depends on Obsidian itself. Check it in a real Obsidian before you open a pull request.
+
+The end-to-end suite in `tests/e2e` runs against the isolated Obsidian. On Linux, `npm run test:e2e` starts it, or reuses the one already running. It stops the instance afterwards only if it started it. On macOS, start it first:
+
+```
+eval "$(npm run --silent \
+  start:e2e-obsidian \
+  -- --print-env)"
+npm run test:e2e
+npm run stop:e2e-obsidian
+```
+
+The runner does not support Windows, so check your change by hand there. [AGENTS.md](AGENTS.md#isolated-worktree-instance-macos-and-linux) shows how to send commands to the isolated Obsidian and how to stop leftover instances.
+
+## Change the docs
+
+The documentation site lives in `docs/` and is built with Astro Starlight. [docs/README.md](docs/README.md) explains its layout, and every page follows [docs/STYLE.md](docs/STYLE.md). The site describes the latest release, so put the docs for new behavior in their own pull request. It merges after the release that ships the behavior.
+
+Screenshots come from `node docs/scripts/screenshots.mjs`, which captures them from a seeded vault. Run it after `npm run build`, with network access, whenever the UI changes. Never add images by hand.
+
+## Open a pull request
+
+- Title the pull request in the Conventional Commits style, such as `fix: keep the queue order after a restart`. The type is one of `feat`, `fix`, `perf`, `docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`, or `revert`. The title becomes the commit on `master`, and the release notes are generated from it.
+- Mark a breaking change with a `BREAKING CHANGE:` footer in your commit message, which GitHub copies into the squash commit body, and say so under **Release impact**. The title check rejects the `!` breaking marker, as in `feat!:`.
+- Fill in the template: what changed for users, how you verified it (commands, Obsidian version, and platform), and any settings, storage, API, or URI impact. Link the issue it fixes, as in `Fixes #123`.
+- Add a screenshot or a short recording for a visible change.
+- Keep the pull request to one change.
+
+Releases are automated from `master`. Contributors do not tag or publish releases.

README.md

@@ -1,90 +1,60 @@
-# [PodNotes](https://podnotes.obsidian.guide)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/chhoumann/PodNotes/HEAD/docs/public/brand/podnotes-mark.svg" width="88" height="88" alt="">
+</p>
 
-<img src="docs/public/resources/podcast_grid_big.png" alt="Podcast grid" align="center">
+<h1 align="center">PodNotes</h1>
 
-<h3 align="center">You can find the documentation <a href="https://podnotes.obsidian.guide">here</a>.</h3>
+<p align="center">
+  <b>Take notes on podcasts without leaving Obsidian.</b><br>
+  Listen beside your notes, capture timestamps that link back to the moment, and create a note for any episode.
+</p>
 
-## Demo Video
-[![Demo video](https://img.youtube.com/vi/SGLfuN15uJY/0.jpg)](https://www.youtube.com/watch?v=SGLfuN15uJY)
+<p align="center">
+  <a href="https://obsidian.md/plugins?id=podnotes">Install</a>&nbsp;·
+  <a href="https://podnotes.obsidian.guide">Documentation</a>&nbsp;·
+  <a href="https://github.com/chhoumann/PodNotes/releases">Release notes</a>
+</p>
 
----
+<p align="center">
+  <a href="https://podnotes.obsidian.guide">
+    <picture>
+      <source media="(max-width: 600px) and (prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chhoumann/PodNotes/HEAD/docs/public/screenshots/hero-phone-dark.webp">
+      <source media="(max-width: 600px)" srcset="https://raw.githubusercontent.com/chhoumann/PodNotes/HEAD/docs/public/screenshots/hero-phone.webp">
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/chhoumann/PodNotes/HEAD/docs/public/screenshots/demo-dark.gif">
+      <img src="https://raw.githubusercontent.com/chhoumann/PodNotes/HEAD/docs/public/screenshots/demo.gif" width="880" alt="An episode note in Obsidian with timestamp links captured while the episode plays in PodNotes">
+    </picture>
+  </a>
+</p>
 
-The one goal for PodNotes is to make it easier to write notes on podcasts.
+## What you can do
 
-Here are the features that will help you do that 👇.
+- **Listen beside your notes.** Search Apple Podcasts or paste any RSS feed, then play audio and video with speed control, a queue, and playlists.
+- **Capture the moment.** One command inserts a timestamp link, such as `00:12:41`, into your note. Select it later to play from that second.
+- **Create a note for any episode.** A template fills in the show, date, description, and a link that resumes playback. Browse the notes as a table with Obsidian Bases.
+- **Take it with you.** PodNotes works on iOS and Android. Download episodes for offline listening, or play your own audio and video files.
+- **Transcribe episodes.** Use your own OpenAI API key, or a Deepgram key when you turn on speaker labels and choose Deepgram.
+- **Build your own workflows.** Use the commands, the JavaScript API, and QuickAdd.
 
-## Features
+## Get started
 
-- Mobile friendly - works on iOS and Android, including offline playback of local files and downloads
-- Podcast player built into Obsidian, for both audio and video episodes
-- Add any publicly available podcast through search, or custom feeds by URL
-- Track played episodes & playback progress, with continuous resume
-- Create podcast notes from templates with rich metadata about episodes
-- Bases-friendly default notes you can sort, filter, and group with [Obsidian Bases](https://help.obsidian.md/bases)
-- Create a feed note for an entire podcast that every episode note links back to
-- Capture timestamps & link directly to the time in the episode
-- Transcribe episodes, with optional speaker labels (diarization)
-- Download episodes for offline playback
-- Support for non-podcast local audio and video files
-- API that can be used by plugins like [QuickAdd](https://github.com/chhoumann/QuickAdd) or [Templater](https://github.com/silentvoid13/Templater) for custom workflows
+PodNotes needs Obsidian 1.13 or later.
 
-## Installation
+1. In Obsidian, open **Settings → Community plugins**. If you see **Exit Restricted mode**, select it. Select **Browse**, search for PodNotes, then select **Install** and **Enable**.
+2. In **Settings → PodNotes**, search for a show or paste its RSS feed URL, then select **Add**.
+3. From the command palette, run **PodNotes: Show player**, then select the show and an episode to play it. In a note in editing view, run **PodNotes: Capture Timestamp**.
 
-**This plugin is in the Obsidian community plugin store. You can find it by searching in the store.**
+[Getting started](https://podnotes.obsidian.guide/getting-started/) walks through each step.
 
-Other installation options can be found in the [documentation](https://podnotes.obsidian.guide).
+## Learn more
 
-## Development
+- [Use PodNotes on your phone](https://podnotes.obsidian.guide/mobile/)
+- [Capture timestamps](https://podnotes.obsidian.guide/timestamps/)
+- [Create episode notes](https://podnotes.obsidian.guide/notes/)
+- [Sync between devices](https://podnotes.obsidian.guide/sync/)
+- [FAQ](https://podnotes.obsidian.guide/faq/)
 
-- `npm run test` runs the accessibility checks and the unit test suite.
-- `npm run build` type-checks and bundles the plugin.
-- `npm run test:e2e` builds the plugin, then runs the local Obsidian-backed E2E suite.
+## Help and contributing
 
-The E2E suite is local-only. It depends on Obsidian being installed, the
-`obsidian` CLI being available on `PATH`, and the target vault being open and
-reachable. The default target vault is `dev`; override it with
-`PODNOTES_E2E_VAULT` when needed. Failed E2E runs may write artifacts to
-`.obsidian-e2e-artifacts/`.
+To report a bug or suggest an idea, [open an issue](https://github.com/chhoumann/PodNotes/issues/new/choose). To work on PodNotes itself, read [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Before running E2E, make sure the target vault's
-`.obsidian/plugins/podnotes/main.js` and `manifest.json` symlinks point at this
-checkout. The tests intentionally fail during preflight instead of relinking the
-vault automatically.
-
-## Screenshots
-
-### Demo
-
-![Demo](docs/public/resources/demo.gif)
-
-### Podcast Grid
-
-![Podcast Grid](docs/public/resources/podcast_grid.png)
-
-### Episode List
-
-![Episode List](docs/public/resources/episode_list.png)
-
-### Player
-
-![Player](docs/public/resources/player.png)
-
-### Episode notes (Bases-friendly)
-
-![Episode note](docs/public/resources/podcast_note.png)
-
-### Timestamps
-
-![Timestamps](docs/public/resources/timestamps.png)
-
-### Transcripts with speaker labels
-
-![Transcript with speaker labels](docs/public/resources/transcript_diarization.png)
-
-### Browse your library with Bases
-
-![Bases view of episode notes](docs/public/resources/bases_view.png)
-
-### Podcast search
-
-![Podcast Search](docs/public/resources/podcast_search.png)
+PodNotes is free and open source under the [MIT license](LICENSE). If it helps you, you can [support its development](https://www.buymeacoffee.com/chhoumann).