Imported from feelyourprotocol/website (.cursor/skills/add-exploration/SKILL.md). Install upstream with npx skills add feelyourprotocol/website --skill add-exploration. Copyright stays with the author.

Add an exploration

Executable playbook for the explorations website only (src/explorations/). Phase 2 of the round-trip, or standalone after brief-protocol-change GO. Do not create or switch branches unless the human asks.

Brief first: brief-protocol-change must already have a human GO (or this session is that GO). Signed-off core question, nature, and proposed CANONICAL are inputs — do not re-litigate them unless the spec contradicts the briefing.

This phase is plan + implement in one go. Design is not a separate human gate — but it is the quality of the exploration. Spend real care here before creating files. Stop only on exception gates.

Concepts: architecture.md, e-components.md, adding-an-exploration.md.

Lookups: canonicalTypes.ts, REGISTRY.ts, types.ts — do not guess IDs or re-list CSS tables in chat.

Repo boundaries: AGENTS.md, repo-structure.mdc.

Design (same turn, before files)

The widget should show and let someone feel the core question. UX is an easy play loop: capture curiosity, invite poking around, teach without a side-knowledge wall or frustrating hurdles. If the first minute is confusing, the exploration failed — even if the spec is correct.

Do this before creating files. Use the signed-off briefing; tighten against source. Taxonomy (topic / timeline / tags) was proposed at briefing and confirmed at GO — do not re-pick unless the spec contradicts it.

1. Read the spec + signed-off briefing (core question, nature, not-the-point, example stories, taxonomy).
2. Confirm taxonomy IDs against source (TOPICS.ts, TIMELINE.ts, TAGS.ts) — do not guess.
3. Field reference: ProtocolChangeCanonical in canonicalTypes.ts; Exploration in REGISTRY.ts.
4. Capture statement — one sentence: after ~30 seconds of play, what did they grasp?
5. First action — the default example and the primary control answer the core question with no spec reading. Labels live on the widget, not in a footnote.
6. Play loop — 2–3 obvious next moves (other examples or one control). Each should confirm or surprise. No hidden “you must know X.”
7. Honest failure — invalid and beyond-edge inputs are teaching, not a crash or a blank panel.
8. Choose a building block (below). Result UI matches changeNature.
9. Pedagogical slice: what the widget lets someone feel; what MCP owns as the superset.
10. Form factors (dedicated pass) — mobile (single column, no horizontal overflow, usable tap targets), tablet, desktop (right-panel / companions stack or collapse). Cover column: if there is no companion, set imageBoxHeight: COVER_COLUMN_IMAGE_HEIGHT (layout.ts, 48rem) — do not copy companion 16rem from 7708, and do not leave the cover uncapped. See exploration-design.mdc. Verify these in the browser before the report.
11. Cross-exploration UI check — for every chrome control from the steps above, search sibling MyC.vue files and src/eComponents/ui/. Same logical control → reuse the UIC, or extract it now (component + tests, then switch old and new call sites) before shipping a second visual. This is required UIC work, not an E-Component exception gate. See exploration-design.mdc.
12. Result panel shell — mount result/compare UI with the scenario (idle placeholders + height for the tallest example). Do not v-if the whole panel on result. See exploration-design.mdc § Result panels.
13. Prose pass — scenario lessons, intro/usage, footers, and labels use plain language; no EthereumJS method/property names in user copy. See exploration-design.mdc § Prose.

Write 4–8 lines of design notes (capture, first action, play loop, form-factor plan, UI reuse/extract, result panel shell) into the phase-2 report. Then code.

Choose a building block

In order:

1. available-e-components.md + reference folder — wire config + examples + execution.
2. E-Component + slots/companion components — e-components.md § extension points.
3. Custom widget with ExplorationC + shared UI — ui-components.md.

Reference explorations by pattern:

Copy the closest folder; adapt canonical.ts, info.ts, examples.ts, MyC.vue, and config.ts as needed. Do not copy result UI across change natures.

