docs: add CLAUDE.md, AGENTS.md, and development docs

.tasks/README.md

@@ -0,0 +1,71 @@
+# Task Tracking
+
+Work is tracked as markdown files organized by status.
+
+## Directory Structure
+
+```
+.tasks/
+├── backlog/          # Tasks not yet started
+├── in-progress/      # Tasks actively being worked on
+├── done/             # Completed tasks
+└── sessions/         # Session work logs (what was done per Claude Code session)
+```
+
+## Task File Format
+
+Filename: `YYYY-MM-DD-short-description.md`
+
+```markdown
+---
+title: Short description of the task
+status: backlog | in-progress | done
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+## Objective
+
+What needs to be done and why.
+
+## Notes
+
+Decisions, context, blockers, or references.
+
+## Outcome
+
+What was accomplished (filled in when done).
+```
+
+## Session Log Format
+
+Filename: `YYYY-MM-DD.md`
+
+```markdown
+---
+date: YYYY-MM-DD
+---
+
+## Summary
+
+Brief overview of what was accomplished.
+
+## Changes
+
+- List of files changed and why.
+
+## Decisions
+
+- Any architectural or design decisions made.
+
+## Next Steps
+
+- What to pick up next session.
+```
+
+## Workflow
+
+1. New work goes in `backlog/`
+2. Move file to `in-progress/` when starting
+3. Move file to `done/` when complete
+4. Log each Claude Code session in `sessions/`

.tasks/backlog/2026-02-16-replace-git-cli-with-go-git.md

