CLAUDE.md git:20260829.b09995aA

Immutable. This exact content never changes and is served at /api/v1/blob/b35d0d29b9d054be.

# beadle

Autonomous agent daemon with cryptographic owner control. GPG-signed instructions, declared permissions, tamperproof audit trail. Runs on the owner's machine as a background daemon. Written in Go.

The shipping component is `beadle-email` — an MCP server for email communication via Proton Bridge with a four-level PGP trust model.

## Identity

You are **Claude Agento** (`claude`), an agent in the Punt Labs org. Your identity is managed by ethos (`ethos show claude`). Beadle is your email system — you read, send, and manage email as `claude@punt-labs.com`.

**No git submodules in this repo — but a plain vendored copy, per org policy.** The org-wide rule "every project adds `punt-labs/team` as a submodule at `.punt-labs/ethos/`" does not apply here: a `git-subdir` install clones with `--recurse-submodules`, so a submodule's gitlink is fetched into every user's plugin cache regardless of path. Plain committed files carry no such risk — `git-subdir` with `path: "plugin"` only ever materializes `plugin/`'s contents (see below), so `.punt-labs/ethos/` never reaches a plugin consumer either way. Per org policy (`punt-labs/CLAUDE.md` "Team Registry"), `.punt-labs/ethos/` is an inline vendored copy — plain committed files, matching lux, cryptd, public-website, and punt-labs itself. This repo-local copy supplies the `ethos` CLI's agent personas (`.claude/agents/<handle>.md` generation, `ethos identity list`, session roster) under ethos's default layered resolution — repo-local first, global `~/.punt-labs/ethos/` as the fallback tail if a handle is missing here. **`beadle-email` itself is unaffected by any of this vendoring:** its own identity resolution (`internal/identity/resolve.go`) reads the operating identity's YAML exclusively from the global `~/.punt-labs/ethos/identities/<handle>.yaml` — the repo-local copy only ever supplies a *handle* (`.punt-labs/ethos.yaml`'s `agent:` field), never the identity data itself. See `README.md` "Identity" for beadle's resolution chain.

**The plugin payload is `plugin/`, and nothing else.** The shippable surface lives under `plugin/` and the marketplace fetches it with Claude Code's `git-subdir` source — a blobless partial clone plus a cone-mode sparse checkout scoped to `path: "plugin"`. Verified by direct inspection of the installed plugin cache (`~/.claude/plugins/cache/punt-labs/<plugin>/<version>/`): it contains only `plugin/`'s contents, no `.git`, no root-level files, no other top-level directories. Before tracking a new file, ask whether a plugin user has a reason to receive it, and put it in a directory rather than at the root when the answer is no — not because the root leaks (it doesn't), but because a small root stays easy to reason about. `.gitignore` records what has already been trimmed and why. See `docs/ARCHITECTURE.md` for the layout.

## No "Pre-existing" Excuse

There is no such thing as a "pre-existing" issue. If you see a problem — in code you wrote, code a reviewer flagged, or code you happen to be reading — you fix it. Do not classify issues as "pre-existing" to justify ignoring them.

## Standards

This project follows [Punt Labs standards](https://github.com/punt-labs/punt-kit). When this CLAUDE.md conflicts with punt-kit standards, this file wins.

## Build & Run

```bash
make build                              # Build beadle-email binary
make install                            # Build and install to ~/.local/bin
make check                              # All quality gates (golangci-lint, govulncheck, staticcheck, markdownlint, tests)
./beadle-email serve                    # Start MCP server (stdio transport)
./beadle-email version                  # Print version
./beadle-email doctor                   # Check installation health
./beadle-email status                   # Current config summary
```

## Quality Gates

Run before every commit. The Makefile is the source of truth (`make help`).

```bash
make check                             # All gates: lint + docs + test
```

## Scratch Files

Use `.tmp/` for scratch and temporary files — never `/tmp`. `TMPDIR` is set via `.envrc`. Exception: GPG test home directories use short `/tmp/bg-*` paths to stay under the 108-byte Unix-socket path limit (see [`docs/TESTING.md`](docs/TESTING.md)); the deep `.tmp/` path would overflow it.

## Mandatory Reading

Source-of-truth documents, `@`-imported so they stay in context. Read them
before writing code. On conflict, `ARCHITECTURE.md` wins for structure and
`WORKFLOW.md` wins for process; [`docs/README.md`](docs/README.md) is the docs
map and conflict-triage guide.

@docs/README.md
@docs/ARCHITECTURE.md
@docs/WORKFLOW.md
@docs/TESTING.md

These org-wide standards from the `punt-kit` sibling repo are the merged source
of truth for how Punt Labs tools are built, `@`-imported so they load at
session start. `go.md` is the Go standard beadle's code answers to; `github.md`
and `workflow.md` are the PR and org-workflow standards. These are cross-repo
(external) imports, so the first load may ask for approval.

@../punt-kit/standards/go.md
@../punt-kit/standards/github.md
@../punt-kit/standards/workflow.md

## Key Documents

- [`docs/README.md`](docs/README.md) — docs map and conflict triage; start here.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — package map, trust model, invariants.
- [`docs/WORKFLOW.md`](docs/WORKFLOW.md) — the three-loop development workflow.
- [`docs/TESTING.md`](docs/TESTING.md) — test pyramid and GPG/Fastmail test config.
- [`.claude/rules/delegation.md`](.claude/rules/delegation.md) — mission pipelines, worker/evaluator table.
- [CLI standard](https://github.com/punt-labs/punt-kit/blob/main/standards/cli.md) — command-design reference for `beadle-email`.
@.punt-labs/vox/CLAUDE.md
@.punt-labs/ethos/CLAUDE.md
@.punt-labs/beadle/CLAUDE.md