@@ -4,206 +4,118 @@ Help coding agents work safely and consistently in this repo.
44
55 ## Important References
66
7+**Design Document**: `client-refaction-design.md` - Primary source of truth for architecture and design decisions
8+
79 **Game Server WebSocket API**: https://www.spacemolt.com/api.md
810
9-The `client/` folder in the root is a reference client that includes the library used to connect to the game server.
10-
11-When testing, **reuse existing accounts** when possible. Memory DB files (`memory-*.sqlite`) are in the root and git-ignored. Examples: `memory-test-cli-override.sqlite`, `memory-swarm-01.sqlite`.
12-
13-## Repo Snapshot
14-
15-- **Runtime**: Bun (TypeScript, ESM)
16-- **UI**: Terminal UI via `blessed`
17-- **LLM**: Local Ollama HTTP API
18-- **Data**: SQLite via `bun:sqlite` at `memory-{name}.sqlite`
19-- **Game client**: SpaceMolt reference client (git submodule in `client/`)
20-
21-## Key Paths
22-
23-- `src/index.ts` - Main entry (orchestrates client + LLM + memory + output)
24-- `src/config.ts` - Configuration and CLI args parsing
25-- `src/ollama.ts` - Ollama HTTP client
26-- `src/memory.ts` - SQLite memory store
27-- `src/prompt.ts` - LLM prompt building
28-- `src/actions.ts` - Action validation and dispatch
29-- `src/game-state.ts` - Game state tracking
30-- `src/registration.ts` - Registration flow
31-- `src/output/tui-output.ts` - Interactive TUI output
32-- `src/output/file-logger-output.ts` - Headless log output
33-- `src/output-interface.ts` - Output interface definition
34-- `src/swarm.ts` - Swarm orchestrator for multiple bots
35-- `src/tui/` - TUI components (layout, formatters, colors, utils)
36-- `src/types.ts` - Type definitions
37-- `src/utils.ts` - Shared utilities
38-- `src/constants.ts` - Constants
11+## Workspace Structure
3912
40-## Commands
13+This is a Bun workspace with the following layout:
4114
42-### Install
43-```bash
44-bun install
4515 ```
46-
47-### Run Single Bot (Interactive)
48-```bash
49-bun run ollama-play --name <instance-name>
16+ollama-spacemolt-workspace/
17+├── packages/
18+│ └── client/ # WebSocket client package
19+│ ├── src/ # Source code
20+│ ├── tests/ # Unit tests
21+│ └── package.json
22+├── client-refaction-design.md # Sacred design document
23+├── package.json # Workspace root
24+├── tsconfig.json # Base TypeScript config
25+└── biome.json # Workspace-level formatting/linting
5026 ```
5127
52-Required:
53-- `--name` or `-n`: Instance name (determines DB: `memory-{name}.sqlite`)
28+## Design Principles
5429
55-Optional character overrides (new registrations only):
56-- `--empire` or `-e`: solarian, voidborn, crimson, nebula, outerrim
57-- `--alignment` or `-a`: lawful, good, neutral, chaotic, evil
58-- `--speech-style` or `-s`: mythic, punny, gritty, scholarly
30+From `client-refaction-design.md`:
5931
60-Note: Personality is now custom-generated by the LLM during registration (title + behavior description). The old `--personality` flag has been removed.
32+1. **Reduce abstraction** - Minimize layers between client and server
33+2. **Direct connection** - Connect to WebSocket without intermediate libraries
34+3. **Neutral errors** - Use language from api.md, avoid behavioral bias
35+4. **Single bias point** - Only `prompt` field influences LLM behavior
36+5. **Minimal translation** - Forward game events directly to LLM
6137
62-Examples:
63-```bash
64-bun run ollama-play -n alice
65-bun run ollama-play -n test-bot -e crimson -a evil -s gritty
66-```
67-
68-### Run Non-Interactive (Headless)
69-```bash
70-bun run ollama-play --name <instance-name> --non-interactive [--max-ticks <number>]
71-```
72-
73-Output:
74-- `ui-{name}.log` - UI output with timestamps
75-- `debug-{name}.log` - Debug info (prompts, responses, thinking)
38+## Commands
7639
77-Example:
78-```bash
79-bun run ollama-play --name test-bot --non-interactive --max-ticks 100
80-```
40+### Workspace Level
8141
82-### Run Swarm
8342 ```bash
84-bun run swarm [--count 5] [--prefix swarm] [--empire <empire>] [--alignment <alignment>] [--speech-style <style>]
85-```
43+# Install dependencies
44+bun install
8645
87-Defaults:
88-- Count: 5
89-- Prefix: swarm (creates swarm-01, swarm-02, etc.)
90-- Model: ministral-3:8b
91-- Thinking: false
46+# Run all checks (format, lint, test)
47+bun run check
9248
93-Example:
94-```bash
95-bun run swarm --count 10 --empire crimson --alignment evil --speech-style gritty
49+# Individual checks
50+bun run check:format
51+bun run check:lint
52+bun run check:test
9653 ```
9754
98-### Format and Lint
99-```bash
100-bun run biome:format
101-bun run biome:lint
102-```
103-
104-### Testing
105-
106-Manual testing only. No test runner configured.
107-
108-Prefer reusing existing accounts:
109-- `test-cli-override` → `memory-test-cli-override.sqlite`
110-- `test-bot-1` → `memory-test-bot-1.sqlite`
111-- `swarm-01` through `swarm-05` → `memory-swarm-*.sqlite`
55+### Client Package
11256
113-If you see `Invalid username or token`, delete the instance DB and rerun.
114-
115-## Environment Variables
57+```bash
58+cd packages/client
11659
117-- `OLLAMA_URL` - Ollama server URL (default: `http://localhost:11434`)
118-- `OLLAMA_MODEL` - Model name (default: `qwen3:8b`)
119-- `OLLAMA_TEMPERATURE` - Temperature (default: `0.5`)
120-- `OLLAMA_THINKING` - Enable thinking mode (default: `true`)
121-- `SPACEMOLT_URL` - Game WebSocket URL (default: `wss://game.spacemolt.com/ws`)
122-- `DEBUG` - Enable TUI prompt pane (default: `false`)
123-- `MEMORY_DB` - Override DB path (default: `memory-{name}.sqlite`)
60+# Run checks
61+bun run check
12462
125-Timeout is configured in `src/config.ts` as `ollamaTimeoutMs` (60000ms).
63+# Start client (once implemented)
64+bun run start
65+```
12666
12767 ## Code Style Guidelines
12868
12969 ### Formatting
130-- Use Biome for formatting and linting
131-- Let Biome handle formatting; avoid manual changes
70+- Use Biome for all formatting and linting
71+- Tabs for indentation (2-space width)
72+- Let Biome handle style automatically
13273
13374 ### Naming Conventions
13475 - Types/interfaces: `PascalCase`
135-- Classes: `PascalCase`
13676 - Functions and variables: `camelCase`
137-- Global constants: `SCREAMING_SNAKE_CASE`
138-- Local constants: `camelCase`
139-- File names: `lowercase` with `.ts`
140-
141-### Types and Strictness
142-- `strict` TypeScript enabled; avoid `any`
143-- Use `unknown` then narrow or validate
144-- Prefer explicit return types for public functions
145-- Prefer `null` over `undefined` for intentionally absent values
77+- Constants: `SCREAMING_SNAKE_CASE`
78+- File names: `kebab-case.ts`
14679
147-### Error Handling
148-- Use `try/catch` around external I/O (HTTP, file, DB)
149-- Throw typed errors where appropriate (e.g., `OllamaTimeoutError`)
150-- Validate external inputs; return structured errors (e.g., `validateAction`)
151-- Log errors with context; keep user-facing messages concise
80+### TypeScript
81+- `strict` mode enabled
82+- Avoid `any`, use `unknown` then narrow
83+- Explicit return types for public functions
84+- Prefer `null` over `undefined` for absent values
15285
153-### Side Effects and State
154-- Keep side effects in `src/index.ts`; helper modules should be pure
155-- Avoid hidden global state; prefer explicit parameters
156-- Use small, focused functions for validation and formatting
157-
158-### Prompts and LLM Outputs
159-- LLM calls must expect malformed output; parse defensively
160-- Enforce JSON-only responses and validate fields before use
161-- Keep prompt updates in `src/prompt.ts`
162-
163-### TUI
164-- TUI is now in `src/output/tui-output.ts` and `src/tui/` directory
165-- Use `blessed` widgets; keep rendering in output modules
166-- Avoid Unicode-heavy UI unless needed (uses `fullUnicode: false`)
167-
168-### SQLite / Memory
169-- Centralize DB operations in `src/memory.ts`
170-- Serialize JSON using helper functions; guard against stringify errors
171-- Keep text fields reasonably bounded
172-
173-### Game Client
174-- Use the reference client from `client/` submodule
175-- Do not modify `client/` unless the change is intended for upstream
176-
177-## Editing Safety
178-
179-- Do not edit or commit `memory-*.sqlite` files
180-- Do not commit secrets or credentials
181-- Keep changes minimal and aligned with current architecture
182-- All DB files and logs are git-ignored
86+### Testing
87+- Use Bun's built-in test runner (`bun test`)
88+- Target: 80% coverage for client code
89+- Unit tests for core logic
90+- Manual tests for TUI (screenshots)
18391
184-## Conventions in This Repo
92+## Database
18593
186-- Use small, focused helpers for formatting and validation
187-- Prefer explicit `if` branches over implicit coercion
188-- Use early returns for invalid states
189-- Maintain descriptive log messages for output
94+SQLite via `bun:sqlite`:
95+- Pattern: `memory-{instance-id}.sqlite`
96+- Two tables: `account_details`, `messages`
97+- Maximum 5000 messages, sorted by tick
98+- Unique instance ID per client (4 characters)
19099
191-## When Adding New Features
100+## Error Handling
192101
193-- Update prompts and validation together
194-- Add to memory tracking only if it improves LLM context
195-- Keep tick timing aligned with server tick (10s; local uses 11s)
196-- Update both `src/output/tui-output.ts` and `src/output/file-logger-output.ts` for UI changes
102+- Neutral, factual language only
103+- Follow error terminology from api.md
104+- No behavioral bias in error messages
105+- Client errors logged but don't stop tick loop
197106
198-## If You Add Tests Later
107+## Development Workflow
199108
200-- Document the test framework and single-test command here
201-- Prefer a runner that supports file and name filtering
109+1. Read `client-refaction-design.md` for context
110+2. Make changes aligned with design principles
111+3. Run `bun run check` before committing
112+4. Keep abstractions minimal
113+5. Test with real game server when possible
202114
203-## Quick Review Checklist
115+## What NOT to Do
204116
205-```bash
206-bun run biome:lint
207-bun run biome:format
208-bun run ollama-play --name test-bot --non-interactive --max-ticks 10
209-```
117+- Do not add intermediate translation layers
118+- Do not add behavioral bias outside `prompt` field
119+- Do not modify sacred `client-refaction-design.md`
120+- Do not commit `*.sqlite` or `*.log` files
121+- Do not create backward compatibility with old implementation