Upload folder using huggingface_hub

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,42 @@
+name: Sync to Hugging Face hub
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python environment
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install Hugging Face Hub library
+        run: pip install huggingface_hub
+
+      - name: Upload project files to HF Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          python -c "
+          import os
+          from huggingface_hub import HfApi
+          
+          # Initialize the API using your GitHub Actions secret
+          api = HfApi(token=os.environ['HF_TOKEN'])
+          
+          # Upload everything in the repository folder directly to your Space
+          api.upload_folder(
+              folder_path='.',
+              repo_id='byte-vortex/Myco',
+              repo_type='space'
+          )
+          "

.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# Environment variables
+.env
+.env.local
+
+# Gradio
+.gradio/
+
+# Hugging Face cache
+.cache/
+huggingface_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# macOS
+.DS_Store
+
+# VS Code
+.vscode/
+
+# PyCharm
+.idea/
+
+# Logs
+*.log
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Model files
+*.gguf
+*.bin
+*.safetensors
+models/downloads/
+models/**/*.gguf
+models/**/*.bin
+models/**/*.safetensors
+
+# Temporary files
+tmp/
+temp/

CODEx_USAGE.md

@@ -0,0 +1,16 @@
+# Codex Usage
+
+This repository intentionally documents how Codex contributed to the project so the Codex track can evaluate both the product quality and the development process.
+
+## Codex-Assisted Milestones
+
+- Generated the initial Gradio skeleton for Myco's first playable loop.
+- Implemented the mushroom discovery engine and companion response flow.
+- Added MycoDex collection tracking with duplicate prevention.
+- Refactored the app into clearer `app.py`, `game/`, `models/`, `ui/`, `data/`, and `tests/` sections.
+- Added an in-repo mushroom catalog with Common, Rare, and Legendary discoveries.
+- Added tests for the catalog, discovery loop, companion replies, collection tracking, and markdown renderers.
+
+## Design Goal
+
+Myco is built to be a polished, small-scope project rather than a sprawling prototype: explore, discover a mushroom, ask Myco, and add the discovery to the MycoDex.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noriko Kono
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,15 +1,82 @@
----
-title: Myco
-emoji: 🌍
-colorFrom: pink
-colorTo: yellow
-sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
-app_file: app.py
-pinned: false
-license: mit
-short_description: Build Small Hackathon Project
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🍄 Myco
+
+Myco is a cozy exploration game prototype for Gradio + Hugging Face Spaces. Myco, an AI mushroom companion, helps players discover strange fungi in a magical forest and collect them in a MycoDex.
+
+## First 60 Seconds
+
+1. Open the game.
+2. Meet Myco: "Hello! I'm Myco. Let's explore the forest."
+3. Click **Explore**.
+4. Discover a mushroom, such as **Glowcap**.
+5. Ask Myco about it.
+6. Add it to the **MycoDex**.
+
+## Hackathon MVP
+
+- Explore button
+- Mushroom discovery
+- Myco chat panel
+- MycoDex collection
+- 30 starter mushroom species
+- Common, Rare, and Legendary rarity tiers
+
+The MVP intentionally skips combat, multiplayer, and a huge map so the first playable loop is clear and achievable.
+
+
+## Project Structure
+
+```text
+hf-gradio-small-hackathon-myco/
+├── app.py
+├── requirements.txt
+├── .gitignore
+├── assets/
+│   ├── images/
+│   └── sounds/
+├── data/
+├── game/
+├── models/
+├── ui/
+├── tests/
+├── CODEx_USAGE.md
+└── README.md
+```
+
+`assets/` and `data/` are tracked with placeholder files so art, sounds, and game data have obvious homes. `models/` contains lightweight Python domain models, while heavyweight local model downloads remain ignored by Git through file patterns and `models/downloads/`.
+
+## Local Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
+
+Then open the local Gradio URL printed in the terminal.
+
+## Hugging Face Space
+
+Create a Gradio Space and include these files at the repository root:
+
+```text
+README.md
+app.py
+requirements.txt
+.gitignore
+```
+
+Hugging Face Spaces will install `requirements.txt` and run `app.py`.
+
+## Future Ideas
+
+- Mushroom rarity progression
+- Mushroom villages
+- Mushroom recipes
+- Mushroom evolution
+- Generated mushroom art
+- Optional small-model backend such as `gpt-oss-20b`
+
+## Codex Track Notes
+
+See [`CODEx_USAGE.md`](CODEx_USAGE.md) for a concise record of how Codex helped shape the app architecture, gameplay loop, refactor, and tests.

app.py

