Status: operational reference. The durable principles that recur across every design doc,
collected once. Each is a compression of decisions logged in the deep docs (IDs cited). When a
new choice conflicts with one of these, that’s a signal to stop and reconsider — or to update the
principle deliberately. Companion to SYSTEM-DESIGN.md.
Product
#
Principle
Why
Source
P-1
Agent-operated product; founder in the loop for strategy
Creative + engineering agents run the pipeline; humans review at gates, not every step
ARCHITECTURE §1
P-2
The content pipeline is itself a product surface
The BO/console isn’t scaffolding — it’s a first-class product we design as carefully as the app
ARCHITECTURE §1
P-3
The unit is “a greeting to send,” not a video to watch
Success = share-intent, not watch-time; optimize time-to-a-good-send, not time-on-app
DIST DS-2
P-4
Amplify the recipe, never the dish
A hit means “make more like this” (production amplification), not “show this to everyone” — we don’t chase virality
DIST DS-4
P-5
Novelty + rarity are first-class; diversity is the product
Uniqueness is the value; a greeting everyone else sent is devalued. Inverts the usual popularity boost
DIST DS-4/DS-5
P-6
Vernacular-first, English-second
Audience is next-billion, Tier-2/3, 35+, Android; languages hi/en/hi-Latn
ARCHITECTURE §2
P-7
Architect for the low-end device
Cache-first sharing, strict .nomedia, pre-positioned bytes; no on-device ML
ARCHITECTURE §2, DIST DS-7/DS-8
P-8
Privacy-light by design
Measure in-app share-intent only; stop at the OS share-sheet — no recipient graph, no off-platform beacon
DIST DS-10
Engineering
#
Principle
Why
Source
P-9
Everything Cloudflare by default
One account/bill/deploy, colocated with data; reach outside only when CF can’t, and document why
ARCHITECTURE D1
P-10
Control plane and execution plane are separate concerns
The BO is UI + thin control API + authoritative mode state — no agent/business logic (the rule that killed n8n)
ARCHITECTURE §3, D2/D4
P-11
Single source of truth
No component keeps a private copy of catalog or control state — the catalog spine and the Control DO are authoritative
ARCHITECTURE §2/§5, D8
P-12
Ports & adapters — provider-agnostic
ModelPort / EmbedderPort / VectorIndex behind our own interfaces; swapping Ollama→Workers AI→Jina is config, not a refactor
BACK-OFFICE BO-2
P-13
Contracts between components are versioned Zod schemas
The brief, the Content Strategy, FeedPolicy, OnboardingSignals — a downstream agent consumes one cold; immutable + reproducible
CP-3, FL-2
P-14
Isomorphic code across sim and serving
One rank(), one coldStartVector() imported by both the Feed Lab and the serving path — kills playground-vs-reality drift
FL-1/FL-10
P-15
LLMs are the offline slow brain; the per-request path is cheap vector math
An LLM call per user per scroll bankrupts a free next-billion app — keep a seam so scale = move LLM work offline
DIST DS-14
P-16
Infrastructure as code; CI is the deployer
Alchemy owns CF resources; GitHub Actions + Wrangler deploy only what changed — reproducible, no click-ops
No overengineering; research scalability + best practice before an architectural choice
AGENTS.md, memory
P-18
Secrets never get committed
secrets/, .env*, .dev.vars, .mcp.json gitignored; CI fails on a tracked secret; shared secrets live in the Secrets Store
AGENTS.md, SEC-3
Agents (the Kernel)
#
Principle
Why
Source
P-19
One agent shape — the Kernel + a manifest
“New agent” = write a manifest + prompts, not a runtime; “more capable” = add subagents, never thicken the orchestrator
AK-1
P-20
Subagent-as-tool with a hard context firewall
A subagent may burn a big context internally but returns only a distilled artifact + lineage; the orchestrator stays fast/cheap
AK-4, OR-3
P-21
Calibrated stop, not a hard budget
Stop on marginal-gain / confidence / coverage / soft-cost; max_loops is only a circuit-breaker; every level is bounded
AK-5
P-22
Control DO gate: ship vs escalate
Autonomy is a governed policy (manual/proposes/auto); low confidence or cultural-veto risk always escalates
AK-6, ARCHITECTURE §3
P-23
All prompts from Langfuse by name@label, versioned
No prompt strings in code; the resolved version is logged in the trace (reproducible); never auto-promote to production
AK-6, memory
P-24
Learn only from verified outcomes
Consolidation is offline and grades on real results — an agent never promotes its own ungraded output to a behaviour-changing lesson
AK-3, AP-6
P-25
Agent artifacts are Markdown (YAML frontmatter for machine fields)
Readable artifacts + clean PR diffs without losing machine-readability; config (manifest) + DB rows excepted
AK-7
P-26
One observability stream
Every Kernel/subagent yields structured events into agents/observability; localize labels in the BO, never bake English into the stream
AK-9, ARCHITECTURE §4
Data & security
#
Principle
Why
Source
P-27
Two-plane data classification
Public content plane (shareable, integrity/availability matter) vs the sensitive PII plane (profiles, phone, behaviour)
SEC-2, DIST DS-15
P-28
The PII plane is region-pinned, minimized, retention-bounded
On-device gave privacy for free; server-side we engineer it (DPDP/GDPR)
DIST DS-15
P-29
Least-privilege service bindings; every agent action is auditable
Each agent gets only the resources its manifest grants; append-only audit + run/step logs from day one
AK-8, SEC-4
How to use this doc
Reviewing a design or PR? Skim for a conflicting principle; cite the ID in the review.
Adding a principle? It must be durable and cross-cutting (recurs across ≥2 planes) and traceable
to a decision — otherwise it belongs in the relevant deep doc, not here.
Overriding one? Do it deliberately in the deep doc’s decisions log, then update the row here.