bd-routing

# bd-routing - Two-Level Beads Routing

Understanding where beads live and how to route commands to the right database.

> **Core Question**: Which database does my bead belong to?

## Overview

**What this skill covers:** The two-level beads architecture in Gas Town and how to route commands correctly.

| User Says | Claude Does |
|-----------|-------------|
| "which database?" | Explain Town vs Rig beads |
| "beads routing" | Show prefix routing table |
| "can't sling hq bead" | Explain BEADS_DIR workaround |
| "two-level beads" | Describe Town/Rig architecture |
| "where do beads live" | Show location hierarchy |

---

## Quick Reference

```bash
# Check what database you're in
pwd                          # Location determines default database
BD_DEBUG_ROUTING=1 bd show <id>  # Debug routing decision

# Target a specific database
BEADS_DIR=~/gt/daedalus/mayor/rig/.beads bd create --title="..."
```

---

## The Two Levels

| Level | Location | Prefix | Purpose | Can Sling? |
|-------|----------|--------|---------|------------|
| **Town** | `~/gt/.beads/` | `hq-*` | Mail, coordination | No |
| **Rig** | `<rig>/crew/*/.beads/` | `gt-*`, `ap-*`, `da-*`, etc. | Project work | Yes |

**The key distinction:**
- Town beads are for Mayor coordination and mail
- Rig beads are for actual project work that polecats execute

---

## Prefix Routing

`bd` routes commands based on bead ID prefix:

```bash
bd show hq-abc    # Routes to ~/gt/.beads/
bd show gt-xyz    # Routes to daedalus beads
bd show ap-123    # Routes to athena beads
```

**Route registration:** `~/gt/.beads/routes.jsonl`

---

## Creating Slingable Beads

**Problem:** HQ beads (`hq-*`) can't be hooked by polecats.

**Solution:** Use `BEADS_DIR` to create beads in the target rig:

```bash
# From Mayor context, create a daedalus bead
BEADS_DIR=~/gt/daedalus/mayor/rig/.beads bd create --title="Fix bug" --type=bug
# Creates: gt-xxxxx (slingable!)

# Then sling it
gt sling gt-xxxxx daedalus
```

---

## Common Patt