# Idlegame Agent Guide

Idlegame is a proprietary idle/incremental text-fantasy RPG inspired by Your
Chronicle. It is a responsive web + PWA project with a pure TypeScript game
engine and a React/Zustand view layer.

## User And Context

- Address the user as **ginnoir** or **senpai**. Never call him Matt.
- The Obsidian vault is the cross-project source of truth for design, story,
  decisions, and session memory.
- Vault MCP path: `claude/Context.md` first, then `Idlegame/_Claude.md`.
- Local vault path for tools without MCP: `C:\Users\MattC\Documents\Obsidian Vault\`.
- Credentials used by AI tools live in the vault at `claude/Credentials.md`.
  Never hardcode tokens or secrets in this repo.
- Repo docs are code-truth: setup, architecture, ADRs, and plans. Vault notes
  hold design intent and durable operational context.

## Commands

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Typecheck: `pnpm typecheck`
- Lint/format check: `pnpm lint`
- Format: `pnpm format`
- Unit tests: `pnpm test`
- Coverage: `pnpm test:coverage`
- Production build: `pnpm build`

The required pre-PR verification chain is:

```powershell
pnpm typecheck
pnpm lint
pnpm test:coverage
pnpm build
```

## Architecture Rules

- `src/engine/` is pure TypeScript. It must not import React, Zustand, browser
  APIs, storage APIs, or wall-clock scheduling.
- `src/content/` contains data-driven resource/action/story definitions and
  Zod validation.
- `src/state/` bridges engine snapshots into Zustand and owns environment
  coupling such as requestAnimationFrame, IndexedDB, localStorage fallback, and
  lifecycle hooks.
- `src/ui/` is the React shell. It renders store snapshots and calls runtime
  commands; gameplay rules stay out of components.
- Saves are versioned and validated at the boundary. Invalid or tampered saves
  must fail explicitly.
- Numbers remain human-readable; use the `src/engine/num.ts` boundary before
  introducing any Decimal-style library.

## Engineering Norms

- TypeScript strict, immutable-by-default, explicit errors at boundaries.
- Keep functions small and modules focused. Prefer many small files over large
  catch-all modules.
- Tests are required for new engine behavior. Maintain at least 80% coverage on
  `src/engine/`.
- Use permissive dependencies only. No GPL dependencies; this game is
  proprietary and may be sold.
- Commit messages use Conventional Commits, with no AI attribution.

## Tool Routing

- Claude Code: architecture, engine-system design, story/design writing, review,
  vault stewardship, homelab/infra work.
- Codex: scoped implementation tickets, debugging, coverage work, mechanical
  refactors.
- Antigravity: UI implementation, responsive polish, browser/playtest
  verification, visual checks.
- Cursor: small ginnoir-driven edits and exploratory pair-programming.

Use one tool per issue or branch at a time. After M0, all code changes should
land through a PR unless ginnoir explicitly says otherwise.

## Workflow

- Default Git host: private Gitea at `gitea.ginnoir.com/ginnoir/idlegame`.
- Trunk is `main`; feature work happens on branches with PRs.
- Gitea Issues are implementation work items. Plane epics are roadmap grouping.
- Internal playtest URL: `idlegame.ginnoir.com` via Caddy `internal_only`.

When a session produces durable knowledge, write it back to
`Idlegame/_Claude.md` or a topic note in the vault before ending.