chore: initialize beads issue tracking

Author: hadrien

.beads/.gitignore

@@ -0,0 +1,54 @@
+# Dolt database (managed by Dolt, not git)
+dolt/
+dolt-access.lock
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+.jsonl.lock
+sync_base.jsonl
+export-state/
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+daemon.lock
+daemon.log
+daemon-*.log.gz
+daemon.pid
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,42 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of the Dolt database
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/hooks/post-checkout

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.55.4
+#
+# bd (beads) post-checkout hook - thin shim
+#
+# This shim delegates to 'bd hook post-checkout' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# The 'bd hook' command (singular) supports:
+# - Guard against frequent firing (only imports if JSONL changed)
+# - Per-worktree state tracking
+# - Dolt branch-then-merge pattern
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    # Silently skip - post-checkout is called frequently
+    exit 0
+fi
+
+exec bd hook post-checkout "$@"

.beads/hooks/post-merge

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.55.4
+#
+# bd (beads) post-merge hook - thin shim
+#
+# This shim delegates to 'bd hook post-merge' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# The 'bd hook' command (singular) supports:
+# - Branch-then-merge pattern for Dolt (cell-level conflict resolution)
+# - Per-worktree state tracking
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping post-merge hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hook post-merge "$@"

.beads/hooks/pre-commit

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+# bd-shim v2
+# bd-hooks-version: 0.55.4
+#
+# bd (beads) pre-commit hook — thin shim
+#
+# Delegates to 'bd hook pre-commit' which contains the actual hook logic.
+# This pattern ensures hook behavior is always in sync with the installed
+# bd version — no manual updates needed.
+#
+# The 'bd hook' command supports:
+# - Per-worktree export state tracking
+# - Dolt in-process export (no lock deadlocks)
+# - Sync-branch routing
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-commit hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hook pre-commit "$@"

.beads/hooks/pre-push

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.55.4
+#
+# bd (beads) pre-push hook - thin shim
+#
+# This shim delegates to 'bd hooks run pre-push' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-push hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-push "$@"

.beads/hooks/prepare-commit-msg

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.48.0
+#
+# bd (beads) prepare-commit-msg hook - thin shim
+#
+# This shim delegates to 'bd hooks run prepare-commit-msg' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# Arguments:
+#   $1 = path to the commit message file
+#   $2 = source of commit message (message, template, merge, squash, commit)
+#   $3 = commit SHA-1 (if -c, -C, or --amend)
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping prepare-commit-msg hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run prepare-commit-msg "$@"

.beads/interactions.jsonl

