Sync upstream v12.0.0 (merge conflicts)

.agents/agents/leaf-schemas-cataloger.md

@@ -0,0 +1,130 @@
+---
+name: leaf-schemas-cataloger
+description: "Maintains a cached catalog of leaf type schemas under `apps/block_scout_web/lib/block_scout_web/schemas/api/v2/general/`. Invoke at the start of any OpenAPI spec authoring task that involves selecting or referencing leaf-type schemas. The agent checks a content hash, regenerates the catalog only when leaf files have changed, and writes the result to `.claude/skills/openapi-spec/references/cache/leaf-schemas/catalog.md`. Self-contained — does not depend on the openapi-spec skill prompt."
+permissionMode: auto
+model: haiku
+tools: Bash, Read, Write
+---
+
+You maintain a cached, human-readable catalog of leaf type schemas defined in the Blockscout codebase. The catalog is consumed by the `openapi-spec` skill to give the parent agent a fast, accurate vocabulary of available leaf schemas without re-reading every source file each session.
+
+## Workflow
+
+1. **Check freshness.** Run:
+   ```
+   bash .claude/skills/openapi-spec/scripts/leaf-schemas-cache-check.sh
+   ```
+   The script emits three `key=value` lines on stdout:
+   - `state=fresh` or `state=stale`
+   - `digest=<sha256>` — the current content digest of `general/*.ex`
+   - `cache_dir=<absolute-path>` — where the catalog and digest live
+
+2. **If `state=fresh`**, stop immediately. Report: `Catalog is fresh (digest=<...>). No work needed.` Do not regenerate.
+
+3. **If `state=stale`**, regenerate:
+   1. Collect facts:
+      ```
+      python3 .claude/skills/openapi-spec/scripts/leaf-schemas-collect-facts.py
+      ```
+      Capture the stdout — it is a single JSON document with one entry per leaf, each containing `module`, `short_name`, `path`, `source`, and up to three `callsites` (file + line).
+   2. Build the catalog (see "Catalog format" below). Use the source content for every leaf; use callsite locations as **input to interpretation** when a leaf's purpose is not obvious from its name and structure alone — open the referenced files via `Read` and inspect the lines around each callsite to see how the leaf is used in practice. Spend this effort only on leaves whose role is genuinely ambiguous (a name like `Tag`, `ProxyType`, or `Implementation` warrants a look; `AddressHash` or `Timestamp` does not).
+   3. Write atomically:
+      - Write the catalog to `<cache_dir>/catalog.md.tmp`, then move to `<cache_dir>/catalog.md`.
+      - Write the new digest to `<cache_dir>/digest.tmp`, then move to `<cache_dir>/digest`.
+      - The two `mv` commands ensure that a half-written cache cannot be mistaken for fresh.
+   4. Report: `Catalog regenerated (digest=<new-digest>, leaves=<count>).`
+
+4. **If a script fails** (non-zero exit, missing file, etc.), report the error verbatim and stop. The parent skill is responsible for falling back to live source reads — your job is to keep the cache truthful or absent, never wrong.
+
+## Catalog format
+
+The catalog is markdown. It must contain exactly these sections in this order:
+
+```markdown
+# Leaf Type Schemas Catalog
+
+Auto-generated by the `leaf-schemas-cataloger` agent. Do not edit by hand —
+changes are overwritten on the next regeneration.
+
+Source directory: `apps/block_scout_web/lib/block_scout_web/schemas/api/v2/general/`
+
+## Scalar leaves
+
+Leaves whose top-level shape is a JSON primitive (`string` with pattern /
+enum / format, `integer`, `boolean`). The "Spec" column captures the full
+constraint at a glance.
+
+| Module | Spec | Purpose |
+|---|---|---|
+| `General.<Name>` | `<type, constraints>` | <one-line purpose> |
+| ... |
+
+## Composite leaves
+
+Leaves whose top-level shape is `object` or `array`. The "Shape" column
+lists top-level fields (or array element kind) only; refer to the source
+file for nested structure.
+
+| Module | Shape | Purpose | Source |
+|---|---|---|---|
+| `General.<Name>` | `object { field1, field2[]? }` | <one-line purpose> | `general/<file>.ex` |
+| ... |
+```
+
+### Classification rule
+
+A leaf is **scalar** if its `OpenApiSpex.schema(%{...})` map has `type: :string`, `type: :integer`, `type: :boolean`, or similar primitive at the top level (with optional `pattern:`, `enum:`, `format:`, `nullable:`, `minimum:`, etc.). It is **composite** if its top level is `type: :object`, `type: :array`, or contains `anyOf:` / `oneOf:` at the top level.
+
+### Spec column conventions (scalar table)
+
+- Write the type plainly: `string`, `integer`, `boolean`.
+- Append constraints as a comma-separated list: `pattern 0x[a-f0-9]{40}`, `enum: [eip1167, eip1967, ...]`, `format: date-time`, `minimum: 0`, `nullable`.
+- For nullable variants, use `string \| null` rather than a separate column. Escape pipe characters (`\|`) inside table cells whenever they appear — GitHub-Flavored Markdown table cells treat raw `|` as a column separator.
+- When `pattern:` references `General.<x>_pattern()`, expand it to the actual regex if you can locate the constant in the source; otherwise write `pattern: General.<x>_pattern()`.
+- When `enum:` is sourced at runtime from `Ecto.Enum.values(SomeModule, :field)`, look up the actual value list by reading the referenced Ecto schema module under `apps/explorer/lib/explorer/chain/` and inline the literal values in the Spec cell. Do **not** leave `Ecto.Enum.values(...)` in the catalog — the reader needs the concrete vocabulary.
+
+### Shape column conventions (composite table)
+
+- Depth = 1 only. Do not descend into nested objects or arrays of objects.
+- Use `object { a, b, c }` for objects; mark optional fields with `?`.
+- Use `array<object>` or `array<string>` for arrays.
+- Use `anyOf [string, object, ...]` for top-level `anyOf` / `oneOf`.
+
+### Purpose column rules — important
+
+The "Purpose" cell must describe **what the schema represents and the kind of context it appears in**, in *general* terms. It must remain valid even if every current callsite is renamed or restructured.
+
+**Do**:
+- Describe the modelled entity ("Ethereum address hash, lowercase 20-byte hex").
+- Describe the typical role ("nullable variant for properties that may be absent in proxy contracts").
+- Describe the data shape's meaning ("decoded event log parameters with name/type/value triples").
+
+**Do not**:
+- Name specific consumer controllers, views, schema modules, or files in the **Purpose** column (`address_controller.ex`, `BlockScoutWeb.Schemas.API.V2.Transaction`, etc.).
+- Reference specific actions or endpoints (`/v2/blocks/...`, `:show_address`, etc.).
+- Quote line numbers or counts of callers.
+- Use words like "used by X" or "called from Y".
+
+Note: the **Source** column of the composite table is *not* a callsite reference — it points at the leaf's own definition file (`general/<file>.ex`), which is structural metadata, not consumer context. Always populate it.
+
+Callsite line context is a tool for *you* to understand the leaf's purpose. It must not leak into the catalog text. If a callsite is the only thing that disambiguates the leaf's purpose, abstract the pattern: instead of "used by `address_controller.ex` to render private tags", write "user-applied label with name and type, attached to account records".
+
+## Atomic write recipe
+
+Always use temp-file-and-rename so that an interrupted run cannot leave a half-written catalog matching a fresh digest:
+
+```bash
+printf '%s' "$CATALOG_CONTENT" > "$CACHE_DIR/catalog.md.tmp"
+mv "$CACHE_DIR/catalog.md.tmp" "$CACHE_DIR/catalog.md"
+printf '%s' "$NEW_DIGEST" > "$CACHE_DIR/digest.tmp"
+mv "$CACHE_DIR/digest.tmp" "$CACHE_DIR/digest"
+```
+
+The `Write` tool itself is fine — write to `catalog.md.tmp` first, then `mv` via `Bash`. Do **not** write directly to `catalog.md` without the rename step.
+
+## What you do NOT do
+
+- You do not modify source files under `schemas/api/v2/general/`. The catalog is downstream of the code, never upstream.
+- You do not edit the `openapi-spec` skill or its references. You only own the cache directory.
+- You do not invoke other agents.
+- You do not commit changes. The cache directory is gitignored.

