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, Change Log, 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`.
- Change Log content is sourced from `src/data/toolkit/changelog.json`.
- Credits Toolkit data is sourced from `src/data/toolkit/credits.json` and synced through the socket server.
- Toolkit Images and Audio records can upload files through the socket into `src/assets/images/uploads/` and `src/assets/music/uploads/`.
- Local Toolkit authoring uses `http://127.0.0.1:5175` by default so it does not collide with deployed socket automation.
- Deployed Toolkit authoring uses `http://bone-kingdom.tabitha.tealthrone:5174` and intentionally runs from the shared repo workspace so edits update development JSON/assets while coding continues.
- Toolkit seed datasets live under `src/data/toolkit/` and are exported through `src/data/index.ts`.
- Shared data interfaces live under `src/data/types/`.

## 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 forms schema-driven from JSON fields unless a resource needs a custom editor.

### Add or change data content

1. Read `src/data/AGENTS.md` first.
2. Keep app-imported JSON covered by a typed export and runtime validation.
3. Export data through `src/data/index.ts` so state stores and screens use one import surface.
4. Keep app content JSON such as Changelog, Credits, and Legal under `src/data/toolkit/`.
5. Update `src/data/types/` when schemas or Toolkit content fields change.
6. Add tests for new data shape, ordering, or Toolkit content expectations.

### Before committing or pushing

1. Review whether the work creates a meaningful product, gameplay, Toolkit, content, build, or process change.
2. Add or update an entry in `src/data/toolkit/changelog.json` for meaningful deliverables before committing or pushing.
3. Keep changelog entries concise, user-facing, and tied to the visible deliverable. Do not rely on Husky to write changelog content.
4. If a commit intentionally has no changelog entry, mention the reason in the final handoff.

### 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.

### Work with browser SCSS

1. Use `src/assets/scss/index.scss` as the only browser SCSS entrypoint.
2. Add design tokens and CSS custom properties in `__variables.scss`.
3. Add shared browser mixins in `__mixins.scss`.
4. Keep reset, root, and browser-wide element rules in `__globals.scss` and `__scrollbars.scss`.
5. Put reusable `.blb-*` class builders in the concern-specific partials: `__typography.scss`, `__layout.scss`, `__surfaces.scss`, `__buttons.scss`, `__forms.scss`, and `__toolkit.scss`.
6. Do not add ad hoc browser CSS in screen files. Add or extend a builder class in `src/assets/scss/`, then reference that class from the browser-only surface that needs it.
7. Shared React Native screens and native-compatible components still use `StyleSheet.create()` unless a task explicitly asks for a web-only class-based migration.
8. Keep browser-only class usage, DOM APIs, and web-specific styling assumptions inside `.web.tsx` files, `src/web/`, or explicitly browser-only surfaces.

## Commands

```bash
npm install
npm run web
npm run dev:toolkit
npm run dev:all
npm run dev:clear
npm run deploy:frontend-health
npm run deploy:toolkit
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 or push handoff: confirm `src/data/toolkit/changelog.json` was updated for meaningful deliverables or state why it was not needed.
- Commit validation: `npm run validate:commit`

Husky runs `npm run version:bump-build` and then `npm run validate:commit` on pre-commit. The version bump updates package metadata and public `.env` build fields for `version-yyyymmdd-last7commit` display.

## 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`