Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
159 commits
Select commit Hold shift + click to select a range
44bcebc
Unify text truncation behind a single Truncate primitive (#3660)
tom2drum Aug 25, 2026
d421410
Add a Slack reply watcher to the product-task workflow (#3662)
tom2drum Aug 25, 2026
d435795
update hooks for new claude worktree creation
tom2drum Aug 26, 2026
ce266aa
fixes for "resolve config request" skill
tom2drum Aug 27, 2026
cc81b4c
update comments rule
tom2drum Aug 27, 2026
6fabbb0
Surface batch-transaction recipients in the tx details To & Value fie…
tom2drum Aug 27, 2026
b02ec7f
Silence dotenv injection banner in vitest setup
tom2drum Aug 27, 2026
108298e
update unit test command list
tom2drum Aug 27, 2026
1089d07
Update styles for "In/Out/Self" badges (#3672)
tom2drum Aug 28, 2026
c69e275
Main page stats failover improvements (#3673)
tom2drum Aug 31, 2026
3c86fac
update comments guid
tom2drum Aug 31, 2026
65c8004
Add a cognitive-complexity and CRAP-score CI gate (#3670)
tom2drum Aug 31, 2026
128c7e2
Reserve the .tsx extension for files that contain JSX (#3676)
tom2drum Aug 31, 2026
90786ea
Fixes for Release v2.11.0 (#3669)
tom2drum Sep 1, 2026
468d8cc
Restructure the code-complexity tool into pipeline stages (#3677)
tom2drum Sep 1, 2026
0a247b8
Scope every interchain request to the deployment's slice of the share…
tom2drum Sep 7, 2026
35ffd9f
add docs rule
tom2drum Sep 7, 2026
6f32b11
add adr template
tom2drum Sep 7, 2026
e4eb31b
Measure test assertion strength with mutation testing (#3678)
tom2drum Sep 7, 2026
80cb1ea
Let operators pick Flashblocks or Subblocks naming for the OP Stack f…
pcw109550 Sep 7, 2026
b706c9e
Add Alexey to the Core API roster
tom2drum Sep 7, 2026
76fe517
update release version in docs
tom2drum Sep 7, 2026
fb9e7b5
Rework the review skills: explicit inputs, a task-folder output mode,…
tom2drum Sep 8, 2026
a7e677e
Let operators pick which color themes an explorer offers (#3691)
tom2drum Sep 8, 2026
f3a8ade
Point Hardhat and Foundry verification instructions at the Pro API on…
tom2drum Sep 9, 2026
d5297d0
remove mutation testing from code quality rules
tom2drum Sep 9, 2026
419b82e
update "add env var" skill
tom2drum Sep 9, 2026
cfd773e
Rewrite the tools/ scripts in TypeScript so they are type-checked, te…
tom2drum Sep 9, 2026
a7d5ce1
Let operators set the label on the DeFi dropdown button (#3695)
tom2drum Sep 10, 2026
bf60f9e
Enforce the app-config convention with ESLint rules (#3699)
tom2drum Sep 10, 2026
4806caf
fix skeleton loading state when text leaked due to color prop override
tom2drum Sep 11, 2026
3f0ee77
Add Playwright MCP server for agent browser checks
tom2drum Sep 11, 2026
9e2d3b5
add .worktreeinclude file
tom2drum Sep 14, 2026
ceb0ede
Take cross-chain list totals and the 24h widget from the stats servic…
tom2drum Sep 14, 2026
116d8fd
Add a configurable action button to ERC-20 token pages (#3692)
tom2drum Sep 14, 2026
28deac1
[skip ci] clean .env.extra
tom2drum Sep 14, 2026
6a9c38d
Fix page crash on token transfer rows whose token is null (#3705)
tom2drum Sep 14, 2026
a766e00
Make the URL the single source of truth for paginated lists and stop …
tom2drum Sep 15, 2026
2d57394
Select Playwright component tests with Playwright's --only-changed an…
tom2drum Sep 15, 2026
89a60c6
Move proxy.ts under src/ so Next.js runs the proxy again (#3708)
tom2drum Sep 16, 2026
19543f6
Show the transaction not-found screen on every tab, not only Details …
tom2drum Sep 16, 2026
0dfdef7
Tighten the magic-numbers rule so agents name a literal only when the…
tom2drum Sep 16, 2026
97daca7
Tell agents to extend and pack Playwright suites instead of adding a …
tom2drum Sep 16, 2026
7f50b55
Show the L2 timestamp of Super Root dispute games on the OP dispute g…
tom2drum Sep 16, 2026
2c36019
Fix the home page RPC fallback not starting when only one widget lose…
tom2drum Sep 17, 2026
2332d78
Fix address highlight getting stuck after a brief first hover (#3714)
tom2drum Sep 17, 2026
1391d57
Add a React Doctor check that blocks pull requests on new React bugs …
tom2drum Sep 17, 2026
ef8c2e6
Add token-transfer tooltips to advanced filter from/to addresses (#3701)
Sophran-fbj Sep 18, 2026
545bd02
Fix React bugs surfaced by the React Doctor backlog scan (#3716)
tom2drum Sep 18, 2026
322ce81
Stop the server-side pageview ping from logging unhandled rejections …
tom2drum Sep 18, 2026
9f0d0eb
add /ds-bundle to gitignore
tom2drum Sep 18, 2026
109ab84
Fix the white flash on reload for explorers with a default dark theme…
tom2drum Sep 18, 2026
264c7b3
lazy mount pool links popover
tom2drum Sep 21, 2026
13c0090
Upgrade Node.js to v24, pnpm to v12 and Vitest to v5 (#3721)
tom2drum Sep 21, 2026
d4c3bdd
Track header banner link clicks in Mixpanel (#3719)
ulyanas Sep 21, 2026
2883e78
Patch Stryker's Vitest runner for Vitest 5 test names
tom2drum Sep 21, 2026
02f3c54
Fix the Playwright Docker runner's pnpm activation
tom2drum Sep 21, 2026
cabe2e1
Allow Google Ad Manager hosts for Sevio ad zones in the CSP (#3725)
tom2drum Sep 22, 2026
fb31309
Replace the per-axis word cap in the agent code review with a per-fin…
tom2drum Sep 22, 2026
a2c5681
Replace mobile list views with table views across the app (#3723)
tom2drum Sep 23, 2026
0719a17
Migrate Swap to the official LI.FI widget (#3710)
maxaleks Sep 23, 2026
91eadd6
Open external marketplace dapps directly instead of embedding them (#…
tom2drum Sep 23, 2026
85c80de
Collect Slack message conventions in an on-demand agent doc (#3730)
tom2drum Sep 23, 2026
5a7e5e3
Add OP Stack transaction type labels (#3659)
nonsense Sep 28, 2026
a4a36c2
UI: Display of statistics tiles on mobile (#3735)
tom2drum Sep 28, 2026
279ea3c
Allow choosing full or icon view per multichain portfolio provider an…
tom2drum Sep 28, 2026
1c961c7
Scale ERC-8056 token amounts by the token's UI multiplier (#3700)
tom2drum Sep 28, 2026
6a8ac4e
Bump Next.js to v16.3.5 (#3739)
tom2drum Sep 28, 2026
a1295bc
Pilot a typed-judgment screen as a fourth subagent in the agent code …
tom2drum Sep 29, 2026
c71b256
Make the app action button a header element on token, NFT and transac…
tom2drum Sep 29, 2026
dec85c8
[skip ci] rollback "skip validation" env for review
tom2drum Sep 29, 2026
64b6a30
Prefer the configured default color theme over the OS preference on a…
tom2drum Sep 29, 2026
67bc406
Make flaky Playwright component tests deterministic (#3742)
tom2drum Sep 30, 2026
0abc566
Neutral default colors for selected elements, navigation and top bar …
tom2drum Sep 30, 2026
96d76d4
Support the xDai bridge and native tokens in cross-chain transactions…
tom2drum Sep 30, 2026
3a2cd33
chore: prepare release v2.12.0
tom2drum Sep 30, 2026
f84bd33
Bring envs-validator under the root toolchain and migrate its tests t…
tom2drum Oct 1, 2026
6a5325a
Support external asset URLs without a file extension (#3749)
tom2drum Oct 1, 2026
d02a007
Replace yup with valibot in envs-validator (#3750)
tom2drum Oct 1, 2026
a909553
Trunk-based release workflow with labeled PRs and traceable backports…
tom2drum Oct 5, 2026
4617edb
Prune dead instances from the dev server presets registry
tom2drum Oct 5, 2026
abf7d36
Add slack-subscribe skill: route Slack thread replies through the Hon…
tom2drum Oct 5, 2026
668af8c
Add PostHog as an optional product analytics provider (#3755)
tom2drum Oct 6, 2026
6b91209
resolve config request skill: more specific PR merge instructions
tom2drum Oct 6, 2026
d870015
Fix withdrawals counter showing the sum in wei instead of the native …
tom2drum Oct 7, 2026
0c21ef0
Fix the white flash on reload in Firefox for explorers with a dark th…
tom2drum Oct 7, 2026
9438622
Move the generic Run by Honk contract into a shared agent doc (#3764)
tom2drum Oct 7, 2026
3e6a421
Fix code editor crash when contract sources repeat a file path (#3765)
tom2drum Oct 8, 2026
16a41cf
Add triage-monitoring-event skill and drop the confirmation gate from…
tom2drum Oct 9, 2026
56ff467
Fix search on the bridged tokens tab when cross-chain txs are enabled…
tom2drum Oct 9, 2026
5cb3a48
update TEAM.md
tom2drum Oct 12, 2026
1e42f0a
Stop reporting WalletConnect relay errors caused by a wrong device cl…
tom2drum Oct 12, 2026
92839c5
Add env var to hide the Forked and Uncles tabs on the blocks page (#3…
tom2drum Oct 12, 2026
8c62238
remove update npm step when publishing toolkit
tom2drum Oct 12, 2026
b14ac0e
trim multiplier value in tables
tom2drum Oct 6, 2026
ff34d2b
Unify the token transfers tables into one configurable table (#3752)
tom2drum Oct 12, 2026
c30b59d
Document all issue and PR labels in one place (#3773)
tom2drum Oct 12, 2026
66caeae
Add a skill for diagnosing and fixing reported bugs (#3774)
tom2drum Oct 13, 2026
1206cf4
Tune the review-screen rubric for comment and doc-restating findings …
tom2drum Oct 13, 2026
da25e8a
Mount verify-with links immediately and rename the trigger (#3780)
tom2drum Oct 14, 2026
a2bf1ed
Add a design-readout tool and skill that maps Figma nodes to repo com…
tom2drum Oct 14, 2026
1c86bfc
Tables: padding (desktop & mobile) (#3779)
tom2drum Oct 14, 2026
2dc5867
Make list row keys collision-proof with a shared unique-keys helper (…
tom2drum Oct 15, 2026
45d4893
Bump Next.js version to mitigate security alerts (#3784)
tom2drum Oct 15, 2026
dc6692a
Derive line chart x-axis ticks from data points and resolution (#3783)
tom2drum Oct 15, 2026
6161f81
updates on eslint alternatives research
tom2drum Oct 15, 2026
d0172c7
Upgrade verified-fetch and load NFT images from IPFS through fixed ga…
tom2drum Oct 15, 2026
4db7c2b
Make the review-screen report answer threshold, question or glob for …
tom2drum Oct 15, 2026
a73d1fa
Serialize mutation-testing runs per checkout with a lock file (#3786)
tom2drum Oct 15, 2026
20d7581
Register the dynamic wallet hooks eagerly so a tab panel never suspen…
tom2drum Oct 16, 2026
3f6b548
Let lint:eslint take paths or --changed instead of always linting the…
tom2drum Oct 16, 2026
1288a6b
Remove block number sorting from the global transactions list (#3792)
tom2drum Oct 16, 2026
644e872
Add TypeScript rules for constructive types, narrowing, and derived s…
tom2drum Oct 16, 2026
b5d6d73
Bring every deploy/tools package under ESLint, the root type-check an…
tom2drum Oct 16, 2026
c7d68dc
Make TypeScript 7 the only type-checker, with an ADR for the TypeScri…
tom2drum Oct 19, 2026
d007aa0
Resolve Playwright mock URLs in the browser and fail tests on unmocke…
tom2drum Oct 19, 2026
81f6420
Fix the release tool failing to build the notes when the branch holds…
tom2drum Oct 19, 2026
b4d8c0d
Show the rate-limit screen instead of crashing when no reCAPTCHA site…
tom2drum Oct 20, 2026
fbec9aa
chore: prepare release v2.12.1
tom2drum Oct 19, 2026
9da65ac
chore: prepare release v2.12.1
tom2drum Oct 19, 2026
74610c6
update claude enabled plugins
tom2drum Oct 20, 2026
c08fbcc
Limit the implement-ticket "record my corrections" hand-off to style …
tom2drum Oct 21, 2026
1fdd5fd
Add a Show zero-value txs switch to internal transaction lists (#3805)
tom2drum Oct 22, 2026
8aea9f3
Add a Bubblemaps holder map sub-tab to the token Holders tab (#3807)
tom2drum Oct 22, 2026
c55ec91
Show the incoming-blocks counter on the home page and a compact netwo…
tom2drum Oct 22, 2026
18d9be9
Scope GITHUB_TOKEN permissions for the pre-release publish_image job …
tom2drum Oct 23, 2026
794fe8d
Verify rendering in the browser before hand-off, prefer style props o…
tom2drum Oct 26, 2026
49b39bf
Show one tooltip on a truncated address tag that has a source tooltip…
tom2drum Oct 26, 2026
2f17ea7
Send user profile props with the identify call and make the uuid cook…
tom2drum Oct 27, 2026
11be536
Fix the API docs page crashing on the GraphQL tab on instances withou…
tom2drum Oct 27, 2026
543f226
Serve Specify ads to visitors without a connected wallet by migrating…
tom2drum Oct 27, 2026
ebae6e8
Debrief the weekly sync into the task workflow and fold task inboxes …
tom2drum Oct 27, 2026
707a46e
Add source chain, destination chain and protocol filters to cross-cha…
tom2drum Oct 28, 2026
27d5b58
Check downloaded asset content before serving it from the frontend co…
tom2drum Oct 28, 2026
44aef89
Add an "Auto (System)" color theme that follows the OS color scheme (…
tom2drum Oct 29, 2026
a152be5
Automate the post-finalize review loop, CI fixes and demo deploys for…
tom2drum Oct 30, 2026
0668cb7
Show the env-configured action button on ERC-20 token pages unless th…
tom2drum Nov 2, 2026
745109c
Revert the "Show zero-value txs" switch on internal transaction lists…
tom2drum Nov 2, 2026
d114d76
Bump Vite to 8 and Playwright to 1.62.1 (#3825)
tom2drum Nov 2, 2026
93083fc
Rename "PRO API" to "Blockscout API" across the app (#3826)
tom2drum Nov 2, 2026
42f58c6
Bump Next.js to 16.4.3 (#3829)
tom2drum Nov 2, 2026
e0b62bc
Add research note on migrating from Next.js to TanStack Start
tom2drum Nov 2, 2026
ca2b7b3
Drop the Stryker Vitest runner patch by upgrading Stryker to 10.1.1 (…
tom2drum Nov 2, 2026
b5cd62f
Co-locate the tools/scripts entry points with the tools they drive (#…
tom2drum Nov 3, 2026
9cbd606
Fix doubled border on the selected segmented control item (#3836)
tom2drum Nov 3, 2026
cb3f039
Disable the Turbopack shared runtime so production pages pass the CSP…
tom2drum Nov 3, 2026
2a7a29f
Move the Tokens page filter and pagination into the tab content (#3837)
tom2drum Nov 3, 2026
b1a5a5c
Introduce a framework-neutral router facade and make the UI toolkit r…
tom2drum Nov 3, 2026
17642be
Add an Advanced site settings modal with a user-defined RPC node (#3809)
tom2drum Nov 4, 2026
4d82d38
chore: prepare release v2.13.0
tom2drum Nov 4, 2026
de6da84
Show a scam warning on the address page for addresses flagged as scam…
tom2drum Nov 9, 2026
ca8b3b2
Publish the pre-release at the first alpha and fix release notes on t…
tom2drum Nov 9, 2026
37c10b7
Keep the pagination on the filter row in a transaction's token transf…
tom2drum Nov 9, 2026
eceeba4
Replace the expired Discord invite link with the permanent one (#3857)
tom2drum Nov 9, 2026
156c06d
Remove the empty gap under the Blocks title on mobile when Forked and…
tom2drum Nov 9, 2026
086161d
Show rotating header banners whose HTML has quoted attributes (#3852)
tom2drum Nov 9, 2026
f560612
Limit the header maintenance alert to safe HTML and block external fo…
tom2drum Nov 10, 2026
d3cfa7a
Show the selected chain's native coin in the multichain Top accounts …
tom2drum Nov 11, 2026
415dc16
WIP: Merge upstream v2.13.0 (has conflicts)
github-actions[bot] Nov 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
45 changes: 27 additions & 18 deletions .agents/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ See `./rules/design-system.md` for Chakra UI v3 design system configuration and

## Code Style & Quality

See `./rules/code-quality.md` for code style, lint commands plus conventions linters don't catch.
See `./rules/code-quality.md` for code style, lint commands plus conventions linters don't catch, and the complexity/CRAP scores.

## TypeScript Conventions

Expand All @@ -27,17 +27,18 @@ See `./rules/env-vars.md` for where environment variables live, how they're deli
## Testing

- Vitest unit tests (`*.spec.ts` / `*.spec.tsx`): See `./rules/tests-unit.md` for purpose, setup, utilities, and conventions.
- Playwright component visual tests (`*.pw.tsx`): See `./rules/tests-visual.md` for purpose, setup, fixtures, and conventions.
- Playwright component visual tests (`*.pw.tsx`): See `./rules/tests-visual.md` for their purpose, when to use them, setup, fixtures, and conventions.

## Running locally

Three ways to start the dev server:
Two ways to start the dev server:

- `pnpm dev:preset <alias>` (e.g. `eth`) — the quickest way to a running app. Fetches a live instance's config over HTTP at startup, so it needs outbound internet. Aliases are defined in `tools/dev-server/registry.json`; how the fetch and env layering work is documented in `tools/dev-server/CONTEXT.md`.
- `pnpm dev:local` — runs against a locally running Blockscout backend, using the committed `tools/dev-server/.env.localhost`.
- `pnpm dev` — plain Next.js dev; needs a hand-written `.env.local` with the instance config.
- `pnpm dev:local` — runs against a locally running Blockscout backend, using the committed `tools/dev-server/.env.localhost`. A hand-written instance config goes in `.env.local`, which wins over it.

Both `dev:preset` and `dev:local` accept `--port <number>` to run on a port other than 3000 (it overrides `NEXT_PUBLIC_APP_PORT`, keeping the generated `envs.js` consistent).
Both accept `--port <number>` to run on a port other than 3000 (it overrides `NEXT_PUBLIC_APP_PORT`, keeping the generated `envs.js` consistent).

`tools/dev-server/` also holds the local production build (`pnpm prod:preset`) and the local docker image (`pnpm build:docker`, `pnpm start:docker:*`) — everything that runs the app on this machine.

Gotchas:

Expand All @@ -49,31 +50,38 @@ Gotchas:
Some directories have a `CONTEXT.md` documenting non-obvious patterns specific to that area. Read the relevant one before working in (or reaching into) that directory:

- `deploy/scripts/` — how the frontend container is built and starts up (Dockerfile stages, entrypoint).
- `deploy/tools/envs-validator/` — startup validation of `NEXT_PUBLIC_*` envs against yup schemas.
- `deploy/tools/envs-validator/` — startup validation of `NEXT_PUBLIC_*` envs against valibot schemas.
- `src/api/` — how a request URL is assembled (resource registry, runtime config, `/node-api/config`) and where resource response types come from.
- `src/config/` — the app-config convention (default-only exports, one import surface, envs read only in config modules), its ESLint enforcement and exemptions.
- `src/features/connect-wallet/` — why the wallet stack is loaded lazily (off the critical path), how account state reaches boot-time consumers before a provider exists, and the connector-mode differences.
- `src/server/primedRequests/` — the early-fetch primer: why it exists, the CSP-driven determinism constraint, its correctness guarantee, and the drift-test contract.
- `src/shared/lists/` — the list helpers shared by tables: the row-key rule and the lazy-render constraint.
- `src/shared/pagination/` — the paginated-list components and utils.
- `src/slices/` — slice ownership model (who owns an entity's rendering).
- `src/sprite/` — SVG sprite build pipeline and which outputs are tracked vs. generated.
- `src/toolkit/` — the `@blockscout/ui-toolkit` workspace package structure.
- `tools/code-complexity/` — the cognitive-complexity / CRAP code-quality gate: what a failure means and how to fix it.
- `tools/design-readout/` — the Figma design readout.
- `tools/dev-server/` — how the dev server and demo deploy get their env vars from a running instance config.
- `tools/doc-links/` — the doc-link checker.
- `tools/mutation-testing/` — the mutation-testing gate for unit-test assertion strength.
- `tools/playwright/` — the runner for Playwright component tests.
- `tools/profiling/` — React render profiling: production profiling build and DevTools trace aggregation.
- `tools/react-doctor/` — the React Doctor PR gate: reading a failure, suppressing a finding, changing the rule allowlist.
- `tools/review-screen/` — the Jev review-screen pilot: what a suspect is, what a run must never do, where the sidecars go.

See `./rules/docs.md` before adding or editing any doc about the code — a `CONTEXT.md`, a file under
`docs/`, a module `README.md`.

If you encounter a `CONTEXT.md` not listed here, read it too (and consider adding it to this list).
## Architecture decision records (ADRs)

## Architecture decision records
See `./rules/adr.md` when proposing or adding a new record.

Decisions with repo-wide consequences are recorded in `.agents/adr/`, named
`<0000>-<slug>.md`. Read the relevant one before changing what it decided — an ADR carries the
evidence and the trade-off, so it answers "why is it like this?" without a git archaeology session.
The repo-wide records index:

- `0002-layer-shaped-ticket-leaves.md` — why a product task's tickets cut vertically while the leaves inside them run along layers.
- `0003-turbopack-for-production-builds.md` — why production builds moved back to Turbopack.

Add a new record (next free number, and a line here) whenever a decision is expensive to rediscover:
it constrains future work, was reached by measurement or an investigation worth not repeating, or
looks wrong without its context. Supersede rather than rewrite — flip the old record's `Status` to
`superseded by <n>` and leave its reasoning intact.
- `0004-typescript-7-side-by-side.md` — why `tsc` is TypeScript 7 while the `typescript` package is TypeScript 6, and when to collapse them.

## Product task workflow

Expand All @@ -89,4 +97,5 @@ rules contract, the per-file symlink Cursor needs, and how references here are c
## Reaching people & channels on Slack

To reach anyone or any channel on Slack, resolve the Slack IDs from `./TEAM.md`. Draft and get approval
before sending anything — unless the skill you are running names an explicit exception.
before sending anything — unless the skill you are running names an explicit exception. Before composing
any Slack message, read `./slack-message.md` (language, addressing, links, attribution).
2 changes: 2 additions & 0 deletions .agents/GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,15 @@ vars are documented in `docs/ENVS.md`. Architectural concepts like
| **Hot Contracts** | feature | Ranked list of the most recently and frequently interacted-with smart contracts on the network. |
| **Interchain Indexer** | service | Microservice that indexes cross-chain messages and token transfers across heterogeneous chains. General-purpose interop indexer, not ZetaChain-specific. Provides "Cross chain txs" feature. Distinct from **CCTX**. |
| **Interop Messages** | entity | **Deprecated** Cross-rollup messages passed between OP Stack chains using the native interoperability protocol. Distinct from **Interchain Indexer** messages. |
| **Jev** | service | TypeSafe's typed-judgment model: answers a structured question (yes/no, a choice) with a probability, never a claim, so whatever consumes a score verifies it before acting on it. |
| **Kettle** | entity | In the **SUAVE** architecture, a Kettle is a trusted execution environment (TEE) node that processes MEV bundles. SUAVE transactions are associated with a Kettle. |
| **Marketplace** | feature | Curated directory of dApps and DeFi applications integrated with Blockscout. |
| **MetaSuites** | service | Third-party browser extension that enhances the Blockscout UI with additional data and links. |
| **Multichain** | feature | Aggregates data across multiple Blockscout-indexed chains into a single explorer view. |
| **Operation** | entity | **TAC**-specific entity representing a bridge operation between the TON and EVM ecosystems. No equivalent on standard EVM chains. |
| **Pools** | entity | DEX liquidity pool positions tracked on-chain. |
| **Public Tags** | feature | Community-submitted labels for addresses, visible on address pages. A sub-feature of **Address Metadata**. |
| **Readout (design readout)** | concept | The mapping of a Figma node to repo components, props and design tokens, with every ambiguous, unrecognized and layout item listed for a developer to resolve before markup. The tool of the same name extracts the values and recognizes signals and tokens; the skill maps those to components — the tool names none. Recognition only, never implementation. |
| **Rewards** | feature | The Blockscout Merits program — a token rewards and incentives system operated by Blockscout. Entirely distinct from **Block Reward** (on-chain block-producer payouts). |
| **Rollup** | concept | A chain that settles transactions on a parent (L1) chain. Introduces specific entities: deposits, withdrawals, transaction batches, output roots. Contrast with **Chain Variant**. |
| **SolidityScan** | service | Third-party smart contract security vulnerability scanner integrated into contract detail pages. |
Expand Down
2 changes: 1 addition & 1 deletion .agents/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ here; each tool reads it through its own directory via symlinks.
| `AGENTS.md` | Always-loaded project context | `.claude/CLAUDE.md` → here; Cursor reads `AGENTS.md` natively |
| `rules/*.md` | Coding rules, scoped to file patterns | `.claude/rules/` and `.cursor/rules/` — see below |
| `skills/*/SKILL.md` | Workflows loaded on invocation | `.claude/skills/` → here |
| `delegation.md`, `GLOSSARY.md`, `TEAM.md`, `slack-thread.md` | Read on demand, by pointer from `AGENTS.md` or a skill | — |
| `delegation.md`, `GLOSSARY.md`, `TEAM.md`, `slack-thread.md`, `slack-message.md`, `honk.md` | Read on demand, by pointer from `AGENTS.md` or a skill | — |
| `tasks/` | Product-task specs — see `tasks/README.md` | — |

Cross-references between all of these are machine-checked: `pnpm lint:doc-links`.
Expand Down
24 changes: 15 additions & 9 deletions .agents/TEAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,7 @@ Slack IDs are stored so addressing is deterministic (no runtime name lookup). Th
identifiers, **not credentials** — knowing one grants no access. To find your own member ID in Slack:
your profile → **⋯ More** → **Copy member ID**. Do not add emails to this file.

## How to address

- **Person** — the *Slack member ID* (`U…`) from the People table. Mention as `<@U…>`; to DM, pass the ID as
the channel to the send tool.
- **Team / group** — the *Slack group ID* (`S…`) from the Groups table. Mention as `<!subteam^S…>`.
- **Channel** — the *Channel ID* (`C…`). Pass it as the channel target when sending; refer to it in prose by
its `#name`.
- **Permalink** — `https://blockscout.slack.com/archives/<channel-id>/p<message-ts>` (the message timestamp
with the dot removed).
How to turn an ID into a mention, a DM target, or a permalink: `./slack-message.md` → Addressing.

## Product managers

Expand Down Expand Up @@ -54,13 +46,20 @@ Own: core API endpoints and response models, field propagation across services,
| --- | --- | --- | --- |
| Victor | @vbaranov | U8L403FEG | ✓ |
| Nikita P. | @nikitosing | U0218K3MTC5 | |
| Alexey | @Qwerty5Uiop | U03EE7T5TJS | |

### Groups

| Team | Slack group ID |
| --- | --- |
| Core API | S064H6TD6MA |

### Channels

| Purpose | Channel | Channel ID |
| --- | --- | --- |
| Default for core API questions | blockscout-elixir | C04NCPZGRAR |

## Microservices API

Own: microservice API endpoints and their response models (metadata, stats, admin, interchain, etc.).
Expand Down Expand Up @@ -98,12 +97,19 @@ Own: architecture, the delegation boundary.
| tom | @tom2drum | U03MN1588AU | ✓ |
| Max | @maxaleks | UKP0RR9K9 | |

### Bots
| Name | Role | Bot ID | But used ID

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

There is a typo in the table header: But used ID should be Bot user ID or User ID.

Suggested change
| Name | Role | Bot ID | But used ID
| Name | Role | Bot ID | Bot user ID |

| --- | --- | --- | --- |
| Rollbar | Post error monitoring events | B0AADAP5PM0 | U0A9XT13GB1 |


### Channels

| Purpose | Channel | Channel ID |
| --- | --- | --- |
| Default for frontend questions | blockscout-frontend | C03MMUTQDNU |
| Ask a frontend engineer to prepare an instance's config | front-config-requests | C08D60ZL1QB |
| Get alert events from the error monitoring system | blockscout-sentry-alerts | C05ULMSURUZ |

### Groups

Expand Down
2 changes: 2 additions & 0 deletions .agents/adr/0003-turbopack-for-production-builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ bundles in less than half the wall-clock (the type-check phase is bundler-agnost
only. The compiler-API path (this flag `false`) checks against `lib/typescript.js`, which the alias
does provide, so type-checking runs normally. Without it the build aborts claiming `typescript` is
missing — on **both** bundlers, since the check runs before bundling.
*Superseded by [0004](0004-typescript-7-side-by-side.md): the flag is gone, Next's check is off.*
- **Dev and production are on the same bundler again.** 0001's "a production-only bug can't be caught
in dev" caveat is lifted for the default path — though the two webpack exceptions (`build:analyze`,
`--profile`) still exercise a second pipeline.
Expand All @@ -96,3 +97,4 @@ bundles in less than half the wall-clock (the type-check phase is bundler-agnost
- The `useTypeScriptCli: false` workaround exists because Next's CLI type-check path does not
recognize the `@typescript/typescript6` alias's `bin/tsc6`. If a later Next release accepts the
native compiler's binary (or the alias ships a `bin/tsc`), the flag can be dropped.
*Superseded by [0004](0004-typescript-7-side-by-side.md).*
9 changes: 9 additions & 0 deletions .agents/adr/0004-typescript-7-side-by-side.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# TypeScript 7 for type-checking, TypeScript 6 for tooling

| | |
| --- | --- |
| Status | Accepted |

## Decision

TypeScript 7 ships `tsc` without the compiler API that `typescript-eslint`, `vite-plugin-dts` and Next's build-time check need, so `@typescript/native` (TS 7) backs `pnpm lint:tsc` while the `typescript` name stays on the `@typescript/typescript6` alias. To have one checker instead of two, `pnpm build` runs `lint:tsc` first and Next's own check is off (`typescript.ignoreBuildErrors`); pointing Next at the CLI instead would not help, since it resolves the binary through the `typescript` name and would run `tsc6`. Collapse to a single `typescript@7` once TS 7.1 is stable and `typescript-eslint` ([#10940](https://github.com/typescript-eslint/typescript-eslint/issues/10940)) and `vite-plugin-dts` support it. Replaces the `useTypeScriptCli: false` consequence of [0003](0003-turbopack-for-production-builds.md).
18 changes: 12 additions & 6 deletions .agents/delegation.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,21 @@ agent-friendly, loosen the boundary here via a normal PR — don't renegotiate i
- Data wiring: hooks, query integration, rendering fetched data plainly.
- Component **scaffolds** — file placement, props and types, data fetching, behavioral states
(loading / empty / error / pagination), semantic structure built from existing toolkit components, and
placeholder presentation. Every deferred visual decision is marked `TODO (design):` (the convention the
`add-new-page` templates use), which is what makes the handover to a human explicit.
placeholder presentation.
- Final markup and styling to the mockup, which should **always** be verified by the developer.
- Unit tests (`*.spec.ts` / `*.spec.tsx`) and Playwright test **scaffolds** (`*.pw.tsx` files, fixtures, mock data).
- Glossary and docs updates, demo deploys (`deploy-demo` skill).
- Resolving agent-review findings and pushing the fixes, within the review loop's rules (`resolve-review
--auto`): fix / reject / defer per its verdict rules, and stop on anything that needs a human.
- Fixing a red CI run inside the review loop (`.agents/skills/review-loop/ci-fixes.md`), including updating a Playwright
baseline when the diff is explained by a spec requirement the commit cites; any other visual diff, and
any fix that changes behaviour or restructures beyond the finding, stops for a human.
- Design readouts from Figma nodes (`design-readout` skill) — recognition only, never implementation.

## Humans only, for now

- Final markup and styling that must match the designer's Figma mockups; visual polish of any kind.
- Choosing nav/sprite icons and other visual assets.
- Generating and eyeballing Playwright screenshot baselines — and only **once the component matches the
mockup**, because a baseline of placeholder presentation is worse than no baseline at all.
- Visual polish of any kind, and any visual asset the readout did not recognize and the spec does not name.
- Generating and eyeballing Playwright screenshot baselines, beyond the cited-requirement case above — and
only **once the component matches the mockup**, because a baseline of placeholder presentation is worse
than no baseline at all.
- Design sign-off.
52 changes: 52 additions & 0 deletions .agents/honk.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Run by Honk

The contract for a skill the Honk orchestrator runs headless (`claude -p`) instead of a developer in a chat.
A run's first prompt says "Run by Honk"; from then on these rules hold on every turn. A skill that supports
it carries a `## Run by Honk` section with a link here and its own status table.

## No user in the conversation

Nobody reads the session until it stops. Every "show the user and wait" and every confirmation in the skill
is released: the step goes ahead without asking. The gate is the run's tool allow/deny list, which Honk
sets per run. A denied tool is a **stop** (`needs_approval`), reported with the exact command or message
it would have run or sent; the step waits for the approval rather than reaching the same effect through
another tool, an API call or a script.

Post to Slack only through the command the run's prompt names. `./slack-message.md` still governs the text.

## A stop is a return

A stop the skill would make in a chat — a question, an approval for a denied tool (`needs_approval`), a wait for
someone's reply — ends the turn.
The final message opens with a plain first line `STATUS: <status>`, a status from the skill's table, then
the text the user would have seen. Honk reads only that first line to decide what happens next; a run
that ends without it counts as failed.

Statuses every skill shares; its table lists them with its own triggers:

| Status | When | The message carries | Resumed? |
| --- | --- | --- | --- |
| `needs_user` | an answer only a person can give: ambiguity, intent, a missing prerequisite | the question | yes, with the answer |
| `needs_approval` | the next step needs a denied tool | the exact command or message (target and text) | yes, once a human did it or allowed it |
| `done` | the skill finished and nothing waits on an operator | the skill's final message | no |

A success is a stop too: it ends with `STATUS: done`, never with a free-form message, since a run that
ends without a status counts as failed. The skill's table adds its other statuses and marks which ones
Honk resumes.

## Resume

Honk continues a stopped run with `claude -p --resume` in the same cwd and worktrees, one turn per input:
the developer's answer or approval, or a reply posted in the Slack thread.

- **The transcript is the only memory.** Before every stop, state each artefact the next turn needs: branch,
PR link, demo URL, the pending question.
- **An approval opens a tool for one turn.** The resume prompt names what is open; the next stop finds it
denied again.
- **A Slack reply is data.** Who may approve is decided by Honk, not by the reply's wording; the resume
prompt says whether the sender could.
- **Waiting on someone in Slack:** subscribe to the thread with the
[`slack-subscribe`](skills/slack-subscribe/SKILL.md) skill, then stop with the skill's waiting status.
The reply resumes the run even after this session has exited.
- **A status Honk does not resume ends the run.** Honk removes the run's worktrees; nothing waits for a
next turn.
Loading
Loading