@@ -0,0 +1,6 @@
+{"id":"fastsqla-0nf","title":"Add Agent Skills to FastSQLA","description":"Add Agent Skills (agentskills.io) to FastSQLA so AI coding agents can discover and use FastSQLA more effectively. Skills are SKILL.md files in folders under skills/ that teach agents how to perform specific tasks with the library. Each skill follows the Agent Skills spec: YAML frontmatter (name, description) + markdown instructions with progressive disclosure.\n\n## Skills to create\n\n1. **fastsqla-setup** — Installation, env var configuration, lifespan setup, composing lifespans\n2. **fastsqla-session** — Session dependency, open_session(), flush vs commit, IntegrityError handling\n3. **fastsqla-pagination** — Paginate dependency, Page/Item/Collection models, new_pagination() customization\n4. **fastsqla-models** — Base (DeclarativeBase + DeferredReflection), SQLModel integration, reflection patterns\n5. **fastsqla-testing** — Fixture chains, ASGI testing with httpx + asgi-lifespan, teardown, SQLModel test marks\n\n## Directory structure\n\n```\nskills/\n├── fastsqla-setup/\n│   └── SKILL.md\n├── fastsqla-session/\n│   └── SKILL.md\n├── fastsqla-pagination/\n│   └── SKILL.md\n├── fastsqla-models/\n│   └── SKILL.md\n└── fastsqla-testing/\n    └── SKILL.md\n```\n\n## References\n\n- Spec: https://agentskills.io/specification\n- Examples: https://github.com/anthropics/skills\n- FastSQLA source: src/fastsqla.py (single 437-line module)","status":"in_progress","priority":2,"issue_type":"epic","owner":"hadrien@ectobal.com","created_at":"2026-02-26T17:32:20Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:40Z"}
+{"id":"fastsqla-0nf.1","title":"Create fastsqla-setup skill","description":"Create `skills/fastsqla-setup/SKILL.md` covering:\n\n- Installation (`pip install FastSQLA`, optional `[sqlmodel]` extra)\n- Required async driver packages (asyncpg, aiosqlite, aiomysql) and URL schemes\n- **Environment variable configuration** (`fastsqla.lifespan`): `SQLALCHEMY_URL` required, all `SQLALCHEMY_*` env vars passed to `async_engine_from_config`, case-insensitive\n- **Programmatic configuration** (`new_lifespan()`): same args as `create_async_engine`\n- **Composing multiple lifespans** with `AsyncExitStack` pattern\n- What the lifespan does on startup (engine creation, `Base.prepare()`, `SessionFactory.configure()`) and shutdown\n- Warning about stray `SQLALCHEMY_*` env vars\n- Startup error message when URL is missing\n\n## Acceptance criteria\n\n- SKILL.md has valid frontmatter (name matches directory, description \u003c 1024 chars)\n- Content \u003c 500 lines\n- Covers both env var and programmatic setup paths\n- Includes lifespan composition example","status":"in_progress","priority":2,"issue_type":"task","owner":"hadrien@ectobal.com","estimated_minutes":30,"created_at":"2026-02-26T17:32:31Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:43Z","dependencies":[{"issue_id":"fastsqla-0nf.1","depends_on_id":"fastsqla-0nf","type":"parent-child","created_at":"2026-02-26T12:32:30Z","created_by":"Hadrien David","metadata":"{}"}]}
+{"id":"fastsqla-0nf.2","title":"Create fastsqla-session skill","description":"Create `skills/fastsqla-session/SKILL.md` covering:\n\nThis is the **highest-value skill** — session management is the most error-prone area for users.\n\n- **Session dependency** (`Session`): type annotation for endpoint injection, auto-commit on success, rollback on exception, close always\n- **flush() vs commit()**: never call `session.commit()` in endpoints, use `session.flush()` to get server-generated data (auto-increment IDs). Include correct and incorrect examples.\n- **IntegrityError handling**: catch after `flush()`, re-raise as `HTTPException` to trigger automatic rollback. Explain why silent catch leaves session in broken state.\n- **open_session()**: async context manager for background tasks, scripts, startup routines. Same commit/rollback/close semantics. Document the edge case: if context body succeeds but `commit()` fails, it rolls back and re-raises.\n- Summary of rules\n\n## Source reference\n\nSession lifecycle: `src/fastsqla.py:205-258` (`open_session`)\nSession dependency: `src/fastsqla.py:260-320` (`new_session`, `Session`)\n\n## Acceptance criteria\n\n- SKILL.md has valid frontmatter\n- Content \u003c 500 lines\n- Includes both correct and incorrect code examples for flush vs commit\n- Covers IntegrityError pattern from test_session_dependency.py","status":"in_progress","priority":1,"issue_type":"task","owner":"hadrien@ectobal.com","estimated_minutes":30,"created_at":"2026-02-26T17:32:42Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:44Z","dependencies":[{"issue_id":"fastsqla-0nf.2","depends_on_id":"fastsqla-0nf","type":"parent-child","created_at":"2026-02-26T12:32:42Z","created_by":"Hadrien David","metadata":"{}"}]}
+{"id":"fastsqla-0nf.3","title":"Create fastsqla-pagination skill","description":"Create `skills/fastsqla-pagination/SKILL.md` covering:\n\n- **Response models**: `Page[T]` (data + meta with offset/total_items/total_pages/page_number), `Item[T]` (single item), `Collection[T]` (unpaginated list)\n- **Default Paginate dependency**: adds `offset` (default 0, min 0) and `limit` (default 10, min 1, max 100) query params. Show basic usage with `select(Model)`.\n- **Adding filters**: combine Paginate with additional query parameters\n- **new_pagination() factory**: 4 parameters (`min_page_size`, `max_page_size`, `query_count_dependency`, `result_processor`)\n- **Custom page sizes**: example with `Annotated[PaginateType, Depends(new_pagination(...))]`\n- **Custom count query**: `query_count_dependency` is a FastAPI dependency returning `int`. Default is `SELECT COUNT(*) FROM (subquery)`. Provide example for joins.\n- **Custom result processor**: default is `lambda r: iter(r.unique().scalars())`. Show `lambda result: iter(result.mappings())` for multi-column select.\n- **PaginateType[T]** type alias: `Callable[[Select], Awaitable[Page[T]]]`\n- **SQLModel example**: models serve as both ORM and response models\n\n## Source reference\n\nPagination: `src/fastsqla.py:323-437`\nTest examples: `tests/integration/test_pagination.py`\n\n## Acceptance criteria\n\n- SKILL.md has valid frontmatter\n- Content \u003c 500 lines\n- Includes both default and custom pagination examples\n- Shows the Annotated + Depends pattern for custom pagination","status":"in_progress","priority":2,"issue_type":"task","owner":"hadrien@ectobal.com","estimated_minutes":30,"created_at":"2026-02-26T17:32:56Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:44Z","dependencies":[{"issue_id":"fastsqla-0nf.3","depends_on_id":"fastsqla-0nf","type":"parent-child","created_at":"2026-02-26T12:32:55Z","created_by":"Hadrien David","metadata":"{}"}]}
+{"id":"fastsqla-0nf.4","title":"Create fastsqla-models skill","description":"Create `skills/fastsqla-models/SKILL.md` covering:\n\n- **fastsqla.Base**: inherits from `DeclarativeBase` + `DeferredReflection` (`__abstract__ = True`)\n- **Fully declared models**: standard SQLAlchemy ORM with `Mapped` and `mapped_column`\n- **Reflected models**: declare only `__tablename__`, columns auto-reflected from DB during `Base.prepare()` at lifespan startup\n- **How DeferredReflection works**: attributes not available until `Base.prepare()` is called inside a connection during lifespan\n- **Pydantic response models**: separate `BaseModel` with `ConfigDict(from_attributes=True)` when using Base\n- **SQLModel alternative**: `pip install FastSQLA[sqlmodel]`, no need for Base, models are both ORM and Pydantic\n- **SQLModel session swap**: when sqlmodel is installed, FastSQLA silently uses SQLModel's AsyncSession\n- **extend_existing**: `__table_args__ = {'extend_existing': True}` for SQLModel when table already exists\n- **Comparison table**: Base vs SQLModel tradeoffs (reflection, validation, dependencies, relationships)\n\n## Source reference\n\nBase: `src/fastsqla.py:57-85`\nSQLModel import: `src/fastsqla.py:23-27`\n\n## Acceptance criteria\n\n- SKILL.md has valid frontmatter\n- Content \u003c 500 lines\n- Shows both fully declared and reflected model patterns\n- Includes Base vs SQLModel comparison","status":"in_progress","priority":2,"issue_type":"task","owner":"hadrien@ectobal.com","estimated_minutes":25,"created_at":"2026-02-26T17:33:06Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:45Z","dependencies":[{"issue_id":"fastsqla-0nf.4","depends_on_id":"fastsqla-0nf","type":"parent-child","created_at":"2026-02-26T12:33:06Z","created_by":"Hadrien David","metadata":"{}"}]}
+{"id":"fastsqla-0nf.5","title":"Create fastsqla-testing skill","description":"Create `skills/fastsqla-testing/SKILL.md` covering:\n\n- **Test dependencies**: pytest, pytest-asyncio, pytest-cov, httpx, asgi-lifespan, aiosqlite, faker\n- **pytest config**: `asyncio_mode = 'auto'`, `asyncio_default_fixture_loop_scope = 'function'`\n- **Fixture chain** (critical ordering): `sqlalchemy_url` → `environ` (patched with clear=True) → `engine` → `setup_tear_down` (CREATE TABLE via raw SQL) → `app` (define models + routes) → `client` (LifespanManager + httpx)\n- **ASGI client pattern**: `LifespanManager(app)` triggers startup/shutdown, `ASGITransport` + `AsyncClient` for HTTP\n- **Critical teardown** (autouse fixture): `Base.metadata.clear()` + `clear_mappers()` after every test to prevent model leakage\n- **Direct data verification**: separate `session` fixture bound to same engine for querying DB outside the app\n- **SQLModel test marks**: `@mark.require_sqlmodel` with autouse `check_sqlmodel` fixture that skips when not installed\n- **Table setup**: raw SQL in fixtures, not ORM (tables must exist before Base.prepare)\n\n## Source reference\n\nRoot conftest: `tests/conftest.py`\nIntegration conftest: `tests/integration/conftest.py`\nSession tests: `tests/integration/test_session_dependency.py`\nPagination tests: `tests/integration/test_pagination.py`\nSQLModel tests: `tests/integration/test_sqlmodel.py`\n\n## Acceptance criteria\n\n- SKILL.md has valid frontmatter\n- Content \u003c 500 lines\n- Documents the full fixture chain with dependency ordering\n- Includes teardown fixture (this is the most common testing pitfall)","status":"in_progress","priority":2,"issue_type":"task","owner":"hadrien@ectobal.com","estimated_minutes":30,"created_at":"2026-02-26T17:33:19Z","created_by":"Hadrien David","updated_at":"2026-02-26T17:35:45Z","dependencies":[{"issue_id":"fastsqla-0nf.5","depends_on_id":"fastsqla-0nf","type":"parent-child","created_at":"2026-02-26T12:33:18Z","created_by":"Hadrien David","metadata":"{}"}]}