Do not create a new shared E-Component by default — but when briefing or design identifies a reusable logic/API + UX/UI structure likely needed for future EIP integrations, take a focused sub-round first: design, implement, test, and document the new E-Component (src/eComponents/<name>EC/, available-e-components.md), then return to the exploration and integrate it (tweak if real use teaches better shapes). Prefer slots / local companions when the pattern is truly one-off.

UIC vs E-Component: copying a sibling’s chrome (two-button toggle, run button, example picker) with different colors or spacing is a required in-between UIC extract (src/eComponents/ui/, tests included). That is not a new E-Component and does not use the exception gate below.

Sub-round checklist: typed config + neutral display types (no third-party imports in E-Component), unit tests, catalogue row, optional provide/inject for loose coupling to exploration execution.

Exception gates

Stop and ask (do not improvise past these):

• New runtime dependency (explicit human ask)
• New shared E-Component — only when the sub-round above was skipped without human approval and the pattern is still one-off (does not apply to extracting a UIC for a duplicate control)
• Briefing verdict no longer holds (spec cannot be taught honestly)
• Spec too underspecified for a truthful widget

Tests (test-first)

Prefer tests before (or in the same turn as) chrome polish — lock the protocol claim first. Tests are for logic and UI, and they must stay usable past the happy path.

Write tests.spec.ts (and Vue mounts) that cover:

• Metadata, CANONICAL, examples, config sanity
• Execution / transform helpers — happy path and beyond-edge (empty, junk, out-of-range, “too big”). Must not crash; fail in a way the widget can show
• Vue: mount MyC (or companions); the play path is present (example picker or primary control, result region)
• Extracted UIC (if any this phase): src/eComponents/ui/__tests__/<Name>UIC.spec.ts — selected state, emit on change, no emit on same click, empty/beyond-edge

Cypress catalog (required): add one row to src/explorations/e2eCatalog.ts (id, path, family). Vitest src/explorations/__tests__/e2eCatalog.spec.ts fails if REGISTRY and the catalog diverge — that is how the visit-all E2E loop picks up the new route. Do not add a per-EIP Cypress describe. Set skipExecute: true when the primary run is too slow for CI (heavy crypto, long VM runs). A new family (not a new EIP in form / scenario / bytecode) also needs an E2E_FAMILY_PLAY representative. Shared layout (touch chrome, companion peek) uses cypress/e2e/layout.cy.ts representatives — do not add one layout spec per EIP. Details: testing.mdc § Cypress E2E.

Also update FEATURED_EXPLORATION_IDS in src/views/homeCatalog.ts (HomeView tests import the helper — no duplicate array).

Invariants and finish commands: testing.mdc, quality.mdc.

Implementation steps

1. Create src/explorations/<id>/
2. canonical.ts — CANONICAL per canonicalTypes.ts (SoT), from the signed-off proposal
3. info.ts — website chrome; introText starts with coreQuestion from CANONICAL; copy coreQuestion and mcpDocsStatus onto INFO for home preview cards. Set imageBoxHeight per exploration-design.mdc (COVER_COLUMN_IMAGE_HEIGHT vs companion 16rem–19rem).
4. examples.ts + execution helpers — tests for the protocol claim first (or immediately with these files)
5. MyC.vue (+ config.ts if E-Component-backed) — then Vue mount tests. After the first chrome pass, run the cross-exploration UI check (design §11). If a sibling already has the same control and there is no UIC, extract + tests in this step, then wire every call site.
6. Register in src/explorations/REGISTRY.ts (nav dropdown is Object.values(EXPLORATIONS)). Add the matching row to src/explorations/e2eCatalog.ts (family + path). The Cypress catalog loop visits it automatically.
7. Engagement lexicon: append one problem_slices row in social/watchlist.yml and add the id to eip_number_fallback. 3–4 search phrases from coreQuestion + mcp.keywords in builder language (wallet, gas, logs, stack — not EIP-NNNN). path from info.ts. avoid_leading_with: EIP-NNNN. Skip if docsStatus is sunset (and remove the row + fallback id if you are sunsetting). Do not edit the x-engagement skill for a new EIP.
8. Latest on the home page: prepend <id> to FEATURED_EXPLORATION_IDS in src/views/homeCatalog.ts. latestExplorationIds() is the first 3 — the new one is Latest; the previous third Latest drops into Catalog. Home tests import the same helper.
9. Cover art (required): cover-image skill. Round-trip default: Template B from signed-off coreQuestion unless the human named a subject at GO. Import image.webp in info.ts. Then npm run generate:og:exploration -- <id>.
10. Dependencies — prefer existing package.json entries
11. Finish tests.spec.ts per Tests

