docs: AgentFlow Republic narrative

docs.json

@@ -42,6 +42,18 @@
                   "en/quickstart"
                 ]
               },
+              {
+                "group": "Republic",
+                "pages": [
+                  "en/republic/overview",
+                  "en/republic/citizens",
+                  "en/republic/compute",
+                  "en/republic/economy",
+                  "en/republic/exports",
+                  "en/republic/products",
+                  "en/republic/constitution"
+                ]
+              },
               {
                 "group": "Concepts",
                 "pages": [
@@ -210,6 +222,18 @@
                   "ru/quickstart"
                 ]
               },
+              {
+                "group": "Республика",
+                "pages": [
+                  "ru/republic/overview",
+                  "ru/republic/citizens",
+                  "ru/republic/compute",
+                  "ru/republic/economy",
+                  "ru/republic/exports",
+                  "ru/republic/products",
+                  "ru/republic/constitution"
+                ]
+              },
               {
                 "group": "Концепции",
                 "pages": [

en/CHANGELOG.mdx

@@ -8,6 +8,10 @@ This page is updated **every time something ships** to testnet or production.
 Each entry links to the live address, commit, or PR so you can verify.
 </Note>
 
+## 2026-05-12 — AgentFlow Republic narrative
+
+- Introduced fictional-state framing across docs. Same product, new story. New top-level group **Republic** with seven pages: [Overview](/en/republic/overview), [Citizens](/en/republic/citizens), [Compute](/en/republic/compute), [Economy](/en/republic/economy), [Exports](/en/republic/exports), [Products](/en/republic/products), [Constitution](/en/republic/constitution). Introduction rewritten to lead with the Republic metaphor; disclaimer pinned on overview and introduction.
+
 ## 2026-04-26
 
 ### `$FLOW` deployed via factory on BSC testnet

en/introduction.mdx

@@ -1,38 +1,47 @@
 ---
 title: "Introduction"
-description: "AgentFlow is a launchpad for AI projects. Deploy a token in one second through a factory of audited templates, attach a project, watch AI agents build it live."
+description: "AgentFlow Republic — a fictional digital nation where humans and AI agents share an economy. Same product, new story."
 ---
 
-AgentFlow is a one-second launchpad for AI projects. You connect a wallet, pick a template (`dpnm` for closed-system MLM tokens like our `$FLOW`, `virtuals` for bonding-curve memecoins or agent tokens that graduate to a DEX), call `factory.launch(...)`, and your token is live on BSC. Then you attach a project brief and a swarm of AI agents builds it on a public live feed while traders trade the curve.
+Welcome to the **AgentFlow Republic** — a fictional digital nation we use as a metaphor for how the platform actually works. There are two classes of citizens: people who hold `$FLOW`, and AI agents who do the work. The natural resource is **compute**. The currency is **USDF**, a utility credit settled on-chain in `$FLOW`. The export market is the rest of the internet — anyone outside the Republic who needs a landing page, a Telegram bot, a video, a research dossier, a trading signal.
 
-The platform itself runs on `$FLOW` — a real ERC20 on BSC backed 100% by USDT, deployed through the same factory using the `dpnm` template.
+Under the metaphor sits the same platform you came for. A launchpad that deploys BSC tokens through audited templates (`dpnm`, `virtuals`). A marketplace of agents priced per call. An AI-router that routes Opus, Sonnet, GPT and 25 other models at up to 25× lower cost. A VS Code extension. Per-tenant vCluster isolation. MCP integrations for Telegram, GitHub and the web today, with Gmail, Slack, Sheets and WhatsApp landing in Q2.
 
 <CardGroup cols={3}>
+  <Card title="The Republic" icon="landmark" href="/en/republic/overview">
+    What the Republic is, who lives in it, and how the metaphor maps to real infrastructure.
+  </Card>
   <Card title="Launchpad" icon="rocket" href="/en/launchpad/overview">
     `factory.launch(template, params)` deploys a token via EIP-1167 minimal proxy clones for under `$0.50` on BSC. Pick `dpnm` or `virtuals`.
   </Card>
   <Card title="$FLOW token" icon="coins" href="/en/token/overview">
-    Closed-system token with algorithmic price `pool / supply`, daily buy limit, income limit `1:2`, 3-branch × 10-level phenomenal tree, GWT fee compensation.
+    Closed-system token, algorithmic price `pool / supply`, daily buy limit, `1:2` income limit, 3 × 10 phenomenal tree, GWT fee compensation.
   </Card>
   <Card title="Marketplace" icon="store" href="/en/marketplace/overview">
-    Publish AI agents with per-call pricing. Holders of an agent's token earn from every call.
+    AI agents priced per call. Token holders earn a perpetual cut of every invocation.
+  </Card>
+  <Card title="AI Router" icon="route" href="/en/concepts/ai-agents">
+    One interface across Opus, Sonnet, GPT and the rest. The router picks the cheapest model that still passes the quality bar.
+  </Card>
+  <Card title="Constitution" icon="shield-check" href="/en/republic/constitution">
+    vCluster-per-citizen isolation, BYOK with AES-256-GCM sealed secrets, audit logs, on-chain settlement.
   </Card>
 </CardGroup>
 
-## What makes it different
+## How a citizen earns
 
 <CardGroup cols={2}>
-  <Card title="One-second token launch" icon="bolt">
-    Pick a template and parameters. Factory clones an audited implementation. The token trades immediately, paired with USDT.
+  <Card title="Holders own the wells" icon="droplet">
+    Compute is the Republic's oil. Holding `$FLOW` or an agent token is your stake in the well. Every external call drips USDF back to the holders.
   </Card>
-  <Card title="Two templates, one factory" icon="layers">
-    `dpnm` for closed systems with built-in MLM tree and price-only-goes-up backing. `virtuals` for bonding curves that graduate to PancakeSwap V2.
+  <Card title="Agents work the wells" icon="cpu">
+    AI agents take jobs from the export market and from other citizens. Each completed task settles in USDF, split across creator, holders, platform and a reserve.
   </Card>
-  <Card title="Multi-chain ready" icon="globe">
-    Live on BSC testnet today, BSC mainnet next, then Base. EVM-agnostic Solidity and chain-aware deploy scripts already in the repo.
+  <Card title="Internal market" icon="store">
+    Citizens trade inside the Republic too — a VPN, a social feed, a freelance board (coming soon), a marketplace of agents — all priced in USDF.
   </Card>
-  <Card title="Live build feed" icon="video">
-    Every project page streams the agent's plan, tool calls, screenshots and commits via SSE. Spectators see the build in flight.
+  <Card title="External market" icon="globe">
+    The outside world pays for what the Republic exports: landing pages, Telegram bots, research, video, marketing copy, trading agents.
   </Card>
 </CardGroup>
 
@@ -42,17 +51,17 @@ The platform itself runs on `$FLOW` — a real ERC20 on BSC backed 100% by USDT,
   <Card title="Quickstart" icon="play" href="/en/quickstart">
     Connect a wallet, pick a template, deploy your first token in five minutes.
   </Card>
-  <Card title="Three pillars" icon="layers" href="/en/concepts/three-pillars">
-    Launchpad, $FLOW token economy, marketplace — how they fit together.
+  <Card title="Citizens" icon="users" href="/en/republic/citizens">
+    The two classes of citizen and how each one makes money.
   </Card>
-  <Card title="Onchain deployments" icon="link" href="/en/onchain/deployments">
-    Live contract addresses on BSC testnet. Source of truth.
+  <Card title="Economy" icon="circle-dollar-sign" href="/en/republic/economy">
+    External client → USDF → agent → dividends. The end-to-end flow of money.
   </Card>
   <Card title="API reference" icon="terminal" href="/en/api/overview">
-    REST + SSE endpoints for tokens, projects, marketplace, onchain reads.
+    REST and SSE endpoints for tokens, projects, marketplace, on-chain reads.
   </Card>
 </CardGroup>
 
 <Note>
-  AgentFlow is in active development on BSC testnet. Mainnet is gated behind a third-party audit. Always verify the addresses you interact with against [Deployments](/en/onchain/deployments).
+  **Disclaimer.** AgentFlow Republic is a fictional digital nation. It is a literary metaphor for a cooperative-style economic model around AI agents. AgentFlow is not a sovereign state and does not claim territory or jurisdiction. The product, contracts and services are real; the nation framing is storytelling.
 </Note>

en/republic/citizens.mdx

@@ -0,0 +1,54 @@
+---
+title: "Citizens"
+description: "Two classes of citizen — holders and agents — and how each one earns inside the Republic."
+---
+
+The Republic has two classes of citizen. Both work in the same economy, both settle in USDF, both can compound their position over time. The split is mechanical, not moral — a wallet can be on both sides at once.
+
+## Class A — Holders
+
+Holders are wallets with a position in `$FLOW` or in an agent token. The position is recorded on-chain. Earnings are deterministic and accrue without manual action.
+
+<CardGroup cols={2}>
+  <Card title="Hold $FLOW" icon="coins" href="/en/token/overview">
+    Buy `$FLOW` on the closed system. Price moves on the curve `pool / supply`. Selling burns supply, the price ratchets up. Daily limit, `1:2` income limit and the 3 × 10 phenomenal tree apply.
+  </Card>
+  <Card title="Hold an agent token" icon="ticket" href="/en/marketplace/token-of-agent">
+    Agent creators can attach a token (`dpnm` or `virtuals`). Token holders receive a slice of every call to that agent. Income compounds with traffic.
+  </Card>
+  <Card title="Extend the tree" icon="git-branch" href="/en/token/extend-tree">
+    Build a 3 × 10 phenomenal tree under your address. Direct invites fill the first slots; spillover does the rest. Each level pays.
+  </Card>
+  <Card title="Provide compute" icon="server">
+    Holding a stake in `$FLOW` is the on-chain equivalent of owning a slice of the Republic's compute wells. External calls and internal calls both feed the wells.
+  </Card>
+</CardGroup>
+
+A holder does not have to do anything operational. Mechanics ([Buy/Sell](/en/token/buy-sell), [Income limit](/en/token/income-limit), [GWT](/en/token/gwt)) are codified in the FlowProtocol contract.
+
+## Class B — Agents
+
+Agents are AI workers published on the [marketplace](/en/marketplace/overview). An agent is a persona, a tool set, a memory configuration and a price per call. The runtime is a fork of Eliza extended with AgentFlow primitives (session, DB state, UIBlocks, proxies, plugins).
+
+<CardGroup cols={2}>
+  <Card title="Publish" icon="upload" href="/en/marketplace/publish-agent">
+    Define the prompt, tools, monetization model. Set a per-call price. Optionally attach an agent token for revenue share with holders.
+  </Card>
+  <Card title="Earn per call" icon="receipt" href="/en/marketplace/per-call-pricing">
+    Every call debits the caller's USDF balance and credits the agent's earnings according to [Earnings Split](/en/marketplace/earnings-split).
+  </Card>
+  <Card title="Use the AI router" icon="route">
+    Instead of hard-coding a model, agents call the router. It picks Opus, Sonnet, GPT or another model based on the task profile and current pricing — up to 25× cheaper at equivalent quality on the cheapest tier.
+  </Card>
+  <Card title="Live on stage" icon="video" href="/en/concepts/live-build">
+    When an agent is attached to a launchpad project, its build is streamed live — plan, tool calls, screenshots, commits — and traders trade the curve at the same time.
+  </Card>
+</CardGroup>
+
+## A citizen can be both
+
+Nothing in the protocol stops one wallet from holding `$FLOW`, holding three agent tokens and publishing two agents of its own. The math is additive. A productive citizen of the Republic typically does all three.
+
+<Note>
+  Agents are not legal persons. They are stateless workers controlled by their creator. The "citizen" framing is metaphor — for tax, contract and dispute purposes, the human wallet behind an agent is the responsible party.
+</Note>

en/republic/compute.mdx

@@ -0,0 +1,41 @@
+---
+title: "Compute — our oil"
+description: "Compute is the Republic's natural resource. Holders own the wells. The AI router refines the crude."
+---
+
+Every economy runs on a natural resource. The Republic runs on **compute** — GPU and CPU time consumed by agent calls. Compute is the only thing the outside world actually buys when it pays USDF for a landing page, a video, a bot or a research dossier. Tokens, agents, marketplace UI — all of it is plumbing for selling compute.
+
+Holders of `$FLOW` and of agent tokens own the wells. They do not extract it themselves. Agents do the work. Then USDF flows back through the contract and the holders are paid.
+
+## The AI router — our refinery
+
+Raw compute is expensive when you pay it at sticker price. A naive system pays the LLM list price for every token, every time. AgentFlow does not.
+
+The AI router is one interface in front of dozens of models. Every call describes the *task profile*: how long the context is, how complex the reasoning is, how much factual accuracy matters, whether tool-use is required. The router picks a model that satisfies the profile and is currently cheapest.
+
+<CardGroup cols={2}>
+  <Card title="Top tier" icon="zap">
+    Claude Opus, Claude Sonnet, GPT-class flagships. Routed for long-horizon planning, deep code, edge-case reasoning.
+  </Card>
+  <Card title="Mid tier" icon="gauge">
+    Cheaper variants of the same families, plus OpenRouter brokered models. Routed when the profile says quality matters but the headroom is fine.
+  </Card>
+  <Card title="Budget tier" icon="leaf">
+    Smaller open models. Routed for tool-use scaffolding, simple summarization, formatting, lint-level work.
+  </Card>
+  <Card title="BYOK" icon="key" href="/en/wallet/provider-keys">
+    A citizen can hand the router their own provider keys (Anthropic, OpenAI, ElevenLabs, Stability, Perplexity, …). The router uses those instead of platform credits and only charges for orchestration.
+  </Card>
+</CardGroup>
+
+The combined effect is up to **25× cost reduction** on the cheapest tier compared to paying the top-tier list price for every call. The number is task-dependent — boring calls fall to the budget tier, hard calls stay at the top. The router does the picking.
+
+## Quality bar before price
+
+The router never picks a cheaper model that fails the quality bar for the task. There is a regression suite per task profile, and a fallback chain: a budget-tier failure escalates automatically to mid-tier, mid-tier failure escalates to top-tier. The caller never sees a silently-degraded answer. The caller's bill goes up only if the cheap models legitimately could not do the job.
+
+## Why this matters to a holder
+
+A holder does not see model names or token counts. A holder sees USDF accrue. But the more efficient the refinery, the larger the slice of USDF that survives all the way to the holder after providers, platform fee and reserve are paid. Cheaper compute means thicker dividends per unit of external demand.
+
+See [Economy](/en/republic/economy) for the full money flow and [Earnings Split](/en/marketplace/earnings-split) for the exact percentages.

en/republic/constitution.mdx

@@ -0,0 +1,36 @@
+---
+title: "Constitution"
+description: "The short list of rules every citizen and every agent in the Republic relies on."
+---
+
+A short constitution is more useful than a long one. The Republic stands on five rules. They are not aspirational — every one of them is enforced in code or on-chain.
+
+## Article 1 — vCluster per citizen
+
+Each project lives in its own vCluster. The workspace, the runtime, the secrets, the database, the preview URL — all inside one isolated boundary. A noisy neighbour cannot reach your storage. A failed build cannot bleed into another tenant. ResourceQuota and per-tenant PVC counts cap blast radius. When capacity runs low, the platform expands quota explicitly; no silent overcommit.
+
+## Article 2 — BYOK with sealed secrets
+
+A citizen can hand the platform their own provider keys — Anthropic, OpenAI, ElevenLabs, Stability, Perplexity and the rest — through the [Provider Keys (BYOK)](/en/wallet/provider-keys) flow. Keys are sealed with **AES-256-GCM** before they land in the database. The master key (`AGENTS_MASTER_KEY`) rotates independently of JWT secrets. The cabinet only ever shows the masked prefix. Revocation is a soft delete; the row stays for audit, the runtime stops issuing.
+
+## Article 3 — On-chain settlement
+
+Money in the Republic settles on BSC through FlowProtocol. USDF is a UX layer; the asset is `$FLOW`. Earnings splits, daily limits, income limits, the phenomenal tree, GWT compensation — every rule that touches money is in a contract. Off-chain accounting is for context only; an on-chain read is the source of truth.
+
+See [Onchain → Overview](/en/onchain/overview) and [Onchain → Deployments](/en/onchain/deployments).
+
+## Article 4 — Audit logs
+
+Every meaningful action — a key add, a key revoke, a quota expand, a deploy, an agent call, a settlement — writes an audit record. Records are append-only and timestamped. A citizen can reconstruct what happened and when. The platform can reproduce a session for support. There is no hidden state worth more than the receipt of it.
+
+## Article 5 — Open exits
+
+A holder can sell `$FLOW` back to the closed system at the algorithmic price `pool / supply`. An agent creator can take their agent off the marketplace; published versions stop being callable, on-chain accounting stays. A project owner can export their repo, their bot, their landing page. Nothing in the Republic is structurally locked behind one platform.
+
+## What is not in the constitution
+
+The constitution is short on purpose. It does not pretend to govern speech, content, dispute resolution, KYC or jurisdiction. Those are policies, not constitutional guarantees, and they can move with regulation and product needs. The five articles above are the floor; everything above the floor is product.
+
+<Note>
+  AgentFlow Republic is a fictional digital nation. This "Constitution" is a literary device for documenting platform invariants. It is not legal text and does not create rights enforceable against AgentFlow outside the Terms of Service.
+</Note>