[Docs] README: hero + 12-species gallery + evolution - #31
Conversation
Rebuild README with a focused layout:
- Hero: EmberFox stage 3 (InfernoFox) as the visual lead
- 12-species grid: each species' stage1 (juvenile) image with
element/role metadata
- Evolution strip: EmberFox stage0 -> stage3 to show the visual
progression
- Battle loop diagram
- Type effectiveness table
- Tech stack
- Quick start
The 12 species are the chibi AI art generated via Pollinations
(frontend/public/assets/monsters/{id}/stage{0-3}.png). The README
references them as relative paths so they render on github.com.
📝 WalkthroughWalkthroughREADME.md is substantially rewritten to describe the 12 species, evolution, deterministic combat, technology stack, setup commands, project status, and MIT license. ChangesREADME refresh
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Adversarial review — APPROVEui-reviewer: Hero (InfernoFox stage 3) leads with a striking bug-hunter: All 14 image references resolve to existing files architecture-reviewer: The README links to the existing Self-merge note: single-maintainer context. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 62-65: Update the evolution image section in README.md to render
the four EmberFox stage images in a single horizontal row using a Markdown table
or HTML row, preserving the existing stage order and image paths.
- Line 71: Update the fenced code block in README.md to specify the text
language identifier by changing its opening fence to ```text, preserving the
block contents.
- Around line 16-26: Correct the element matrix in the README so each element
row contains exactly three species and every species matches its documented
elemental classification below. Remove duplicate or contradictory entries, and
update the table header and explanatory text to reflect the corrected
three-species-per-element mapping.
- Line 17: Update the hatch randomness descriptions in README.md to state that
the configured IRandoмSource, via randomSource.seed(salt), determines the result
rather than implying hatch is hardwired to block.prevrandao. Mention
BlockPrevRandaoSource only as the current implementation where useful, and
revise all affected references consistently.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| Four elements, three species each. Rarity comes from a deterministic on-chain RNG | ||
| (`block.prevrandao + tokenId + msg.sender`); the same inputs always hatch the same monster. | ||
|
|
||
| ## Next concrete step | ||
| Open ISSUE-0001 (Foundry workspace init) and ISSUE-0002 (Next.js workspace init) in parallel. | ||
| | | Common (50%) | Common (50%) | Common (50%) | Common (50%) | | ||
| |---|---|---|---|---| | ||
| | 🔥 **Fire** | EmberFox | MagmaTurtle | AquaPup | BubbleFish | | ||
| | 💧 **Water** | AquaPup | MagmaTurtle | OceanDragon | ForestDeer | | ||
| | 🌱 **Nature** | LeafRabbit | MossGolem | ForestDeer | SparkMouse | | ||
| | ⚡ **Electric** | VoltCat | SparkMouse | AquaPup | ThunderWolf | | ||
|
|
||
| ## Quick start (once Phase 1 lands) | ||
| ```bash | ||
| # install Foundry (one-time) | ||
| curl -L https://foundry.paradigm.xyz | bash && foundryup | ||
| (*Shuffled by RNG; Common species shown for illustration.*) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the element matrix.
The section claims three species per element, but each row contains four entries, duplicates species, and contradicts the classifications shown below—for example, MagmaTurtle appears under Water and AquaPup appears under Fire/Electric. Replace this with a three-species-per-element table or remove the illustrative matrix.
Proposed correction
-Four elements, three species each. Rarity comes from a deterministic on-chain RNG
+Four elements, three species each. Rarity comes from a deterministic on-chain RNG
...
-| | Common (50%) | Common (50%) | Common (50%) | Common (50%) |
-|---|---|---|---|---|
-| 🔥 **Fire** | EmberFox | MagmaTurtle | AquaPup | BubbleFish |
-| 💧 **Water** | AquaPup | MagmaTurtle | OceanDragon | ForestDeer |
-| 🌱 **Nature** | LeafRabbit | MossGolem | ForestDeer | SparkMouse |
-| ⚡ **Electric** | VoltCat | SparkMouse | AquaPup | ThunderWolf |
+| Element | Species |
+|---|---|
+| 🔥 **Fire** | EmberFox, MagmaTurtle, FlameBird |
+| 💧 **Water** | AquaPup, BubbleFish, OceanDragon |
+| 🌱 **Nature** | LeafRabbit, MossGolem, ForestDeer |
+| ⚡ **Electric** | VoltCat, SparkMouse, ThunderWolf |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Four elements, three species each. Rarity comes from a deterministic on-chain RNG | |
| (`block.prevrandao + tokenId + msg.sender`); the same inputs always hatch the same monster. | |
| ## Next concrete step | |
| Open ISSUE-0001 (Foundry workspace init) and ISSUE-0002 (Next.js workspace init) in parallel. | |
| | | Common (50%) | Common (50%) | Common (50%) | Common (50%) | | |
| |---|---|---|---|---| | |
| | 🔥 **Fire** | EmberFox | MagmaTurtle | AquaPup | BubbleFish | | |
| | 💧 **Water** | AquaPup | MagmaTurtle | OceanDragon | ForestDeer | | |
| | 🌱 **Nature** | LeafRabbit | MossGolem | ForestDeer | SparkMouse | | |
| | ⚡ **Electric** | VoltCat | SparkMouse | AquaPup | ThunderWolf | | |
| ## Quick start (once Phase 1 lands) | |
| ```bash | |
| # install Foundry (one-time) | |
| curl -L https://foundry.paradigm.xyz | bash && foundryup | |
| (*Shuffled by RNG; Common species shown for illustration.*) | |
| Four elements, three species each. Rarity comes from a deterministic on-chain RNG | |
| (`block.prevrandao + tokenId + msg.sender`); the same inputs always hatch the same monster. | |
| | Element | Species | | |
| |---|---| | |
| | 🔥 **Fire** | EmberFox, MagmaTurtle, FlameBird | | |
| | 💧 **Water** | AquaPup, BubbleFish, OceanDragon | | |
| | 🌱 **Nature** | LeafRabbit, MossGolem, ForestDeer | | |
| | ⚡ **Electric** | VoltCat, SparkMouse, ThunderWolf | | |
| (*Shuffled by RNG; Common species shown for illustration.*) |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 16 - 26, Correct the element matrix in the README so
each element row contains exactly three species and every species matches its
documented elemental classification below. Remove duplicate or contradictory
entries, and update the table header and explanatory text to reflect the
corrected three-species-per-element mapping.
| ## Project status | ||
| See [`PROJECT_STATUS.md`](PROJECT_STATUS.md). Current phase: **Phase 0 — Bootstrap — Done.** Next: Phase 1 — Core shell. | ||
| Four elements, three species each. Rarity comes from a deterministic on-chain RNG | ||
| (`block.prevrandao + tokenId + msg.sender`); the same inputs always hatch the same monster. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Document hatch RNG as the configured source, not only block.prevrandao. README.md:17/74/104 still reads like hatch is hardwired to block.prevrandao, but MonsterNFT.hatch uses randomSource.seed(salt) behind IRandomSource. Describe the configured random source explicitly, and mention BlockPrevRandaoSource only as the current implementation if needed.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 17, Update the hatch randomness descriptions in README.md
to state that the configured IRandoмSource, via randomSource.seed(salt),
determines the result rather than implying hatch is hardwired to
block.prevrandao. Mention BlockPrevRandaoSource only as the current
implementation where useful, and revise all affected references consistently.
|  | ||
|  | ||
|  | ||
|  |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Render the evolution images as an actual strip.
These are four separate Markdown image blocks, so GitHub will render them vertically rather than as the promised stage 0–3 evolution strip. Use a Markdown table or HTML row to place the four images horizontally.
🧰 Tools
🪛 LanguageTool
[style] ~62-~62: Using many exclamation marks might seem excessive (in this case: 14 exclamation marks for a text that’s 4427 characters long)
Context: ...nd/public/assets/monsters/1/stage0.png) 
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 62 - 65, Update the evolution image section in
README.md to render the four EmberFox stage images in a single horizontal row
using a Markdown table or HTML row, preserving the existing stage order and
image paths.
|
|
||
| ## How a round plays | ||
|
|
||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language identifier to the fenced block.
Change the fence to ```text so the README passes markdownlint rule MD040.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 71-71: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` at line 71, Update the fenced code block in README.md to specify
the text language identifier by changing its opening fence to ```text,
preserving the block contents.
Source: Linters/SAST tools
1 participant
Summary
Rebuild the root README with a focused marketing-driven layout using the AI-generated species art.
Visual structure
Image sources
All 14 image references resolve to files under
frontend/public/assets/monsters/{id}/stage{0-3}.png(the Pollinations batch from earlier).Self-merge note
Single-maintainer context.
Summary by CodeRabbit