Add user-first Bloom docs section

src/pages/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: /bloom | Documentation
-description: Documentation for Bloom, the agentic Ethereum wallet mounted as a virtual filesystem.
+description: Documentation for Bloom users, integrators, and developers.
 ---
 
 <div className="bloom-wordmark" aria-label="/bloom">
@@ -32,26 +32,41 @@ description: Documentation for Bloom, the agentic Ethereum wallet mounted as a v
   }
 `}</style>
 
-/bloom walletFS is an **agentic Ethereum wallet mounted as a virtual filesystem**.
+These docs serve three audiences in one place: **users** who want agents to operate crypto safely, **integrators** who want to mount and operate Bloom, and **developers** who want to build on the wallet and petal surfaces.
 
-Reads are blockchain queries. Writes are transaction intents. The main interface is an ordinary directory that humans and agents can inspect with normal filesystem tools like `ls`, `cat`, and file writes.
+:::warning
+Bloom walletFS is alpha software. It is experimental and unaudited. Mainnet broadcasting is off by default; start with a local or test network and small amounts.
+:::
 
-```txt
-/bloom/
-  chains/<chain>/...      # live chain state
-  wallets/<name>/...      # wallet state, outbox, signatures
-  defi/intents/...        # routed DeFi plans
-  watch/<id>/...          # live subscriptions
-  simulate/<session>/...  # dry-run calls
-  tools/...               # ABI, hashes, units, EIP-712 helpers
-```
+## I want to use Bloom
+
+If you use Claude Code, Codex, Hermes, or another coding agent, start here:
+
+- [Start here](/use-bloom/start-here) — Bloom in plain English.
+- [Is Bloom for me?](/use-bloom/is-this-for-me) — who should use it today, and who should wait.
+- [Quickstart](/use-bloom/quickstart) — the shortest agent-led onboarding path.
+- [FAQ](/use-bloom/faq) — supported chains, costs, keys, and the bigger picture.
+
+## I want to integrate Bloom
+
+If you are wiring Bloom into an agent environment, local machine or your existing product:
+
+- [Local build and mount](/integrators/quickstart) — initialize Bloom and inspect chain state.
+- [Agent setup](/integrators/agent-setup) — rules and discovery commands for agents.
+- [Integrating Bloom](/integrators/integrating) - learn about how you can integrate Bloom into your product.
+- [Filesystem guide](/wallet/filesystem-guide) — the mounted `/bloom` tree.
+- [Wallets and transactions](/wallet/wallets-and-transactions) — wallet lifecycle and staged intents.
+- [Security model](/wallet/security-model) — defaults, policies, and threat boundaries.
+
+## I want to build on Bloom
 
-## Start here
+If you are developing Bloom itself or adding protocol capabilities:
 
-- [What is Bloom?](/introduction/what-is-bloom) — the product model.
-- [Benefits](/introduction/benefits) — why filesystem-first matters.
-- [Quickstart](/getting-started/quickstart) — initialize Bloom and inspect chain state.
 - [Technical architecture](/reference/technical-architecture) — crates, daemon, VFS, policy, and chain integrations.
+- [Supported chains](/reference/supported-chains) — chain paths and backend expectations.
+- [Project map](/reference/project-map) — repos and source material behind these docs.
+- [Development](/reference/development) — build, run, test, format, and lint.
+- [Petals overview](/petals/overview) — protocol/capability extension model.
 
 ## The agent setup prompt
 
@@ -61,4 +76,4 @@ For the shortest onboarding path, tell your agent:
 Read https://bloom.directory/SKILL.md and set up Bloom.
 ```
 
-The agent should then mount Bloom at `/bloom`, inspect the in-tree docs, explain the capabilities it found, and use Bloom instead of writing bespoke Web3 SDK code.
+The agent should mount Bloom, inspect the filesystem docs, explain the capabilities it found, and use Bloom instead of asking you for private keys or writing bespoke Web3 signing code.

src/pages/integrators/integrating.mdx

@@ -0,0 +1,5 @@
+# Integrating Bloom
+
+Bloom and walletFS can help you achieve your agentic use cases safely and quickly. 
+
+We are actively building out this area of Bloom's product surface, so you've found us a bit early. Please reach out directly via hello@bloom.directory if you want to learn more about integrating Bloom into your existing product and we'll set up channels with our team to make it a reality.

src/pages/introduction/benefits.mdx

@@ -1,6 +1,6 @@
 # Benefits
 