Run npm run dev and verify the exploration route and home Latest cards. Do the form-factor pass (mobile / tablet / desktop) before the report.

If the briefing promised a twin, add or stub mcp-docs/use/eips/eip-NNNN.md in this phase when that is the ship gate for a live exploration (Runnable or Planned). Do not implement the engine module here.

Ship gates

Invariants (also in explorations.mdc)

• No hardcoded Tailwind colors — use e-* classes from src/main.css
• Same logical control, one UIC — do not restyle a sibling copy; extract to src/eComponents/ui/ with tests (exploration-design.mdc)
• Libraries only in the exploration folder
• Companion UI inside E-Component slots
• Register in REGISTRY.ts (nav)
• Engagement lexicon — social/watchlist.yml problem_slices + eip_number_fallback for live ids; remove on sunset
• Cover art — image.webp on every exploration
• New shared fields only on canonicalTypes.ts
• Keep after mainnet — do not set docsStatus: sunset because the fork activated

Finish gates

npm run lf:ci
npm run type-check
npx vitest run src/explorations/<id>/ src/explorations/__tests__/e2eCatalog.spec.ts
# plus src/eComponents/ui/__tests__/<Name>UIC.spec.ts when a UIC was extracted this phase

Apply quality.mdc and testing.mdc.

Tests passing is the quality bar, not the pedagogy bar. The report below is the handoff; the human reviews intro, usage, examples, play loop, and form factors before MCP GO (round-trip) or before OG/PR (standalone).

Report template — then STOP (round-trip) or wait for review (standalone)

## Phase 2 — Exploration (eip-NNNN)

**Core question:** …
**Capture / first action / play loop:** …
**Route:** `/…`
**Change nature / building block:** … (reference folder or custom)
**Slice:** what the widget teaches vs what MCP should own

**eComponents / UI:** reused UIC | extracted UIC (this phase) | slotted | local companion | new shared EC (only if asked)
**Touched / evolved / created:** paths + one line each
**Files:** created / modified (short list)
**Latest:** prepended to `FEATURED_EXPLORATION_IDS` — dropped from Latest trio: …
**Watchlist:** `problem_slices` + `eip_number_fallback` updated (or sunset removed)
**Cover:** `image.webp` — Template A/B — shown in context

**Tests:** `npx vitest run src/explorations/<id>/ src/explorations/__tests__/e2eCatalog.spec.ts` — N specs, pass/fail (logic + UI + beyond-edge + e2e catalog row)
**Quality:** `lf:ci`, `type-check`
**Browser:** route + home Latest; mobile / tablet / desktop — notes

**Carry to MCP:** hints (bytecode vs widget, comparison forks, prompts, what not to clone)
**Open questions:** …

Follow-ups

• MCP module: round-trip phase 3, or add-mcp-module when a verb is ready
• Bro & Bruh comic: round-trip phase 4 (bro-bruh-comic) — after MCP, on a separate yes
• Cover and OG are in this phase, not follow-ups

Out of scope

• Engine module implementation (phase 3)
• Bro & Bruh comic (phase 4)
• Edits to roadmap, community-token, or docs-hub sites (mcp-docs EIP pages are a ship gate, not out of scope)
• New E-Components unless the briefing/design sub-round applies, the human explicitly asked, or an exception gate was approved (UIC extraction for a duplicate control is in scope)