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

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/.
• 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.

Commands

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:

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

type(scope): short description

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

Examples:

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