# The Settled Reach

A top-down immersive sim — occlusion-based detective game with combat elements, set in an original science fiction universe. Single-character perspective, asymmetric information as core mechanic, Rimworld-style storyteller. Godot 4 client + Rust/bevy_ecs simulation server via subprocess/IPC (D-020).

**Official Title:** The Settled Reach (D-021)
**Repository name:** commonwealth (historical code name, retained for path stability)

## Project Structure

```
DECISIONS.md          # Confirmed decisions (D-001+), open questions (Q-001+)
TEAM.md               # Team roster and roles
docs/
  discussions/        # Discussion rounds (all rounds archived here per D-022)
  briefings/          # Per-agent context briefings (maintained by Qatux)
  architecture/       # Technical architecture documents
  design/             # Game design documents
db/
  commonwealth.db     # SQLite ticketing database
  schema.sql          # Database schema
  connectors/         # Connector scripts for SQLite and Qdrant
    config.json       # Endpoint configuration
    sqlite_connector.py   # SQLite mini MCP
    qdrant_connector.py   # Qdrant + ollama mini MCP
.claude/
  agents/             # Agent personality files
  skills/             # Skill definitions
```

## Agent Instructions

### Before starting work
1. Read your briefing at `docs/briefings/{your-name}.md` for current project context
2. Read `DECISIONS.md` for confirmed decisions relevant to your work
3. Check `docs/discussions/` for recent discussion rounds if needed

### SQLite access
**Never use the `sqlite3` CLI** - it crashes in Claude Code due to a known std::bad_alloc bug.

Use the whitelistable wrapper scripts:
```bash
db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='in_progress'"
db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1"
```

### Qdrant / document search
```bash
db/connectors/qdrant-search "asymmetric information design"
db/connectors/qdrant-index docs/briefings/tyre.md
db/connectors/qdrant-health
db/connectors/qdrant-count
```

### File conventions
- Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected)
- Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete
- Briefings: one per agent, updated after decision-producing rounds
- Tickets: managed via `/ticket` skill or `sqlite_connector.py` directly

### Commit conventions
Use conventional commits with project-specific scopes:
`agents`, `skills`, `docs`, `briefings`, `discussions`, `schema`, `db`, `config`, `engine`, `simulation`, `client`, `ui`, `audio`, `assets`, `meta`

### Local services
- Qdrant: `http://tower-of-joy:6333/`
- Ollama: `http://tower-of-joy:11434/` (nomic-embed-text)
- Collection: `commonwealth` (768 dimensions, cosine distance)