mathias
477701fea2
Replaces the original "useful to me, specifically" gate with "me OR a friend
returns unprompted in >=2 separate weeks" — friendly-user signal counts, but the
test stays behavioural (return usage) not feedback-based, to resist politeness
bias. Folds the old Stage 1 ("a trusted user returns") into the new Stage 0 (they
were near-identical), renumbers hardening to Stage 1, and updates the drift
signals (the gate can be softened by mistaking polite feedback for evidence;
multi-user shipping ahead of the gate was a recorded exception per ADR-012, not a
precedent). Rationale recorded in ADR-016.
120 lines
6.3 KiB
Markdown
120 lines
6.3 KiB
Markdown
# 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 customers):** the maintainer and a small number of known, trusted
|
||
friends — each with their own account, isolated data, optional BYO-AI. The maintainer is
|
||
the first customer; friendly users provide the earliest real-world signal.
|
||
- **Maybe (Future C, explicitly not built yet):** a public multi-tenant service. Deferred
|
||
until there is evidence of sustained 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 or a friend (the gate)
|
||
|
||
> **Headline test:** Over a 3–4 week window, *either* the maintainer *or* at least one
|
||
> onboarded friend returns to Tapir **unprompted** and reads/acts on summaries in **≥2
|
||
> separate weeks**. The test is *return usage* (behavioural), not stated approval.
|
||
|
||
- Captions-first summarization works end-to-end for real subscriptions (the maintainer's
|
||
and onboarded friends').
|
||
- Summaries land in each user's own store and (optionally) brain.
|
||
- Local-first AI produces summaries of acceptable quality without manual intervention
|
||
most of the time.
|
||
- **Why behavioural, not feedback.** Friend *feedback* is gathered and genuinely valuable —
|
||
but it is **not** the gate. Asked-for feedback from friendly users is the least reliable
|
||
signal in product development (politeness bias); whether they *come back on their own* is
|
||
the thing we actually care about. So the gate measures returns, not nice words.
|
||
- **Why "me OR a friend".** This replaces the original "useful to *me*, specifically" gate
|
||
(2026-06-03 decision, recorded in DECISIONS.md ADR-016). Getting signal from friendly
|
||
users is valuable enough to count — but the bar stays behavioural so it can't be cleared
|
||
by a polite reaction. (Ties to the 2026-07-01 check-in.)
|
||
- **This is the gate.** Hardening (Stage 1) and any SaaS ambition stay deferred until this
|
||
behavioural signal exists. Note: multi-user machinery was deliberately built *ahead* of
|
||
this gate (ADR-012) with isolation enforced — that was an explicit, recorded call, not a
|
||
sign the gate had passed. The gate is about *evidence of use*, which is still open.
|
||
|
||
### Stage 1 — Trustworthy at rest (hardening, 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.
|
||
|
||
- Per-user data isolation is enforced and tested (delivered early via ADR-012 RLS).
|
||
- Per-user credentials are encrypted at rest (ADR-015 envelope encryption; build in infra#89).
|
||
- A new user can self-connect a YouTube/Vimeo account and get summaries with no code change.
|
||
- Optional BYO-AI works per-user.
|
||
|
||
### 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 declare the Stage 0 gate "passed" on the strength of polite feedback rather than
|
||
behavioural return-usage (the politeness-bias trap the gate is designed to resist).
|
||
- We build Stage 1 hardening or Future C machinery while the Stage 0 use-evidence is still
|
||
absent. (Multi-user machinery already shipped ahead of the gate via ADR-012 — a recorded,
|
||
deliberate exception, not a precedent for more.)
|
||
- 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`._
|