powerloom · anomit · Jun 14, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 26, 2026
diff --git a/.gitignore b/.gitignore
@@ -3,7 +3,7 @@
 
 # Production
 /build
-
+/typesense/
 # Generated files
 .docusaurus
 .cache-loader

diff --git a/docs/Protocol/Protocol_v2/overview.md b/docs/Protocol/Protocol_v2/overview.md
@@ -4,6 +4,10 @@ sidebar_position: 0
 
 # Overview
 
+:::info
+This page documents the Protocol v2 upgrade path and its historical architecture framing. For the live decentralized sequencer-validator network, see [`DSV Mainnet`](/category/dsv-mainnet), especially [`Why DSV Exists`](/dsv-mainnet/why-dsv-exists) and [`Protocol Workflow`](/dsv-mainnet/protocol-workflow).
+:::
+
 
 ## Necessity of an upgrade
 
@@ -30,7 +34,7 @@ The above approach required the snapshotter peers to send out their submissions
 
 ### Composed snapshots finality
 
-A combination of the above couple of issues also affects the [composability principle](/Protocol/data-composition.md) of building higher order snapshots. Dropped transactions and increased delays in confirmation times of snapshot submissions ultimately affect the aggregate data points that power complex use cases like the [Uniswap V2 dashboard](/build-with-powerloom/use-cases/existing-implementations/uniswap-dashboard/) and [Aave V3 dashboard](/build-with-powerloom/use-cases/existing-implementations/aavev3-dashboard/).
+A combination of the above issues also affects the [composability principle](/Protocol/data-composition.md) of building higher order snapshots. Dropped transactions and increased delays in confirmation times of snapshot submissions ultimately affect aggregate data products and downstream consumers.
 
 
 ## Upgraded workflow

diff --git a/docs/Protocol/Protocol_v2/sequencer.md b/docs/Protocol/Protocol_v2/sequencer.md
@@ -5,6 +5,10 @@ sidebar_position: 1
 
 # Sequencer
 
+:::info
+This page describes the Protocol v2 sequencer model. For the live DSV mainnet flow, including two-level validator aggregation and VPA-based submission, see [`Protocol Workflow`](/dsv-mainnet/protocol-workflow) and [`Roles and Topology`](/dsv-mainnet/roles-and-topology).
+:::
+
 :::warning
 The sequencer listening interfaces for specific data markets are listed in the following trusted sequencer JSON file hosted on the Powerloom Github repository:
 

diff --git a/docs/Protocol/Protocol_v2/validator.md b/docs/Protocol/Protocol_v2/validator.md
@@ -4,6 +4,10 @@ sidebar_position: 3
 
 # Validator
 
+:::info
+This page describes the Protocol v2 validator flow. For the live DSV mainnet consensus path, see [`Protocol Workflow`](/dsv-mainnet/protocol-workflow), [`On-Chain Submission and Verification`](/dsv-mainnet/onchain-submission-and-verification), and [`Stability and Scale`](/dsv-mainnet/stability-and-scale).
+:::
+
 ## Overview
 
 ![Protocol V2 validator worklow](/images/validator-workflow.png)

diff --git a/docs/Protocol/Specifications/Snapshotter/components.md b/docs/Protocol/Specifications/Snapshotter/components.md
@@ -113,4 +113,4 @@ In the end,
 
 Its API endpoints are used by a decoupled frontend adapter logic that ultimately support building of rich data products for smart contracts and other web3 based applications. 
 
-In our [`All about Data` section of docs](/build-with-powerloom/snapshotter-node/data), find out more about the way this API is used by a frontend adapter to serve the Uniswap V2, Uniswap V3, and Aave V3 dashboards.
+In the [`All about Data` section](/build-with-powerloom/snapshotter-node/data), learn how resolver APIs serve finalized data while preserving verification metadata for applications and agents.
diff --git a/docs/Protocol/Specifications/Snapshotter/snapshot-build.md b/docs/Protocol/Specifications/Snapshotter/snapshot-build.md
@@ -7,7 +7,7 @@ sidebar_position: 2
 ## Snapshot Computation Modules
 ---
 
