From c315e3e00323643dfc8eb6f16fd1604ee171ff34 Mon Sep 17 00:00:00 2001 From: mathias Date: Fri, 12 Jun 2026 20:52:23 +0000 Subject: [PATCH 1/2] feat(language): add hand-written vocabulary + caveman rubric pilot Phase 1 of the ubiquitous-language system (tapir#18). Tapir-specific terms verified against domain/ports code + README/VISION; homelab-core terms (brain sink, LiteLLM gateway) derived from brain#5 glossary. Tooling-free pilot. --- LANGUAGE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 LANGUAGE.md diff --git a/LANGUAGE.md b/LANGUAGE.md new file mode 100644 index 0000000..5effe7f --- /dev/null +++ b/LANGUAGE.md @@ -0,0 +1,26 @@ +# Vocabulary (hand-written pilot 2026-06 — will be generated by langgen in Phase 2) + +| Term | Means | Never say | +|---|---|---| +| transcript | Captions-first text of a video; the source for summarizing. Shared store keyed by `(provider, video_id)`. | "subtitles file", "the audio" | +| video | Per-user record of a seen video; the unit of work. Not globally deduped. | "the shared video" | +| subscription | A watched channel on a user's connection that Tapir polls for new videos. | "feed", "follow" | +| summary | A video's produced output: summary text + highlights + takeaways + AI provenance. | "transcript" | +| highlight | A notable point pulled from a video (`Summary.Highlights`). | "takeaway" | +| takeaway | An actionable conclusion from a video (`Summary.Takeaways`). | "highlight" | +| sink | A delivery destination for a summary (`store`, `brain`). New one = new adapter. | "the database" | +| AI router | Local-first chain: local Primary → local fallback → external worst-case. | "the API" | +| BYO-AI fallback | User's own external AI key, used only when local fails; opt-in. Without it, content is never sent externally. | "the default AI" | +| brain | Persistent homelab knowledge store; in Tapir, one optional HTTP sink (`brain_ingest`), not the filesystem package. | "the database", "the store" | +| LiteLLM gateway | Local AI gateway (`koala:30401/v1`); the Primary in the AI router. | "piguard", "the cloud" | +| connection | A connected video account a user authorizes via OAuth; subscriptions hang off it. | "login", "session" | + +## Caveman rubric +Before any HIGH/CRITICAL operation, output one line: +`caveman: me , not ` +Valid iff: (1) only vocabulary terms + plain verbs, (2) a stranger could identify +the exact operation, (3) names one thing explicitly NOT being done. + +Examples: +- `caveman: me delete user connection, not the shared transcript` +- `caveman: me send transcript to BYO-AI fallback, not the LiteLLM gateway` From b79fb892c84695d90778bde394dffd1ff7f36817 Mon Sep 17 00:00:00 2001 From: Mathias Date: Fri, 12 Jun 2026 22:54:57 +0200 Subject: [PATCH 2/2] docs(claude): point to LANGUAGE.md + caveman rubric Wires the Phase 1 vocabulary pilot into the canonical agent instructions (tapir#18). CLAUDE.md is canonical here (no .context/ source, no generation header). Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CLAUDE.md b/CLAUDE.md index 2e77c0a..cf4a939 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,6 +12,7 @@ docs it indexes. 3. `DECISIONS.md` — the ADRs. Decisions are settled here; do not re-litigate without a new ADR. 4. `docs/architecture/architecture.md`, `docs/data-model.md`, `docs/use-cases/*.feature`. 5. `docs/homelab-integration.md` — the concrete endpoints/conventions you'll need. +6. `LANGUAGE.md` — the project vocabulary. Apply the caveman rubric before destructive operations. ## How to work in this repo