# construct-purupuru-codex

Canonical knowledge base for the **Purupuru universe** — a world of honey-rooted magic, sentient Puruhani beings, and the Wuxing elemental cycles that bind them.

Built as a [construct-format](https://github.com/0xHoneyJar/construct-base) codex following the patterns established by [construct-mibera-codex](https://github.com/0xHoneyJar/construct-mibera-codex). Serves canonical lore over HTTP and MCP via [HyperJS](https://hyperjs.ai), wiring into the freeside API ecosystem.

## What's in the codex

| Category | Count | Path |
|----------|-------|------|
| KIZUNA Characters | 5 | `characters/` |
| Puruhani | 5 | `puruhani/` |
| Locations | 19 | `locations/` |
| Jani Variants | 15 | `jani/` |
| Cards | 15 | `cards/` |
| Wuxing Elements | 5 | `core-lore/wuxing.yaml` |
| **Total Entities** | **59** | |

### The HENLO System

| Letter | Element | Character | Trait | Puruhani |
|--------|---------|-----------|-------|----------|
| **H** | Wood | Kaori | Hopeful | Happy |
| **E** | Earth | Nemu | Empty | Exhausted |
| **N** | Fire | Akane | Naughty | Nefarious |
| **L** | Metal | Eun | Loyal | Loving |
| **O** | Water | Ruan | Overstimulated | Overwhelmed |

## HTTP API

RESTful API served via HyperJS with OpenAPI 3.1 spec and Swagger UI.

```bash
bun install
bun run dev    # starts on http://localhost:3000
```

### Endpoints

| Route | Method | Description |
|-------|--------|-------------|
| `/v1/characters/:slug` | GET | Look up a KIZUNA character |
| `/v1/puruhani/:identifier` | GET | Look up a Puruhani by element or name |
| `/v1/locations/:slug` | GET | Look up a location |
| `/v1/jani/:variant` | GET | Look up a Jani variant |
| `/v1/cards/:slug` | GET | Look up a canonical card |
| `/v1/elements/:name` | GET | Wuxing element with cycle relationships |
| `/v1/search?q=&limit=` | GET | Fuzzy search across all entities |
| `/v1/entities?type=` | GET | List all entities of a type |
| `/v1/validate` | POST | Validate a claim against canonical data |
| `/health` | GET | Service status with entity counts |
| `/openapi.json` | GET | OpenAPI 3.1 spec |
| `/docs` | GET | Swagger UI |

All entity responses include `world: "purupuru"` for cross-service identification.

## MCP

The same 9 tools are available over MCP via JSON-RPC 2.0 at `POST /mcp`, or via stdio for agent constructs:

```bash
node dist/server.js   # stdio transport (for Claude Desktop, etc.)
```

### 9 Tools

| Tool | Description |
|------|-------------|
| `lookupCharacter` | Look up a KIZUNA character by name or slug |
| `lookupPuruhani` | Look up a Puruhani by element or name |
| `lookupLocation` | Look up a location by slug |
| `lookupJani` | Look up a Jani variant |
| `lookupCard` | Look up a canonical card |
| `lookupElement` | Wuxing element with Sheng/Ke cycle relationships |
| `validateWorldElement` | Anti-hallucination — validate claims against canonical data |
| `search` | Fuzzy search across all entities |
| `listEntities` | List all entities of a given type |

### Add to Claude Desktop

```json
{
  "mcpServers": {
    "purupuru-codex": {
      "command": "node",
      "args": ["/path/to/construct-purupuru-codex/dist/server.js"]
    }
  }
}
```

## Browse

Navigate entities by dimension:

- `browse/by-element/` — Wood, Earth, Fire, Metal, Water
- `browse/by-generation/` — Kizuna
- `browse/by-type/` — Character, Puruhani, Location, Jani
- `browse/by-district/` — Horai Surface, Old Horai, Tsuheji
- `browse/by-canon-tier/` — Canonical, Established, Exploratory, Speculative

## Data Exports

Machine-readable exports in `_codex/data/`:

| File | Format | Content |
|------|--------|---------|
| `characters.jsonl` | JSONL | 5 character records |
| `puruhani.jsonl` | JSONL | 5 puruhani records |
| `locations.jsonl` | JSONL | 19 location records |
| `jani.jsonl` | JSONL | 15 jani records |
| `cards.jsonl` | JSONL | 15 card records |
| `wuxing.json` | JSON | Element system with Sheng/Ke cycles |
| `graph.json` | JSON | Knowledge graph (44 nodes, 67 edges) |
| `scope.json` | JSON | Entity counts and version |

## Skills

Three construct skills for agent-driven exploration:

- **browse-codex** — Navigate by dimension
- **query-entity** — Deterministic lookup with fuzzy fallback
- **cross-reference** — Traverse entity relationships

## Canon Authority

Content follows a four-tier authority model:

| Tier | Meaning |
|------|---------|
| **Canonical** | Binding truth from lore-bible |
| **Established** | Committed decisions from design cycles |
| **Exploratory** | Validated but not locked |
| **Speculative** | Not yet validated |

Source material: [world-purupuru](https://github.com/project-purupuru/world-purupuru)

## Development

```bash
bun install               # Install deps
bun run dev               # HTTP API server (port 3000)
bun run dev:mcp           # MCP stdio server (watch mode)
bun run test              # Run tests (69 specs)
bun run test:api          # Run API tests only
bun run lint              # Lint
bun run build             # Build MCP stdio server
bun run validate:schema   # Validate all entity frontmatter
bun run generate:exports  # Regenerate JSONL/JSON exports
bun run generate:indices  # Regenerate browse indices
```

## License

MIT