fix: address review — migration comment, link ring buffer constants (#170)

docs/PRODUCT-TRUTH.md

@@ -0,0 +1,109 @@
+# PRODUCT-TRUTH.md — What We Can and Cannot Claim
+
+This file is the source of truth for all product messaging, docs, and marketing.
+If a claim isn't here or contradicts what's here, it's wrong. Update this file
+when the protocol changes — not the marketing copy.
+
+**Last updated:** 2026-02-22
+**Updated by:** Johann + Clawy after user test review session
+
+---
+
+## Target Audience
+
+- **Crypto natives** who know DeFi but don't know KrAIken
+- NOT beginners. NOT "new to DeFi" users.
+- Think: people who've used Uniswap, understand liquidity, know what a floor price means
+
+## The Floor
+
+✅ **Can say:**
+- Every KRK token has a minimum redemption price backed by real ETH
+- The floor is enforced by immutable smart contracts
+- The floor is backed by actual ETH reserves, not promises
+- No rug pulls — liquidity is locked in contracts
+- "Programmatic guarantee" (borrowed from Baseline — accurate for us too)
+
+❌ **Cannot say:**
+- "The floor can never decrease" — **FALSE.** Selling withdraws ETH from reserves. The floor CAN decrease.
+- "Guaranteed profit" or "risk-free" — staking is leveraged exposure, it has real downside
+- "Floor always goes up" — only true if fee income exceeds sell pressure, which isn't guaranteed
+
+## The Optimizer
+
+✅ **Can say:**
+- Reads staker sentiment (% staked, average tax rate) to calculate parameters
+- Returns 4 parameters: capitalInefficiency, anchorShare, anchorWidth, discoveryDepth
+- Runs autonomously on-chain — no human triggers needed for parameter reads
+- Is a UUPS upgradeable proxy — can be upgraded to new versions
+- Currently admin-upgradeable (single admin key set at initialization)
+- Multiple versions exist: Optimizer, OptimizerV2, OptimizerV3, OptimizerV3Push3
+- "The optimizer evolves" — true in the sense that new versions get deployed
+
+❌ **Cannot say:**
+- "No admin keys" — **FALSE.** UUPS upgrade requires admin. Admin key exists.
+- "No proxy patterns" — **FALSE.** It IS a UUPS proxy.
+- "Stakers vote for new optimizers" — **NOT YET.** This is roadmap, not current state.
+- "Simply evolves" / "evolves without upgrades" — misleading. It's an explicit upgrade via proxy.
+- "Three strategies" — **FALSE.** It's ONE strategy with THREE positions (Floor, Anchor, Discovery).
+- "AI learns from the market" — overstated. The optimizer reads staking sentiment, not market data directly.
+
+🔮 **Roadmap (can say "planned" / "coming"):**
+- Staker governance for optimizer upgrades (vote with stake weight)
+- On-chain training data → new optimizer contracts via Push3 transpiler
+- Remove admin key in favor of staker voting
+
+## Liquidity Positions
+
+✅ **Can say:**
+- Three positions: Floor, Anchor, Discovery
+- Floor: deep liquidity at VWAP-adjusted prices (safety net)
+- Anchor: near current price, fast price discovery (1-100% width)
+- Discovery: borders anchor, captures fees (wide range, ~3x current price)
+- The optimizer adjusts position parameters based on sentiment
+- "Recenter" = atomic repositioning of all liquidity in one transaction
+- Anyone can trigger a recenter; the protocol bot does it automatically
+- Bull mode: wider discovery, aggressive fee capture. Bear mode: tight around floor.
+
+❌ **Cannot say:**
+- "Three trading strategies" — it's three positions in ONE strategy
+- "Token-owned liquidity" — ⚠️ USE CAREFULLY. KRK doesn't "own" anything in the legal/contract sense. The LiquidityManager manages positions. Acceptable as metaphor in marketing, not in technical docs.
+
+## Staking
+
+✅ **Can say:**
+- Staking = leveraged directional exposure
+- Stakers set tax rates; positions can be "snatched" by others willing to pay higher tax
+- Tax rates influence optimizer sentiment → bull/bear positioning
+- "Stakers profit when the community grows" (via supply expansion + leverage)
+- Staking is optional — most holders just hold
+
+❌ **Cannot say:**
+- "Start Earning" / "Earn yield" / "APY" — staking is NOT yield farming
+- "Guaranteed returns" — leveraged positions amplify losses too
+- "Passive income" — tax payments are a cost, not income
+
+## Supply Mechanics
+
+✅ **Can say:**
+- Elastic supply: buy = mint, sell = burn
+- Protocol controls minting exclusively through LiquidityManager
+- LiquidityManager address is set once on Kraiken contract and cannot be changed
+
+## Code / Open Source
+
+✅ **Can say:**
+- Smart contracts are verifiable on Basescan
+- Key contracts are viewable on the docs/code page
+- "Full source will be published at mainnet launch" (if that's the plan)
+
+❌ **Cannot say:**
+- "Open source" — the Codeberg repo is **private**. This is currently false.
+- "Audited" — unless an audit has been completed
+
+## General Rules
+
+1. When in doubt, understate. "The floor is backed by ETH" > "The floor guarantees you'll never lose money"
+2. Separate current state from roadmap. Always.
+3. Technical docs: be precise. Marketing: metaphors OK but never contradict technical reality.
+4. If you're not sure a claim is true, check this file. If it's not here, verify against contract source before writing it.