From 9d0127adf52abb97c21d6c5a6d8d21925fc309c9 Mon Sep 17 00:00:00 2001
From: zzstoatzz <thrast36@gmail.com>
Date: Tue, 14 Jul 2026 01:07:57 -0500
Subject: [PATCH] document public copy context

---
 README.md                    |  5 ++-
 docs/product-copy-context.md | 59 ++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/product-copy-context.md

diff --git a/README.md b/README.md
index 3842f86..1a69902 100644
--- a/README.md
+++ b/README.md
@@ -54,4 +54,7 @@ queue depth, current transient bytes, and peak transient bytes are exported on
 
 ## docs
 
-`docs/` holds the port record — jss format byte spec, seal spec, upstream bootstrap/compaction/subscribe condensations (every deliberate divergence is written down there), and lessons carried over from zlay.
+The docs folder holds the port record — jss format byte spec, seal spec,
+upstream bootstrap/compaction/subscribe condensations (every deliberate
+divergence is written down there), lessons carried over from zlay, and durable
+product/copy context for public surfaces.
diff --git a/docs/product-copy-context.md b/docs/product-copy-context.md
new file mode 100644
index 0000000..911e625
--- /dev/null
+++ b/docs/product-copy-context.md
@@ -0,0 +1,59 @@
+# Product and copy context
+
+This file preserves ecosystem facts and language decisions that should survive
+individual implementation sessions. It is input to public copy, not a license
+to turn an inference into a product claim.
+
+## Bobbin, Hydrant, and Jetstream V2
+
+The [Bobbin announcement](https://blog.tangled.org/bobbin/) describes Bobbin as
+a read-only, API-only Tangled AppView with no permanent local storage. Its
+in-memory view is rebuilt from an upstream source on restart.
+
+Public follow-up context supplied on 14 July 2026 adds two important details:
+
+- Paul Frazee recommended the upcoming Jetstream V2 backfill for this class of
+  restart hydration.
+- Lewis says Bobbin hydrates from its Hydrant twin. Under normal operation,
+  this does not repeatedly request repository CARs from origin PDSes. Origin
+  network load is reserved for exceptional Hydrant recovery, such as corrupted
+  storage or an intentional wipe.
+
+Treat those bullets as attributed public statements until the corresponding
+architecture or API contract is available in source. The useful architectural
+shape is:
+
+    origin PDS network -> durable Hydrant/Jetstream archive -> ephemeral Bobbin view
+
+The distinction matters. “Rebuilt from upstream every restart” does not imply
+“fan out to every PDS every restart.” A durable, colocated or nearby archive can
+make ephemeral consumers cheap without making the network absorb the rebuild.
+
+## Claims the public pages may make
+
+- Say **historical bootstrap** only when it is configured and actually running.
+- Distinguish a live-only canary from a whole-network historical archive.
+- While filling, say that completion is not yet proven and subscriptions remain
+  gated. Do not describe the experiment as a completed full-network archive.
+- A sequence number is the upstream network position. Prefer “following the
+  network at sequence …” over shorthand such as “waves are seq …”.
+- The moving waves are ambient animation, not evidence that the document
+  refreshes itself. Do not tell readers to refresh unless the page actually
+  auto-refreshes or offers a meaningful refresh action.
+- Dated compatibility and load-test results are audit receipts, not timeless
+  statements about the currently running build.
+- Runtime facts belong on /status; the / page should remain legible, welcoming,
+  and honest about whether it is filling or serving.
+
+## Presentation guardrails
+
+- Give the quote, attribution, runtime note, endpoint inventory, and footer
+  distinct vertical space.
+- Endpoint methods begin in one left-aligned column. Paths begin in a second
+  left-aligned column; do not right-align GET against POST.
+- Browser copy must remain usable on a phone. Horizontal scrolling is acceptable
+  for the ASCII river, but the document should start at the left edge on narrow
+  screens rather than centering an overflowing block off-screen.
+- Prefer ordinary language over implementation jokes. A clever detail earns its
+  place only when a visitor can understand it without knowing Stream internals.
+
-- 
2.54.0