GEMINI.md

# Project Map (AGENTS.md)

This file is a navigation map for agents. Durable knowledge lives in `docs/`.

## Start Here

- Docs index: [docs/README.md](docs/README.md)
- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Operations: [docs/RUNBOOK.md](docs/RUNBOOK.md)
- Validate: `opencode-ctx docs validate`
- Test: `uv run pytest tests/ -v`

## System-of-Record Documents

| Category | Location | Type | Purpose |
|----------|----------|------|---------|
| Guides | [docs/guides/README.md](docs/guides/README.md) | how-to | Practical procedures |
| Design docs | [docs/design-docs/index.md](docs/design-docs/index.md) | explanation | Feature design, ADRs |
| Core beliefs | [docs/design-docs/core-beliefs.md](docs/design-docs/core-beliefs.md) | explanation | Agent-first principles |
| Learnings | [docs/learnings/README.md](docs/learnings/README.md) | reference | Durable patterns |
| Exec plans | [docs/exec-plans/README.md](docs/exec-plans/README.md) | how-to | Complex work tracking |
| Discovery | [docs/discovery/index.md](docs/discovery/index.md) | explanation | Validate + Taste |
| Delivery specs | [docs/delivery-specs/index.md](docs/delivery-specs/index.md) | reference | Engineering handoff |
| References | [docs/references/README.md](docs/references/README.md) | reference | External docs |
| Exploration | [docs/exploration/README.md](docs/exploration/README.md) | exploration | Ideas, scratchpad |
| Taxonomy | [docs/DOCS_TAXONOMY.md](docs/DOCS_TAXONOMY.md) | reference | Where to put new docs |
| Quality | [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md) | reference | Domain grades |

## Guardrails

- **Testing:** Use the package manager (`uv run pytest ...`), never bare `pytest`.
- **Skills:** Call `skill({ name: "<name>" })` first when asked to use a skill.
- **Config:** Project config in `opencode.jsonc` (repo root); `.opencode/` holds project agents/commands; global fallback in `~/.config/opencode/`.
- **Git safety:** No destructive commands (`reset --hard`, `push --force`) unless explicit.
- **Secrets:** Never commit `.env` or credentials.

## Quick Commands

| Task | Command |
|------|---------|
| Install | `uv sync` |
| Init project | `opencode-ctx docs init` (scaffolds docs, config, git hooks) |
| Docs validate | `opencode-ctx docs validate` |
| Arch snapshot | `opencode-ctx docs architecture apply` |
| Lint | `uv run ruff check --fix .` |
| Format | `uv run ruff format .` |
| Test | `uv run pytest tests/ -v` |
| Run | `uv run python -m <module>` |

## Development Workflow

- Run via package manager (`uv run ...`), never bare commands.
- List existing files before creating new ones (avoid naming drift).
- Prefer vertical slices over horizontal refactors.
- No premature abstraction until multiple use-cases require it.

<!-- GUIDELINES-BEGIN -->

<!-- Managed by: opencode-ctx guidelines apply --packs python,testing,delivery-safety -->
<!-- Run the command above to populate this section -->

<!-- GUIDELINES-END -->