theredguild · mattaereal · Apr 3, 2026 · Apr 7, 2026 · Apr 7, 2026 · Apr 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,139 @@
+# AGENTS.md — InteractivETH
+
+## What This Project Is
+
+**InteractivETH** is an interactive educational platform for learning Ethereum protocol concepts. It uses hands-on simulations (transaction lifecycle, block building, gas auctions, security attacks) to teach concepts from the book [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook).
+
+**Branding**: The name is InteractivETH (capital ETH). Favicon is a lotus flower 🪷 (The Red Guild).
+
+## Critical Rules
+
+### 1. ALWAYS USE `pnpm`
+Never use `npm` or `yarn`. All commands use `pnpm`:
+```bash
+pnpm install
+pnpm dev
+pnpm build
+```
+
+### 2. ALWAYS EXTRACT STRINGS TO TRANSLATIONS
+Never hardcode user-facing text. Always use `useTranslations()`:
+
+```typescript
+import { useTranslations } from 'next-intl';
+
+const t = useTranslations('namespace');  // or useTranslations() for root
+```
+
+**Translation workflow:**
+1. Add the key to `messages/en.json` first
+2. Add the Spanish equivalent to `messages/es.json`
+3. Keep both files in sync — same keys, translated values
+4. Use the component with `t('key')` or `t('nested.key')`
+
+**Example:**
+```json
+// messages/en.json
+{ "sandwich": { "title": "Sandwich Attack Simulator" } }
+
+// messages/es.json
+{ "sandwich": { "title": "Simulador de Ataque Sandwich" } }
+```
+
+```tsx
+const t = useTranslations('sandwich');
+<h1>{t('title')}</h1>
+```
+
+### 3. UPDATE TODOS AND STATUS
+After completing work:
+- Update `TODO.md` with current status
+- Update `SECURITY_TODO.md` for security modules
+- Keep this file current if project structure changes
+
+## Project Structure
+
+```
+app/[locale]/          → Pages (i18n routing: /en, /es)
+components/
+  layout/              → Sidebar, breadcrumbs, tutorial layout, page nav
+  navigation/          → Search modal, locale switcher
+  ethereum/            → Shared simulator components
+  tutorials/           → Per-tutorial components (validator/, gas-auction/, etc.)
+  ui/                  → Reusable primitives (CodeBlock, etc.)
+messages/              → en.json, es.json (keep keys in sync!)
+notes/
+  chapters/            → Original Markdown study notes rendered for Spanish and auto-listed in the sidebar
+  translations/
+    en/                → English note translations rendered under /en/notes/[slug]
+book/                  → Mastering Ethereum git submodule (17 chapters)
+public/                → Static assets (lotus favicon)
+```
+
+## Code Patterns
+
+### New tutorial page
+```tsx
+'use client';
+import { useTranslations } from 'next-intl';
+import { TutorialLayout } from '@/components/layout/tutorial-layout';
+
+export default function MyTutorialPage() {
+  const t = useTranslations('myTutorial');
+  // ...
+}
+```
+
+### New Coming Soon page
+All use the shared pattern in `security/*/page.tsx` with `useTranslations('common')`.
+
+### File naming
+- Components: `kebab-case.tsx`
+- Hooks: `use-kebab-case.ts`
+- Pages: `page.tsx` in route directories
+
+## Adding Content
+
+1. **New tutorial**: Create page in `app/[locale]/slug/`, components in `components/tutorials/slug/`, translations in both JSON files
+2. **New translation key**: Add to `en.json` AND `es.json` simultaneously
+3. **New route**: Register in `breadcrumbs.tsx` PAGE_HIERARCHY and `sidebar.tsx`
+4. **Difficulty badges**: Use `useTranslations('difficulty')` → `td('beginner')`, `td('intermediate')`, `td('advanced')`
+
+### Study notes
+- Add chapter notes as Markdown files in `notes/chapters/`
+- Add English translations in `notes/translations/en/` when needed
+- Landing-page chapter resources can link to them through `/{locale}/notes/[slug]`
+
+## Book Reference
+
+The `book/` directory contains Mastering Ethereum as a git submodule with all 17 chapters in Markdown. Use it as the technical reference when building new tutorials. Key mappings:
+
+| Tutorial | Chapter |
+|----------|---------|
+| Transactions | 6 (Transactions) |
+| Block Builder | 15 (Consensus) |
+| Gas & Fees | 6 (Gas) |
+| Block Internals | 14 (EVM) + 15 (Consensus) |
+| Smart Contracts | 7 (Solidity) + 8 (Vyper) |
+| EVM | 14 (EVM) |
+| Security modules | 9 (Smart Contract Security) |
+| MEV | 16 (Scaling) |
+
+## Verification
+
+Before marking work complete:
+```bash
+pnpm build          # Must compile with zero errors
+```
+
+Check translation parity:
+```bash
+node -e "const en=require('./messages/en.json');const es=require('./messages/es.json');const ek=Object.keys(en);const sk=Object.keys(es);console.log('en:',ek.length,'es:',sk.length);"
+```
+
+## Current Status (as of 2026-04-03)
+
+**Completed:** Transactions, Block Builder, Gas & Fees, Block Internals, Protocol Visualizer, Sandwich Attack simulator
+**In progress:** Security section (7/8 modules are "Coming Soon" placeholders)
+**Planned:** Smart Contracts, EVM, MEV tutorials
+**i18n:** English + Spanish fully wired, all translation keys synced (510+ keys)
diff --git a/README.md b/README.md
@@ -1,70 +1,129 @@
-# InteractiveETH
+# InteractivETH
 
 Interactive educational visualizations for understanding Ethereum protocol concepts, based on [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook).
 
 ## Features
 
