From ccbfa4d33cbf2868560ae97fbe4bc10c24757226 Mon Sep 17 00:00:00 2001 From: Violet Agent Date: Tue, 14 Jul 2026 16:04:28 +0300 Subject: [PATCH 1/4] docs: add user-first Bloom guide --- src/pages/index.mdx | 48 ++++++++++++------- src/pages/use-bloom/chains-and-faq.mdx | 50 ++++++++++++++++++++ src/pages/use-bloom/is-this-for-me.mdx | 27 +++++++++++ src/pages/use-bloom/petals-for-users.mdx | 34 +++++++++++++ src/pages/use-bloom/policies.mdx | 42 ++++++++++++++++ src/pages/use-bloom/quickstart.mdx | 38 +++++++++++++++ src/pages/use-bloom/safety-and-approvals.mdx | 38 +++++++++++++++ src/pages/use-bloom/start-here.mdx | 37 +++++++++++++++ vocs.config.ts | 20 ++++++-- 9 files changed, 313 insertions(+), 21 deletions(-) create mode 100644 src/pages/use-bloom/chains-and-faq.mdx create mode 100644 src/pages/use-bloom/is-this-for-me.mdx create mode 100644 src/pages/use-bloom/petals-for-users.mdx create mode 100644 src/pages/use-bloom/policies.mdx create mode 100644 src/pages/use-bloom/quickstart.mdx create mode 100644 src/pages/use-bloom/safety-and-approvals.mdx create mode 100644 src/pages/use-bloom/start-here.mdx diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 1804457..75a022b 100644 --- a/src/pages/index.mdx +++ b/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. ---
@@ -32,26 +32,40 @@ description: Documentation for Bloom, the agentic Ethereum wallet mounted as a v } `} -/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. +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. -```txt -/bloom/ - chains//... # live chain state - wallets//... # wallet state, outbox, signatures - defi/intents/... # routed DeFi plans - watch//... # live subscriptions - simulate//... # dry-run calls - tools/... # ABI, hashes, units, EIP-712 helpers -``` +:::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. +::: + +## Start as a user + +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. +- [Safety and approvals](/use-bloom/safety-and-approvals) — how staging, policy, approval, signing, and audit logs work. + +## Integrate or operate Bloom + +If you are wiring Bloom into an agent environment or local machine: + +- [Agent setup](/getting-started/agent-setup) — rules and discovery commands for agents. +- [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. + +## 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. +- [Petals overview](/petals/overview) — protocol/capability extension model. +- [Petal authoring](/petals/authoring) — the developer surface for building petals. ## The agent setup prompt @@ -61,4 +75,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. diff --git a/src/pages/use-bloom/chains-and-faq.mdx b/src/pages/use-bloom/chains-and-faq.mdx new file mode 100644 index 0000000..9b51bcb --- /dev/null +++ b/src/pages/use-bloom/chains-and-faq.mdx @@ -0,0 +1,50 @@ +--- +title: Chains and FAQ +description: Supported chains, cost, keys, existing wallets, and where Bloom is heading. +--- + +# Chains and FAQ + +## Which chains work? + +Bloom walletFS 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. + +## Can I use the wallet I already have? + +Bloom walletFS 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. + +walletFS 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. diff --git a/src/pages/use-bloom/is-this-for-me.mdx b/src/pages/use-bloom/is-this-for-me.mdx new file mode 100644 index 0000000..ebe3aaa --- /dev/null +++ b/src/pages/use-bloom/is-this-for-me.mdx @@ -0,0 +1,27 @@ +--- +title: Is Bloom for me? +description: Who should use Bloom walletFS today, and who should wait. +--- + +# Is Bloom for me? + +Bloom walletFS is for people who already work with AI agents and want those agents to touch crypto without handling private keys. + +## 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. diff --git a/src/pages/use-bloom/petals-for-users.mdx b/src/pages/use-bloom/petals-for-users.mdx new file mode 100644 index 0000000..bcd7d3e --- /dev/null +++ b/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) diff --git a/src/pages/use-bloom/policies.mdx b/src/pages/use-bloom/policies.mdx new file mode 100644 index 0000000..669f518 --- /dev/null +++ b/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. diff --git a/src/pages/use-bloom/quickstart.mdx b/src/pages/use-bloom/quickstart.mdx new file mode 100644 index 0000000..6ea7d4e --- /dev/null +++ b/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](/getting-started/agent-setup) has lower-level setup guidance for agent operators. diff --git a/src/pages/use-bloom/safety-and-approvals.mdx b/src/pages/use-bloom/safety-and-approvals.mdx new file mode 100644 index 0000000..39c5a78 --- /dev/null +++ b/src/pages/use-bloom/safety-and-approvals.mdx @@ -0,0 +1,38 @@ +--- +title: Safety and approvals +description: How Bloom stages, checks, approves, signs, and logs wallet actions. +--- + +# Safety and approvals + +This is the part to actually read. It is the part that keeps you safe. + +## How money moves + +1. **Your agent stages an intent.** You say “swap 0.05 ETH for USDC.” Your agent writes that intention into the outbox. At this point, nothing has happened on-chain. +2. **Bloom checks the plan against policy.** Spend caps, allow-lists, deny-lists, chain restrictions, and approval rules are enforced outside the agent's sandbox. If the plan violates policy, it should stop there. +3. **You read a human-readable plan.** Not a wall of hex: a readable explanation of what will happen, where value moves, and why. +4. **You approve.** Only after approval does signing happen, using keys the agent has never seen. +5. **Bloom logs the action.** Meaningful actions are written to audit logs you can inspect later. + +## What if my agent gets prompt-injected? + +A manipulated agent can try to stage a bad plan. That is the honest risk. + +Bloom reduces the blast radius by keeping the private key outside the agent's readable world. A bad plan still has to pass policy and receive approval before it can be signed. That does not make risk zero, but it is much safer than giving an agent unrestricted signing power or secrets in its context window. + +Stay skeptical. Read plans before approving them. Keep caps low. + +## What if my agent mistypes an address? + +Agents are bad at long random-looking strings. Bloom encourages address labels so the wallet, not the agent, resolves a human name to an exact address. + +Prefer “send to Josh” over “send to `0x...`” once you have set up and checked the label. The wallet should resolve the label to the actual address from your trusted address book. + +## Why there is no “Connect Wallet” button + +Bloom deliberately avoids the browser extension and “Connect Wallet” pattern. + +Website front-ends are a major crypto attack surface: a protocol can be sound while a compromised website feeds your wallet a poisoned transaction. Bloom's model is for your agent to talk directly to protocol capabilities through the filesystem and petals, subject to policy and approval. + +The agent is the front-end. Bloom is the guardrail between the agent and your money. diff --git a/src/pages/use-bloom/start-here.mdx b/src/pages/use-bloom/start-here.mdx new file mode 100644 index 0000000..3171755 --- /dev/null +++ b/src/pages/use-bloom/start-here.mdx @@ -0,0 +1,37 @@ +--- +title: Start here +description: Bloom in plain English for people who build with agents. +--- + +# Start here + +Bloom's current wallet surface, **walletFS**, is a crypto wallet your AI agent can actually use without ever seeing your private keys. + +Instead of giving an agent a pile of Web3 tools or, worse, a seed phrase, Bloom turns wallet and chain interactions into ordinary files and folders. Agents already know how to read, inspect, and write files. Bloom uses that strength as the interface. + +- **Reading a file** asks the blockchain a question. +- **Writing a file** stages a transaction intent. It does not send money. +- **Approving a plan** is the step that can actually sign and broadcast. + +Your keys are not files in the Bloom filesystem. They live in an encrypted keystore outside the agent's sandbox. The agent can draft work, explain it, and prepare a plan, but signing only happens after the plan passes policy and gets approval. + +:::warning +Bloom walletFS is alpha software. It is experimental and unaudited. Mainnet broadcasting is off by default; you have to deliberately enable it. Start on a local or test network, use small amounts, and treat the system like early software. +::: + +## Who these docs are for + +Start here if you use Claude Code, Codex, Hermes, or another coding agent and want it to interact with crypto safely: check balances, stage transfers, inspect positions, or prepare protocol actions without pasting secrets into a chat window. + +If you are integrating Bloom into an app or building petals, this first section gives the product model. The later sections go deeper: + +- [Agent setup](/getting-started/agent-setup) for integrators and agent operators. +- [Filesystem guide](/wallet/filesystem-guide) for the wallet surface. +- [Technical architecture](/reference/technical-architecture) for implementation details. +- [Petals](/petals/overview) for protocol/capability authors. + +## The whole model + +Your agent proposes. Bloom checks. You approve. Bloom signs. + +That is the core safety loop. A prompt-injected or confused agent can stage a bad plan, but it should not be able to steal a private key because the key was never in the agent's readable world. diff --git a/vocs.config.ts b/vocs.config.ts index 25456ad..24d5d32 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -12,7 +12,7 @@ const siteUrl = export default defineConfig({ title: '/bloom | Documentation', description: - 'Documentation for Bloom, the agentic Ethereum wallet mounted as a virtual filesystem.', + 'Documentation for Bloom users, integrators, and developers: agentic wallets, filesystem-first crypto workflows, and petals.', logoUrl: '/logo.svg', iconUrl: { light: '/favicon-options/bloom-mono-black.svg', @@ -34,7 +34,19 @@ export default defineConfig({ sidebar: [ { text: 'Overview', link: '/' }, { - text: 'Introduction', + text: 'Use Bloom', + items: [ + { text: 'Start here', link: '/use-bloom/start-here' }, + { text: 'Is Bloom for me?', link: '/use-bloom/is-this-for-me' }, + { text: 'Quickstart', link: '/use-bloom/quickstart' }, + { text: 'Safety and approvals', link: '/use-bloom/safety-and-approvals' }, + { text: 'Policies', link: '/use-bloom/policies' }, + { text: 'Petals for users', link: '/use-bloom/petals-for-users' }, + { text: 'Chains and FAQ', link: '/use-bloom/chains-and-faq' }, + ], + }, + { + text: 'Product model', items: [ { text: 'What is Bloom?', link: '/introduction/what-is-bloom' }, { text: 'Benefits', link: '/introduction/benefits' }, @@ -42,14 +54,14 @@ export default defineConfig({ ], }, { - text: 'Getting started', + text: 'Integrators', items: [ { text: 'Quickstart', link: '/getting-started/quickstart' }, { text: 'Agent setup', link: '/getting-started/agent-setup' }, ], }, { - text: 'Agentic wallet', + text: 'Wallet reference', items: [ { text: 'Filesystem guide', link: '/wallet/filesystem-guide' }, { text: 'Wallets and transactions', link: '/wallet/wallets-and-transactions' }, From 33bc3c21191c440e9491f5b0af62c77bb134bd7b Mon Sep 17 00:00:00 2001 From: Violet Agent Date: Tue, 14 Jul 2026 16:38:33 +0300 Subject: [PATCH 2/4] docs: incorporate Claude review feedback --- src/pages/index.mdx | 17 +++++++++++++++ src/pages/use-bloom/chains-and-faq.mdx | 8 ++++--- src/pages/use-bloom/concepts.mdx | 22 ++++++++++++++++++++ src/pages/use-bloom/is-this-for-me.mdx | 6 +++--- src/pages/use-bloom/quickstart.mdx | 8 +++---- src/pages/use-bloom/safety-and-approvals.mdx | 10 ++++----- src/pages/use-bloom/start-here.mdx | 2 +- vocs.config.ts | 3 ++- 8 files changed, 59 insertions(+), 17 deletions(-) create mode 100644 src/pages/use-bloom/concepts.mdx diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 75a022b..4e00884 100644 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -36,6 +36,16 @@ These docs serve three audiences in one place: **users** who want agents to oper 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. +```txt +/bloom/ + chains//... # live chain state + wallets//... # wallet state, outbox, signatures + defi/intents/... # routed DeFi plans + watch//... # live subscriptions + simulate//... # dry-run calls + tools/... # ABI, hashes, units, EIP-712 helpers +``` + :::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. ::: @@ -46,13 +56,18 @@ 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. +- [Concepts](/use-bloom/concepts) — sandbox, plans, outbox, policy, petals, and self-custody. - [Quickstart](/use-bloom/quickstart) — the shortest agent-led onboarding path. - [Safety and approvals](/use-bloom/safety-and-approvals) — how staging, policy, approval, signing, and audit logs work. +- [Policies](/use-bloom/policies) — the rules that limit what agents can do. +- [Petals for users](/use-bloom/petals-for-users) — how Bloom grows protocol capabilities. +- [Chains and FAQ](/use-bloom/chains-and-faq) — supported chains, costs, keys, and the bigger picture. ## Integrate or operate Bloom If you are wiring Bloom into an agent environment or local machine: +- [Local build and mount](/getting-started/quickstart) — initialize Bloom and inspect chain state. - [Agent setup](/getting-started/agent-setup) — rules and discovery commands for agents. - [Filesystem guide](/wallet/filesystem-guide) — the mounted `/bloom` tree. - [Wallets and transactions](/wallet/wallets-and-transactions) — wallet lifecycle and staged intents. @@ -64,6 +79,8 @@ If you are developing Bloom itself or adding protocol capabilities: - [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. - [Petal authoring](/petals/authoring) — the developer surface for building petals. diff --git a/src/pages/use-bloom/chains-and-faq.mdx b/src/pages/use-bloom/chains-and-faq.mdx index 9b51bcb..08f222d 100644 --- a/src/pages/use-bloom/chains-and-faq.mdx +++ b/src/pages/use-bloom/chains-and-faq.mdx @@ -7,7 +7,7 @@ description: Supported chains, cost, keys, existing wallets, and where Bloom is ## Which chains work? -Bloom walletFS targets EVM-compatible chains: if a chain speaks standard Ethereum RPC, Bloom can model it through the wallet filesystem. +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. @@ -29,9 +29,11 @@ Bloom is free, open-source software that runs on your machine. You pay normal bl 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 walletFS 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. +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? @@ -47,4 +49,4 @@ Then ask it to inspect the mounted Bloom filesystem and summarize the docs it fi 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. -walletFS 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. +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. diff --git a/src/pages/use-bloom/concepts.mdx b/src/pages/use-bloom/concepts.mdx new file mode 100644 index 0000000..6965b6d --- /dev/null +++ b/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. diff --git a/src/pages/use-bloom/is-this-for-me.mdx b/src/pages/use-bloom/is-this-for-me.mdx index ebe3aaa..30f4efb 100644 --- a/src/pages/use-bloom/is-this-for-me.mdx +++ b/src/pages/use-bloom/is-this-for-me.mdx @@ -1,18 +1,18 @@ --- title: Is Bloom for me? -description: Who should use Bloom walletFS today, and who should wait. +description: Who should use Bloom today, and who should wait. --- # Is Bloom for me? -Bloom walletFS is for people who already work with AI agents and want those agents to touch crypto without handling private keys. +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”. +- 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 diff --git a/src/pages/use-bloom/quickstart.mdx b/src/pages/use-bloom/quickstart.mdx index 6ea7d4e..1f63668 100644 --- a/src/pages/use-bloom/quickstart.mdx +++ b/src/pages/use-bloom/quickstart.mdx @@ -25,10 +25,10 @@ Because everything is a file, the agent can answer by exploring the mounted tree ## 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. +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 diff --git a/src/pages/use-bloom/safety-and-approvals.mdx b/src/pages/use-bloom/safety-and-approvals.mdx index 39c5a78..d3096a3 100644 --- a/src/pages/use-bloom/safety-and-approvals.mdx +++ b/src/pages/use-bloom/safety-and-approvals.mdx @@ -9,8 +9,8 @@ This is the part to actually read. It is the part that keeps you safe. ## How money moves -1. **Your agent stages an intent.** You say “swap 0.05 ETH for USDC.” Your agent writes that intention into the outbox. At this point, nothing has happened on-chain. -2. **Bloom checks the plan against policy.** Spend caps, allow-lists, deny-lists, chain restrictions, and approval rules are enforced outside the agent's sandbox. If the plan violates policy, it should stop there. +1. **Your agent stages an intent.** You say "swap 0.05 ETH for USDC." Your agent writes that intention into the outbox. At this point, nothing has happened on-chain. +2. **Bloom checks the plan against policy.** Spend caps, allow-lists, deny-lists, chain restrictions, and approval rules are enforced outside the agent's sandbox. If the plan violates policy, it stops there. 3. **You read a human-readable plan.** Not a wall of hex: a readable explanation of what will happen, where value moves, and why. 4. **You approve.** Only after approval does signing happen, using keys the agent has never seen. 5. **Bloom logs the action.** Meaningful actions are written to audit logs you can inspect later. @@ -27,11 +27,11 @@ Stay skeptical. Read plans before approving them. Keep caps low. Agents are bad at long random-looking strings. Bloom encourages address labels so the wallet, not the agent, resolves a human name to an exact address. -Prefer “send to Josh” over “send to `0x...`” once you have set up and checked the label. The wallet should resolve the label to the actual address from your trusted address book. +Prefer "send to Josh" over "send to `0x...`" once you have set up and checked the label. The wallet resolves the label to the actual address from your trusted address book. -## Why there is no “Connect Wallet” button +## Why there is no "Connect Wallet" button -Bloom deliberately avoids the browser extension and “Connect Wallet” pattern. +Bloom deliberately avoids the browser extension and "Connect Wallet" pattern. Website front-ends are a major crypto attack surface: a protocol can be sound while a compromised website feeds your wallet a poisoned transaction. Bloom's model is for your agent to talk directly to protocol capabilities through the filesystem and petals, subject to policy and approval. diff --git a/src/pages/use-bloom/start-here.mdx b/src/pages/use-bloom/start-here.mdx index 3171755..d0b758f 100644 --- a/src/pages/use-bloom/start-here.mdx +++ b/src/pages/use-bloom/start-here.mdx @@ -16,7 +16,7 @@ Instead of giving an agent a pile of Web3 tools or, worse, a seed phrase, Bloom Your keys are not files in the Bloom filesystem. They live in an encrypted keystore outside the agent's sandbox. The agent can draft work, explain it, and prepare a plan, but signing only happens after the plan passes policy and gets approval. :::warning -Bloom walletFS is alpha software. It is experimental and unaudited. Mainnet broadcasting is off by default; you have to deliberately enable it. Start on a local or test network, use small amounts, and treat the system like early software. +Bloom is alpha software. Its current wallet surface, walletFS, is experimental and unaudited. Mainnet broadcasting is off by default; you have to deliberately enable it. Start on a local or test network, use small amounts, and treat the system like early software. ::: ## Who these docs are for diff --git a/vocs.config.ts b/vocs.config.ts index 24d5d32..daaa259 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -38,6 +38,7 @@ export default defineConfig({ items: [ { text: 'Start here', link: '/use-bloom/start-here' }, { text: 'Is Bloom for me?', link: '/use-bloom/is-this-for-me' }, + { text: 'Concepts', link: '/use-bloom/concepts' }, { text: 'Quickstart', link: '/use-bloom/quickstart' }, { text: 'Safety and approvals', link: '/use-bloom/safety-and-approvals' }, { text: 'Policies', link: '/use-bloom/policies' }, @@ -56,7 +57,7 @@ export default defineConfig({ { text: 'Integrators', items: [ - { text: 'Quickstart', link: '/getting-started/quickstart' }, + { text: 'Local build and mount', link: '/getting-started/quickstart' }, { text: 'Agent setup', link: '/getting-started/agent-setup' }, ], }, From e41ad0f4a03487629f0de402475e9915685355c8 Mon Sep 17 00:00:00 2001 From: Violet Agent Date: Tue, 14 Jul 2026 17:35:50 +0300 Subject: [PATCH 3/4] fix: omit preview base URL for docs --- vocs.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vocs.config.ts b/vocs.config.ts index daaa259..198b1b2 100644 --- a/vocs.config.ts +++ b/vocs.config.ts @@ -7,7 +7,7 @@ const env = (globalThis as typeof globalThis & { const siteUrl = env.CF_PAGES_BRANCH === 'master' ? 'https://docs.bloom.directory' - : env.CF_PAGES_URL + : undefined export default defineConfig({ title: '/bloom | Documentation', From 28845b22c6e280d3be7cc721ca926bf7fd4c6923 Mon Sep 17 00:00:00 2001 From: Gavin Pacini Date: Tue, 14 Jul 2026 19:12:44 +0100 Subject: [PATCH 4/4] artisanal polish --- src/pages/index.mdx | 32 +++++-------------- .../agent-setup.mdx | 0 src/pages/integrators/integrating.mdx | 5 +++ .../quickstart.mdx | 0 src/pages/introduction/benefits.mdx | 2 +- src/pages/introduction/demos.mdx | 13 ++++++++ src/pages/introduction/what-is-bloom.mdx | 21 +++++++++--- .../use-bloom/{chains-and-faq.mdx => faq.mdx} | 4 +-- src/pages/use-bloom/quickstart.mdx | 2 +- src/pages/use-bloom/start-here.mdx | 3 +- vocs.config.ts | 8 +++-- 11 files changed, 54 insertions(+), 36 deletions(-) rename src/pages/{getting-started => integrators}/agent-setup.mdx (100%) create mode 100644 src/pages/integrators/integrating.mdx rename src/pages/{getting-started => integrators}/quickstart.mdx (100%) create mode 100644 src/pages/introduction/demos.mdx rename src/pages/use-bloom/{chains-and-faq.mdx => faq.mdx} (98%) diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 4e00884..3e879ee 100644 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -34,46 +34,31 @@ description: Documentation for Bloom users, integrators, and developers. 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. -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. - -```txt -/bloom/ - chains//... # live chain state - wallets//... # wallet state, outbox, signatures - defi/intents/... # routed DeFi plans - watch//... # live subscriptions - simulate//... # dry-run calls - tools/... # ABI, hashes, units, EIP-712 helpers -``` - :::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. ::: -## Start as a user +## 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. -- [Concepts](/use-bloom/concepts) — sandbox, plans, outbox, policy, petals, and self-custody. - [Quickstart](/use-bloom/quickstart) — the shortest agent-led onboarding path. -- [Safety and approvals](/use-bloom/safety-and-approvals) — how staging, policy, approval, signing, and audit logs work. -- [Policies](/use-bloom/policies) — the rules that limit what agents can do. -- [Petals for users](/use-bloom/petals-for-users) — how Bloom grows protocol capabilities. -- [Chains and FAQ](/use-bloom/chains-and-faq) — supported chains, costs, keys, and the bigger picture. +- [FAQ](/use-bloom/faq) — supported chains, costs, keys, and the bigger picture. -## Integrate or operate Bloom +## I want to integrate Bloom -If you are wiring Bloom into an agent environment or local machine: +If you are wiring Bloom into an agent environment, local machine or your existing product: -- [Local build and mount](/getting-started/quickstart) — initialize Bloom and inspect chain state. -- [Agent setup](/getting-started/agent-setup) — rules and discovery commands for agents. +- [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. -## Build on Bloom +## I want to build on Bloom If you are developing Bloom itself or adding protocol capabilities: @@ -82,7 +67,6 @@ If you are developing Bloom itself or adding protocol capabilities: - [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. -- [Petal authoring](/petals/authoring) — the developer surface for building petals. ## The agent setup prompt diff --git a/src/pages/getting-started/agent-setup.mdx b/src/pages/integrators/agent-setup.mdx similarity index 100% rename from src/pages/getting-started/agent-setup.mdx rename to src/pages/integrators/agent-setup.mdx diff --git a/src/pages/integrators/integrating.mdx b/src/pages/integrators/integrating.mdx new file mode 100644 index 0000000..7e203db --- /dev/null +++ b/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. \ No newline at end of file diff --git a/src/pages/getting-started/quickstart.mdx b/src/pages/integrators/quickstart.mdx similarity index 100% rename from src/pages/getting-started/quickstart.mdx rename to src/pages/integrators/quickstart.mdx diff --git a/src/pages/introduction/benefits.mdx b/src/pages/introduction/benefits.mdx index 16ea79b..240c21e 100644 --- a/src/pages/introduction/benefits.mdx +++ b/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 diff --git a/src/pages/introduction/demos.mdx b/src/pages/introduction/demos.mdx new file mode 100644 index 0000000..dd867a2 --- /dev/null +++ b/src/pages/introduction/demos.mdx @@ -0,0 +1,13 @@ +# Demos + +## x402 Paid HTTP Request + +
+