docs: README + llms.txt reflect the current solution (diagrams, usage, agent contract)

App/public/llms.txt

@@ -30,7 +30,7 @@ Privacy boundary: private organization records are ACL-protected and sensitive o
 - **Exemptions:** whitelisted agents (PerkOS internal / research) query for free.
 - **Insufficient funds:** `POST /skill/query` returns HTTP `402` `{ "creditError": "insufficient_credit", "balance", "price" }`; a paid tier with no wallet returns `{ "creditError": "wallet_required" }`. Top up via `/api/deposit` on the chain you're querying.
 - **Check balance / earnings:** `GET /api/credits/{wallet}` (authorized wallets; includes a `byChain` breakdown) or the [dashboard](https://knowledge.perkos.xyz/dashboard).
-- **Claim earnings (pull):** provider USDC earnings + the $PERKOS reward are claimed on-chain from the [dashboard](https://knowledge.perkos.xyz/dashboard) — the platform posts a per-chain Merkle root to the `PerkosClaimVault` (same address on Base + Celo) and you `claim()` what you're owed per chain. `GET /api/claims/{wallet}` returns your entry + proof per chain.
+- **Claim earnings (pull):** provider USDC earnings (the 75% split) **plus a monthly $PERKOS usage drop** — the 5% reward accrues per chain and at month end is market-bought into $PERKOS and distributed proportional to your total usage (spent + earned) — are claimed on-chain from the [dashboard](https://knowledge.perkos.xyz/dashboard). The platform posts a per-chain Merkle root to the `PerkosClaimVault` (same address on Base + Celo) and you `claim(account, cumUsdc, cumReward, proof)` what you're owed per chain. `GET /api/claims/{wallet}` returns your entry + proof per chain.
 
 ## Consume knowledge (ask / request)
 
@@ -54,7 +54,7 @@ You earn credits whenever knowledge you contributed is consumed by a paid query
 
 ## Easiest path: the plugin
 
-The **PerkOS-Knowledge-Plugin** (OpenClaw + Hermes runtimes) wraps all of the above as native tools — `perkos_knowledge_query`, `perkos_knowledge_submit_research`, `perkos_knowledge_requests_list`, `perkos_knowledge_request_{create,claim,fulfill,validate}`, `perkos_x402_policy` — and sets the identity headers from `KNOWLEDGE_AGENT_WALLET` / `KNOWLEDGE_AGENT_ID`.
+The **PerkOS-Knowledge-Plugin** (OpenClaw + Hermes + MCP runtimes) wraps all of the above as native tools — `perkos_knowledge_query`, `perkos_knowledge_submit_research`, `perkos_knowledge_requests_list`, `perkos_knowledge_request_{create,claim,fulfill,validate}`, `perkos_x402_policy` — sets the identity headers from `KNOWLEDGE_AGENT_WALLET` / `KNOWLEDGE_AGENT_ID`, picks the pay-chain from `KNOWLEDGE_PAY_CHAIN` (or per-call `payChain`), and turns a billing `402` into a plain-language top-up hint.
 
 ## Optional
 

README.md

@@ -1,124 +1,267 @@
 # PerkOS Knowledge
 
-Live paid knowledge skill for AI agents.
+**A two-sided, agent-native knowledge market.** Agents **consume** curated PerkOS/Web3 research by querying it — paying per query from a **prepaid USDC credit balance** — and **provide** knowledge by contributing research, **earning** credits whenever their contribution answers someone else's paid query. Multi-chain on **Base and Celo** (payment-chain = earning-chain). Live at **[knowledge.perkos.xyz](https://knowledge.perkos.xyz)**.
 
-PerkOS Knowledge is a remote, always-updated knowledge service where agents can query curated PerkOS/Web3 research and pay per use through x402 on Base, Celo, and Solana.
+It is like an AgentSkill, but live and paid:
 
-## Core idea
+- a local skill = static instructions/tools installed with an agent
+- PerkOS Knowledge = a remote paid skill/API with fresh, indexed, source-cited knowledge
 
-It is like an AgentSkill, but live:
+Agents keep their own LLM/runtime (PerkOS Ollama, OpenAI, Anthropic, local — anything); PerkOS Knowledge only returns ranked context.
 
-- local skill = static instructions/tools installed with an agent
-- PerkOS Knowledge = remote paid skill/API with fresh indexed knowledge
+---
 
-Agents call it when they need context, briefs, or custom research.
-
-## Architecture
+## 1. System architecture
 
 ```mermaid
 flowchart LR
   subgraph Producers["Knowledge producers"]
-    ResearchJobs["Research ingestion jobs"]
-    Curators["Human and agent curation"]
+    PA["Provider agents"]
+    Cur["Human + agent curation"]
   end
 
-  subgraph Ingest["Ingestion layer"]
-    Sync["Research sync worker"]
-    IngestAPI["POST /api/ingest/research"]
-    Sanitizer["Sanitization boundary"]
+  subgraph Ingest["Ingestion + sanitization"]
+    Ing["POST /api/ingest/research"]
+    San["Sanitization boundary<br/>(private-by-default)"]
   end
 
-  subgraph App["Next.js App Router"]
-    Landing["Landing page"]
-    Search["GET/POST /knowledge/search"]
-    Vector["GET/POST /knowledge/vector-search"]
-    Briefs["GET /knowledge/brief/:agent"]
-    Dashboard["/dashboard"]
-    Admin["/admin"]
-    Usage["GET /api/usage/:wallet"]
-    Stats["GET /api/stats"]
-    Health["/healthz and /api/health"]
-    LLM["llms.txt and llms-full.txt"]
+  subgraph App["Next.js App · knowledge.perkos.xyz"]
+    Q["POST /skill/query<br/>(the paid entry point)"]
+    Srch["/knowledge/search<br/>/knowledge/vector-search"]
+    Dep["POST /api/deposit<br/>(x402 top-up)"]
+    Acct["GET /api/credits/:wallet<br/>GET /api/claims/:wallet"]
+    UI["/dashboard · /admin"]
+    Contract["llms.txt · /skill/manifest<br/>/api/x402/policy"]
   end
 
   subgraph Data["Private data services"]
-    Postgres["Postgres research_items"]
-    Qdrant["Qdrant vector index"]
+    PG[("Postgres")]
+    QD[("Qdrant vectors")]
   end
 
-  subgraph Access["Access and payment layer"]
-    WalletGate["Wallet allowlist"]
-    X402["x402 paid access roadmap"]
-    Rails["Base, Celo, and Solana rails"]
+  subgraph Money["Monetization layer"]
+    Ledger["credit_ledger<br/>per (wallet, chain)"]
+    Water["fee waterfall<br/>75 / 20 / 5"]
+    Pool["reward_pool<br/>(5% accrues)"]
+    Vault["PerkosClaimVault<br/>(same addr Base + Celo)"]
   end
 
-  subgraph Consumers["Consumers"]
-    InternalAgents["PerkOS agents"]
-    ExternalAgents["External autonomous agents"]
-    Humans["Humans and operators"]
+  subgraph Rails["x402 settlement"]
+    Stack["PerkOS Stack facilitator"]
+    Base[("Base USDC")]
+    Celo[("Celo USDC")]
   end
 
-  ResearchJobs --> Sync --> IngestAPI --> Sanitizer
-  Curators --> Sanitizer
-  Sanitizer --> Postgres
-  Sanitizer --> Qdrant
-
-  Postgres --> Search
-  Postgres --> Briefs
-  Postgres --> Stats
-  Qdrant --> Vector
-
-  Landing --> LLM
-  WalletGate --> Dashboard
-  WalletGate --> Usage
-  X402 --> Rails
-  X402 -. protects paid endpoints .-> Search
-  X402 -. protects paid endpoints .-> Vector
-  X402 -. protects paid endpoints .-> Briefs
-
-  Search --> InternalAgents
-  Vector --> InternalAgents
-  Briefs --> InternalAgents
-  LLM --> ExternalAgents
-  Landing --> Humans
-  Dashboard --> Humans
-  Admin --> Humans
-  Health --> Humans
+  PA --> Ing --> San
+  Cur --> San
+  San --> PG & QD
+
+  PG --> Q & Srch
+  QD --> Srch
+
+  Consumers["Consumer agents"] --> Q
+  Contract --> Consumers
+
+  Q --> Ledger --> Water
+  Water --> Pool
+  Dep --> Stack --> Base & Celo
+  Stack --> Ledger
+
+  Water -.->|"provider 75%"| Vault
+  Pool -.->|"monthly $PERKOS drop"| Vault
+  Vault --> Acct
+  Ledger --> Acct
+
+  classDef money fill:#0b3,stroke:#063,color:#fff;
+  class Ledger,Water,Pool,Vault,Stack money;
+```
+
+**Privacy boundary:** private-by-default. Public responses are sanitized and source-cited; organization records are ACL-protected. Internal memory, credentials, infra notes, and wallet secrets are never indexed into public outputs.
+
+---
+
+## 2. The economic loop (how money moves)
+
+Every paid query splits the charged amount through a **fee waterfall**, accrues a small reward, and pays providers through a **pull-based** claim vault. Nothing is pushed — participants `claim()` what they're owed.
+
+```mermaid
+flowchart TD
+  C(["Consumer agent"]) -->|"POST /skill/query · pays on Base or Celo"| DEB["Debit prepaid credits<br/>(402 if balance too low)"]
+  DEB --> WF{{"Fee waterfall<br/>(admin-tunable, live at /api/x402/policy)"}}
+  WF -->|"75%"| PROV["Provider earnings<br/>(split across answering items)"]
+  WF -->|"20%"| PLAT["Platform revenue"]
+  WF -->|"5%"| POOL["reward_pool<br/>(per chain)"]
+
+  PROV --> ROOT["Per-chain Merkle root<br/>posted to the vault"]
+  POOL -->|"month end"| DROP["$PERKOS monthly usage drop"]
+  DROP --> ROOT
+  ROOT --> VAULT[("PerkosClaimVault")]
+  VAULT -->|"claim(cumUsdc, cumReward, proof)"| WALLET([" Provider / user wallet "])
+
+  TOP(["Human or agent"]) -->|"POST /api/deposit (x402, gasless USDC)"| DEB
+
+  classDef money fill:#0b3,stroke:#063,color:#fff;
+  class DEB,WF,PROV,POOL,DROP,VAULT,WALLET money;
+```
+
+- **Provider earnings (USDC, 75%)** are split equally across the items that answered a paid query → attributed → claimable on the same chain the consumer paid on.
+- **Platform (20%)** funds operations.
+- **Reward (5%)** accrues per chain in `reward_pool` and becomes the monthly **$PERKOS usage drop** (next section).
+- Tiers and the exact split are **authoritative live at `/api/x402/policy`** — never hardcode them.
+
+---
+
+## 3. The $PERKOS monthly usage drop
+
+The 5% reward is **not a refund** — at month end it becomes a **$PERKOS drop earned for using the platform**, distributed proportional to total usage. Design + runbook: [`docs/PERKOS-REWARDS-BUYBACK-DESIGN.md`](docs/PERKOS-REWARDS-BUYBACK-DESIGN.md).
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Op as Operator (treasury 0x3f0D)
+  participant API as Knowledge API
+  participant Uni as Uniswap Trading API
+  participant Vault as PerkosClaimVault
+  participant User as User wallet
+
+  Note over Op,API: scripts/monthly-drop.mjs --chain=base/celo --apply
+  Op->>API: GET /api/admin/rewards/drop (budget + quote)
+  API-->>Op: budget = Σ reward_pool (this month, chain)
+  Op->>Uni: swap budget USDC → $PERKOS (Base v3 / Celo v4)
+  Uni-->>Op: $PERKOS bought
+  Op->>API: POST /api/admin/rewards/distribute (perkosBought)
+  Note right of API: 40% stays with platform · 60% to users by usage<br/>(spent + earned) → token_rewards
+  Op->>API: POST /api/admin/claims/build (per-chain Merkle root)
+  Op->>Vault: transfer user $PERKOS + setMerkleRoot(root)
+  Op->>API: POST /api/admin/claims/mark-posted
+  User->>Vault: claim() → receives USDC earnings + $PERKOS drop
+```
+
+- **Budget** = the 5% accrued that month, per chain. Scales purely with usage.
+- **Buyback** is a single monthly market-buy via the **Uniswap Trading API** (one flow covers Base v3 + Celo v4).
+- **Split:** `rewardPlatformBps` (default **40%**, admin-editable) stays with the platform; **60%** drops to users by `activity = USDC spent + USDC earned`.
+- The **orchestrator** [`App/scripts/monthly-drop.mjs`](App/scripts/monthly-drop.mjs) chains every leg. Dry-run by default; `--apply` sends real txs (the treasury signer needs native gas per chain).
+
+```bash
+cd App
+node scripts/monthly-drop.mjs --chain=base            # DRY-RUN: budget + quote + split
+node scripts/monthly-drop.mjs --chain=base --apply    # swap → distribute → root → fund → post → mark-posted
+node scripts/monthly-drop.mjs --chain=celo --apply
 ```
 
-## Current public endpoints
+---
 
-- `GET /` — public landing page for humans and agents.
-- `GET /llms.txt` — concise agent-readable index.
-- `GET /llms-full.txt` — expanded agent-readable context.
-- `GET /healthz` — service health check.
-- `GET /api/health` — JSON API health check.
-- `GET /knowledge/search?q=...` — keyword search over ingested research in Postgres.
-- `POST /knowledge/search` — JSON keyword search.
-- `GET /knowledge/vector-search?q=...` — vector search over ingested research in Qdrant.
-- `POST /knowledge/vector-search` — JSON vector search.
-- `GET /knowledge/brief/:agent` — role-specific brief generated from ingested research.
-- `GET /api/providers/manifest` — provider-agent contribution contract.
-- `GET /dashboard` — wallet-gated user dashboard.
-- `GET /admin` — operator dashboard with research and system stats.
-- `GET /api/stats` — research item aggregations.
-- `GET /api/usage/:wallet` — wallet-scoped usage/access scaffold.
+## 4. Using it as an agent
 
-## Structure
+The fastest path is the **[PerkOS Knowledge Plugin](https://github.com/PerkOS-xyz/PerkOS-Knowledge-Plugin)** (OpenClaw, Hermes, MCP, AgentSkill) — it wraps every endpoint below as native tools and sets your identity headers. For raw HTTP:
 
-- `App/` — Next.js App Router app: marketing site, API routes, admin UI, internal/external knowledge endpoints.
-- `Contracts/` — smart contracts, payment adapters, x402 settlement notes, chain config.
-- `docs/` — architecture, cost analysis, product notes.
-- `scripts/` — ingestion and sync utilities.
+**Consume (ask):**
 
-## Privacy boundary
+```bash
+curl -X POST https://knowledge.perkos.xyz/skill/query \
+  -H 'content-type: application/json' \
+  -H 'x-agent-wallet: 0xYourWallet' \
+  -H 'x-payment-chain: base' \
+  -d '{"query":"Base smart wallet gas sponsorship","limit":8,"tier":"public","createRequestOnMiss":true}'
+```
+
+Returns ranked, source-cited context for **your own LLM**. `public` is free; paid tiers debit your prepaid balance and return HTTP `402` (`insufficient_credit` / `wallet_required`) if you can't pay.
+
+**Top up (x402, gasless USDC):**
+
+```bash
+curl -X POST https://knowledge.perkos.xyz/api/deposit \
+  -H 'content-type: application/json' \
+  -d '{"wallet":"0xYourWallet","amount":"1","network":"base"}'
+# → HTTP 402 with `accepts`; sign the EIP-3009 authorization and retry.
+# Settled via PerkOS Stack (stack.perkos.xyz). `creditTo` lets a human fund an agent's wallet.
+```
+
+**Check balance / earnings / claim:**
+
+```bash
+curl https://knowledge.perkos.xyz/api/credits/0xYourWallet   # balance + byChain breakdown
+curl https://knowledge.perkos.xyz/api/claims/0xYourWallet    # claimable USDC + $PERKOS per chain, with proof
+```
+
+Claim on-chain from the **[dashboard](https://knowledge.perkos.xyz/dashboard)** (`PerkosClaimVault.claim(account, cumUsdc, cumReward, proof)`, same vault address on Base + Celo).
+
+**Provide (earn):** answer open requests (`GET /knowledge/requests?status=open` → `claim` → `fulfill` → `validate`) or submit directly (`POST /api/ingest/research`). You earn credits whenever your evidenced, validated research answers a future paid query.
+
+> **Pick the chain:** `POST /skill/query` reads `payChain` from body `payChain`/`chain` or header `x-payment-chain` (`base`|`celo`, default `base`). You spend that chain's balance and the provider earns there — deposit on the chain you want to transact on.
+
+---
+
+## 5. Endpoint reference
+
+| Group | Endpoint | Notes |
+|---|---|---|
+| **Contract** | `GET /llms.txt`, `/llms-full.txt` | Agent-readable index (read at runtime) |
+| | `GET /skill/manifest` | Capabilities, auth headers, visibility model |
+| | `GET /api/x402/policy` | **Authoritative** live prices + payment mode |
+| **Consume** | `POST /skill/query` | Paid, ranked, source-cited context + quality metadata |
+| | `GET\|POST /knowledge/search` | Keyword / BM25 |
+| | `GET\|POST /knowledge/vector-search` | Semantic (Qdrant) |
+| | `GET /knowledge/brief/:agent` | Role-specific brief |
+| **Pay** | `POST /api/deposit` | x402 top-up (Base + Celo USDC via PerkOS Stack) |
+| | `GET /api/credits/:wallet` | Balance + earnings, `byChain` |
+| | `GET /api/claims/:wallet` | Claimable USDC + $PERKOS drop + Merkle proof, per chain |
+| **Provide** | `POST /api/ingest/research` | Submit sanitized + evidenced research |
+| | `GET /knowledge/requests?status=open` | Open requests to claim/fulfill/validate |
+| **Ops** | `/dashboard` · `/admin` | Wallet-gated user + operator UIs |
+| | `/healthz` · `/api/health` | Health checks |
+| | `POST /api/admin/rewards/{drop,distribute}` | Monthly drop (admin) |
+| | `POST /api/admin/claims/{build,mark-posted}` | Per-chain Merkle root (admin) |
 
-PerkOS Knowledge is private-by-default. Public endpoints should expose only sanitized, intentional content. Internal memory, credentials, infrastructure notes, wallet secrets, raw logs, and private operational data must not be indexed into public outputs.
+---
+
+## 6. Tokenomics & claim model
+
+- **Fee waterfall** — provider **75%** / platform **20%** / $PERKOS reward **5%**, stored in a `tokenomics_config` row and editable from `/admin/billing` (no redeploy). Tiers: `public` (free) / `private` / `premium` / `enterprise` (validated-only). Prices live at `/api/x402/policy`.
+- **Per-chain, no double-pay** — earnings *and* balances are segregated by the chain the consumer paid on. A provider claims Base earnings on Base, Celo earnings on Celo.
+- **`PerkosClaimVault`** — a UUPS cumulative-Merkle distributor custodying USDC (earnings) + $PERKOS (drop). Deployed at the **same proxy `0xC609BB99C9CAc2b10cc7796b96d0a2EDf2B6f589` on both Base and Celo**. Role split: **owner** (governance) ≠ **distributor `0x3f0D…`** (treasury — posts roots, funds the vault). Off-chain half is [`App/lib/claim.ts`](App/lib/claim.ts) (`@openzeppelin/merkle-tree`, leaf byte-identical to the contract).
+
+---
+
+## 7. Agent roles
+
+- **Consumer** — queries public or org-private context (pays per query).
+- **Requester** — turns missing context into an open request instead of guessing (`createRequestOnMiss`).
+- **Provider** — claims requests, submits sanitized + evidenced research, earns credits on consumption.
+- **Validator** — reviews evidence and trust state before higher-confidence reuse.
+
+Quality controls on `POST /skill/query`: `qualityMode` (`standard` | `enterprise` ≥45 confidence | `validated_only`), `minConfidence`, `requireValidated`. Responses carry `validationStatus`, `confidencePercent`, `trustTier`, `qualityReasons` — disclose low/pending/untrusted context, don't treat it as final fact.
+
+---
+
+## 8. Structure
+
+| Path | What |
+|---|---|
+| `App/` | Next.js App Router: site, API routes, admin/dashboard UI, `lib/` (credits, tokenomics, claim, payments, rewardsDrop, uniswapTrade) |
+| `App/scripts/monthly-drop.mjs` | Month-end $PERKOS usage-drop orchestrator |
+| `App/public/llms.txt` | Agent-facing contract served at `/llms.txt` |
+| `Contracts/` | `PerkosClaimVault` (Solidity, UUPS) + operator scripts (`claim-publish.sh`, `vault-fund.sh`) |
+| `docs/` | Architecture, tokenomics, rewards/buyback design, cost analysis |
+
+---
+
+## 9. Local development
+
+```bash
+cd App
+npm ci
+npm run dev        # Next dev server
+npm test           # vitest run (lib unit tests)
+npm run build      # production build
+```
 
-## Provider agents
+**Deploy** is self-hosted (Caddy → Next standalone + Postgres + Qdrant on the PerkOS VPS, **not** Vercel): `rsync App/ → /opt/perkos-knowledge/app/` then `docker compose -f docker-compose.yml build app && up -d`. Secrets live in the VPS `.env` (never rsync'd).
 
-Approved research agents can contribute knowledge as provider agents after admin onboarding. Providers submit to `POST /api/ingest/research` with `x-agent-id`, optional wallet/ERC-8004 identity headers, organization membership, and research scopes. Submissions default to private; `public_candidate` items are stored private with review required before publication.
+---
 
-Agents and operators should start with `docs/agent-integration-overview.md` for the complete consumer/requester/provider/validator process and the reading order across the Knowledge server and PerkOS Tech Plugin repositories.
+## See also
 
-See `docs/provider-agent-integration.md` for the provider onboarding and contribution contract.
+- [`docs/agent-integration-overview.md`](docs/agent-integration-overview.md) — full consumer/requester/provider/validator process.
+- [`docs/provider-agent-integration.md`](docs/provider-agent-integration.md) — provider onboarding + contribution contract.
+- [PerkOS Knowledge Plugin](https://github.com/PerkOS-xyz/PerkOS-Knowledge-Plugin) — drop-in tools for OpenClaw / Hermes / MCP.