.agents/agents/openapi-spec-inspector.md

@@ -54,4 +54,6 @@ The report should include:
 6. A prioritized list of issues (Critical / Major / Minor / Nit) with concrete file:line references.
 7. Suggested fixes (described, not applied).
 
+Apply the finding-quality gates in `references/inspection-checklist.md` §7 before finalizing items (6) and (7).
+
 Keep the report focused and actionable. After writing, respond with only a one-line confirmation of the file path.

.agents/skills/alphabetically-ordered-aliases/SKILL.md

@@ -13,6 +13,8 @@ Elixir code style conventions prefer that module aliases are alphabetically orde
 - When organizing module aliases at the top of a file
 - When multiple aliases from related modules are defined together
 - When refactoring code to improve consistency and readability
+- When adding a new alias into an existing `alias ...{...}` grouped block
+- When touching files that already have `Credo.Check.Readability.AliasOrder` warnings
 
 ## Anti-Patterns (Avoid These)
 
@@ -75,6 +77,15 @@ For modules with the same prefix like:
 
 Sort by the last component: `Create...` < `Drop...` < `Helper`
 
+For grouped aliases like:
+
+```elixir
+alias BlockScoutWeb.API.V2.{ApiView, Helper, InternalTransactionView, TokenView}
+```
+
+sort entries exactly as Credo expects by module name order within the group.
+When two names share a long prefix (for example `InternalTransaction...`), compare the next character and keep strict lexical order.
+
 ### Step 3: Reorder in code
 
 Rearrange the alias statements to match the alphabetical order determined in Step 2.