@@ -0,0 +1,9 @@
+"""Hugging Face Spaces entrypoint for Myco."""
+
+from ui.gradio_app import build_app
+
+
+demo = build_app()
+
+if __name__ == "__main__":
+    demo.launch()

data/mushrooms.json

@@ -0,0 +1,32 @@
+[
+  {"name": "Glowcap", "rarity": "Common", "habitat": "mossy logs", "lore": "I think this one glows at night, but I'm not completely sure."},
+  {"name": "Moonveil", "rarity": "Rare", "habitat": "moonlit clearings", "lore": "Its veil catches moonbeams like a tiny silver net."},
+  {"name": "Honeybell", "rarity": "Common", "habitat": "old beehives", "lore": "Forest beetles nap beneath its sticky amber cap."},
+  {"name": "Ember Button", "rarity": "Rare", "habitat": "warm ash beds", "lore": "It keeps a gentle heat long after campfires fade."},
+  {"name": "Velvet Spore", "rarity": "Common", "habitat": "fern shadows", "lore": "Touching the cap leaves a soft violet dust on your glove."},
+  {"name": "Rainwhistle", "rarity": "Common", "habitat": "stream banks", "lore": "When rain is near, its hollow stem hums a little tune."},
+  {"name": "Fox Lantern", "rarity": "Rare", "habitat": "fox trails", "lore": "Foxes seem to use these as quiet waymarkers after dusk."},
+  {"name": "Stardrop Morel", "rarity": "Legendary", "habitat": "fallen star hollows", "lore": "Its pits sparkle like someone tucked the night sky inside."},
+  {"name": "Puddle Parasol", "rarity": "Common", "habitat": "muddy puddles", "lore": "It opens wide enough to shelter a sleepy field mouse."},
+  {"name": "Lacefin", "rarity": "Rare", "habitat": "misty slopes", "lore": "The frills look delicate, but they spring back after every breeze."},
+  {"name": "Bluebell Inkcap", "rarity": "Common", "habitat": "bluebell patches", "lore": "It leaves blue-black trails that fade into tiny flower shapes."},
+  {"name": "Cinnamon Puff", "rarity": "Common", "habitat": "pine needles", "lore": "It smells cozy, though Myco still recommends caution."},
+  {"name": "Oracle Cup", "rarity": "Legendary", "habitat": "ancient roots", "lore": "Dew pools inside it in patterns that almost look like maps."},
+  {"name": "Tiny Crown", "rarity": "Rare", "habitat": "stump kingdoms", "lore": "Several beetles were clearly holding a meeting around it."},
+  {"name": "Marshmallow Shelf", "rarity": "Common", "habitat": "willow trunks", "lore": "It looks pillowy, but has the firmness of polished cork."},
+  {"name": "Ghost Gill", "rarity": "Legendary", "habitat": "fog pockets", "lore": "Its gills vanish unless you look from the corner of your eye."},
+  {"name": "Sunfreckle", "rarity": "Common", "habitat": "sunny meadows", "lore": "Golden dots move across the cap as the afternoon passes."},
+  {"name": "Acorn Bonnet", "rarity": "Common", "habitat": "oak roots", "lore": "Squirrels keep hiding acorns underneath its cap."},
+  {"name": "Glass Stem", "rarity": "Legendary", "habitat": "crystal springs", "lore": "Its stem is clear enough to see bubbles rising through it."},
+  {"name": "Pepper Pixie", "rarity": "Rare", "habitat": "bramble edges", "lore": "A sneezy little mushroom that dusts the air with silver specks."},
+  {"name": "Dream Oysterlace", "rarity": "Legendary", "habitat": "sleepy groves", "lore": "Standing nearby makes the forest sound softer and farther away."},
+  {"name": "Moss Muffin", "rarity": "Common", "habitat": "deep moss beds", "lore": "It grows in plump clusters that look like a tiny bakery window."},
+  {"name": "Wisp Ear", "rarity": "Rare", "habitat": "lantern groves", "lore": "It tilts toward whispers and away from loud bootsteps."},
+  {"name": "Ruby Knuckle", "rarity": "Legendary", "habitat": "red clay banks", "lore": "Its red bumps are shiny, knobbly, and oddly cheerful."},
+  {"name": "Snowcap", "rarity": "Rare", "habitat": "cold hilltops", "lore": "A cool powder rests on top even in warm weather."},
+  {"name": "Clockwork Chanterelle", "rarity": "Legendary", "habitat": "abandoned paths", "lore": "Its ridges tick softly, though nobody knows what time it keeps."},
+  {"name": "Lavender Lantern", "rarity": "Rare", "habitat": "twilight gardens", "lore": "A calm purple glow gathers beneath the cap at sunset."},
+  {"name": "Pebblecap", "rarity": "Common", "habitat": "gravel paths", "lore": "It disguises itself as a stone until the forest gets quiet."},
+  {"name": "Tea Saucer", "rarity": "Common", "habitat": "cottage ruins", "lore": "Rainwater in its cap smells faintly of chamomile."},
+  {"name": "Aurora Fan", "rarity": "Legendary", "habitat": "northern pines", "lore": "Its fan-shaped cap shimmers green and pink when clouds move."}
+]