-- Interactive transaction lifecycle visualization
-- Block creation and consensus simulation
-- Multi-language support (English, Spanish)
-- Modular tutorial architecture for adding new content
+- **Interactive Simulators** — Hands-on exploration of Ethereum concepts (transactions, block building, gas markets, consensus)
+- **Security Section** — Learn about attack vectors (sandwich attacks, front-running, reentrancy, etc.) with both attack and defense perspectives
+- **Bilingual** — Full English/Spanish support via `next-intl` with locale-based routing (`/en/...`, `/es/...`)
+- **Difficulty Levels** — Beginner and Advanced modes per tutorial
+- **Modular Architecture** — Easy to add new tutorials following established patterns
+- **Responsive Design** — Works on desktop and mobile with collapsible sidebar
+- **Lotus Flower Favicon** — Branded with The Red Guild identity 🪷
 
 ## Getting Started
 
 ```bash
-# Install dependencies
 pnpm install
-
-# Run development server
 pnpm dev
-
-# Build for production
-pnpm build
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser.
+Open [http://localhost:3000](http://localhost:3000).
 
 ## Available Tutorials
 
-| Tutorial | Status |
-|----------|--------|
-| Transactions | Available |
-| Blocks | Available |
-| Smart Contracts | Coming Soon |
-| Gas & Fees | Coming Soon |
-| EVM | Coming Soon |
-| MEV | Coming Soon |
+### Core Concepts
+
+| Tutorial | Route | Status |
+|----------|-------|--------|
+| Transactions | `/transactions` | ✅ Available |
+| Block Builder | `/validator` | ✅ Available |
+| Gas & Fees | `/gas` | ✅ Available |
+| Block Internals | `/block-internals` | ✅ Available |
+| Protocol Visualizer | `/protocol-visualizer` | ✅ Available |
+
+### Security
+
+| Tutorial | Route | Status |
+|----------|-------|--------|
+| Sandwich Attack | `/security/sandwich-attack` | ✅ Available |
+| Front-Running | `/security/front-running` | 🚧 Coming Soon |
+| Reentrancy | `/security/reentrancy` | 🚧 Coming Soon |
+| Oracle Manipulation | `/security/oracle-manipulation` | 🚧 Coming Soon |
+| Rogue Proposer | `/security/rogue-proposer` | 🚧 Coming Soon |
+| Double-Signing | `/security/double-signing` | 🚧 Coming Soon |
+| Eclipse Attack | `/security/eclipse-attack` | 🚧 Coming Soon |
+| 51% Attack | `/security/51-percent` | 🚧 Coming Soon |
+
+### Planned
+
+| Tutorial | Book Chapter |
+|----------|-------------|
+| Smart Contracts | Chapter 7 (Solidity) / Chapter 8 (Vyper) |
+| EVM Deep Dive | Chapter 14 |
+| MEV & PBS | Chapter 16 |
 
 ## Project Structure
 
 ```
