Adding an Exploration

An exploration is a folder under src/explorations/ with canonical.ts, website chrome, and an interactive widget. You define the pedagogical goal and review the result; your agent implements.

Default for a new EIP: tell the agent “round-trip for EIP-xxxx”. That runs the round-trip skill — brief, then exploration, then MCP, then an optional Bro & Bruh comic — with a GO from you between phases. Widget-only work still uses brief-protocol-change then add-exploration.

Brief your agent

Include (or let the briefing phase propose these for you to accept):

• EIP/ERC spec link and what the widget should let someone understand (practical, curiosity, or research audience)
• Suggested topic, timeline, and tags (Architecture — agent must read TOPICS.ts, TIMELINE.ts, TAGS.ts, not guess)
• Building block: precompile repricing → EIP-7883; precompile new-capability → EIP-7951; bytecode stepper → EIP-8024; custom → EIP-7928
• Ask for human review before OG image or PR

Folder contract

src/explorations/eip-XXXX/
├── canonical.ts     # required — source of truth (website + MCP)
├── info.ts          # required — website chrome only
├── MyC.vue          # required
├── examples.ts      # recommended
├── tests.spec.ts    # required
├── config.ts        # when using an E-Component
└── *.vue / *.ts     # optional companions, helpers

Register in REGISTRY.ts or the exploration will not appear. Add a matching row to e2eCatalog.ts (id, path, family) so Cypress visits the new route automatically.

Canonical metadata (canonical.ts)

Shared meaning lives here — replicated into MCP engine modules and docs. Schema: src/explorations/canonicalTypes.ts. Agent contract: eip-canonical-data.mdc.

import type { ProtocolChangeCanonical } from '@/explorations/canonicalTypes'
import { Tag } from '@/explorations/TAGS'

/** Source of truth for this protocol change (website + MCP). Replicate into engine EipCapability and mcp-docs. */
export const CANONICAL: ProtocolChangeCanonical = {
  identity: {
    id: 'eip-XXXX',
    eip: 0,
    specUrl: 'https://github.com/ethereum/EIPs/blob/<commit>/EIPS/eip-XXXX.md',
    specDate: '2026-07-10',
    name: '…',
    status: 'Review',
    testReleaseUrl: 'https://github.com/ethereum/execution-specs/releases/tag/tests-glamsterdam-devnet@v8.1.0',
    testReleaseName: 'tests-glamsterdam-devnet@v8.1.0',
  },
  question: { coreQuestion: '…', changeNature: 'new-capability' },
  taxonomy: { topic: 'scaling', timeline: 'glamsterdam', tags: [Tag.EVM] },
  mcp: { shapes: ['simulate'], docsStatus: 'runnable' },
}

Website chrome (info.ts)

Website-only fields — agent fills values; you review copy. Derive topic, timeline, tags, title, infoURL from CANONICAL where possible:

import type { Exploration } from '@/explorations/REGISTRY'
import { CANONICAL } from './canonical'

export const INFO: Exploration = {
  id: CANONICAL.identity.id,
  path: '/eip-XXXX-short-description',
  title: CANONICAL.identity.name,
  seoDescription: '…',
  infoURL: CANONICAL.identity.specUrl,
  specDate: CANONICAL.identity.specDate,
  specStatus: CANONICAL.identity.status,
  testReleaseUrl: CANONICAL.identity.testReleaseUrl,
  testReleaseName: CANONICAL.identity.testReleaseName,
  topic: CANONICAL.taxonomy.topic,
  timeline: CANONICAL.taxonomy.timeline,
  tags: CANONICAL.taxonomy.tags,
  coreQuestion: CANONICAL.question.coreQuestion,
  mcpDocsStatus: CANONICAL.mcp.docsStatus,
  introText: `<b>${CANONICAL.question.coreQuestion}</b> …`,
  usageText: 'How to use the widget below.',
}

Field guide (what you must judge)

Field	Your judgment
topic	Fixed set — must match Architecture § topics
timeline	Valid ID from TIMELINE.ts
tags	3–4 reusable concepts; follow tag rules
seoDescription	Discovery/search (~120–160 chars); not the same as introText
introText / usageText	Pedagogy and accuracy vs the spec
introText vs seoDescription	Intro teaches on-page; SEO targets search queries
image	Required — Images. Page uses image.webp; cards use imageSmall.
imageBoxHeight	Cover-only: COVER_COLUMN_IMAGE_HEIGHT (48rem). Companion: 16rem–19rem with rightPanel: true.
rightPanel	Set when a companion teleports into #exploration-right-panel; otherwise omit.

Agent field lookup: JSDoc on Exploration in REGISTRY.ts.

After mainnet

Keep the exploration and its MCP twin when the EIP activates. Fork role may rotate (preview → current → historical); that is not a cue to sunset. Use docsStatus: sunset only when the lab cannot honestly show the effect, or for a later explicit cleanup.

Discovery & SEO

Write seoDescription for how people search (EIP number, acronyms, “interactive explainer”). Keep pedagogical framing in introText.

Wiring the widget

Do not hand-implement from docs — tell the agent to copy a reference folder and read Available E-Components.

Extension rule: extra teaching UI goes inside E-Component slots, not as siblings next to the component (provide/inject is descendant-only). See E-Components.

Reuse rule: the same logical chrome (hardfork toggle, run button, example picker) uses one shared UIC. Agents extract duplicates in-between; they do not restyle a copy. See UI Components.

Tests

Agent adds tests.spec.ts (logic and UI mounts) — metadata, examples, execution helpers, beyond-edge inputs, play-path presence. Prefer tests before chrome polish. You verify the exploration behaves in the browser, including a mobile/tablet pass.

Cover, Latest, and link previews

• Cover art (required): Images + cover-image skill. Round-trip uses Template B from the signed-off core question unless you named a subject at GO.
• Home Latest: agent prepends the new id to FEATURED_EXPLORATION_IDS in src/views/homeCatalog.ts (the previous third Latest moves to the Catalog row). Home cards use ExplorationPreviewC (cover + core question), not the full widget chrome. Catalog pills (ExplorationMetaPills) appear on home/topic preview cards and on the exploration shell (ExplorationC) below the title: topic → topic hub, timeline → /all?timeline=…, MCP → mcp-docs/use/eips/eip-NNNN.html when mcpDocsStatus is runnable or planned-module (label is always MCP, not Runnable/Planned).
• OG card: npm run generate:og:exploration -- <id> after cover and metadata

Human review

Tests green ≠ ready. Before OG/PR, review:

• Pedagogy — does it help someone understand the protocol change?
• Play loop — can someone feel the core question in the first minute without side knowledge?
• Copy — introText / usageText accurate vs spec?
• Examples — meaningful inputs, not only edge hex?
• Form factors — usable on mobile, tablet, and desktop (no overflow, tap targets, stacking)
• Visual pass — spacing, overflow, topic colors in the browser

Checklist

• Round-trip briefing (or standalone brief) + human GO on core question and taxonomy
• Folder + canonical.ts + REGISTRY.ts entry (nav) + e2eCatalog.ts row
• Home Latest (FEATURED_EXPLORATION_IDS prepend in homeCatalog.ts)
• Engagement lexicon (social/watchlist.yml problem_slices + eip_number_fallback; remove on sunset)
• Cover art (image.webp)
• mcp-docs/use/eips/eip-NNNN.md for every live exploration
• Human review of copy, examples, UX, form factors
• Quality gates pass (lf:ci, typecheck, tests — logic + UI + beyond-edge)
• MCP phase GO when a twin should ship (engine module and/or catalogue page)
• OG generated when shipping