---
name: bnna-platform-repo
description: Repo orientation checklist for bnna-platform. Use at session start or after context compaction to get current state from the code, not from stale docs.
user-invocable: true
---

# bnna-platform-repo Orientation

Checklist for getting oriented in this repo. Run these checks — don't trust
cached knowledge or documentation alone. Code is the source of truth.

## 0. Load Go skills

MUST: Load these skills every session and after every context compaction:

```
/create-skill
/go
/use-modern-go
/go-stack
/go-sqlc
/go-auth
```

These contain coding conventions, approved libraries, and patterns that
apply to all work in this repo.

## 1. Read project instructions

```
AGENTS.md          # domain model, critical rules, conventions, current goals
LOCAL.md           # deployment-specific: real hostnames, IPs, tokens, DSNs
```

MUST: Read both before doing any work. LOCAL.md is gitignored and
environment-specific — it has the actual connection strings and deploy targets.

If LOCAL.md is missing, load `skills/init-local-memory/` and gather the
information from the user before doing any deploy or migration work.

## 2. Check git state

```sh
git branch --show-current
git log --oneline -10
git status
```

Look for: current branch, recent direction of work, uncommitted changes or
WIP that might conflict with new work.

## 3. Run the binaries

Documentation drifts. The `--help` output is the truth about what's wired up.

```sh
go run ./cmd/bnpd help
go run ./cmd/bnna help
go run ./cmd/bnadm help
```

For deeper subcommand discovery:

```sh
go run ./cmd/bnadm accounts help
go run ./cmd/bnadm networks help
go run ./cmd/bnadm databases help
```

## 4. Check build health

```sh
go generate ./...
go vet ./...
```

If either fails, fix before starting new work. A red build means the last
session left something broken.

## 5. Check sqlc generation is in sync

```sh
# Compare query file timestamps vs generated code
ls -lt db/queries/*.sql | head -5
ls -lt internal/bnnadb/*.go | head -5
```

If queries are newer than generated code, run:

```sh
sqlc generate
```

## 6. Review database schema and migration state

```sh
ls db/migrations/
ls db/queries/
```

Know what the latest migration is. The query files in `db/queries/` are the
truth about which tables and columns exist — each file maps to a domain
(accounts, networks, instances, etc.). If you'll be touching schema, read
the relevant query file and the latest migration.

## 7. Scan for known issues and gaps

```sh
# Maintained docs about what's broken or missing
cat docs/known-gaps.md
```

Also check for any session files left by a previous agent:

```sh
cat agents/TASKS.md 2>/dev/null
cat agents/REVIEW.md 2>/dev/null
cat agents/HANDOFF.md 2>/dev/null
```

## 8. Survey skills and internal packages

Skills and packages grow between sessions. Check what's actually on disk:

```sh
ls skills/
ls internal/
```

Compare against the Skills Index and Internal Packages table in AGENTS.md
if something looks unfamiliar. The reference docs live in `docs/` — see
the Docs Index in AGENTS.md for the full list.