From d1a0b49fa99d7c6122322d574e736e7a7744db5d Mon Sep 17 00:00:00 2001 From: mathias Date: Tue, 2 Jun 2026 10:30:15 +0000 Subject: [PATCH] docs: add product vision and staged definition of success The top-level guardrail for Tapir: the problem, the product, the principles (local-first, standalone-first, attention-as-scarce-resource, data isolation), who it's for (now / Future B / deferred Future C), and a staged, falsifiable definition of success with Stage 0 ("useful to me") as the gate. --- VISION.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 VISION.md diff --git a/VISION.md b/VISION.md new file mode 100644 index 0000000..a73400b --- /dev/null +++ b/VISION.md @@ -0,0 +1,111 @@ +# Tapir — Product Vision + +> **One line:** Tapir quietly watches the channels you already follow and hands you +> the substance of each new video — highlights and takeaways — so you can decide what +> deserves your full attention without watching everything. + +## The problem + +People subscribe to far more YouTube/Vimeo channels than they can watch. Valuable +videos go unwatched; time is spent watching videos that turn out not to be worth it. +The signal is buried in hours of runtime. Existing "summary" tools are one-off, +paste-a-URL affairs — they don't *watch on your behalf* and they don't respect where +your attention and data should live. + +## The product + +Tapir connects to a user's YouTube/Vimeo account, learns their subscriptions, and +when a subscribed channel posts a new video, it: + +1. Detects the new video. +2. Fetches its transcript (captions first). +3. Summarizes it into highlights and takeaways relevant to the user. +4. Delivers the summary to the user's store (and, optionally, to other sinks). + +The analysis runs on a **local-first AI stack**. If the local stack cannot do the job +reliably, the user may connect their own Claude / ChatGPT / Gemini account as a +fallback — their key, their choice. + +## Principles (the guardrails) + +- **Local-first, user-owned.** The default processor is the self-hosted stack. External + AI is opt-in, per-user, with the user's own credentials. Tapir never silently ships a + user's content to a third-party model. +- **Standalone is the product.** Tapir is a standalone service first. Feeding a personal + knowledge base ("brain") is *one optional sink*, not the reason Tapir exists. +- **Attention is the scarce resource, not compute.** Every feature is judged by whether it + helps the user spend less time deciding what to watch. Summaries exist to protect + attention. +- **Data isolation is a promise, not a feature flag.** Each user's connected accounts, + credentials, and summaries are separated. This holds from the first user, not "later." +- **Respect the source.** Captions where available; no fragile or ToS-hostile scraping in + the core path. Where richer transcription is added later, it is a clearly-bounded, + optional component. + +## Who it is for + +- **Now (the first customer):** the maintainer — one person, their own subscriptions, + summaries delivered to their own store and brain. +- **Soon (Future B):** a small number of known, trusted users (friends / beta) — each with + their own account, isolated data, optional BYO-AI. +- **Maybe (Future C, explicitly not built yet):** a public multi-tenant service. Deferred + until there is evidence of sustained personal use **and** real demand. Building for C + before that evidence is a known anti-goal. + +## Definition of Success + +Success is staged. Each stage has a single, falsifiable headline test. We do not advance +to the next stage's ambition until the current stage's test passes. + +### Stage 0 — Useful to me (the gate) + +> **Headline test:** For four consecutive weeks, the maintainer reads Tapir-produced +> summaries for their own subscriptions at least weekly, and at least once acts on a +> summary (watches / skips / saves a video *because of* the summary). + +- Captions-first summarization works end-to-end for the maintainer's real subscriptions. +- Summaries land in the maintainer's store and (optionally) brain. +- Local-first AI produces summaries of acceptable quality without manual intervention + most of the time. +- **This is the gate.** Multi-user, BYO-AI-for-others, and any SaaS ambition stay deferred + until Stage 0 holds. (Ties to the 2026-07-01 self-use check-in.) + +### Stage 1 — Useful to a few (Future B) + +> **Headline test:** At least one trusted user other than the maintainer connects their +> own account and, within their first month, keeps using it (returns to read summaries in +> ≥2 separate weeks) without the maintainer hand-holding each summary. + +- Multiple users, each with isolated accounts, credentials, and summaries. +- A new user can self-connect a YouTube/Vimeo account and get summaries with no code change. +- Optional BYO-AI works per-user. +- No cross-user data leakage — demonstrable, not assumed. + +### Stage 2 — Trustworthy at rest (hardening, still Future B) + +> **Headline test:** Credentials (OAuth tokens, BYO-AI keys) are encrypted at rest via the +> homelab's existing secrets convention; a documented, rehearsed recovery path exists; and +> a deliberate isolation test (user A cannot read user B's data) passes in CI or a +> documented manual drill. + +### Non-goals (current) + +- Public sign-up / billing / a marketing surface. +- Google OAuth app verification at production scale. +- Audio-download + speech-to-text transcription in the core path (a bounded optional + component at most, deferred). +- Becoming a general-purpose video archive, player, or recommendation engine. + +## How we will know we are drifting + +- We are building Stage 1+ machinery before the Stage 0 gate has passed. +- A user's content reaches a third-party model without that user's explicit, per-user opt-in. +- "Brain ingestion" starts dictating the architecture instead of being one sink behind an + interface. +- The codebase acquires a second language or a parallel auth/secrets system that duplicates + the homelab's existing Dex / ESO conventions. + +--- + +_This document is a guardrail. Changes to the principles, the staged definition of success, +or the non-goals are architecture decisions and must be recorded in `DECISIONS.md`._