@@ -0,0 +1,37 @@
+---
+title: Replace git CLI dependency with go-git
+status: backlog
+created: 2026-02-16
+updated: 2026-02-16
+---
+
+## Objective
+
+Remove the implicit runtime dependency on the git CLI by replacing it with
+[go-git](https://github.com/go-git/go-git). This would eliminate the
+requirement for git >= 2.20 to be installed and in `$PATH`, making Gilt fully
+self-contained.
+
+go-git supports bare clones and has enough worktree support for what Gilt needs
+(clone, checkout specific version, copy files out).
+
+## Blockers
+
+- **Blocked on go-git partial clone support:**
+  [go-git/go-git#1381](https://github.com/go-git/go-git/issues/1381).
+  Gilt uses `--filter=blob:none` for efficient partial clones; go-git does not
+  yet support this.
+
+## Notes
+
+- Related issue: [retr0h/gilt#72](https://github.com/retr0h/gilt/issues/72)
+- The current git CLI wrapper lives in `internal/git/` and implements the
+  `GitManager` interface. The interface-based design means go-git can be
+  swapped in as an alternative implementation with minimal changes to the
+  rest of the codebase.
+- Consider a phased approach: implement go-git backend behind a flag first,
+  fall back to CLI for partial clone operations until go-git catches up.
+
+## Outcome
+
+_To be filled in when complete._

.tasks/backlog/2026-02-16-switch-to-bun.md

@@ -0,0 +1,23 @@
+---
+title: Switch docs site package manager to bun
+status: backlog
+created: 2026-02-16
+updated: 2026-02-16
+---
+
+## Objective
+
+Replace yarn/npm with bun as the package manager for the Docusaurus
+documentation site.
+
+## Notes
+
+- `.mise.toml` already includes `bun = "latest"` so the runtime is available.
+- Requires updating `Taskfile.yml` docs tasks (currently reference yarn).
+- Update `package.json` scripts if needed.
+- Update CI workflows to use bun instead of yarn/npm.
+- Update `docs/docs/contributing.md` references to yarn.
+
+## Outcome
+
+_To be filled in when complete._

AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this
+repository.
+
+## Project Overview
+
+Gilt is a Git repository overlay tool written in Go 1.25. It clones Git
+repositories, checks out specific versions (tags or SHAs), and copies files or
+directories into a target project. Module path: `github.com/retr0h/gilt/v2`.
+
+## Development Reference
+
+For setup, building, testing, and contributing, see the Docusaurus docs:
+
+- @docs/docs/development.md - Prerequisites, setup, code style, testing, commit
+  conventions
+- @docs/docs/contributing.md - PR workflow and contribution guidelines
+- @docs/docs/testing.md - How to run tests and list task recipes
+- @docs/docs/architecture.md - Package architecture and design patterns
+
+Quick reference for common commands:
+
+```bash
+task deps          # Install all dependencies
+task test          # Run all tests (lint + unit + coverage + bats)
+task unit          # Run unit tests only
+task vet           # Run golangci-lint
+task fmt           # Auto-format (gofumpt + golines)
+task fmt:check     # Check formatting without modifying
+go test -run TestName -v ./internal/...  # Run a single test
+```
+
+## Architecture (Quick Reference)
+
+- **`cmd/`** - Cobra CLI commands (`root`, `overlay`, `init`, `version`)
+- **`internal/`** - Interface definitions (`git.go`, `exec.go`, `repository.go`,
+  `repositories.go`)
+- **`internal/git/`** - Git CLI wrapper (clone, worktree, update, remote)
+- **`internal/exec/`** - Command execution abstraction
+- **`internal/repository/`** - Single repository operations (clone, worktree,
+  copy sources)
+- **`internal/repositories/`** - Orchestrates overlay across all configured
+  repositories
+- **`internal/path/`** - Path utility functions
+- **`internal/mocks/`** - Generated mocks (mockgen)
+- **`pkg/config/`** - Configuration types (`Repositories`, `Repository`,
+  `Source`, `Command`) with Viper + validator tags
+- **`pkg/repositories/`** - Public API entry point for repository operations
+- **`test/integration/`** - Bats integration tests
+- **`docs/`** - Docusaurus documentation site
+- **`python/`** - Python wheel packaging for PyPI distribution
+
+## Code Standards (MANDATORY)
+
+### Testing
+
+- Unit tests: `*_test.go` in same package for private functions
+- Public tests: `*_public_test.go` in test package (e.g., `package git_test`)
+  for exported functions
+- Integration tests in `test/integration/` using Bats
+- Use `testify/assert` and `testify/require`
+
+### Go Patterns
+
+- Interface segregation: small interfaces in `internal/*.go`, implementations
+  in sub-packages
+- Dependency injection via constructors (e.g., `NewGit(execManager)`)
+- Error wrapping: `fmt.Errorf("context: %w", err)`
+- Early returns over nested if-else
+- Unused parameters: rename to `_`
+- Import order: stdlib, third-party, local (blank-line separated)
+
+### Linting
+
+golangci-lint with: errcheck, errname, goimports, govet, prealloc, predeclared,
+revive, staticcheck. Formatting via gofumpt + golines.
+
+### Branching
+
+See @docs/docs/development.md#branching for full conventions.
+
+When committing changes, create a feature branch first if currently on `main`.
+Branch names use the pattern `type/short-description` (e.g.,
+`feat/add-dns-retry`, `fix/memory-leak`, `docs/update-readme`).
+
+### Commit Messages
+
+See @docs/docs/development.md#commit-messages for full conventions.
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) with the
+50/72 rule. Format: `type(scope): description`.
+
+## Task Tracking
+
+Work is tracked as markdown files in `.tasks/`. See @.tasks/README.md for
+format details.
+
+```
+.tasks/
+├── backlog/          # Tasks not yet started
+├── in-progress/      # Tasks actively being worked on
+├── done/             # Completed tasks
+└── sessions/         # Session work logs (per session)
+```
+
+When starting a session:
+
+1. Check `.tasks/in-progress/` for ongoing work
+2. Check `.tasks/backlog/` for next tasks
+3. Move task files between directories as status changes
+4. Log session work in `.tasks/sessions/YYYY-MM-DD.md`

CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+@AGENTS.md
+
+When committing via Claude Code, end commit messages with:
+
+- `Co-Authored-By: Claude <noreply@anthropic.com>`
+
+### Claude Code Plugin
+
+Install the **commit-commands** plugin for `/commit` and `/commit-push-pr`
+slash commands:
+
+```
+/plugin install commit-commands@claude-plugins-official
+```