-As briefly introduced in the section on Snapshotter implementations that [leverage Git Submodules for specific computation logic](/build-with-powerloom/snapshotter-node/architecture), the modules are specified in the configuration for project types under the key `processor`.
+As briefly introduced in the section on [Snapshotter architecture](/build-with-powerloom/snapshotter-node/architecture), compute modules are pulled into the node runtime by setup scripts and are specified in the configuration for project types under the key `processor`.
 
 ```json reference
 https://github.com/powerloom/snapshotter-configs/blob/39e4713cdd96fff99d100f1dea7fb7332df9e491/projects.example.json#L15-L28
@@ -102,7 +102,7 @@ https://github.com/powerloom/pooler/blob/634610801a7fcbd8d863f2e72a04aa8204d27d0
 
 ### Example of snapshot computation
 
-#### Base snapshot of trade events for the [Uniswap V2 and V3 dashboard data markets](/category/uniswap-dashboard):
+#### Base snapshot of trade events:
 ```python reference
 https://github.com/powerloom/snapshotter-computes/blob/6fb98b1bbc22be8b5aba8bdc860004d35786f4df/trade_volume.py#L14-L44
 ```
@@ -111,13 +111,13 @@ https://github.com/powerloom/snapshotter-computes/blob/6fb98b1bbc22be8b5aba8bdc8
 ## Aggregate Snapshots
 ---
 
-Aggregate and higher-order snapshots that build on base snapshots are configured in their specific repositories, such as the following in our [Uniswap Dashboard use case](/category/uniswap-dashboard). This is where you can observe the [dependency graph of snapshot composition](/Protocol/data-composition#dependency-graph) in action.
+Aggregate and higher-order snapshots that build on base snapshots are configured in market-specific repositories. This is where you can observe the [dependency graph of snapshot composition](/Protocol/data-composition#dependency-graph) in action.
 
 :::info
 
 - [Single Project Composition](/Protocol/data-composition#single-project-composition)
 - [Multi-Project Composition](/Protocol/data-composition#multiple-projects-composition)
-- [Walkthrough of the Snapshotter Implementation for the Uniswap V2 and V3 Dashboards](/build-with-powerloom/use-cases/existing-implementations/uniswap-dashboard/)
+- [BDS Data Market](/category/bds-data-market)
 :::
 
 The order and dependencies of these compositions are specified according to the `aggregate_on` key.
@@ -133,7 +133,7 @@ https://github.com/powerloom/snapshotter-configs/blob/fcf9b852bac9694258d7afcd8b
   * For example, a base snapshot built on a project ID like `pairContract_trade_volume:0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc:UNISWAPV2` triggers the worker `AggregateTradeVolumeProcessor` as defined in the `processor` config, against the pair contract `0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc`.
 * The span of epochs on which corresponding base snapshots will be aggregated is determined by the logic contained in the module specified in the `processor` key.
 
-The following implementation aggregates [trade volume snapshots](/build-with-powerloom/use-cases/existing-implementations/uniswap-dashboard/closer-look-at-snapshots.md) across a span of 24 hours worth of epochs, if available. Otherwise, it aggregates the entire span of epochs available on the protocol against the data market and reports it back.
+The following implementation aggregates trade volume snapshots across a span of 24 hours worth of epochs, if available. Otherwise, it aggregates the entire span of epochs available on the protocol against the data market and reports it back.
 
 
 ```python reference