game/catalog.py

@@ -0,0 +1,18 @@
+"""Mushroom catalog loading for Myco."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+from models.mushroom import Mushroom
+
+CATALOG_PATH = Path(__file__).resolve().parents[1] / "data" / "mushrooms.json"
+
+
+@lru_cache(maxsize=1)
+def load_mushrooms() -> tuple[Mushroom, ...]:
+    """Load the in-repo mushroom catalog."""
+    raw_mushrooms = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+    return tuple(Mushroom.from_dict(item) for item in raw_mushrooms)

game/engine.py

@@ -0,0 +1,75 @@
+"""Core Myco gameplay actions independent from Gradio."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+
+from game.catalog import load_mushrooms
+from game.state import (
+    ChatHistory,
+    CollectionState,
+    MushroomState,
+    collection_contains,
+    mushroom_from_state,
+    welcome_history,
+)
+from models.mushroom import Mushroom
+
+
+def choose_mushroom(catalog: Sequence[Mushroom] | None = None) -> Mushroom:
+    """Choose a mushroom discovery from the catalog."""
+    mushrooms = tuple(catalog or load_mushrooms())
+    return random.choice(mushrooms)
+
+
+def discover_mushroom(collection: CollectionState, catalog: Sequence[Mushroom] | None = None) -> tuple[Mushroom, MushroomState, ChatHistory]:
+    """Discover a mushroom and return the updated discovery state."""
+    mushroom = choose_mushroom(catalog)
+    current = mushroom.to_dict()
+    history = welcome_history()
+    history.append(
+        {
+            "role": "assistant",
+            "content": f"We found a {mushroom.name}! Ask me about it, or add it to your MycoDex.",
+        }
+    )
+    return mushroom, current, history
+
+
+def myco_reply(message: str, history: ChatHistory, current: MushroomState | None) -> tuple[str, ChatHistory]:
+    """Generate a lightweight companion reply without requiring an external model."""
+    clean_message = message.strip()
+    if not clean_message:
+        return "", history
+
+    next_history = [*history, {"role": "user", "content": clean_message}]
+
+    if current:
+        mushroom = mushroom_from_state(current)
+        answer = (
+            f"I think this is **{mushroom.name}**. {mushroom.lore} "
+            "The MycoDex still marks edible, magic, and danger as unknown, "
+            "so let's observe it gently instead of tasting anything."
+        )
+    else:
+        answer = "Let's explore first. The forest usually reveals a mushroom when we move slowly and listen."
+
+    next_history.append({"role": "assistant", "content": answer})
+    return "", next_history
+
+
+def collect_current(
+    current: MushroomState | None,
+    collection: CollectionState,
+    history: ChatHistory,
+) -> tuple[CollectionState, ChatHistory]:
+    """Add the current mushroom to the MycoDex if it is not already collected."""
+    if current is None:
+        return collection, [*history, {"role": "assistant", "content": "Let's discover a mushroom before updating the MycoDex."}]
+
+    if collection_contains(collection, current["name"]):
+        return collection, [*history, {"role": "assistant", "content": f"{current['name']} is already safe in your MycoDex."}]
+
+    updated_collection = [*collection, current]
+    return updated_collection, [*history, {"role": "assistant", "content": f"Added {current['name']} to the MycoDex. Nice find!"}]

game/state.py

@@ -0,0 +1,27 @@
+"""State helpers for Myco's first playable loop."""
+
+from __future__ import annotations
+
+from models.mushroom import Mushroom
+
+WELCOME_MESSAGE = "Hello! I'm Myco. Let's explore the forest."
+EMPTY_DEX = "Your MycoDex is empty. Discover a mushroom, then add it here."
+
+ChatHistory = list[dict[str, str]]
+MushroomState = dict[str, str]
+CollectionState = list[MushroomState]
+
+
+def welcome_history() -> ChatHistory:
+    """Return the opening Myco companion message."""
+    return [{"role": "assistant", "content": WELCOME_MESSAGE}]
+
+
+def mushroom_from_state(current: MushroomState) -> Mushroom:
+    """Hydrate a mushroom from Gradio state."""
+    return Mushroom.from_dict(current)
+
+
+def collection_contains(collection: CollectionState, mushroom_name: str) -> bool:
+    """Return whether the MycoDex already has a mushroom by name."""
+    return any(entry["name"] == mushroom_name for entry in collection)

