dirtydishes/islandflow
1
0
Fork 0
Code Issues 2 Pull requests 4 Projects Releases Packages Wiki Activity Actions 1

update AGENTS.md with updated beads usage guidelines

Browse source
This commit is contained in:
Kellan Drucquer 2026-04-03 21:35:14 -04:00
parent 6e39320579
commit d301c7b4f3
2 changed files with 564 additions and 134 deletions
Download patch file Download diff file Expand all files Collapse all files

270
AGENTS.md
View file

@ -1,186 +1,188 @@
# AGENTS.md — Execution Guardrails for Codex # Agent Instructions
This file defines **how Codex should think, act, and prioritize** when working in this repository. See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.
Its purpose is to keep development **focused, correct, and non-drifting**.
If there is any conflict between speed and correctness, **correctness wins**. This file exists for compatibility with tools that look for AGENTS.md.
--- ## Key Sections
## Mission - **Issue Tracking** - How to use bd for work management
- **Development Guidelines** - Code standards and testing
- **Visual Design System** - Status icons, colors, and semantic styling for CLI output
Build a **real-time, non-delayed options flow and off-exchange trade analysis platform** for personal use that is: ## Visual Design Anti-Patterns
- explainable **NEVER use emoji-style icons** (🔴🟠🟡🔵⚪) in CLI output. They cause cognitive overload.
- deterministic
- replayable
- microstructure-correct
- low-latency
- built on **Bun**
Codex is an **engineering executor**, not a product visionary. **ALWAYS use small Unicode symbols** with semantic colors:
Do not invent scope. Do not “improve” the plan. Implement it faithfully. - Status: `○ ◐ ● ✓ ❄`
- Priority: `● P0` (filled circle with color)
--- See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines.
## Non-Negotiable Constraints ## Agent Warning: Interactive Commands
- **Bun is mandatory** **DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
- Use Bun for runtime, package manager, scripts, and dev tooling.
- Do not introduce npm, yarn, pnpm, or Node-only assumptions.
- **TypeScript only**
- No JS-only files unless unavoidable (and document why).
- **No black-box logic**
- All classifiers must be rule-based and explainable.
- **Personal-use architecture**
- No multi-user assumptions.
- No redistribution mechanisms.
- **Deterministic pipelines**
- Live behavior must match replay behavior.
If a change violates any of the above, **do not implement it**. Use `bd update` with flags instead:
```bash
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
--- # Use stdin for descriptions with special characters (backticks, !, nested quotes)
echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=-
echo 'Updated text' | bd update <id> --description=-
```
## Source of Truth ## Testing Commands (No Ambiguity)
The authoritative documents are, in order: - Default local test command: `make test` (or `./scripts/test.sh`).
- Full CGO-enabled suite: `make test-full-cgo` (or `./scripts/test-cgo.sh ./...`).
- On macOS, do **not** run raw `CGO_ENABLED=1 go test ./...` unless ICU flags are set; use the script/Make target above.
- If you need package- or test-scoped CGO runs:
```bash
./scripts/test-cgo.sh ./cmd/bd/...
./scripts/test-cgo.sh -run '^TestName$' ./cmd/bd/...
```
1. `PLAN.md` ## Non-Interactive Shell Commands
2. `AGENTS.md`
3. Code already merged into `main`
If a request contradicts `PLAN.md`, Codex must **stop and ask for clarification**. **ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
--- Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
## Development Rules **Use these forms instead:**
```bash
# Force overwrite without prompting
cp -f source dest # NOT: cp source dest
mv -f source dest # NOT: mv source dest
rm -f file # NOT: rm file
### 1. Never Skip the Event Layer # For recursive operations
- All incoming market data becomes **immutable events**. rm -rf directory # NOT: rm -r directory
- Never compute directly off live feeds without persisting the event. cp -rf source dest # NOT: cp -r source dest
- Never add UI-only logic that bypasses persisted data. ```
### 2. Separate Fact from Inference **Other commands that may prompt:**
- Raw data (`OptionPrint`, `EquityPrint`) is **fact**. - `scp` - use `-o BatchMode=yes` for non-interactive
- Classifiers and dark pool signals are **inference**. - `ssh` - use `-o BatchMode=yes` to fail instead of prompting
- Store and label them separately. - `apt-get` - use `-y` flag
- Never overwrite facts with inferred labels. - `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
### 3. Explainability Is Required ## Landing the Plane (Session Completion)
Every classifier must:
- have a unique ID
- expose its inputs
- produce a human-readable explanation string
- link back to evidence prints
If an alert cannot explain itself, it is invalid. **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
### 4. Favor Simple, Explicit Logic **MANDATORY WORKFLOW:**
- Prefer clear thresholds over clever heuristics.
- Avoid premature ML or probabilistic tuning.
- If logic becomes complex, break it into named steps.
This is a research system, not a trading bot. 1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
```bash
git pull --rebase
git push
git status # MUST show "up to date with origin"
```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session
--- **CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
## Classifier Implementation Rules <!-- BEGIN BEADS INTEGRATION -->
## Issue Tracking with bd (beads)
- Classifiers operate on **FlowPackets**, not raw prints. **IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
- Each classifier:
- returns `{ confidence, direction, explanations[] }`
- contributes to alert scoring but does not decide alerts alone
- Never infer intent with certainty.
- Use language like:
- “likely”
- “suggests”
- “consistent with”
- Never use language like:
- “smart money”
- “institutional intent”
- “guaranteed”
--- ### Why bd?
## Time & Market Structure Rules - Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
- Always join prints to NBBO using bounded time windows. ### Quick Start
- Track and expose join quality (`nbbo_age_ms`, etc.).
- Explicitly handle:
- 0DTE
- low-liquidity contracts
- wide spreads
- If confidence is low, say so.
--- **Check for ready work:**
## Charting Rules ```bash
bd ready --json
```
- Candles are built **server-side only**. **Create new issues:**
- Client never computes OHLC.
- Overlays must be viewport-aware and decimated.
- Performance beats decoration.
If a chart stutters, reduce data density first—not visual quality. ```bash
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
--- # Use stdin for descriptions with special characters (backticks, !, nested quotes)
echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=- --json
```
## UI Rules **Claim and update:**
- Prefer clarity over density. ```bash
- Every alert must be clickable to evidence. bd update <id> --claim --json
- No “magic colors” without legend or explanation. bd update bd-42 --priority 1 --json
- Motion must feel physical, not flashy. ```
UI exists to **inspect**, not to impress. **Complete work:**
--- ```bash
bd close bd-42 --reason "Completed" --json
```
## Observability & Safety ### Issue Types
- Add metrics alongside new pipelines. - `bug` - Something broken
- Log failures explicitly. - `feature` - New functionality
- Never silently drop events. - `task` - Work item (tests, docs, refactoring)
- During overload: - `epic` - Large feature with subtasks
- persistence > compute > UI (in that priority order) - `chore` - Maintenance (dependencies, tooling)
--- ### Priorities
## What Codex Must NOT Do - `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (default, nice-to-have)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
- Do not invent new features or markets. ### Workflow for AI Agents
- Do not introduce predictive claims.
- Do not optimize prematurely.
- Do not refactor without reason.
- Do not replace explicit logic with ML.
- Do not broaden scope beyond personal use.
--- 1. **Check ready work**: `bd ready` shows unblocked issues
2. **Claim your task atomically**: `bd update <id> --claim`
3. **Work on it**: Implement, test, document
4. **Discover new work?** Create linked issue:
- `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
5. **Complete**: `bd close <id> --reason "Done"`
## When to Stop and Ask ### Auto-Sync
Codex must pause and ask for guidance if: bd automatically syncs via Dolt:
- a data provider limitation blocks implementation
- licensing or entitlement assumptions change
- a requested change conflicts with `PLAN.md`
- a design decision affects determinism or replayability
--- - Each write auto-commits to Dolt history
- Use `bd dolt push`/`bd dolt pull` for remote sync
- No manual export/import needed!
## Definition of “Done” ### Important Rules
A task is done only when: - ✅ Use bd for ALL task tracking
- it matches `PLAN.md` - ✅ Always use `--json` flag for programmatic use
- it compiles and runs under Bun - ✅ Link discovered work with `discovered-from` dependencies
- it is deterministic - ✅ Check `bd ready` before asking "what should I work on?"
- it is explainable - ❌ Do NOT create markdown TODO lists
- it is testable or replayable - ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
--- For more details, see README.md and docs/QUICKSTART.md.
## Final Reminder <!-- END BEADS INTEGRATION -->
This system is built to **understand markets**, not to mythologize them.
If something cannot be justified by observable data and clear logic, it does not belong here.

428
AGENT_INSTRUCTIONS(1).md Normal file
View file

@ -0,0 +1,428 @@
# Detailed Agent Instructions for Beads Development
**For project overview and quick start, see [AGENTS.md](AGENTS.md)**
This document contains detailed operational instructions for AI agents working on beads development, testing, and releases.
## Development Guidelines
### Code Standards
- **Go version**: 1.24+
- **Linting**: `golangci-lint run ./...` (baseline warnings documented in [docs/LINTING.md](docs/LINTING.md))
- **Testing**: All new features need tests (`make test` for local baseline, `make test-full-cgo` when validating full CGO paths)
- **Documentation**: Update relevant .md files
### File Organization
```
beads/
├── cmd/bd/ # CLI commands
├── internal/
│ ├── types/ # Core data types
│ └── storage/ # Storage layer
│ └── dolt/ # Dolt implementation
├── examples/ # Integration examples
└── *.md # Documentation
```
### Testing Workflow
**IMPORTANT:** Never pollute the production database with test issues!
**For manual testing**, use the `BEADS_DB` environment variable to point to a temporary database:
```bash
# Create test issues in isolated database
BEADS_DB=/tmp/test.db bd init --quiet --prefix test
BEADS_DB=/tmp/test.db bd create "Test issue" -p 1
# Or for quick testing
BEADS_DB=/tmp/test.db bd create "Test feature" -p 1
```
**For automated tests**, use `t.TempDir()` in Go tests:
```go
func TestMyFeature(t *testing.T) {
tmpDir := t.TempDir()
testDB := filepath.Join(tmpDir, ".beads", "beads.db")
s := newTestStore(t, testDB)
// ... test code
}
```
**Git test isolation:** For tests that create temporary git repos, force repo-local hooks:
```bash
git config core.hooksPath .git/hooks
```
Do not rely on the developer's global git config. Global `core.hooksPath` can leak
into temp repos and produce flaky test behavior.
**Warning:** bd will warn you when creating issues with "Test" prefix in the production database. Always use `BEADS_DB` for manual testing.
### Before Committing
1. **Run tests**: `make test` (or `./scripts/test.sh`)
- For full CGO validation: `make test-full-cgo`
2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings)
3. **Update docs**: If you changed behavior, update README.md or other docs
4. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed
### Commit Message Convention
When committing work for an issue, include the issue ID in parentheses at the end:
```bash
git commit -m "Fix auth validation bug (bd-abc)"
git commit -m "Add retry logic for database locks (bd-xyz)"
```
This enables `bd doctor` to detect **orphaned issues** - work that was committed but the issue wasn't closed. The doctor check cross-references open issues against git history to find these orphans.
### Git Workflow
bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command).
**Install git hooks** for automatic sync:
```bash
bd hooks install
```
### Git Integration
**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No JSONL export/import needed.
**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md).
**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution.
## Git Workflow: Push to Main, Never PR
Crew workers push directly to main. **Never create pull requests.**
- `git push` to main is the only way to land work
- `gh pr create` is forbidden — PRs are for external contributors, not crew
- Do not create feature branches for your own work — commit and push to main
- When handling external PRs, use fix-merge: checkout the PR branch locally,
fix/rebase onto main, merge locally, `git push`, then close the PR
This is enforced by pre-use hooks. If you try `gh pr create`, it will be blocked.
## Landing the Plane
**When the user says "let's land the plane"**, you MUST complete ALL steps below. The plane is NOT landed until `git push` succeeds. NEVER stop before pushing. NEVER say "ready to push when you are!" - that is a FAILURE.
**MANDATORY WORKFLOW - COMPLETE ALL STEPS:**
1. **File beads issues for any remaining work** that needs follow-up
2. **Ensure all quality gates pass** (only if code changes were made):
- Run `make lint` or `golangci-lint run ./...` (if pre-commit installed: `pre-commit run --all-files`)
- Run `make test` (and `make test-full-cgo` when CGO-relevant code changed)
- File P0 issues if quality gates are broken
3. **Update beads issues** - close finished work, update status
4. **PUSH TO REMOTE - NON-NEGOTIABLE** - This step is MANDATORY. Execute ALL commands below:
```bash
# Pull first to catch any remote changes
git pull --rebase
# MANDATORY: Push everything to remote
# DO NOT STOP BEFORE THIS COMMAND COMPLETES
git push
# MANDATORY: Verify push succeeded
git status # MUST show "up to date with origin/main"
```
**CRITICAL RULES:**
- The plane has NOT landed until `git push` completes successfully
- NEVER stop before `git push` - that leaves work stranded locally
- NEVER say "ready to push when you are!" - YOU must push, not the user
- If `git push` fails, resolve the issue and retry until it succeeds
- The user is managing multiple agents - unpushed work breaks their coordination workflow
5. **Clean up git state** - Clear old stashes and prune dead remote branches:
```bash
git stash clear # Remove old stashes
git remote prune origin # Clean up deleted remote branches
```
6. **Verify clean state** - Ensure all changes are committed AND PUSHED, no untracked files remain
7. **Choose a follow-up issue for next session**
- Provide a prompt for the user to give to you in the next session
- Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]"
**REMEMBER: Landing the plane means EVERYTHING is pushed to remote. No exceptions. No "ready when you are". PUSH IT.**
**Example "land the plane" session:**
```bash
# 1. File remaining work
bd create "Add integration tests for sync" -t task -p 2 --json
# 2. Run quality gates (only if code changes were made)
go test -short ./...
golangci-lint run ./...
# 3. Close finished issues
bd close bd-42 bd-43 --reason "Completed" --json
# 4. PUSH TO REMOTE - MANDATORY, NO STOPPING BEFORE THIS IS DONE
git pull --rebase
git push # MANDATORY - THE PLANE IS STILL IN THE AIR UNTIL THIS SUCCEEDS
git status # MUST verify "up to date with origin/main"
# 5. Clean up git state
git stash clear
git remote prune origin
# 6. Verify everything is clean and pushed
git status
# 7. Choose next work
bd ready --json
bd show bd-44 --json
```
**Then provide the user with:**
- Summary of what was completed this session
- What issues were filed for follow-up
- Status of quality gates (all passing / issues filed)
- Confirmation that ALL changes have been pushed to remote
- Recommended prompt for next session
**CRITICAL: Never end a "land the plane" session without successfully pushing. The user is coordinating multiple agents and unpushed work causes severe rebase conflicts.**
## Agent Session Workflow
**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead:
```bash
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
```
**Use stdin for descriptions with special characters** (backticks, `!`, nested quotes):
```bash
# Pipe via stdin to avoid shell escaping issues
echo 'Description with `backticks` and "quotes"' | bd create "Title" --stdin
echo 'Updated description with $variables' | bd update <id> --description=-
# Or use --body-file for longer content
bd create "Title" --body-file=description.md
```
**Example agent session:**
```bash
# Make changes (each write auto-commits to Dolt)
bd create "Fix bug" -p 1
bd create "Add tests" -p 1
bd update bd-42 --claim
bd close bd-40 --reason "Completed"
# Push Dolt data to remote if configured
bd dolt push
# Now safe to end session
```
This installs:
- **pre-commit** — Commits pending Dolt changes
- **post-merge** — Pulls remote Dolt changes after git merge
**Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users).
## Common Development Tasks
### CLI Design Principles
**Minimize cognitive overload.** Every new command, flag, or option adds cognitive burden for users. Before adding anything:
1. **Recovery/fix operations → `bd doctor --fix`**: Don't create separate commands like `bd recover` or `bd repair`. Doctor already detects problems - let `--fix` handle remediation. This keeps all health-related operations in one discoverable place.
For git hook marker migration specifically: use `bd migrate hooks --dry-run` to preview operations, and `bd doctor --fix` for the standard apply path.
2. **Prefer flags on existing commands**: Before creating a new command, ask: "Can this be a flag on an existing command?" Example: `bd list --stale` instead of `bd stale`.
3. **Consolidate related operations**: Related operations should live together. Version control uses `bd vc {log,diff,commit}`, not separate top-level commands.
4. **Count the commands**: Run `bd --help` and count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping.
5. **New commands need strong justification**: A new command should represent a fundamentally different operation, not just a convenience wrapper.
### Adding a New Command
1. Create file in `cmd/bd/`
2. Add to root command in `cmd/bd/main.go`
3. Implement with Cobra framework
4. Add `--json` flag for agent use
5. Add tests in `cmd/bd/*_test.go`
6. Document in README.md
### Adding Storage Features
1. Add Dolt SQL schema changes in `internal/storage/dolt/`
2. Add migration if needed
3. Update `internal/types/types.go` if new types
4. Implement in `internal/storage/dolt/` (queries, issues, etc.)
5. Add tests
6. Update export/import in `cmd/bd/export.go` and `cmd/bd/import.go`
### Adding Examples
1. Create directory in `examples/`
2. Add README.md explaining the example
3. Include working code
4. Link from `examples/README.md`
5. Mention in main README.md
## Building and Testing
```bash
# Build and install bd to ~/.local/bin (the canonical location)
make install
# Test (local baseline)
make test
# Test with full CGO-enabled suite (local/CI parity)
make test-full-cgo
# Coverage run
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Verify installed binary
bd init --prefix test
bd create "Test issue" -p 1
bd ready
```
> **WARNING**: Do NOT use `go build -o bd ./cmd/bd` or `go install ./cmd/bd`.
> These create stale binaries in the working directory or `~/go/bin/` that
> shadow the canonical install at `~/.local/bin/bd`. Always use `make install`.
## Version Management
**IMPORTANT**: When the user asks to "bump the version" or mentions a new version number (e.g., "bump to 0.9.3"), use the version bump script:
```bash
# Preview changes (shows diff, doesn't commit)
./scripts/bump-version.sh 0.9.3
# Auto-commit the version bump
./scripts/bump-version.sh 0.9.3 --commit
git push origin main
```
**What it does:**
- Updates ALL version files (CLI, plugin, MCP server, docs) in one command
- Validates semantic versioning format
- Shows diff preview
- Verifies all versions match after update
- Creates standardized commit message
**User will typically say:**
- "Bump to 0.9.3"
- "Update version to 1.0.0"
- "Rev the project to 0.9.4"
- "Increment the version"
**You should:**
1. Run `./scripts/bump-version.sh <version> --commit`
2. Push to GitHub
3. Confirm all versions updated correctly
**Files updated automatically:**
- `cmd/bd/version.go` - CLI version
- `claude-plugin/.claude-plugin/plugin.json` - Plugin version
- `.claude-plugin/marketplace.json` - Marketplace version
- `integrations/beads-mcp/pyproject.toml` - MCP server version
- `README.md` - Documentation version
- `PLUGIN.md` - Version requirements
**Why this matters:** We had version mismatches (bd-66) when only `version.go` was updated. This script prevents that by updating all components atomically.
See `scripts/README.md` for more details.
## Release Process (Maintainers)
**Automated (Recommended):**
```bash
# One command to do everything (version bump, tests, tag, Homebrew update, local install)
./scripts/release.sh 0.9.3
```
This handles the entire release workflow automatically, including waiting ~5 minutes for GitHub Actions to build release artifacts. See [scripts/README.md](scripts/README.md) for details.
**Manual (Step-by-Step):**
1. Bump version: `./scripts/bump-version.sh <version> --commit`
2. Update CHANGELOG.md with release notes
3. Run tests: `make test` (and `make test-full-cgo` for CGO-related changes)
4. Push version bump: `git push origin main`
5. Tag release: `git tag v<version> && git push origin v<version>`
6. Update Homebrew: `./scripts/update-homebrew.sh <version>` (waits for GitHub Actions)
7. Verify: `brew update && brew upgrade beads && bd version`
See [docs/RELEASING.md](docs/RELEASING.md) for complete manual instructions.
## Checking GitHub Issues and PRs
**IMPORTANT**: When asked to check GitHub issues or PRs, use command-line tools like `gh` instead of browser/playwright tools.
**Preferred approach:**
```bash
# List open issues with details
gh issue list --limit 30
# List open PRs
gh pr list --limit 30
# View specific issue
gh issue view 201
```
**Then provide an in-conversation summary** highlighting:
- Urgent/critical issues (regressions, bugs, broken builds)
- Common themes or patterns
- Feature requests with high engagement
- Items that need immediate attention
**Why this matters:**
- Browser tools consume more tokens and are slower
- CLI summaries are easier to scan and discuss
- Keeps the conversation focused and efficient
- Better for quick triage and prioritization
**Do NOT use:** `browser_navigate`, `browser_snapshot`, or other playwright tools for GitHub PR/issue reviews unless specifically requested by the user.
## Questions?
- Check existing issues: `bd list`
- Look at recent commits: `git log --oneline -20`
- Read the docs: README.md, ADVANCED.md, EXTENDING.md
- Create an issue if unsure: `bd create "Question: ..." -t task -p 2`
## Important Files
- **README.md** - Main documentation (keep this updated!)
- **EXTENDING.md** - Database extension guide
- **ADVANCED.md** - Advanced features (rename, merge, compaction)
- **CONTRIBUTING.md** - Contribution guidelines
- **SECURITY.md** - Security policy