diff --git a/docs/Protocol/Specifications/state-v1.md b/docs/Protocol/Specifications/state-v1.md
@@ -130,4 +130,4 @@ event SnapshotFinalized(uint256 indexed epochId, uint256 epochEnd, string projec
 ## See Also
 ---
 
-* [Build with Powerloom – All about data](/build-with-powerloom/snapshotter-node/data.md#verifying-data)
+* [Build with Powerloom – All about data](/build-with-powerloom/snapshotter-node/data.md)
diff --git a/docs/Protocol/Specifications/state-v2.md b/docs/Protocol/Specifications/state-v2.md
@@ -4,6 +4,10 @@ sidebar_position: 1
 
 # Protocol State: V2
 
+:::info
+This page documents the Protocol v2 state model. For the live DSV mainnet submission and verification path, see [`On-Chain Submission and Verification`](/dsv-mainnet/onchain-submission-and-verification) and [`Why DSV Exists`](/dsv-mainnet/why-dsv-exists).
+:::
+
 ## Overview: Smart Contract Architecture
 
 The smart contracts that maintain the state of the protocol V2 interact are arranged as depicted in the diagram that follows.

diff --git a/docs/Protocol/data-composition.md b/docs/Protocol/data-composition.md
@@ -24,7 +24,7 @@ As defined by the data sources configuration, the protocol state collects snapsh
 
 ## Higher-Order Aggregations
 
-An example of this can be found in the [Uniswap V2 and V3 dashboard implementation](/build-with-powerloom/use-cases/existing-implementations/uniswap-dashboard/), where a trade activity aggregation dataset is generated by:
+A market can generate higher-order aggregation datasets by:
 
 - Combining individual snapshots of trade volume and fees across multiple pair contracts.
 - Spanning a specific set of epochs that satisfy a time duration (e.g., 24 hours).

diff --git a/docs/Protocol/data-sources.md b/docs/Protocol/data-sources.md
@@ -11,18 +11,15 @@ The data sources defined by a market can be static or dynamic, depending on the
 
 ## Static Data Sources
 
-Our implementation of a data market serves datasets to render live Uniswap V2, Uniswap V3, and Aave V3 dashboards. Further details about the data source configurations and snapshot schemas can be found in the following sections of our documentation:
+Static data sources are useful when a market tracks a known set of contracts. In the current BDS market, snapshotter nodes track active Uniswap V3 pools on Ethereum mainnet and submit market-specific snapshots for DSV finalization.
 
-* [Building with Powerloom -- Uniswap V2 and V3 Dashboards](/build-with-powerloom/use-cases/existing-implementations/uniswap-dashboard/)
-* [Building with Powerloom -- Aave V3 Dashboard](/build-with-powerloom/use-cases/existing-implementations/aavev3-dashboard/)
-
-Continuing with the Uniswap V2 example, you can explore the data sources list defined as part of the Uniswap v2 specific configuration in the [`snapshotter-configs`](https://github.com/powerloom/snapshotter-configs/blob/fcf9b852bac9694258d7afcd8beeaa4cf961c65f/projects.example.json#L1-L11) repository.
+You can explore an older static configuration example in the [`snapshotter-configs`](https://github.com/powerloom/snapshotter-configs/blob/fcf9b852bac9694258d7afcd8beeaa4cf961c65f/projects.example.json#L1-L11) repository.
 
 ```json reference
 https://github.com/powerloom/snapshotter-configs/blob/fcf9b852bac9694258d7afcd8beeaa4cf961c65f/projects.example.json#L1-L11
 ```
 
-The `projects` field in the above configuration snippet represents the Uniswap v2 pair contract addresses that are tracked, and snapshots are generated for these contracts. To further understand how snapshots on these contracts are tracked, refer to the section on [Project Types and IDs](#project-types-and-ids).
+The `projects` field in the above configuration snippet represents contract addresses that are tracked, and snapshots are generated for those contracts. To further understand how snapshots on these contracts are tracked, refer to the section on [Project Types and IDs](#project-types-and-ids).
 
 ## Dynamic Data Sources
 

diff --git a/docs/agents-and-bds/_category_.json b/docs/agents-and-bds/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Agents & BDS",
+  "position": 1.7,
+  "link": {
+    "type": "generated-index"
+  }
+}
diff --git a/docs/agents-and-bds/aeon-whale-radar.md b/docs/agents-and-bds/aeon-whale-radar.md
@@ -0,0 +1,209 @@
+---
+sidebar_position: 5
+title: Aeon Whale Radar (GitHub Actions)
+---
+
+# Aeon Whale Radar — GitHub Actions Setup
+
+Run verified Uniswap V3 whale alerts on a schedule using [Aeon](https://github.com/aaronjmars/aeon) + the [aeon-skills](https://github.com/powerloom/aeon-skills) package. Python prefetch owns BDS fetch and epoch cursor; the LLM only dispatches pre-built alerts via `./notify`. No VPS, no MCP server, no cron server.
+
+**Skill repository:** [github.com/powerloom/aeon-skills](https://github.com/powerloom/aeon-skills)
+
+---
+
+## What you get
+
+- Per-block BDS snapshot catch-up (`GET /mpp/snapshot/allTrades/{block}`)
+- Deterministic cursor in `memory/powerloom-bds-state.json` (auto-committed)
+- LLM only dispatches pre-built alerts — no sandbox fetch, no cursor hallucination
+- OpenClaw `whale-cron.mjs` parity, adapted for GitHub Actions
+- Alerts delivered to Telegram, Discord, or Slack via Aeon `./notify`
+
+## Prerequisites
+
+1. A GitHub account
+2. BDS API key (`sk_live_...`) from [metering signup](./metering-and-api-keys.md#browser-signup-free--2-credits-included) (2 free credits)
+3. At least one notify channel (Telegram bot token + chat ID, Discord webhook, or Slack webhook)
+
+---
+
+## Step 1 — Fork Aeon and enable Actions
+
+Go to [github.com/aaronjmars/aeon](https://github.com/aaronjmars/aeon) and click **Fork**. Clone your fork locally.
+
+GitHub disables Actions on new forks by default. Go to your fork → **Settings → Actions → General** and enable workflow runs:
+
+![Enable GitHub Actions on the Aeon fork — Settings → Actions → General, allow workflows](/images/bds-agentic-workflow/aeon-fork-enable-actions.png)
+
+---
+
+## Step 2 — Install the powerloom-bds skill
+
+Clone the skill repo and run the installer against your Aeon fork:
+
+```bash
+git clone https://github.com/powerloom/aeon-skills.git
+cd your-aeon-fork   # must contain aeon.yml at repo root
+
+/path/to/aeon-skills/install-into-aeon.sh
+```
+
+**Usage note:** The script defaults to `$(pwd)` when no argument is given — so **cd into your Aeon fork first**, or pass the fork path explicitly:
+
+```bash
+/path/to/aeon-skills/install-into-aeon.sh /path/to/your-aeon-fork
+```
+
+This copies:
+
+| Source | Destination |
+|--------|-------------|
+| `powerloom-bds/` | `skills/powerloom-bds/` |
+| 5 scripts | `scripts/prefetch-bds.sh`, `fetch-bds-epochs.py`, `bds_normalize.py`, `process-bds-skill.py`, `postprocess-bds.sh` |
+
+It also runs `patch-aeon-fork.sh` (`.gitignore`, workflow env, commit allowlist).
+
+---
+
+## Step 3 — Enable the skill in aeon.yml
+
+Open `aeon.yml` in your fork root. Under `skills:`, add:
+
+```yaml
+  powerloom-bds: { enabled: true, schedule: "*/5 * * * *" }
+```
+
+The schedule is cron syntax. `*/5` runs every 5 minutes, but Aeon's scheduler dedup typically gives you an effective ~15 minute cadence, which is fine for whale radar.
+
+![aeon.yml with powerloom-bds skill enabled — add the skill entry under the skills block](/images/bds-agentic-workflow/aeon-yml-skill-enabled.png)
+
+---
+
+## Step 4 — Set GitHub secrets
+
+In your fork: **Settings → Secrets and variables → Actions → New repository secret**
+
+| Secret | Required | Value |
+|--------|----------|-------|
+| `BDS_API_KEY` | **Yes** | `sk_live_...` from [metering signup](./metering-and-api-keys.md#browser-signup-free--2-credits-included) |
+| `TELEGRAM_BOT_TOKEN` | For TG alerts | Your Telegram bot token from @BotFather |
+| `TELEGRAM_CHAT_ID` | For TG alerts | Target chat ID (use @userchatidbot to find it) |
+| `DISCORD_WEBHOOK_URL` | For Discord | Webhook URL from your Discord channel settings |
+
+If you want Telegram alerts, set both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`. For Discord, set `DISCORD_WEBHOOK_URL`. For Slack, set `SLACK_WEBHOOK_URL`. At least one notify channel is required, otherwise alerts go nowhere.
+
+![GitHub secrets configured in the Aeon fork — BDS_API_KEY plus Telegram bot token and chat ID](/images/bds-agentic-workflow/aeon-fork-github-secrets.png)
+
+:::note
+Vanilla Aeon does **not** pass `BDS_API_KEY` into the prefetch step automatically. The `patch-aeon-fork.sh` script (run by the installer) adds it to the workflow env block. If you skipped patching, add this under the prefetch step in `.github/workflows/aeon.yml`:
+
+```yaml
+          BDS_API_KEY: ${{ secrets.BDS_API_KEY }}
+```
+:::
+
+---
+
+## Step 5 — Optional: configure whale threshold
+
+```bash
+cp templates/powerloom-bds.yml.example memory/powerloom-bds.yml
+```
+
+Edit `thresholds.whale_usd` (default `25000`). Lower values (e.g. `5000`) produce more alerts; higher values filter to larger trades only. If the file is missing, prefetch creates a default at `whale_usd: 25000`.
+
+---
+
+## Step 6 — Commit and push
+
+```bash
+git add skills/powerloom-bds scripts/prefetch-bds.sh scripts/fetch-bds-epochs.py \
+        scripts/bds_normalize.py scripts/process-bds-skill.py scripts/postprocess-bds.sh \
+        .gitignore aeon.yml
+# include .github/workflows/aeon.yml if patch-aeon-fork changed it
+git commit -m "Add powerloom-bds whale radar skill"
+git push
+```
+
+Ensure `.bds-cache/` is **not** tracked (ephemeral, wiped each run).
+
+---
+
+## Step 7 — Verify first run
+
+Go to **Actions → aeon** workflow in your fork and trigger a run (or wait for cron). Select the `powerloom-bds` skill run and check the logs.
+
+Healthy prefetch output:
+
+```
+Cursor lastStreamEpoch=25185635 → fetch from block 25185636
+Fetched 5 snapshot(s): 25185636 - 25185640
+process-bds-skill: epochs=5 trades=82 alerts=27 cursor=25185640
+```
+
+First run with no cursor fetches the **latest finalized epoch only**. Subsequent runs catch up block-by-block (max 100 per run). Silent runs ("no alerts") are normal when no swap exceeds your threshold.
+
+![First successful Aeon run — prefetch log shows fetched snapshots, trades, and alerts count](/images/bds-agentic-workflow/aeon-first-run-healthy.png)
+
+![Successful Aeon run — Telegram alerts delivered](/images/bds-agentic-workflow/aeon-first-run-telegram-alerts.png)
+
+---
+
+## Fetch model
+
+The prefetch script calls:
+
+```http
+GET /mpp/snapshot/allTrades/{block_number}
+Authorization: Bearer sk_live_...
+```
+
+It loops from `lastStreamEpoch + 1` through the latest finalized block (cap 100 blocks per run). This is the same per-block catch-up model as OpenClaw `whale-cron.mjs`.
+
+**Do not use** query param forms like `/mpp/snapshot/allTrades?from_epoch=N` — the API catalog does not support them for this use case.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `BDS_API_KEY not set` in prefetch | Add the secret in fork Settings; ensure `patch-aeon-fork.sh` ran or add env mapping manually in `.github/workflows/aeon.yml` |
+| `Fetched N snapshots` but `trades=0` always | Wrong API path — must be `/mpp/snapshot/allTrades/{block}`, not `?from_epoch=` |
+| Cursor never advances | Add `memory/powerloom-bds-state.json` to workflow auto-commit allowlist (patch script does this) |
+| Telegram formatting broken | Use the shipped alert template (project slug only in verification footer) |
+| Alerts with gaps / years apart | Tip-only sampling bug — reinstall scripts from aeon-skills |
+
+---
+
+## Comparison with OpenClaw whale-cron
+
+| | OpenClaw `whale-cron.mjs` | Aeon `powerloom-bds` |
+|--|---------------------------|----------------------|
+| Runtime | VPS / local OpenClaw | GitHub Actions |
+| Fetch | MCP `bds_mpp_snapshot_allTrades/{block}` | Prefetch `GET /mpp/snapshot/allTrades/{block}` |
+| Cursor | `.powerloom/whale-cron-state.json` | `memory/powerloom-bds-state.json` (git-committed) |
+| Agent role | Node script only | Python prefetch + LLM notify dispatch |
+| Infrastructure | Your server | GitHub (free for public repos) |
+
+Both use **per-block snapshot catch-up**. Both produce alerts with the same verification block (CID + epoch + project slug).
+
+---
+
+## Re-sync after aeon-skills updates
+
+```bash
+cd your-aeon-fork
+/path/to/aeon-skills/install-into-aeon.sh
+git diff   # review, commit, push
+```
+
+---
+
+## Related pages
+
+- [`Metering & API Keys`](./metering-and-api-keys.md)
+- [`Quickstart`](./quickstart.md)
+- [`OpenClaw & Hosted MCP`](./openclaw-and-mcp.md)
+- [`Verification in Agent Workflows`](./verification-in-agents.md)
+- [aeon-skills repository](https://github.com/powerloom/aeon-skills)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -113,4 +113,4 @@ In the end,

		Its API endpoints are used by a decoupled frontend adapter logic that ultimately support building of rich data products for smart contracts and other web3 based applications.

		In our [`All about Data` section of docs](/build-with-powerloom/snapshotter-node/data), find out more about the way this API is used by a frontend adapter to serve the Uniswap V2, Uniswap V3, and Aave V3 dashboards.
		In the [`All about Data` section](/build-with-powerloom/snapshotter-node/data), learn how resolver APIs serve finalized data while preserving verification metadata for applications and agents.