models/mushroom.py

@@ -0,0 +1,44 @@
+"""Domain models for Myco discoveries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Mushroom:
+    """A discoverable mushroom species for the MycoDex."""
+
+    name: str
+    rarity: str
+    habitat: str
+    lore: str
+    edible: str = "Unknown"
+    magic: str = "Unknown"
+    danger: str = "Unknown"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Mushroom":
+        """Create a mushroom from JSON-compatible data."""
+        return cls(
+            name=str(data["name"]),
+            rarity=str(data["rarity"]),
+            habitat=str(data["habitat"]),
+            lore=str(data["lore"]),
+            edible=str(data.get("edible", "Unknown")),
+            magic=str(data.get("magic", "Unknown")),
+            danger=str(data.get("danger", "Unknown")),
+        )
+
+    def to_dict(self) -> dict[str, str]:
+        """Return a JSON/state-friendly representation."""
+        return {
+            "name": self.name,
+            "rarity": self.rarity,
+            "habitat": self.habitat,
+            "lore": self.lore,
+            "edible": self.edible,
+            "magic": self.magic,
+            "danger": self.danger,
+        }

requirements.txt

@@ -0,0 +1 @@
+gradio>=5.0,<6.0

tests/test_game_loop.py

@@ -0,0 +1,70 @@
+"""Tests for Myco's core game loop."""
+
+from __future__ import annotations
+
+import unittest
+
+from game.catalog import load_mushrooms
+from game.engine import collect_current, discover_mushroom, myco_reply
+from game.state import EMPTY_DEX, welcome_history
+from models.mushroom import Mushroom
+from ui.renderers import dex_markdown, mushroom_card
+
+
+class MycoGameLoopTests(unittest.TestCase):
+    """Coverage for the first playable Myco loop."""
+
+    def test_catalog_has_mvp_scale_and_rarities(self) -> None:
+        mushrooms = load_mushrooms()
+
+        self.assertEqual(len(mushrooms), 30)
+        self.assertEqual({mushroom.rarity for mushroom in mushrooms}, {"Common", "Rare", "Legendary"})
+
+    def test_discover_mushroom_returns_current_state_and_myco_prompt(self) -> None:
+        glowcap = Mushroom("Glowcap", "Common", "mossy logs", "I think this one glows at night, but I'm not completely sure.")
+
+        mushroom, current, history = discover_mushroom([], catalog=[glowcap])
+
+        self.assertEqual(mushroom, glowcap)
+        self.assertEqual(current["name"], "Glowcap")
+        self.assertEqual(history[0], {"role": "assistant", "content": "Hello! I'm Myco. Let's explore the forest."})
+        self.assertIn("We found a Glowcap", history[1]["content"])
+
+    def test_myco_reply_comments_on_current_mushroom(self) -> None:
+        current = Mushroom(
+            "Glowcap",
+            "Common",
+            "mossy logs",
+            "I think this one glows at night, but I'm not completely sure.",
+        ).to_dict()
+
+        prompt, history = myco_reply("What is it?", welcome_history(), current)
+
+        self.assertEqual(prompt, "")
+        self.assertEqual(history[-1]["role"], "assistant")
+        self.assertIn("I think this is **Glowcap**", history[-1]["content"])
+        self.assertIn("not completely sure", history[-1]["content"])
+
+    def test_collect_current_adds_once(self) -> None:
+        current = Mushroom("Glowcap", "Common", "mossy logs", "I think this one glows at night, but I'm not completely sure.").to_dict()
+
+        collection, history = collect_current(current, [], welcome_history())
+        second_collection, second_history = collect_current(current, collection, history)
+
+        self.assertEqual([entry["name"] for entry in collection], ["Glowcap"])
+        self.assertEqual(second_collection, collection)
+        self.assertIn("already safe", second_history[-1]["content"])
+
+    def test_renderers_show_unknown_traits_and_empty_dex(self) -> None:
+        mushroom = Mushroom("Glowcap", "Common", "mossy logs", "I think this one glows at night, but I'm not completely sure.")
+
+        card = mushroom_card(mushroom)
+
+        self.assertIn("**Edible:** Unknown", card)
+        self.assertIn("**Magic:** Unknown", card)
+        self.assertIn("**Danger:** Unknown", card)
+        self.assertEqual(dex_markdown([]), EMPTY_DEX)
+
+
+if __name__ == "__main__":
+    unittest.main()

