198 lines
8.8 KiB
Markdown
198 lines
8.8 KiB
Markdown
# 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`
|