@@ -87,6 +98,26 @@ Run Credo to ensure no warnings remain:
 mix credo --strict
 ```
 
+If you changed only a few files, prefer targeted checks first:
+
+```bash
+mix credo --strict --files path/to/file1.ex,path/to/file2.ex
+```
+
+## Trigger Cues
+
+- Credo output includes: `The alias ... is not alphabetically ordered among its group`
+- A diff adds/reorders aliases near module top
+- A grouped alias block contains names that are visually close (`InternalTransaction...` vs `InternalTransactions...`)
+
+## Reliable Checklist
+
+1. Re-read every alias group in the touched file after edits.
+2. Re-sort grouped aliases (inside `{...}`) and standalone aliases.
+3. Ensure new aliases are inserted in-place, not appended.
+4. Run `mix format` after edits.
+5. Run Credo (targeted or full) and confirm no alias-order warnings remain.
+
 ## Example Violations and Fixes
 
 ### Violation 1: Helper before DropTransactions

.agents/skills/elixir-clause-grouping/SKILL.md

@@ -7,19 +7,26 @@ description: Use when refactoring Elixir multi-clause functions, extracting help
 
 In Elixir modules, all clauses of the same function should stay together. Inserting a `defp` helper between clauses of a `def` or `defp` makes the function harder to read and can trigger Credo readability warnings. When shared logic needs to be extracted, keep the original clause group contiguous and place the helper after the full group.
 
+This also applies to Phoenix view modules that define many `render/2` clauses with different templates: all `render/2` clauses still belong to the same function and must be contiguous.
+
 ## When to Use
 
 - When refactoring a multi-clause `def` or `defp`
 - When extracting duplicated logic from multiple function clauses
 - When addressing Credo warnings about clause grouping or readability
 - When editing controller, view, or context modules with several clauses of the same function
 - During review when a helper was added in the middle of another function's clauses
+- When editing Phoenix `render/2` clauses and introducing helper functions nearby
+- When adding any `defp` between two definitions that share the same function name/arity
+- When you see compiler output like: `clauses with the same name and arity ... should be grouped together`
 
 ## Core Rule
 
 - Keep all clauses of the same function contiguous
 - Do not place `defp` helpers between clauses of another function
 - Extract shared logic into a helper placed after the full clause group
+- Before finishing edits, scan up/down around each new helper and verify no same-name/same-arity clauses are split
+- In view modules, keep all `render/2` clauses contiguous even if clause heads match different template strings
 
 ## Anti-Pattern
 
@@ -58,6 +65,14 @@ end
 3. Extract shared logic only after the full clause group.
 4. Re-check that no unrelated `def` or `defp` appears inside the group.
 5. Run formatting after the refactor.
+6. For Phoenix views, explicitly verify all `render/2` clauses are contiguous (not only clauses for the same template).
+7. If you add a helper used by `render/2`, place it after the last `render/2` clause in the module.
+
+## Trigger Cues
+
+- Compiler warning: `clauses with the same name and arity ... should be grouped together`
+- Credo warning about grouping/splitting function clauses
+- A diff that inserts `defp` between two `def render(` declarations
 
 ## Notes
 

.agents/skills/openapi-spec/SKILL.md

@@ -25,7 +25,7 @@ All paths are relative to `apps/block_scout_web/lib/block_scout_web/`. Most endp
 | Account controllers (Private spec) | `controllers/account/api/v2/<domain>_controller.ex` |
 | Legacy controllers | `controllers/api/legacy/<domain>_controller.ex` (routed under `/legacy`) |
 | V2 schema modules | `schemas/api/v2/<domain>.ex` and `schemas/api/v2/<domain>/*.ex` |
-| V2 chain-type schema subdirs | `schemas/api/v2/<chain>/*.ex` (e.g. `schemas/api/v2/{arbitrum,beacon,celo,optimism,scroll,zilliqa,mud}/*.ex`) |
+| V2 chain-type schema subdirs | `schemas/api/v2/<chain>/*.ex` (e.g. `schemas/api/v2/{arbitrum,beacon,celo,optimism,scroll,zilliqa}/*.ex`) |
 | V2 proxy schemas | `schemas/api/v2/proxy/*.ex` |
 | Account schemas (Private spec) | `schemas/api/v2/account/*.ex` |
 | Legacy schemas | `schemas/api/legacy/*.ex` |
@@ -46,6 +46,12 @@ All paths are relative to `apps/block_scout_web/lib/block_scout_web/`. Most endp
 
 **On router coverage of the public spec:** `specs/public.ex` builds `paths` via `Paths.from_router(ApiRouter)`, which picks up everything reachable from `api_router.ex` — including endpoints declared in the sub-routers that `api_router.ex` `forward`s to (api-key, utils, address-badges). Only `TokensApiV2Router` and `SmartContractsApiV2Router` need the extra `Paths.from_routes(...)` merges in `public.ex` because their prefixes are stripped by Phoenix `forward` and must be re-added. A new annotated endpoint placed in any of the other sub-routers needs no extra wiring beyond the `forward` that already exists in `api_router.ex`.
 
+## Leaf-schemas catalog (bootstrap step)
+
+Before any workflow below, invoke the `leaf-schemas-cataloger` agent (prompt: `Refresh the leaf-schemas catalog if stale.`). It maintains a compact catalog of every leaf type schema under `schemas/api/v2/general/` at `references/cache/leaf-schemas/catalog.md` (auto-generated, gitignored). Read that file when picking a primitive leaf type for a response property or parameter `schema:`.
+
+**Fallback:** if the agent fails or the catalog is unavailable, glob `apps/block_scout_web/lib/block_scout_web/schemas/api/v2/general/*.ex` and read individual leaf files as needed.
+
 ## Core patterns
 
 ### The operation macro
@@ -144,7 +150,7 @@ The order of tag groups in the generated public spec is not derived from the con
 If a new annotated controller introduces a brand-new tag, the agent must register it in the right group, or the tag will still appear in the spec (via controller-side `tags(...)`) but with no ordering guarantee and no entry in the top-level `tags:` list:
 
 - Base endpoint → append the kebab-case tag to `@default_api_categories`.
-- Chain-type endpoint → add it inside the relevant `case @chain_identity` branch, matching the existing patterns (module-attribute + `defp` for static lists, full `defp` body when the tag set depends on a runtime flag such as `mud_enabled?()`).
+- Chain-type endpoint → add it inside the relevant `case @chain_identity` branch, matching the existing patterns (module-attribute + `defp` for static lists, full `defp` body when the tag set depends on a runtime flag).
 - Legacy endpoint → no action; `"legacy"` is already the trailer.
 
 Tags that are already covered by an existing group (e.g. another `addresses` endpoint) need no change.
@@ -229,7 +235,7 @@ For each parameter the controller reads:
    - **Domain-specific but used by multiple operations in the same controller?** Add a private helper function in the controller itself. This avoids polluting `general.ex` with chain-specific concerns while preventing duplication across operations.
    - **Truly one-off (single operation)?** Define an inline `%OpenApiSpex.Parameter{}` struct directly in the `operation` macro arguments.
 
-3. **For pagination parameters**, use `define_paging_params(field_names)` — pass the cursor field names as strings, and always include `"items_count"` (the `next_page_params` helper adds it to every cursor automatically). See `references/parameter-discovery.md` section "The `define_paging_params` factory" for details.
+3. **For pagination parameters**, use `define_paging_params(field_names)` — pass the cursor field names as strings. See `references/parameter-discovery.md` section "The `define_paging_params` factory" for details.
 
 ### Step 3: Create or locate response schema
 
@@ -365,6 +371,7 @@ Use this to audit an existing declaration for correctness, completeness, and adh
 | `references/inspection-checklist.md` | You're running an audit of an existing declaration (Workflow C) |
 | `references/spec-generation-and-verification.md` | You need to generate the spec YAML, validate it, or inspect specific operations/schemas with oastools |
 | `references/oastools-audit-recipes.md` | You want to audit the generated spec for spec-wide convention drift or reuse candidates, without reading every source file |
+| `references/cache/leaf-schemas/catalog.md` | You need to pick a primitive leaf type (`General.AddressHash`, `General.IntegerString`, `General.Tag`, …) for a property or parameter — auto-generated by the `leaf-schemas-cataloger` agent; invoke it first if missing |
 
 ## Using subagents
 

.agents/skills/openapi-spec/references/cache/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore