docs: layered information architecture (#140) (#163)

docs/README.md

@@ -0,0 +1,28 @@
+# KrAIken (Harb)
+
+**A token system where your tokens earn for you — backed by real ETH, governed by transparent on-chain rules.**
+
+## What is it?
+
+KRK is a token on Base (Ethereum L2). When you hold KRK tokens, they're backed by ETH in a trading vault — there's a built-in minimum value your tokens can't drop below.
+
+You can **stake** your tokens to earn a share of every trade. The longer you stake, the more you accumulate. But there's a twist: someone else can **challenge** your position by committing to a higher earning rate. If that happens, you get compensated at market value — you never lose money, you just get bought out.
+
+The system adjusts itself automatically based on how people are staking. No manual intervention, no hidden operators. Everything is on-chain and verifiable.
+
+## Quick Links
+
+- [How It Works](./how-it-works.md) — The mechanics explained simply
+- [Getting Started](./getting-started.md) — Buy, stake, earn in 5 minutes
+- [Technical Deep Dive](./technical/) — Architecture, contracts, development
+
+## Key Numbers
+
+- **20,000 staking positions** available (20% of total supply)
+- **30 earning rate tiers** from 1% to 97% yearly
+- **3-day minimum hold** before a position can be challenged
+- **ETH-backed floor price** — your tokens always have a minimum value
+
+## Is it safe?
+
+The contracts are **not yet audited**. The code is [open source](https://codeberg.org/johba/harb) and deployed on Base. Use at your own risk, and never invest more than you can afford to lose.

docs/getting-started.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+## What You Need
+
+1. A Web3 wallet (MetaMask, Coinbase Wallet, etc.)
+2. Some ETH on **Base** network
+3. 5 minutes
+
+## Step 1: Get KRK Tokens
+
+1. Go to the [KrAIken app](/app/get-krk)
+2. Connect your wallet
+3. Swap ETH for KRK on Uniswap
+   - Make sure you're on **Base** network
+   - Use the 1% fee tier pool
+
+**Tip:** Start small. The protocol is unaudited — only use what you're comfortable risking.
+
+## Step 2: Stake Your Tokens
+
+1. Go to the [Staking Dashboard](/app/stake)
+2. Connect your wallet (if not already connected)
+3. Choose how many KRK tokens to stake
+   - Minimum stake is displayed in the form
+4. Pick your earning rate (tax rate)
+   - Lower = cheaper to hold, but easier to challenge
+   - Higher = more expensive, but harder to challenge
+   - Start with a mid-range rate if you're unsure
+5. Click **Stake** and confirm the transaction
+
+## Step 3: Monitor Your Position
+
+Once staked, you'll see your position in the **Active Positions** section:
+- Your slot count and ownership percentage
+- Current earning rate
+- Accrued tax obligation
+
+You can view detailed stats in your [Wallet Dashboard](/app/wallet/).
+
+## Understanding the Numbers
+
+- **Owner Slots**: Your share of the staking pool. 1,000 slots = 1% ownership.
+- **Tax Rate**: What you pay yearly to hold your position. Paid when you unstake or manually.
+- **Floor Tax**: The minimum rate needed to challenge existing positions.
+- **Positions Buyout**: How many positions your rate would displace.
+
+## Unstaking
+
+To exit a position:
+1. Find your position in the Active Positions list
+2. Click to expand it
+3. Choose to unstake (partially or fully)
+4. You receive your staked tokens plus any earnings, minus tax owed
+
+## Tips
+
+- **Check the floor tax** before staking. If it's high, many positions are actively defended.
+- **Watch the ETH reserve** on the landing page — growing reserve = healthy protocol.
+- **Don't panic if challenged** — you get paid out at market value. You can always re-stake.
+- **Join the community** — [Telegram](https://t.me/kraikenportal) for questions and discussion.

docs/how-it-works.md

@@ -0,0 +1,62 @@
+# How It Works
+
+## The Basics
+
+KRK tokens trade on Uniswap (Base network). Behind the scenes, a **trading vault** holds ETH that backs every KRK token. This creates a **floor price** — the absolute minimum value your tokens are worth.
+
+## Earning by Staking
+
+When you stake KRK tokens, you claim **owner slots** — a percentage of the protocol's staking pool. Every time someone buys KRK on the open market, new tokens are minted, and stakers get a proportional share. The more slots you hold, the more you earn.
+
+### Choosing Your Rate
+
+When you stake, you pick an **earning rate** (called a "tax rate" in the contracts). This is the yearly cost of holding your position:
+
+| Rate Level | Yearly Cost | Trade-off |
+|-----------|------------|-----------|
+| Low (1-5%) | Cheap to hold | Easy for others to challenge |
+| Medium (12-30%) | Moderate cost | Balanced protection |
+| High (50%+) | Expensive to hold | Very hard to challenge |
+
+**The key insight:** Your earning rate is also your protection level. A higher rate costs more, but makes it harder for anyone to take your position.
+
+## Challenges (Snatching)
+
+If someone wants your staking slots and is willing to pay a higher rate than you, they can **challenge** (snatch) your position:
+
+1. The challenger stakes at a higher rate
+2. Your position is automatically closed
+3. You receive the **full market value** of your staked tokens — including any earnings
+4. The challenger takes over your slots
+
+**You never lose money in a challenge.** You get compensated at current market value. You just stop earning from those slots.
+
+## The Trading Vault
+
+The Liquidity Manager automatically manages the ETH/KRK trading pool:
+
+- When staking activity is high (bullish signal), it concentrates liquidity for better trading
+- When activity drops, it spreads liquidity wider for stability
+- It tracks a **volume-weighted average price (VWAP)** to set the range
+
+This happens automatically — no human decisions, no hidden operators. The rules are in the smart contract.
+
+## Floor Price
+
+Every KRK token is backed by ETH in the vault. The **floor price** is calculated as:
+
+```
+floor = ETH in vault ÷ total KRK supply
+```
+
+Your tokens can never be worth less than the floor. When someone buys KRK, more ETH enters the vault. When someone sells, ETH leaves. The system maintains balance.
+
+## Summary
+
+1. **Buy KRK** on Uniswap (Base)
+2. **Stake** to earn from every trade
+3. **Choose your rate** — higher = more protection, higher cost
+4. **Earn passively** as the protocol generates trading activity
+5. If challenged, you get **paid out at market value**
+
+→ [Getting Started Guide](./getting-started.md)

docs/technical/architecture.md

@@ -0,0 +1,90 @@
+# Technical Architecture
+
+## System Overview
+
+KrAIken consists of three on-chain contracts, a real-time indexer, and two web frontends.
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────────────┐
+│   Kraiken    │────▶│    Stake     │     │  LiquidityManager    │
+│   (ERC20)    │     │  (Staking)   │     │  (Pool Management)   │
+└──────────────┘     └──────────────┘     └──────────────────────┘
+       │                    │                        │
+       └────────────────────┼────────────────────────┘
+                            │
+                    ┌───────▼────────┐
+                    │  Ponder Indexer │
+                    │  (GraphQL API)  │
+                    └───────┬────────┘
+                            │
+              ┌─────────────┼─────────────┐
+              │                           │
+      ┌───────▼────────┐         ┌───────▼────────┐
+      │  Landing Page  │         │   Staking App  │
+      │  (Vue 3/Vite)  │         │  (Vue 3/Vite)  │
+      └────────────────┘         └────────────────┘
+```
+
+## Smart Contracts
+
+### Kraiken.sol (ERC20 Token)
+- Standard ERC20 with controlled minting by LiquidityManager
+- 20% of supply reserved for staking pool
+- Min stake fraction: 1/3000 of total supply (~399 KRK at current supply)
+- Tracks `previousTotalSupply` for staking calculations
+- Version field for indexer compatibility
+
+### Stake.sol (Staking Positions)
+- Creates/manages staking positions with self-assessed tax rates
+- 30 discrete tax rate tiers: 1%, 3%, 5%, 8%, 12%, ... up to 97%
+- Snatching: higher tax rate can displace lower positions
+- 3-day minimum hold (`TAX_FLOOR_DURATION`) before snatch
+- Position payout at market value when snatched or unstaked
+
+### LiquidityManager.sol (Pool Management)
+- Manages Uniswap V3 concentrated liquidity position
+- Recenters liquidity based on VWAP and market conditions
+- Emits `EthAbundance`, `EthScarcity`, `Recentered` events
+- Optimizer V3: reads staking sentiment to adjust parameters
+
+## Indexer (Ponder)
+
+[Ponder](https://ponder.sh) indexes on-chain events into PostgreSQL via GraphQL:
+
+- **Stats**: Protocol-wide metrics (supply, reserves, fees)
+- **Positions**: Individual staking positions with status
+- **Holders**: Token balances with cost basis tracking
+- **Recenters**: Liquidity management history
+- **Ring Buffer**: 7-day hourly snapshots of ETH reserve, mints, burns, tax
+
+### Key Endpoints
+- GraphQL: `http://localhost:42069` (proxied at `/api/graphql`)
+- Health: `http://localhost:42069/health`
+- Ready: `http://localhost:42069/ready` (200 when historical sync complete)
+
+## Web Frontends
+
+### Landing Page (`/`)
+- Marketing + protocol health dashboard
+- LiveStats component with real-time metrics
+- Wallet connect + holder card for returning users
+- Three variants: defensive, offensive, mixed
+
+### Staking App (`/app/`)
+- Full staking dashboard
+- Position management (stake, unstake, adjust tax)
+- Wallet P&L with cost basis tracking
+- Charts and protocol statistics
+
+### Shared Package (`packages/web3/`)
+- `createHarbConfig()` — wagmi config with Base chain + connectors
+- `useTokenBalance` composable
+- Re-exports of wagmi composables for consistent imports
+
+## Infrastructure
+
+- **Chain**: Base (Ethereum L2), chainId 8453
+- **Local dev**: Anvil fork of Base Sepolia (chainId 31337)
+- **Proxy**: Caddy reverse proxy on port 8081
+- **CI**: Woodpecker CI with pre-built Docker images
+- **Source**: [codeberg.org/johba/harb](https://codeberg.org/johba/harb)

docs/technical/staking-mechanics.md

@@ -0,0 +1,83 @@
+# Staking Mechanics
+
+## Tax Rates
+
+Staking uses a **self-assessed tax** mechanism (Harberger Tax). You choose what yearly rate you're willing to pay. This creates a continuous auction for staking slots.
+
+### Rate Tiers
+
+There are 30 discrete tax rates (percentages are yearly):
+
+```
+1%, 3%, 5%, 8%, 12%, 18%, 24%, 30%, 40%, 50%,
+60%, 80%, 100%, 130%, 180%, 250%, 320%, 420%, 540%, 700%,
+920%, 1200%, 1600%, 2000%, 2600%, 3400%, 4400%, 5700%, 7500%, 9700%
+```
+
+Rates are discrete (not continuous) to prevent micro-increment griefing.
+
+### Tax Calculation
+
+Tax accrues continuously from the moment you stake:
+
+```
+tax_owed = (staked_amount × tax_rate × time_held) / (365 days × 100)
+```
+
+Tax is paid when you:
+- Unstake (deducted from payout)
+- Get snatched (deducted from compensation)
+- Manually pay via the dashboard
+
+## Snatching (Position Challenges)
+
+Anyone can take your staking slots by committing to a higher tax rate.
+
+### Rules
+1. **Higher rate required**: The challenger must use a strictly higher tax rate tier
+2. **3-day minimum hold**: Positions are protected for 72 hours after creation
+3. **Full compensation**: The snatched owner receives market value of their position minus accrued tax
+4. **Discrete tiers only**: You can't snatch by increasing the rate by 0.01% — you must jump to the next tier
+
+### What the snatched owner receives
+
+```
+payout = (shares / total_shares) × current_total_supply - tax_owed
+```
+
+The payout reflects the current token price, not the entry price. If the protocol grew, you get more back than you put in.
+
+## Staking Pool
+
+The staking pool holds 20% of all KRK supply. When new tokens are minted (from buys), stakers receive a proportional share. When tokens are burned (from sells), the pool shrinks proportionally.
+
+### Owner Slots
+
+- Total: 20,000 slots (representing 20% of supply)
+- Your slots = your percentage × 20,000
+- 1,000 slots = 1% of the staking pool
+
+### Minimum Stake
+
+To prevent fragmentation, there's a minimum stake:
+
+```
+min_stake = total_supply / 3000
+```
+
+At ~1.2M total supply, this is approximately 399 KRK.
+
+## Adjusting Your Rate
+
+You can change your tax rate on an existing position:
+- **Increasing**: Takes effect immediately, extends snatch protection
+- **Decreasing**: Takes effect after a delay to prevent gaming
+
+## Strategy Guide
+
+| Goal | Recommended Rate | Why |
+|------|-----------------|-----|
+| Long-term earning | Low (1-8%) | Cheap to hold, accept challenge risk |
+| Defensive holding | Medium (18-40%) | Balance of cost and protection |
+| Aggressive accumulation | High (60%+) | Hard to challenge, but expensive |
+| Short-term flip | Lowest available | Minimize holding cost |

docs/technical/tokenomics.md

@@ -0,0 +1,60 @@
+# Tokenomics
+
+## KRK Token
+
+- **Standard**: ERC20 on Base (Ethereum L2)
+- **Supply**: Dynamic (minted on buys, burned on sells)
+- **Backing**: Every KRK token is backed by ETH in the trading vault
+
+## ETH Reserve & Floor Price
+
+The protocol maintains an ETH reserve in a Uniswap V3 concentrated liquidity position. This creates a floor price:
+
+```
+floor_price = ETH_reserve / total_KRK_supply
+```
+
+**Key property**: The floor price can only go up (in ETH terms) because:
+- Buys add ETH to the reserve and mint KRK at market price (above floor)
+- Sells remove KRK from supply and return ETH at market price
+- Trading fees from the pool add to the reserve without minting new tokens
+
+## Supply Mechanics
+
+### Minting (on buy)
+When someone buys KRK on Uniswap:
+1. ETH enters the pool
+2. KRK is minted at market price
+3. 20% of new tokens go to the staking pool (for stakers)
+4. 80% goes to the buyer
+
+### Burning (on sell)
+When someone sells KRK:
+1. KRK is burned
+2. ETH leaves the pool at market price
+3. The staking pool burns proportionally
+
+## Liquidity Management
+
+The LiquidityManager positions liquidity in a concentrated range around the current price:
+
+### Modes
+- **Scarcity** (bearish signal): Wide range, conservative positioning
+- **Abundance** (bullish signal): Narrow range, aggressive fee capture
+
+### Signals
+The optimizer reads staking activity as a sentiment indicator:
+- High staking ratio + low tax rates = genuine confidence → Bull mode
+- Dropping staking or rising tax rates = uncertainty → Bear mode
+
+### VWAP Tracking
+The system tracks a volume-weighted average price (VWAP) to set liquidity ranges. This creates a "mirror floor" — a second price support level based on recent trading history.
+
+## Fee Generation
+
+Trading activity generates fees from the Uniswap V3 position. These fees accrue to the ETH reserve, increasing the floor price for all holders.
+
+The fee rate depends on:
+- Trading volume
+- Liquidity concentration (narrower range = more fees per trade)
+- Pool fee tier (1% on the KRK/WETH pair)