-├── app/                    # Next.js app router pages
-│   ├── [locale]/          # i18n routing
-│   └── [locale]/transactions/  # First tutorial
-├── components/            # React components
-│   ├── ethereum/         # Simulator components
-│   └── ui/              # UI primitives
-├── book/                  # Mastering Ethereum source (git submodule)
-├── hooks/                # Custom React hooks
-├── i18n/                  # Internationalization config
-├── lib/                  # Utilities and types
-└── messages/             # Translation files
+├── app/
+│   ├── [locale]/              # i18n routing (en, es)
+│   │   ├── page.tsx           # Landing page
+│   │   ├── transactions/      # Core concept tutorials
+│   │   ├── validator/
+│   │   ├── gas/
+│   │   ├── block-internals/
+│   │   ├── protocol-visualizer/
+│   │   └── security/          # Security section
+│   │       ├── page.tsx       # Security overview
+│   │       ├── sandwich-attack/
+│   │       └── ...            # Coming soon modules
+│   └── layout.tsx             # Root layout with metadata
+├── components/
+│   ├── layout/                # Sidebar, breadcrumbs, navigation
+│   ├── navigation/            # Search modal, locale switcher
+│   ├── ethereum/              # Shared simulator components
+│   ├── tutorials/             # Per-tutorial components
+│   │   ├── validator/
+│   │   ├── gas-auction/
+│   │   └── block-internals/
+│   └── ui/                    # Reusable UI primitives
+├── hooks/                     # Custom React hooks
+├── i18n/                      # next-intl config & routing
+├── lib/                       # Utilities and types
+├── messages/                  # Translation files (en.json, es.json)
+├── notes/
+│   ├── chapters/              # Original Markdown study notes, used for Spanish and auto-listed in the sidebar
+│   └── translations/
+│       └── en/                # English note translations rendered for /en/notes/[slug]
+├── public/                    # Static assets (lotus favicon, etc.)
+└── book/                      # Mastering Ethereum (git submodule)
 ```
 
 ## Adding a New Tutorial
 
-1. Create a new page: `app/[locale]/[tutorial]/page.tsx`
-2. Add tutorial metadata to the landing page
-3. Create translations in `messages/en.json` and `messages/es.json`
+1. **Create the page**: `app/[locale]/[tutorial-slug]/page.tsx`
+2. **Build components**: `components/tutorials/[tutorial-slug]/`
+3. **Add translations**: Keys in both `messages/en.json` and `messages/es.json`
+4. **Register on landing page**: Add to `LEARNING_CARDS` or `COMING_SOON_CARDS`
+5. **Add to sidebar**: Update `sidebar.tsx` navigation config
+6. **Add breadcrumbs**: Register in `components/navigation/breadcrumbs.tsx`
+
+See `AGENTS.md` for detailed development guidelines.
+
+## i18n
+
+- **Default locale**: English (`en`)
+- **Supported locales**: English, Spanish
+- **Routing**: Prefix-based (`/en/...`, `/es/...`)
+- **Translation files**: `messages/en.json`, `messages/es.json`
+- **Usage**: Always use `useTranslations()` — never hardcode user-facing strings
 
 ## Tech Stack
 
-- Next.js 16
+- Next.js 16 (App Router)
 - React 19
 - TypeScript
 - Tailwind CSS
 - Framer Motion
 - next-intl (i18n)
+- Lucide React (icons)
+- Vercel Analytics
+
+## Book Reference
+
+Content is based on [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook) by Andreas M. Antonopoulos and Gavin Wood. The book is included as a git submodule in `book/` with all 17 chapters in Markdown format.
 
 ## License
 

diff --git a/TODO.md b/TODO.md
@@ -3,6 +3,21 @@
 ## Project Overview
 Interactive educational visualizations for Ethereum protocol concepts, based on [Mastering Ethereum](https://github.com/ethereumbook/ethereumbook).
 
+### Recent Updates
+- 2026-04-07: Added a Discord invite CTA to the current chapter area on the front page so people can join the study-group coordination space directly from the landing page.
+- 2026-04-07: Removed the dead Chapter 2 notes link from the front page and replaced it with a non-clickable "after reading" status until those notes actually exist.
+- 2026-04-07: Updated the front page chapter-link model to use explicit lesson mappings and linked Chapter 2 to the existing Transactions and Gas lessons, based on the chapter’s focus on wallets, transactions, and gas basics.
+- 2026-04-07: Added English note translations under `notes/translations/en/` and updated the notes page to render localized content, with an English-only notice that translations were produced using GPT-5.4.
+- 2026-04-07: Made the sidebar discover chapter notes dynamically from `notes/chapters/` through an API route, so new Markdown notes appear automatically without manual nav updates.
+- 2026-04-07: Installed `marked` and converted chapter notes into rendered in-app pages under `/{locale}/notes/[slug]`, with a banner clarifying that notes are currently available only in Spanish.
+- 2026-04-07: Replaced the Chapter 1 notes placeholder with detailed study notes in `notes/chapters/chapter-1.md`, preserving links to the slide deck and replay playlist.
+- 2026-04-07: Added a versioned `notes/chapters/` workspace plus a `/notes/[slug]` route so each study chapter can link to Markdown notes directly from the front page.
+- 2026-04-07: Added the Chapter 1 slide deck to the front-page archive as a direct resource link while keeping the shared YouTube playlist as the replay entry point.
+- 2026-04-07: Adjusted the front page study sequence so the current chapter points to Chapter 2 via the Luma embed and the archive starts with Chapter 1 while reusing the shared playlist for replay access.
+- 2026-04-07: Refocused the localized front page around the current chapter, with the Luma embed as the primary study surface, a dedicated playlist replay panel, and an archive of past chapters with linked InteractivETH resources.
+- 2026-04-06: Reworked the localized landing page into a minimalist hacker-style front page with embedded Luma and YouTube study surfaces plus a NotebookLM resource entry point.
+- 2026-04-06: Added a chapter directory to the front page with Mastering Ethereum chapter links, replay access, InteractivETH routes, and related project resources.
+
 ---
 
 ## Completed Tutorials
@@ -279,7 +294,7 @@ t('simulator.validator.gasUsed', { used: 15000000, limit: 30000000 });
 ---
 
 ## Last Updated
-Date: 2026-04-02  
+Date: 2026-04-07  
 Current Status: ✅ All 3 block-building tutorials complete (Validator, Gas, Block Internals)
 Next Milestone: Smart Contracts tutorial