ui/gradio_app.py

@@ -0,0 +1,78 @@
+"""Gradio app composition for Myco."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from game.engine import collect_current, discover_mushroom, myco_reply
+from game.state import CollectionState, MushroomState, welcome_history
+from ui.renderers import dex_markdown, mushroom_card
+
+
+def explore(collection: CollectionState) -> tuple[str, MushroomState, list[dict[str, str]], str]:
+    """Gradio callback for the Explore button."""
+    mushroom, current, history = discover_mushroom(collection)
+    return mushroom_card(mushroom), current, history, dex_markdown(collection)
+
+
+def ask_myco(
+    message: str,
+    history: list[dict[str, str]],
+    current: MushroomState | None,
+) -> tuple[str, list[dict[str, str]]]:
+    """Gradio callback for the companion chat panel."""
+    return myco_reply(message, history, current)
+
+
+def add_to_dex(
+    current: MushroomState | None,
+    collection: CollectionState,
+    history: list[dict[str, str]],
+) -> tuple[CollectionState, str, list[dict[str, str]]]:
+    """Gradio callback for collecting the current mushroom."""
+    updated_collection, updated_history = collect_current(current, collection, history)
+    return updated_collection, dex_markdown(updated_collection), updated_history
+
+
+def build_app() -> gr.Blocks:
+    """Build the Gradio interface for Hugging Face Spaces."""
+    theme = gr.themes.Soft(primary_hue="green", secondary_hue="emerald")
+    with gr.Blocks(theme=theme, title="Myco") as demo:
+        current_mushroom = gr.State(None)
+        collection = gr.State([])
+
+        gr.Markdown(
+            """
+            # 🍄 Myco
+            **Explore a magical forest with Myco, an AI mushroom companion. Discover edible, magical, dangerous, and legendary fungi while completing your MycoDex.**
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                discovery = gr.Markdown(mushroom_card(None), elem_id="discovery-card")
+                with gr.Row():
+                    explore_button = gr.Button("Explore", variant="primary")
+                    add_button = gr.Button("Add to MycoDex")
+            with gr.Column(scale=3):
+                chat = gr.Chatbot(value=welcome_history(), label="Myco Chat", type="messages", height=360)
+                with gr.Row():
+                    prompt = gr.Textbox(
+                        label="Ask Myco",
+                        placeholder="What do you know about this mushroom?",
+                        scale=4,
+                    )
+                    ask_button = gr.Button("Ask Myco", scale=1)
+
+        dex = gr.Markdown(dex_markdown([]), elem_id="mycodex")
+
+        explore_button.click(
+            explore,
+            inputs=[collection],
+            outputs=[discovery, current_mushroom, chat, dex],
+        )
+        ask_button.click(ask_myco, inputs=[prompt, chat, current_mushroom], outputs=[prompt, chat])
+        prompt.submit(ask_myco, inputs=[prompt, chat, current_mushroom], outputs=[prompt, chat])
+        add_button.click(add_to_dex, inputs=[current_mushroom, collection, chat], outputs=[collection, dex, chat])
+
+    return demo

ui/renderers.py

@@ -0,0 +1,32 @@
+"""Markdown renderers for the Myco Gradio interface."""
+
+from __future__ import annotations
+
+from game.state import CollectionState, EMPTY_DEX
+from models.mushroom import Mushroom
+
+
+def mushroom_card(mushroom: Mushroom | None) -> str:
+    """Render the current mushroom discovery as markdown."""
+    if mushroom is None:
+        return "### 🌲 Forest Clearing\nClick **Explore** to search for a strange fungus."
+
+    return (
+        f"### 🍄 {mushroom.name}\n"
+        f"* **Rarity:** {mushroom.rarity}\n"
+        f"* **Habitat:** {mushroom.habitat}\n"
+        f"* **Edible:** {mushroom.edible}\n"
+        f"* **Magic:** {mushroom.magic}\n"
+        f"* **Danger:** {mushroom.danger}\n"
+    )
+
+
+def dex_markdown(collection: CollectionState) -> str:
+    """Render collected mushrooms as a compact MycoDex."""
+    if not collection:
+        return EMPTY_DEX
+
+    rows = ["### 📖 MycoDex", ""]
+    for entry in collection:
+        rows.append(f"* 🍄 **{entry['name']}** — {entry['rarity']} — found near {entry['habitat']}")
+    return "\n".join(rows)