blb-throne-of-the-bone-king/AGENTS.md

# AGENTS.md - Throne of the Bone King

AI agent and coding assistant instructions for this repo.

## Project Summary

Throne of the Bone King is an early-stage Bone Lord Bob game shell. It uses React Native 0.85.3 with a shared UI layer for browser, Electron, and future native mobile targets.

Primary iteration targets today:

- Browser: Vite + React Native Web
- Desktop: Electron with a Vite renderer
- Toolkit: browser-only support surface backed by a local Socket.IO server

Native React Native source is present, but `android/` and `ios/` are not currently in this checkout.

Read `llm.txt`, `manifest.llm.json`, and this file before broad changes.

## Ground Rules

### Do

- Write TypeScript with strict, explicit types. Avoid `any` unless genuinely unavoidable.
- Use functional components and React hooks exclusively.
- Keep shared UI in React Native components and `StyleSheet.create()`.
- Keep `App.tsx` as the app root and `src/navigation/AppNavigator.tsx` as the lightweight navigator.
- Use existing Zustand stores and persistence helpers for app state.
- Put browser-only APIs in `.web.ts`, `.web.tsx`, or `src/web/` only.
- Write focused tests in `__tests__/` for new logic, route metadata, stores, socket helpers, or screen behavior.
- Commit as Jacob Mathison (`jacob@mathisonprojects.com`) when asked to commit. Never commit as an AI identity.

### Don't

- Do not use `window`, `document`, `localStorage`, `Audio`, or other DOM/browser APIs in shared native code.
- Do not add React Navigation or another navigation library unless explicitly requested.
- Do not modify `android/` or `ios/` native files unless explicitly asked and those folders exist.
- Do not commit `node_modules/`, `Pods/`, `dist/`, or other build artifacts.
- Do not run destructive commands such as `rm -rf`, `git reset --hard`, `git checkout --`, or `git push --force` without explicit confirmation.
- Do not replace user work in a dirty worktree. Work with existing changes.

## Structure Conventions

```text
src/
  assets/             # Images, fonts, music, SCSS entrypoints
  components/         # Reusable React Native UI components
  config/             # Build/runtime labels and platform config
  data/               # Editable JSON content and typed data exports
  hooks/              # Custom hooks and platform hooks
  navigation/         # Route metadata and app-state navigator
  screens/            # Screen-level components
  settings/           # Game setting definitions
  socket/             # Browser client for Toolkit socket sync
  state/              # Zustand stores and persistence helpers
  styles/             # Shared RN typography/style helpers
  types/              # Asset and ambient type declarations
socket/               # Local Toolkit Socket.IO server
electron/             # Electron main/preload source
__tests__/            # Jest tests
```

## Current App Behavior

- Home menu shows New Game, Saves, Settings, Policies, Credits, and Toolkit.
- Toolkit is shown only when the resolution setting is `browser`.
- Toolkit is clickable only when the socket status is connected.
- Route state persists through refreshes.
- Settings persist resolution, autosave, mute, and master/music/ambience/speech/SFX volume.
- Browser background music is implemented in `useBackgroundMusic.web.ts`.
- Credits Toolkit data is sourced from `src/data/credits.json` and synced through the socket server.

## Common Tasks

### Add or change a screen

1. Update route metadata in `src/navigation/routes.ts` when adding a route.
2. Wire route rendering in `src/navigation/AppNavigator.tsx` if needed.
3. Add or update the screen in `src/screens/`.
4. Add tests in `__tests__/screenScaffold.test.tsx` or a focused test file.
5. Update `manifest.llm.json` if routes, screens, or architecture change.

### Add or change persisted state

1. Prefer an existing store in `src/state/` when the state belongs there.
2. Use `createPersistOptions`.
3. Keep platform storage inside `persistStorage.ts` and `persistStorage.web.ts`.
4. Add merge/migration handling for persisted shape changes.
5. Add store tests.
6. Update `manifest.llm.json` if store names, persist keys, or state surfaces change.

### Add Toolkit content sync

1. Keep canonical editable JSON in `src/data/`.
2. Add a typed model and runtime validation near the data export.
3. Extend `socket/contentStore.cjs` and `socket/server.mjs` for server read/save/watch behavior.
4. Extend `src/socket/toolkitSocketClient.ts` and a store under `src/state/` for client state.
5. Keep Toolkit UI read-only unless editable forms are explicitly requested.

### Work with assets

- Images: `src/assets/images/`
- Fonts: `src/assets/fonts/`
- Music: `src/assets/music/`
- Browser SCSS: `src/assets/scss/`
- Add or update asset type declarations in `src/types/assets.d.ts` when needed.

## Commands

```bash
npm install
npm run web
npm run dev:toolkit
npm run dev:all
npm run dev:clear
npm run electron:dev
npm run web:build
npm run electron:build
npm run lint
npm run test -- --runInBand
npm run validate:commit
```

Mobile commands remain available for when native folders are restored:

```bash
npm run android
npm run ios
npm run start
```

## Verification

- Logic or store changes: `npm run test -- --runInBand`
- UI changes: `npm run lint`, `npm run test -- --runInBand`, `npm run web:build`
- Electron changes: `npm run electron:build`
- Socket changes: run tests plus `npm run dev:toolkit` and check `/health`
- Commit validation: `npm run validate:commit`

Husky runs `npm run validate:commit` on pre-commit.

## Commit Message Format

```text
type(scope): short description
```

Types: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `style`.

Examples:

```text
feat(toolkit): add credits content sync
fix(settings): persist audio mute state
docs: update project agent instructions
```

## Gitea Repo

`http://100.79.253.19:3000/jacob-mathison/blb-throne-of-the-bone-king`

Default branch: `main`