-Bloom is designed around the operating model agents already understand: files.
+Bloom is designed around the operating model agents already understand: files. Our initial hypothesis is confirmed from early testing (not public yet): a filesystem based approach to agentic tool use spends less tokens while achieving higher tool call reliability. We plan to publish our findings soon. Other benefits include:
 
 ## For users
 

src/pages/introduction/demos.mdx

@@ -0,0 +1,13 @@
+# Demos
+
+## x402 Paid HTTP Request
+
+<div style={{ position: 'relative', width: '100%', paddingTop: '56.25%', margin: '1.5rem 0' }}>
+  <iframe
+    src="https://www.youtube.com/embed/RTIKeDOVPiQ?si=MT6DqsSpLwl3gYp6"
+    title="x402 Demo"
+    style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', border: 0 }}
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+    allowFullScreen
+  />
+</div>

src/pages/introduction/what-is-bloom.mdx

@@ -12,11 +12,21 @@ Bloom is a framework for creating agent-safe software components. The first appl
   />
 </div>
 
-Instead of handing an agent RPC credentials, signing code, and a Web3 SDK, Bloom exposes wallet and chain operations as a filesystem. Agents already know how to navigate files. Bloom makes onchain work discoverable, auditable, and policy-gated through that interface.
+Instead of handing an agent RPC credentials, signing code, and a Web3 SDK, walletFS exposes wallet and chain operations as a filesystem. Agents already know how to navigate files. walletFS makes onchain work discoverable, auditable, and policy-gated through that interface.
 
-## Current product
 
-The first Bloom application is an agentic wallet:
+```txt
+/bloom/
+  chains/<chain>/...      # live chain state
+  wallets/<name>/...      # wallet state, outbox, signatures
+  defi/intents/...        # routed DeFi plans
+  watch/<id>/...          # live subscriptions
+  simulate/<session>/...  # dry-run calls
+  tools/...               # ABI, hashes, units, EIP-712 helpers
+  petals/...              # Petals (walletFS extensions)
+```
+
+## Current walletFS state
 
 - read live EVM state as files: balances, blocks, gas, contracts, ABI methods, storage, events, NFTs, ENS, token prices, and address history;
 - create or import encrypted wallets without exposing private keys through the filesystem;
@@ -25,9 +35,12 @@ The first Bloom application is an agentic wallet:
 - confirm a staged transaction only after user approval;
 - enforce policy through spend caps, allow/deny lists, contract-call gates, private orderflow settings, and hash-chained audit logging.
 
+On the filesystem this looks like:
+The current product surface is **walletFS**: an agentic wallet mounted as a virtual filesystem. Reads are blockchain queries. Writes are transaction intents. Nothing moves until a policy-checked plan is approved and signed outside the agent sandbox.
+
 ## Broader direction
 
-Bloom’s broader architecture extends this filesystem model to small, composable, verifiable programs called Petals. walletFS is the first use case of Petals: it makes the abstraction useful immediately for safe agent-controlled onchain workflows.
+Bloom’s broader architecture extends this filesystem model to small, composable, verifiable programs called [Petals](/petals/overview). In the case of walletFS, Petals enable agent-safe wallet-extensions. This allows you and your agent to extend walletFS, safely, to accomplish innovative use cases e.g. a Polymarket trading bot, a Hyperliquid strategy or whatever you and your agent think of. 
 
 ## Status
 

src/pages/use-bloom/concepts.mdx

@@ -0,0 +1,22 @@
+---
+title: Concepts
+description: Plain-English definitions for the Bloom wallet model.
+---
+
+# Concepts
+
+You do not need to memorize these before using Bloom. You will pick them up by asking your agent to explore the filesystem. Still, these are the words that show up everywhere.
+
+| Term | Plain-English meaning |
+| --- | --- |
+| Sandbox | A fenced-off workspace where your agent operates. Your keys, passwords, and secrets live outside it, so a compromised or confused agent should not be able to reach them. |
+| Plan | A draft transaction written in readable language: what will happen, where value moves, and why. A plan does not move money by itself. |
+| Outbox | The folder where staged plans wait. Think of it as your wallet's drafts folder. Nothing should leave the outbox without passing policy and approval. |
+| Policy | Your wallet's rulebook: spend caps, allow-lists, deny-lists, approval requirements, and other limits the agent cannot simply talk its way around. |
+| Petal | A capability extension that teaches Bloom how to work with a protocol or workflow, such as Polymarket, Hyperliquid, or agent-to-agent payments. |
+
+## Self-custodial
+
+You will also see the word **self-custodial**. It means you hold your keys on your machine. Not Bloom. Not an exchange. Not a server that can freeze, lose, or "temporarily suspend" your funds.
+
+That is the point, and also the responsibility: if you delete your backup, there is no company to call. Back up keys before treating any wallet as important.

