# Project Purupuru

> Tsuheji trading cards — a ghibli-warm world where bears roam, honey flows, and five elements hold everything in balance.

## What This Is

A world-building construct for Project Purupuru, a card collection experience set in Tsuheji (土和吉). Not a game engine. Not a codebase. A knowledge architecture — the canonical world state, design vocabulary, and card system that multiple repos, agents, and team members build from.

Three consumers: humans reading markdown, AI agents querying entities, machines processing structured data.

For the full expanded context, read `llms-full.txt`. For programmatic access, connect the MCP server (`npx purupuru-mcp`).

## Quick Orientation

- **World**: 5 Wuxing elements (Wood/Fire/Earth/Metal/Water), 5 KIZUNA characters, Puruhani honey creatures, the city of Horai
- **Cards**: 168 total (30 per element × 5 + 18 special). Rarity through art quality, not labels.
- **Tone**: Warm, wholesome, low-conflict. Studio Ghibli aesthetic. The greeting is "henlo."
- **Anti-patterns**: Never wallet before beauty. Never prices on collection page. Never scarcity language.

## Key Files

| What | Where |
|------|-------|
| World constants + anti-patterns | `CLAUDE.md` |
| Canonical lore (single source of truth) | `grimoires/purupuru/lore-bible.md` |
| Entity-Component-System architecture | `grimoires/purupuru/ecs/INDEX.md` |
| Design tokens (OKLCH, motion, spacing) | `taste.md` |
| Product philosophy | `grimoires/purupuru/dna/product-philosophy.md` |
| Score API contract (wallet → element) | `grimoires/purupuru/specs/score-api-contract.md` |
| Lore gaps (open questions) | `grimoires/purupuru/gaps/gaps.md` |
| Construct declaration | `construct.yaml` |
| World ontology (relational model) | `grimoires/project-purupuru/world/ontology.yaml` |
| Construct manifest (programmatic index) | `grimoires/purupuru/manifest.json` |

## Lookup Patterns

- Characters: `grimoires/purupuru/lore-bible.md` § 5 (KIZUNA)
- Elements: `grimoires/purupuru/ecs/entities/element.md` or `grimoires/purupuru/ecs/components/wuxing-data.md`
- Locations: `grimoires/purupuru/lore-bible.md` § 2 (Horai)
- Card types: `grimoires/purupuru/ecs/entities/card.md`
- ECS systems: `grimoires/purupuru/ecs/systems/{system-name}.md`
- Design decisions: `grimoires/purupuru/decisions/{topic}.md`
- Research: `grimoires/purupuru/research/{topic}.md`
- Tracks: `grimoires/purupuru/tracks/track{N}-{name}.md`

## The Five Elements

| Element | Kanji | Character | Bear | Virtue | Color |
|---------|-------|-----------|------|--------|-------|
| Wood (木) | 木 | Kaori (Hopeful) | Panda | Benevolence (仁) | oklch(0.81 0.144 112.7) |
| Earth (土) | 土 | Nemu (Empty) | Brown | Fidelity (信) | oklch(0.85 0.153 83.8) |
| Fire (火) | 火 | Akane (Naughty) | Black | Propriety (禮) | oklch(0.64 0.181 28.4) |
| Metal (金) | 金 | Ren (Loyal) | Polar | Righteousness (義) | oklch(0.52 0.126 309.7) |
| Water (水) | 水 | Ruan (Overstimulated) | Red Panda | Wisdom (智) | oklch(0.53 0.180 266.2) |

## Skills

| Command | What It Does |
|---------|-------------|
| `/puru-ground` | Load world vocabulary and design direction |
| `/canon-check` | Verify a lore claim against canonical sources |
| `/lore-lookup` | Query specific lore topics |
| `/lore-gap` | Log an unanswered question for resolution |

## Canon Tiers

Content in this construct carries one of four status levels:

| Tier | Meaning |
|------|---------|
| `canonical` | World truth. Contradicting this is a build failure. |
| `established` | Committed design decisions. Stable but revisable. |
| `exploratory` | Active investigation. May become established or be pruned. |
| `speculative` | Ideas not yet validated. Not actionable. |

## Team

| Handle | Domain |
|--------|--------|
| @zksoju | Architecture, contracts, game design, UI engineering |
| @gumi | Lore, art direction, world-building — **lore bible authority** |
| @zerker | Behavioral intelligence, Score API, on-chain data |
| @lily | APAC GTM, bazi/metaphysical agent direction |

## Agent Access

| Method | For |
|--------|-----|
| `AGENTS.md` | **Universal agent instructions** — start here if you're an AI agent |
| `npx skills add project-purupuru/world` | **Install as agent skill** — one command, gain bazi readings + Wuxing queries + world voice |
| `llms.txt` (this file) | Quick orientation |
| `llms-full.txt` | Full agent context (elements, characters, cards, design, integration points) |
| `npx purupuru-mcp` | MCP server — query elements, characters, cards, bazi, lore programmatically |
| `/constructs install project-purupuru` | Install as a Claude Code construct |
| `construct.yaml` | Machine-readable declaration (schema v3) |
| `grimoires/purupuru/manifest.json` | Programmatic entity index |
| `grimoires/purupuru/construct-nav.md` | Full construct routing map (26 packs) |

## Related Repos

- **App repo**: `purupuru` (Next.js consumer app, contracts, Convex backend)
- **Mibera Codex**: `construct-mibera-codex` (sibling construct, pattern reference)
- **HivemindOS**: `hivemind-os` (organizational OS)
- **Echelon constructs**: `tremor`, `corona`, `breath` (environmental data oracles)