openpod 0.1.0__tar.gz

openpod-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv*/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+
+# OpenPod local libraries created while developing/testing
+.openpod/
+
+# Never commit internal strategy docs into the public repo
+/Docs/

openpod-0.1.0/CHANGELOG.md

@@ -0,0 +1,202 @@
+# Changelog
+
+All notable changes to OpenPod are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow SemVer.
+
+## [0.1.0] — 2026-07-16
+
+First Stage 1 alpha: local-pure, pull-only.
+
+### Added
+- **Two-layer persona: who you are vs. what this folder is for.** Global
+  (`~/.openpod/persona.md`): role, language & style, standing
+  interests/filters, what you want from long-form — true in every
+  workspace, the layer a cloud tier would sync. Workspace
+  (`.openpod/persona.md`): current projects, local amplify/filter topics,
+  and the machine-derived blocks (derived from *this* library). The MCP
+  `persona` tool returns both layers labeled — identity/language lean
+  global, relevance decisions lean workspace — and routes writes by kind.
+  Existing single-file personas get a **split proposal**: sections are
+  classified (Role → global, Current projects → local, unknowns → ask) and
+  offered as one multiple-choice confirmation — the user picks, never
+  writes prose — then `persona_split` / `openpod persona split --to-global`
+  moves exactly the confirmed sections. Machine-owned blocks are never
+  offered and never move. CLI: `persona init|show --global`, `persona
+  split`. House rule codified in the skill: users choose from options
+  mined from evidence; system files never demand elaboration.
+- **`summary.md` — the cross-session memory artifact**: a durable, local
+  distillation of an episode, written by the agent (or user) after actually
+  engaging with it, and loaded by future sessions as context. The contract
+  is deliberately minimal: OpenPod owns placement and identity frontmatter
+  (entry_id, episode_key — sync-ready for the cloud tier, updated_at,
+  revision count); the body — structure, language, depth, relevance — is
+  entirely the author's. `write_summary(append=True)` lets sessions add
+  dated takes without losing prior ones. Surfaces: MCP `save_summary` +
+  `recall_summaries` (the "load what past sessions learned" call),
+  summary included in `get_briefing`, CLI `openpod summary` (read / write
+  / list), and the **Remember This** skill — guidance (personalize from
+  the session, exclude what didn't matter, cite moments, budget tokens),
+  explicitly defaults-not-mandates.
+- **No more silent Whisper fallback** — a cost-based gate keeps interaction
+  fast: every ASR run is *announced* (why captions failed, the wall-clock
+  estimate, and that it's local compute — no tokens or API cost — recorded
+  in `transcript.notes`), but the user is only *asked* when it's worth
+  asking. Caption failures are classified: permanent (no captions exist →
+  ASR just runs, announced) vs transient (429/IP throttling → a short
+  transcription under `asr.auto_threshold_seconds` (default 180s) runs with
+  a notice, a long one raises structured `captions_unavailable` with both
+  options priced — wait and re-catch for free captions, or `asr="now"` /
+  `--asr-now`). `--no-asr` never transcribes. Throttled-then-ASR
+  transcripts carry "a later re-catch may upgrade this to platform
+  captions". RSS enclosure ASR announces itself the same way. Caption
+  language follows `locale.preferred_language` (a Hebrew interview fetches
+  Hebrew captions first, then fallback, then English).
+- **Caption data contract + export package** (naval-clipper design port —
+  contracts, not renderers):
+  - Clips carry a **structured caption track in their `.json`**: phrases
+    chunked by the karaoke rules (≤5 words / sentence / `‖` force-break —
+    the marker translated Hebrew keeps so nothing regroups it), language +
+    `rtl`, and honest `timing` (`approximate` for rolling YouTube cues,
+    `exact` only with word-level).
+  - **Word-level track** (`--word-level` on `clip` and `captions`, asr
+    extra): whisper on just the clip window/file → `*.words.json` — the
+    karaoke-highlight layer.
+  - **Burn gate**: burning refuses unverified translations and any
+    `captions_file` that fails the coverage check (dropped speech named in
+    the note); RTL burns warn to eyeball `verify.png` for missing glyphs.
+  - **Export package**: the working folder now also gets `deeplink.txt`,
+    `label.json` (label + optional `hook`), `*.words.json`, and `verify.png`
+    (start/mid/end frames of the burned derivative, tiled).
+  - **Speakers**: `{title}`/`{role}` template aliases and a workspace
+    `speakers.yaml` (keyed by show) as fallback — teach OpenPod a show's
+    hosts once.
+  - **`clip.style` setting** (default `karaoke`) reserved for renderers.
+  - **New skill: Make it Shareable** — the export pipeline end-to-end
+    (doctor first, captions as data, line-locked translation, verified burn,
+    export-folder hygiene); `cut-the-clip` hands off to it, and
+    `sharpen-my-persona` may offer `locale.preferred_language` when the
+    library skews non-English.
+- **The two-artifact clip contract** (QA session 2026-07-09): the library
+  clip is the clean master and is never mutated; presentation — captions,
+  name-plate labels, social encodes — are **export derivatives**:
+  - **Settings schema v0** (`settings.yaml`, documented defaults merged at
+    read time): `locale.preferred_language`/`fallback_language`,
+    `clip.captions` (`off|soft|burn`), `clip.caption_language`,
+    `clip.burn_in` (default **false**), `clip.label`, `clip.label_template`,
+    `clip.export_dir`, `clip.keep_clean_master`. Unknown keys are rejected
+    with the documented list. CLI `openpod settings`, MCP `settings` tool.
+  - **Caption primitive** (`captions.py`): SRT/VTT sidecars generated from
+    `transcript.window(start, end)` — full coverage by construction — plus a
+    **coverage verify** (`openpod captions --verify`, MCP `captions`) that
+    catches dropped lines in edited/translated caption files before any
+    burn-in. Translation is flagged (`translation_needed`), never guessed.
+  - **Clip presentation flags**: `--captions off|soft|burn`, `--lang`,
+    `--label` / `--label-from-meta`, `--out DIR` (and `clip.export_dir`):
+    derivatives and copies land in the working folder; burned files land
+    *only* there. Labels render from structured `source.speakers`
+    (name/role), never from agent memory.
+  - **`openpod doctor`**: ffmpeg capability report (libass/drawtext probed
+    before any burn is promised), settings status, and library hygiene —
+    foreign files (venvs, scripts, previews) under `library/` are flagged
+    and quarantined to `library/_scratch/` with `--fix`.
+  - **cut-the-clip skill v2**: teaches the two-artifact contract — never
+    burn the master, captions from transcript with verify, labels from
+    meta, working files never in the vault.
+- **Deterministic cross-platform resolution** — episode identity is product
+  code now, not per-session agent improvisation:
+  - **Apple Podcasts ingest** (`ingest/apple.py`): `id{show}` + `i={episode}`
+    + country parsed from the URL, resolved via the keyless iTunes Lookup API
+    to the RSS feed and the episode's guid — the exact episode, never
+    "newest in feed".
+  - **Spotify ingest** (`ingest/spotify.py`): oEmbed title → iTunes episode
+    search → guid-anchored feed match. No HTML scraping, no open-ended web
+    search; Spotify-exclusives fail with a structured, actionable error.
+  - **Identity crosswalk** (`crosswalk.py`, `EpisodeIdentity`): per-episode
+    records under `.openpod/crosswalk/` mapping YouTube/Spotify/Apple/RSS ids
+    with per-field provenance, plus a show-level table. Resolved once, cached
+    forever; schema is user-free so it can later be served globally.
+  - **Confirmation gate**: fuzzy matches below confidence 0.8 raise/return a
+    structured `needs_confirmation` candidate instead of silently ingesting;
+    `catch(..., confirmed=true)` records the user's confirmation. Confidence
+    is corroborated (title + duration + date), never a single signal.
+  - **No silent defaults**: unclassifiable links are `unknown` and return a
+    structured `unresolved_link` error (with what was tried), instead of
+    falling through into the RSS parser.
+- **Origin/source decoupling + capability-aware links** — `catch` persists
+  what the user pasted (`origin`) separately from the transcript source;
+  `build_link()` renders the output on the user's platform (explicit arg →
+  `preferred_playback_app` setting → origin) from a per-app capability table
+  and reports honestly when it degrades ("Apple opens the episode, not the
+  moment"). New MCP tools: `playback_link`, `set_preferred_app`.
+- **Cross-source timestamp alignment** (`align.py`) — piecewise-constant
+  offset maps recovered by probe-and-bisect (≈10–20 fifteen-second ASR
+  probes per episode, O(log n) per ad break), cached on the crosswalk record.
+- **Content-type validation** (`ingest/validate.py`) — HEAD + magic-byte
+  sniffing with a defined support matrix; tracking redirectors resolve to
+  their terminal URL once; unsupported content raises `unsupported_format`
+  instead of being piped into Whisper on luck.
+- **Shared media cache + video-preserving clips** — one download per episode
+  under `.openpod/media/`; `clip` keeps video by default when the source has
+  it (`--video` / `--audio-only` on the CLI, `video=` on MCP) and reports
+  `has_video` + a capability note *before* delivering a mismatched artifact.
+- **Follow-time show resolution** — following an Apple show URL resolves and
+  stores its RSS feed once, recorded in the crosswalk show table.
+
+- **`catch`** — ingest a podcast/RSS/YouTube link (or local file) into a local
+  library: timed transcript, extracted key ideas, navigable TOC, and a briefing
+  scaffold for the agent to complete.
+- **`search`** — cross-episode local search over the whole library (SQLite FTS5
+  keyword retrieval + a dependency-free local embedding re-rank).
+- **`export_timestamps`** — emit timed segments + deep-links as JSON or Markdown.
+- **`clip`** — sentence-snapped, local clip extraction via ffmpeg, plus a
+  shareable deep-link card. Local files only; no re-hosting.
+- **`follow` / `digest`** — local follow list (podcast RSS + YouTube channels)
+  and a "what's new" digest polled locally. Digest items carry
+  `in_rotation`: follows the user has never caught are flagged as the
+  **discovery pool** — the What's New skill surfaces interest-matching
+  episodes from unfamiliar shows with a cheap trial (briefing or the one
+  matching beat) instead of burying them under familiar names. Persona
+  filters apply to topics, never to sources.
+- **`persona`** — a local, user-owned `persona.md` that evolves from the
+  library. Machine-owned blocks (`## Derived from my library`, `## Imported
+  interests (opt-in)`) are regenerated in place under a marker contract that
+  provably never touches the human-authored sections.
+- **`import`** — opt-in OPML import: stages the raw export verbatim in
+  `.openpod/imports/`, merges subscriptions into `follows.yaml` de-duplicated
+  and tagged with `source:` provenance, and refreshes the persona's
+  imported-interests block. Snapshot, not sync; no OAuth, no cloud APIs.
+- **`note`** — append to an episode's user-owned `notes.md` (also exposed to
+  agents as `append_note`, append-on-request only).
+- **`persona scan`** — a fast, bounded, read-only workspace evidence sweep
+  (project folders by recency, markdown doc titles, `CLAUDE.md` headings,
+  library themes, follows) powering a **guess-and-confirm interview**: the
+  agent presents multi-select options mined from the evidence and the user
+  picks instead of typing. Extra roots are opt-in only. The trust-question
+  was retired (follows/OPML answer it); all interview questions are now
+  multi-select guesses with a free-text escape hatch.
+- **Skills catalog** — nine versioned `SKILL.md` bundles shipped in the package
+  (Catch Me Up, Set Up My Persona, Bring In My World, Sharpen My Persona, Find
+  the Moment, Cut the Clip, What's New, Chapter It, Follow This); `openpod
+  skills` lists them and the MCP server exposes them as prompts.
+- **MCP server** (`openpod-mcp`) exposing the primitives to AI agents, plus
+  `list_entries`, `append_note`, and `import_opml`; every tool result carries
+  the entry id and the path(s) touched.
+- **CLI UX contract** — mutating commands print the path(s) they wrote;
+  read/produce commands take `--json` shaped identically to the MCP tools;
+  errors name the fix; `catch` on a persona-less workspace suggests "Set Up My
+  Persona".
+- Transcript parsers for WebVTT, SubRip, YouTube `json3`, and cue lists.
+- Deep-link construction for YouTube, Spotify, and open podcast enclosures.
+- **The anchor ladder** — every idea, search hit, and TOC entry carries up to
+  three labeled deep-links, because different readers want different
+  landings: the creator's **chapter** ("take me to the topic"), the detected
+  **beat** where the idea starts being articulated ("play the argument from
+  its start"), and the exact **moment** ("show me where they said it").
+  Beats come from creator chapters when the source ships them (YouTube
+  chapter markers, or timestamp lists parsed from the description) — with
+  over-long chapters sub-segmented by local lexical-cohesion topic detection
+  — and from pure topic detection otherwise. No link ever lands mid-sentence
+  without a labeled alternative. Beats persist in `meta.json`; hits carry
+  `chapter_*`, `segment_*`, and `deeplink` fields; `ideas.md` renders the
+  ladder with a one-line legend.
+- MIT license; offline test suite; CI across Python 3.10–3.13.

openpod-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to OpenPod
+
+Thanks for helping! OpenPod is a local-first tool with a few hard invariants —
+please keep them in mind, they're the whole point of the project.
+
+## The invariants (non-negotiable)
+
+1. **Local-pure.** No code path may upload the user's audio, transcripts,
+   library, or persona to any server. If a feature needs a server, it's Stage 2
+   and doesn't belong here.
+2. **Pull, not push.** No background processes, no always-on monitoring.
+3. **Artifacts, not telemetry.** Persist what the user explicitly produces.
+   Never capture behavioral signal (play/skip/replay).
+4. **Navigate, don't re-host.** Sharing is deep-links to the moment in the
+   native player, never republished audio/video.
+
+If a change touches these, open an issue first.
+
+## Dev setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+The test suite must stay **fully offline** — no network calls, no model
+downloads. Use fixtures (see `tests/conftest.py`). Heavy/network dependencies
+(`yt-dlp`, `youtube-transcript-api`, `faster-whisper`, `mcp`) are optional
+extras and must be imported lazily so the core installs and tests without them.
+
+## Style
+
+- Standard library first; add a dependency only when it clearly earns its place.
+- Keep the public surface small (`catch`, `clip`, `export_timestamps`, `search`,
+  plus `follow`/`persona`).
+- New optional integrations go behind an extra in `pyproject.toml` and a lazy
+  import with a clear "install `openpod[...]`" error message.
+
+## License
+
+By contributing you agree your contributions are licensed under
+**MIT**, the project's license.

openpod-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoav Dori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openpod-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: openpod
+Version: 0.1.0
+Summary: Local-first CLI + MCP server that turns long-form audio/video into personalized, cited, navigable briefings — everything runs on your machine.
+Project-URL: Homepage, https://github.com/openpodhq/openpod
+Project-URL: Repository, https://github.com/openpodhq/openpod
+Author: OpenPod contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,local-first,mcp,podcast,transcript,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: feedparser>=6.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: faster-whisper>=1.0; extra == 'all'
+Requires-Dist: mcp>=1.2; extra == 'all'
+Requires-Dist: numpy>=1.24; extra == 'all'
+Requires-Dist: playwright>=1.40; extra == 'all'
+Requires-Dist: youtube-transcript-api>=0.6; extra == 'all'
+Requires-Dist: yt-dlp>=2024.1; extra == 'all'
+Provides-Extra: asr
+Requires-Dist: faster-whisper>=1.0; extra == 'asr'
+Provides-Extra: bridge
+Provides-Extra: card-png
+Requires-Dist: playwright>=1.40; extra == 'card-png'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: numpy>=1.24; extra == 'embeddings'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: sync
+Provides-Extra: youtube
+Requires-Dist: youtube-transcript-api>=0.6; extra == 'youtube'
+Requires-Dist: yt-dlp>=2024.1; extra == 'youtube'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/openpodhq/openpod/main/assets/brand/wordmark-blue-dark-636.png">
+    <img src="https://raw.githubusercontent.com/openpodhq/openpod/main/assets/brand/wordmark-blue-636.png" alt="OpenPod" width="212">
+  </picture>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/openpodhq/openpod/main/assets/demo.gif" alt="An AI agent pulls the minutes that matter from hundreds of hours across the shows you follow — every hit timestamped to verify" width="720">
+</p>
+
+# OpenPod
+
+**Pull the ten minutes that matter — to you.**
+
+[![PyPI](https://img.shields.io/pypi/v/openpod)](https://pypi.org/project/openpod/) [![Python](https://img.shields.io/pypi/pyversions/openpod)](https://pypi.org/project/openpod/) [![CI](https://github.com/openpodhq/openpod/actions/workflows/ci.yml/badge.svg)](https://github.com/openpodhq/openpod/actions) [![License](https://img.shields.io/badge/license-MIT-black)](LICENSE) [![Telemetry](https://img.shields.io/badge/telemetry-0-black)](#nothing-leaves-your-machine) [![MCP](https://img.shields.io/badge/MCP-server-black)](https://modelcontextprotocol.io)
+
+Hundreds of hours pile up across the shows you follow. OpenPod pulls out the minutes you're chasing — cited, timestamped to verify, extracted on your own machine — as the starting point your AI agent works from.
+
+OpenPod is a local-first agent toolkit — primitives plus packaged skills — that your agent drives over MCP or the CLI. It connects to nothing external; the only corpus is your library on disk.
+
+```bash
+pip install openpod
+openpod catch "https://example.com/podcast/feed.xml"
+```
+
+**Catch your first episode** — one command, about a minute. You get a timestamped transcript, the key ideas, and jump-to-moment links, all as plain files in a folder you own.
+
+`0 servers · 0 accounts · 0 telemetry · $0 to run · test suite runs fully offline`
+
+> **Status:** Stage 1 alpha. Local-pure, pull-only. It does what this page shows — nothing more yet.
+
+---
+
+## The problem
+
+You subscribe to twelve shows. You're forty episodes behind, every one is three hours long, and the one segment you actually needed last week — you can't find it, because nobody remembers a timestamp. So the backlog grows, the guilt compounds, and "I'll listen on the weekend" becomes a lie you tell yourself on Mondays.
+
+Cloud summarizers answer this by asking you to upload what you listen to — and to trust their summary with no way to check it. OpenPod doesn't summarize your listening on someone else's computer. It gives **your** agent the ability to listen, cite, and link — locally.
+
+## What you get
+
+Point OpenPod (or your agent) at an RSS feed or a YouTube link. In return:
+
+- **A briefing you can verify.** Every claim carries a timestamp and a deep link. Don't trust the summary? Click and hear the source in the native player. OpenPod never re-hosts anyone's audio — it navigates you to the moment.
+- **A library that compounds.** Everything you catch lands in `.openpod/` as plain files — transcripts, briefings, ideas, notes, clips. Searchable across everything you've ever caught, keyword and semantic, all local.
+- **Personalized by your own agent.** OpenPod reads your local `persona.md`, so your AI foregrounds the decisions, tools, and numbers *you* care about and drops the rest — the same episode briefs differently for you than for the next person, and no cloud model ever sees who you are.
+
+## Nothing leaves your machine
+
+There is no OpenPod server, no account, no telemetry — there is nothing to opt out of, because nothing phones home. The only corpus is your own library on disk. Publisher transcripts and captions are used when they exist; otherwise audio is transcribed locally with Whisper. Your agent brings the intelligence; OpenPod supplies extraction, structure, citations, deep links, and local search. That's the whole trade — and it's why running it costs nothing.
+
+## Your agent can drive all of it
+
+OpenPod's toolkit is exposed as an [MCP](https://modelcontextprotocol.io) server, so Claude Code, Cowork, Codex — any MCP client — can catch, search, clip, and brief by name:
+
+```bash
+openpod-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "openpod": { "command": "openpod-mcp", "env": { "OPENPOD_HOME": "/path/to/your/workspace" } }
+  }
+}
+```
+
+Say *"catch me up on this episode"* and the agent runs `catch`, reads your local persona file, and writes a cited briefing back into your library — then hands you the path. Mid-conversation, no dashboard, no copy-paste.
+
+## The four primitives
+
+| Tool | Does | Writes |
+|---|---|---|
+| `catch <link>` | Ingest → transcribe → structure → brief | `transcript.json`, `ideas.md`, `briefing.md` |
+| `search <query>` | Retrieve across your local library | ranked cues with deep links |
+| `export_timestamps <entry>` | Navigable TOC with deep links | JSON / Markdown |
+| `clip <entry> <start> <end>` | Sentence-snapped local cut + shareable deep-link card | media in `clips/`, card |
+
+Every mutating command prints the path it wrote — the output of an action is the address of the artifact it produced. Every read command takes `--json`, shaped identically to the matching MCP tool.
+
+## Skills — the features, by name
+
+Primitives are the API; **skills are the product.** Each is a versioned instruction bundle (`openpod skills` lists them; the MCP server exposes them as prompts) that tells an agent how to compose the primitives and report back:
+
+| Skill | You ask | It writes |
+|---|---|---|
+| **Catch Me Up** | "Brief me on this episode" | `briefing.md`, `ideas.md` |
+| **Find the Moment** | "Where did they talk about X?" | deep-linked hits |
+| **What's New** | "What dropped in my feeds?" | digest |
+| **Cut the Clip** | "Pull the shareable minute" | media + share card |
+| **Chapter It** | "Give me a navigable TOC" | timestamps (md/json) |
+| **Follow This** | "Keep me on this show" | `follows.yaml` entry |
+| **Set Up My Persona** | "Learn who I am" | `persona.md` — yours, local |
+| **Sharpen My Persona** | "Update what you know about me" | persona Derived block |
+| **Bring In My World** | "Import my subscriptions" | `imports/`, `follows.yaml` |
+
+## More things it does
+
+```bash
+# Already have a transcript? Skip the network entirely.
+openpod catch "https://example.com/ep1" --kind podcast --transcript ./ep1.vtt
+
+# Search everything you've ever caught (keyword + local semantic)
+openpod search "what did they say about raft consensus"
+
+# Follow feeds locally; see what's new on your schedule — nothing polls in the background
+openpod follow "https://example.com/feed.xml"
+openpod digest
+
+# Cut a local, sentence-snapped clip (needs ffmpeg) + a shareable deep-link card
+openpod clip "test-pod/episode-one-consensus" 320 385
+
+# Import subscriptions from a file you export (OPML) — point-in-time, opt-in
+openpod import ~/Downloads/overcast.opml
+
+# Annotate; notes feed future personalization
+openpod note "test-pod/episode-one-consensus" "the Raft segment matters for our design"
+```
+
+Everything lands in a plain, user-owned tree:
+
+```
+.openpod/
+  persona.md              # who you are (evolving, local)
+  follows.yaml            # subscribed RSS + YouTube channels
+  library/<show>/<episode>/
+    transcript.json  briefing.md  ideas.md  notes.md  clips/
+  index/                  # local search index (SQLite FTS + embeddings)
+```
+
+Want it on two machines? Put the tree in git or Dropbox yourself. OpenPod won't sync it for you.
+
+## Install options
+
+```bash
+pip install openpod                 # core: RSS ingest, local search, deep links, clip
+pip install 'openpod[youtube]'      # + YouTube captions & audio
+pip install 'openpod[asr]'          # + local Whisper transcription
+pip install 'openpod[mcp]'          # + the MCP server
+pip install 'openpod[all]'          # everything
+```
+
+`ffmpeg` on your `PATH` is required for `clip`.
+
+## Use it as a library
+
+```python
+from openpod import catch, search
+
+result = catch("https://example.com/ep1", transcript_path="ep1.vtt", kind="podcast")
+print(result.entry_id, len(result.transcript), result.ideas)
+
+for hit in search("consensus algorithms"):
+    print(hit.show, hit.start, hit.deeplink)
+```
+
+## Trust & posture FAQ
+
+**Does OpenPod download or re-host other people's content?**
+It navigates, it doesn't republish. Deep links open the moment in YouTube, Spotify, or the open podcast enclosure. Podcast RSS — content published for open distribution — is the primary surface; YouTube support is an optional module that uses official captions, or local transcription of audio you can already access. OpenPod never touches DRM, paywalls, or age gates.
+
+**What data do you collect about me?**
+None. There is no endpoint to send it to.
+
+**How is transcription chosen?**
+Publisher-provided timed transcripts and captions first — free, fast, good for navigation (±2–4s cue timing). Otherwise local Whisper (`asr` extra). Nothing is uploaded either way. `clip` snaps cuts to cue boundaries so clips land on sentences.
+
+**Why MIT?**
+[MIT](LICENSE): maximally permissive and frictionless — install it at work without tripping a license policy, embed it, build on it, no obligations. OpenPod isn't protected by its license; it's protected by being local-pure and simple. No copyleft, no lock-in.
+
+**Can I hack on it without heavy models or network?**
+Yes — the test suite runs fully offline against fixtures.
+
+Built by Yoav — building OpenPod in public.
+
+## Development
+
+```bash
+git clone https://github.com/openpodhq/openpod
+cd openpod
+python -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+Contributions that package or connect OpenPod travel furthest: Homebrew formula, Docker image, MCP client recipes, note-app bridges. Open an issue first; response is fast.
+
+---
+
+**Long-form is a lot. OpenPod pulls the ten minutes that matter — to you — with a link straight to every one.**
+
+```bash
+pip install openpod
+```
+
+If it saved you an hour this week, [star the repo](../../stargazers) — stars are how the next person finds it.