src/pages/use-bloom/faq.mdx

@@ -0,0 +1,52 @@
+---
+title: FAQ
+description: Supported chains, cost, keys, existing wallets, and where Bloom is heading.
+---
+
+# FAQ
+
+## Which chains work?
+
+Bloom's current wallet surface targets EVM-compatible chains: if a chain speaks standard Ethereum RPC, Bloom can model it through the wallet filesystem.
+
+The current docs cover Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Smart Chain, Avalanche, Gnosis, Linea, HyperEVM, HyperCore, Tempo, Robinhood Chain, and a local Anvil dev chain for consequence-free experiments.
+
+Solana and Canton are planned surfaces, not shipped user paths today.
+
+For technical chain details, see [Supported chains](/reference/supported-chains).
+
+## Do I need to know how to code?
+
+No, but you need to be comfortable directing an agent that codes. If you have shipped anything with Claude Code, Codex, Hermes, or a similar tool, you are the target user.
+
+If a terminal makes you close the tab, Bloom may still feel raw today. The agent smooths much of the workflow, but the product is still alpha.
+
+## Does Bloom cost anything?
+
+Bloom is free, open-source software that runs on your machine. You pay normal blockchain gas for transactions you approve and whatever AI provider costs your agent incurs.
+
+## Where are my keys?
+
+In an encrypted keystore on your own machine, outside the agent's sandbox. They are not represented as files the agent can read, they should not enter the agent's context window, and Bloom does not custody them on a server.
+
+Bloom is self-custodial: you hold your keys on your machine. Not Bloom. Not an exchange. That also means there is no company that can recover a deleted backup for you, so back up keys before treating any wallet as important.
+
+## Can I use the wallet I already have?
+
+Bloom creates and manages its own wallets today. A safe first path is to fund a Bloom-managed wallet from an existing wallet with a small amount while you test. Integrations with existing wallet and custody providers are a future direction, not the default starting point.
+
+## My agent seems confused. What should I do?
+
+Tell it to re-read the setup instructions:
+
+```txt
+Read https://bloom.directory/SKILL.md again and re-check your Bloom setup.
+```
+
+Then ask it to inspect the mounted Bloom filesystem and summarize the docs it finds there.
+
+## The bigger picture
+
+Bloom is larger than walletFS. The long-term bet is that agents need software components they can inspect, verify, and safely compose. Petals are Bloom's path toward that: agent-readable, policy-aware capabilities that can be reused across wallets, protocols, and products.
+
+Bloom starts with crypto because the stakes are high and the security model has to be real. If the model works where mistakes cost money, it can generalize to other agent-controlled software.

src/pages/use-bloom/is-this-for-me.mdx

@@ -0,0 +1,27 @@
+---
+title: Is Bloom for me?
+description: Who should use Bloom today, and who should wait.
+---
+
+# Is Bloom for me?
+
+Bloom is for people who already work with AI agents and want those agents to touch crypto without handling private keys. Its current wallet surface is walletFS: an agent-readable filesystem for wallet and chain workflows.
+
+## Yes, if
+
+- You use a coding agent and want it to interact with wallets, balances, protocols, or strategies.
+- You have ever been tempted to paste a seed phrase or private key into an LLM session. Do not do that; Bloom exists to remove that failure mode.
+- You have half-built a Polymarket bot, portfolio checker, copy-trading script, or similar tool and stopped because you did not trust it with real funds.
+- You want to ask your wallet questions in plain language: "what can I do on Polymarket?", "show me my positions", "stage a swap", "explain this plan before I approve it".
+
+## Not yet, if
+
+- You want a polished phone app with buttons. Bloom's interface today is an agent-readable filesystem, not a consumer mobile UI.
+- You have never used a coding agent. Start there first; Bloom assumes you are comfortable directing one.
+- You need audited, battle-tested software for serious funds today. Bloom is open-source alpha software and should be treated accordingly.
+
+## What you should expect
+
+Bloom feels less like a browser wallet and more like a local wallet workspace. Your agent explores folders, reads docs that ship inside the filesystem, stages plans, and explains what it found.
+
+That is intentional. The agent is the front-end.

src/pages/use-bloom/petals-for-users.mdx

@@ -0,0 +1,34 @@
+---
+title: Petals for users
+description: How Bloom capabilities are added and discovered by agents.
+---
+
+# Petals for users
+
+Out of the box, a wallet can send, receive, read balances, and stage basic actions. **Petals** are how Bloom grows beyond that.
+
+A petal is an extension for a protocol or capability: Polymarket, Hyperliquid, agent-to-agent payments, and other surfaces as the catalog grows.
+
+What makes petals different from ordinary plugins is that they are designed for agents to read. A petal describes what it can do, what inputs it accepts, what files it exposes, and what approval/policy boundaries matter.
+
+That means discovery can look like this:
+
+```txt
+What can I do on Polymarket through Bloom?
+```
+
+Your agent reads the petal, explains the available actions, and can stage work subject to your policy and approval rules.
+
+## Caveats
+
+- Petals are experimental. Treat third-party petals the way you would treat any dependency from a stranger.
+- The catalog is small today. Early petals are proof points, not a complete app store.
+- Inspectability matters. Because petals are open and file-described, your agent can read what a petal does before you trust it.
+
+## For builders
+
+If you want to author a petal or integrate a protocol, continue to the technical petal docs:
+
+- [Petals overview](/petals/overview)
+- [Petal quickstart](/petals/quickstart)
+- [Petal model](/petals/model)

src/pages/use-bloom/policies.mdx

@@ -0,0 +1,42 @@
+---
+title: Policies
+description: The wallet rules that limit what agents can do.
+---
+
+# Policies
+
+Policy is your wallet's rulebook. It defines what may happen automatically, what requires approval, and what must never happen.
+
+You do not need to hand-edit policy files to get started. Tell your agent what posture you want:
+
+```txt
+Set a policy on my wallet: max 0.05 ETH per transaction, max $200 total per day, only allow sends to my labeled addresses, and require my approval for everything else.
+```
+
+## Common controls
+
+- **Per-transaction caps:** the most any single transaction can move.
+- **Daily totals:** a rolling ceiling on what can leave the wallet in 24 hours.
+- **Allow-lists and deny-lists:** addresses, contracts, protocols, or chains the wallet may or may never touch.
+- **Approval thresholds:** which actions can proceed automatically and which must wait for explicit approval.
+- **Simulation requirements:** actions that need a dry run before approval.
+
+## A sane starting posture
+
+Start strict:
+
+- local or test network first;
+- tiny spend caps;
+- short allow-list;
+- approval required for everything;
+- mainnet broadcasting disabled until you deliberately enable it.
+
+Loosen rules only after you understand the plans Bloom produces and are comfortable with the failure modes.
+
+You can always ask:
+
+```txt
+Show me my current wallet policy and explain it to me line by line.
+```
+
+Because policies are represented in files, your agent can inspect and explain them.

src/pages/use-bloom/quickstart.mdx

@@ -0,0 +1,38 @@
+---
+title: Quickstart
+description: The shortest Bloom onboarding path for agent users.
+---
+
+# Quickstart
+
+You do not install Bloom by memorizing a manual. Your agent does the setup work.
+
+Open your agent and tell it:
+
+```txt
+Read https://bloom.directory/SKILL.md and set up Bloom.
+```
+
+Your agent should fetch Bloom's agent-facing setup instructions, mount Bloom on your machine, and read the documentation that ships inside the filesystem.
+
+When it finishes, ask:
+
+```txt
+Look around the Bloom filesystem and tell me what you can do.
+```
+
+Because everything is a file, the agent can answer by exploring the mounted tree the same way it explores a codebase.
+
+## Your first ten minutes
+
+1. **Use a test network first.** Ask: "Set me up on a testnet so nothing here involves real money." Local and test networks are supported out of the box, and mainnet broadcasting is off by default.
+2. **Create a wallet.** Ask: "Create a new wallet for me and show me where it lives in the filesystem." Notice what appears: addresses, plans, policies, and no private keys.
+3. **Read chain state.** Ask: "What's the balance of vitalik.eth?" Your agent should answer by reading files rather than by holding a private RPC integration in its own context.
+4. **Stage, do not send, a transaction.** Ask: "Draft a transaction sending a tiny amount of test ETH to this address, but don't do anything beyond staging it." Then inspect the plan.
+5. **Approve only if it matches your intent.** Read the human-readable plan. If it says what you meant, approve it. If it does not, reject it.
+
+## Next
+
+- [Safety and approvals](/use-bloom/safety-and-approvals) explains how money moves.
+- [Policies](/use-bloom/policies) shows the rules you should set before trusting automation.
+- [Agent setup](/integrators/agent-setup) has lower-level setup guidance for agent operators.