beads/docs/getting-started/quickstart.md
Vishnu J 102372dabd
fix(notion): keep notion.token out of the Dolt database (#6676) (#6724)
* fix(notion): keep notion.token out of the Dolt database (#6676)

notion.token was missing from YamlOnlyKeys, so `bd config set
notion.token` (the command `bd notion status` recommends) wrote the
token to the Dolt config table, whose contents `bd dolt push` sends to
the remote. The git-tracked-config guard never fired for it either,
because checkSecretGitTracked only considers yaml-only keys.

- Add notion.token to YamlOnlyKeys, next to github.token, gitlab.token,
  jira.api_token and ado.pat, so `bd config set` writes it to
  config.yaml and refuses a git-tracked config.yaml.
- Map notion.token to NOTION_TOKEN in secretKeyEnvVarHints so that
  refusal suggests the variable bd actually reads, not BD_NOTION_TOKEN.
- notion.ResolveAuth now reads config.yaml first, then the database,
  then NOTION_TOKEN. The database read is kept only so a token stored
  by an older bd keeps authenticating after an upgrade.
- resolveNotionAuth's no-store fallback goes through ResolveAuth, so a
  config.yaml token is found even when no store is open.
- The proxied `bd serve` settings integration test used notion.token as
  its credential-bearing key and read it back with `bd config get`,
  which now reads config.yaml; it uses notes.api_token instead.
- The DB-backed-secret guard test used notion.token as its example of a
  non-yaml secret key; it uses custom.api_token instead.
- Docs list notion.token with the other yaml-only secrets, and the
  quickstart leads with NOTION_TOKEN because `bd init` in a git repo
  leaves config.yaml tracked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(config,notion): delete leaked secret rows on unset; name the legacy auth source

Maintainer review fixes for #6724 (GH#6676).

Finding 1 (major, PR-introduced): moving notion.token into YamlOnlyKeys made
`bd config unset notion.token` return before the store, so a workspace that had
already leaked the token into the pushed config table lost its only bd-side
remover — exactly the population the PR exists to protect. configUnsetCmd now
best-effort deletes the database row for yaml-only SECRET keys and reports which
copies it removed. It is keyed on IsYamlOnlyKey+IsSecretKey rather than on
notion.token, so it closes the gap for the whole class; measured, that is at
least ado.pat, github.token, gitlab.token, jira.api_token, linear.api_key,
linear.oauth_client_secret and notion.token, plus whatever the prefix rules
(`ai.`, `sync.`, `federation.`, ...) admit. Non-secret yaml-only keys are gated
out before the store is opened, so an ordinary `bd config unset routing.mode`
still costs no database open. It reads before deleting because DeleteConfig
reports no miss, so the common never-leaked workspace stays silent instead of
announcing a removal that did not happen.

Finding 2 (major, pre-existing class): internal/notion/auth.go asserted "It must
never be written to the database" as an unqualified invariant while
PUT /v0/beads/config/notion.token still writes that row with no refusal. Scoped
the comment to the CLI door and named the HTTP/dashboard door as the known
remaining hole. Closing that door is deliberately NOT attempted here: it is a
cross-tracker change at workapi.ValidateSettingWrite/SetSetting on a
pre-existing surface, and belongs where every tracker credential gets the rule
at once.

Finding 3 (minor): the config.yaml token and the legacy row both reported
`config_token`, collapsing the safe case with the leaked one. Added
AuthSourceDatabaseLegacy plus a `bd notion status` rotation warning — the only
signal that gives the CHANGELOG's rotation advice an addressee.

Finding 4 (minor): pinned the end-to-end shape `bd config set` actually writes.
The finding cited internal/config/config.go:653 (setNestedKey), which is
SaveConfigValue's writer and not on this path — SetYamlConfig routes through
updateYamlKey/updateNestedYamlKey — but its conclusion held: the written shape
is nested. The new test drives the real writer rather than a second fixture, and
both its assertions were proven live by mutation (breaking the config.yaml read
trips the round-trip; forcing the flat fallback trips the non-vacuity guard,
while the round-trip alone still passed, which is why that guard exists).

Finding 5 (nit): both "not configured" errors led with `bd config set
notion.token`, which the new git-tracked refusal rejects in the default
post-`bd init` layout. They now lead with `export NOTION_TOKEN`, matching the
quickstart's ordering.

Also corrected the CHANGELOG, which still claimed unset clears config.yaml only.

Validation: ./internal/notion and ./internal/config green under `env -u
BEADS_DIR`. The cmd/bd notion/config tests are green except
TestConfigValidateReadOnlyIsHermetic and
TestGetNotionConfigReadsDBPathWhenStoreUnset, which fail identically at the PR
head with these fixes stashed (A/B in this same worktree) — ambient, not
introduced here.

--- Iteration 2 review fixes (one major, three minors, one nit) ---

Finding 1 (major, introduced by the iteration-1 fixup above): the cleanup
reached the store through openWorkspaceConfig -> ensureDirectMode ->
ensureStoreActive, which is open-OR-CREATE. So `bd config unset <yaml-only
secret>` in a workspace holding only .beads/config.yaml created a 2.1 MB
embedded Dolt database and flipped it out of db-less mode for every later
command -- from a command whose contract is "edit a YAML file", silently and
with exit 0. It also contradicted configCommandCanRunWithoutStore, which
classifies this exact invocation as runnable with no store precisely when
beads.FindDatabasePath() is empty. unsetLeakedSecretRow now returns early
rather than reach an open-OR-CREATE store in a workspace that has no database to
reach. The proxied route is exempt rather than gated --
proxiedWorkspaceConfig reaches an already-connected provider and creates
nothing, and a server-mode workspace legitimately has no local database
directory for FindDatabasePath to find, so gating it on the local path would
silently disable the cleanup exactly where the row is most replicated. Iteration 3 finishes
that thought: the same is true of the DIRECT server-mode route, which this gate
still skipped.

Finding 2 (minor): the remover ran only if the YAML unset succeeded first,
which skipped it for the population it exists for -- no config.yaml, or a shape
UnsetYamlConfig refuses. Base deleted the row there and the fixup did not, while
`bd notion status` names this very command as the remover. The cleanup now runs
either way, and a failed YAML unset carries the row's fate in its error instead
of telling the user to run `bd init` while a credential sits in the pushed
table.

Finding 3 (minor): a failed DELETE of a row the read had found was rendered as
"Could not check the database ..." under a JSON key asserting unreachability --
the one outcome that is certain, reported as the inconclusive one.
removeStoredSecretRow now returns the found bit alongside the error, and the
delete-failure case gets its own message and its own JSON keys
(database_row_present / database_delete_failed), carrying the rotation warning.

Finding 4 (minor): nothing pinned the command -> cleanup wiring; deleting the
call left every test green. The yaml-only branch is now runConfigUnsetYamlOnly
and four new tests drive configUnsetCmd itself against a recording settings
surface: the row is read, deleted and reported; a non-secret yaml-only key
touches the config plane zero times; --json carries the new keys; and .beads/ is
byte-unchanged (config.yaml aside) after unsetting a secret with no database
present.

Finding 5 (nit): CHANGELOG and docs/reference/configuration.md described the
dual removal unconditionally. Both now say the database half is best effort and
name the cases where it is skipped or refused.

Every new pin proven by mutation, one at a time, each failing only with its fix
removed: dropping the FindDatabasePath gate takes the no-database test into
embeddeddolt.OpenSQL (it really does provision); re-gating the cleanup behind
the YAML unset leaves the row undeleted and unmentioned; replacing the command's
cleanup call with a zero value drops the report and the --json field; returning
false for `present` on a failed delete puts database_unreachable back.

Complexity ledger flat by construction: worst_changed stays
showConfigYAMLOverrides at cyclomatic 17 / cognitive 29, which this PR does not
touch and which measures identically at the base blob. The extracted
runConfigUnsetYamlOnly is 6/9 and the three report helpers are at most 5/2.

Iteration 2 validation: ./internal/notion and ./internal/config green under
`env -u BEADS_DIR`; all nine cmd/bd leaked-secret/notion-auth tests green, one
-run per invocation (a batched regex shares rootCmd and produces false reds);
the CGO_ENABLED=0 gms_pure_go cmd/bd test binary still compiles (the new test
file is untagged, so it carries its own tree-snapshot helper rather than the
cgo-tagged twin); scripts/check-doc-flags.sh and `go test -tags=gms_pure_go
./test/docsync` pass for the docs edit.

--- Iteration 3 review fixes (two minors, both on the gate itself) ---

Finding 1 (minor, introduced by the iteration-2 gate above): "not proxied and no
local database directory" over-fires. findDatabaseInBeadsDir answers on
metadata.json plus embeddeddolt/ and dolt/, and it skips the stat for server mode
only when metadata.json is present -- so a metadata-less server workspace, whose
host comes from config.yaml or BEADS_DOLT_SERVER_HOST (main.go, GH#3545, the
shape gc provisions on every `gc-beads-bd start`), reports "" while its row sits
on the shared server, replicated to every remote it pushed to. The skip was not
buying anything there either: PersistentPreRun has already CONNECTED that
workspace's store, and ensureStoreActive early-returns on an active store without
opening or creating anything. For notion.token this was a narrow regression of a
base capability -- at base that key was not yaml-only, so `bd config unset
notion.token` took the database branch and deleted the row. The seven
pre-existing yaml-only secrets never had a remover at base, so for them the skip
withheld only new coverage, which is what holds this at minor. The gate is now
mayProvisionDatabase, which asks about the store before the disk; each arm that
returns false is a route where the database is already open -- proxied, or a
store already active and tracked, which is provably non-provisioning because it
is ensureStoreActive's own no-op arm.

Finding 2 (minor): neither arm of that gate had a behavioral test. Deleting the
!usesProxiedServer() clause left all four command-level tests green, and it is
the only thing keeping the cleanup alive for proxied workspaces, which have no
local database directory by construction -- the clause a later simplification is
most likely to read as redundant was the one clause nothing defended.
TestConfigUnsetCleansTheRowWithNoLocalDatabaseDirectory now pins both arms as the
mirror of TestConfigUnsetDoesNotProvisionADatabase: "no local database directory"
is the state all three share, so the route to the database is the only thing that
distinguishes them.

Both arms mutation-proved, one at a time, each red on exactly one subtest while
the four pre-existing command-level tests stayed green under both mutations:
deleting the active-store arm reproduces the finding verbatim (GetSetting calls =
[], UnsetSetting calls = [] for a connected server workspace, exit 0); deleting
the !usesProxiedServer() arm leaves the proxied workspace's row never looked for.
That second half -- the pre-existing suite staying green -- is the claim Finding 2
rests on, and only a run under the mutation can state it.

The CHANGELOG's "skipped where there is no database to hold a row" and the
matching sentence in docs/reference/configuration.md asserted exactly what the
gate got wrong; both now say it is skipped only where reaching the row would mean
creating a database, and that a server-mode or proxied workspace whose database
is simply not on local disk still gets the cleanup.

Complexity ledger still flat: worst_changed stays showConfigYAMLOverrides at
cyclomatic 17 / cognitive 29 (untouched, identical at the base blob), and
extracting the gate took unsetLeakedSecretRow from 6/5 to 5/4 with
mayProvisionDatabase at 4/3.

Iteration 3 validation: gofmt clean, `go build ./cmd/bd/`, `go vet ./cmd/bd/` and
`git diff --check` clean; the six leaked-secret/notion-auth tests and the four
command-level tests all green against the real fix, one -run per invocation under
a private TMPDIR (a batched regex shares rootCmd and produces false reds; a
sibling suite's sweep deletes shared temp roots mid-run); the CGO_ENABLED=0
gms_pure_go cmd/bd test binary still compiles; scripts/check-doc-flags.sh,
scripts/check-doc-freshness.sh and `go test -tags=gms_pure_go ./test/docsync`
pass for the docs edit (no new links, anchors or headings, so the render check
does not apply).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
2026-09-27 14:53:11 -07:00

373 lines
10 KiB
Markdown

---
title: Quick Start
description: Initialize beads, create issues with dependencies, find ready work, and sync with your team in a few minutes
---
Get up and running with Beads in a few minutes.
## Why Beads?
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:
**Flat tracker (GitHub Issues):**
```
Open issues: Set up database, Create API, Add authentication
→ An agent picks "Add authentication" and gets stuck immediately
```
**Beads:**
```bash
$ bd ready
1. [P1] [task] bd-1: Set up database
$ bd ready --explain --json | jq '.blocked[0]'
{
"id": "bd-3",
"title": "Add authentication",
"blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
}
```
The agent picks the right task every time. No wasted cycles.
## Installation
Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).
**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.
```bash
bd --help
```
## Initialize
First time in a repository:
```bash
# Basic setup (prompts for contributor mode)
bd init
# For AI agents (non-interactive)
bd init --quiet
# OSS contributor (fork workflow with separate planning repo)
bd init --contributor
# Team member (branch workflow for collaboration)
bd init --team
# Protected main branch (GitHub/GitLab)
# Note: Dolt stores data under refs/dolt/data, separate from
# Git refs, so no --branch flag is needed.
```
The wizard will:
- Create `.beads/` directory and embedded Dolt database
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
- Import existing issues from git (if any)
- Install git hooks (skip with `--skip-hooks`)
Notes:
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
- To import issues from an older installation, run `bd init --from-jsonl`.
### Role configuration
During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"
- Answer **Y** if you're contributing to a fork (runs contributor wizard)
- Answer **N** if you're the maintainer or have push access
This sets `git config beads.role` which determines how beads routes issues:
| Role | Use case | Issue storage |
|------|----------|---------------|
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
You can also configure manually:
```bash
# Set as contributor
git config beads.role contributor
# Set as maintainer
git config beads.role maintainer
# Check current role
git config --get beads.role
```
**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.
## Your first issues
```bash
# Create a few issues
bd create "Set up database" -p 1 -t task
bd create "Create API" -p 2 -t feature
bd create "Add authentication" -p 2 -t feature
# List them
bd list
```
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
## Hierarchical issues (epics)
For large features, use hierarchical IDs to organize work:
```bash
# Create epic (generates parent hash ID)
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Create child tasks (use --parent to attach to the epic)
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
# View hierarchy
bd dep tree bd-a3f8e9
```
Output:
```
Dependency tree for bd-a3f8e9:
> bd-a3f8e9: Auth System [epic] [P1] (open)
> bd-a3f8e9.1: Design login UI [P1] (open)
> bd-a3f8e9.2: Backend validation [P1] (open)
> bd-a3f8e9.3: Integration tests [P1] (open)
```
Children inherit the epic's labels by default — if the epic carries a size/effort label, see [Labels](/core-concepts/labels) for how to keep it off the children.
## Add dependencies
```bash
# API depends on database
bd dep add bd-2 bd-1
# Auth depends on API
bd dep add bd-3 bd-2
# View the tree
bd dep tree bd-3
```
Output:
```
Dependency tree for bd-3:
> bd-3: Add authentication [P2] (open)
> bd-2: Create API [P2] (open)
> bd-1: Set up database [P1] (open)
```
**Dependency visibility:** `bd list` shows blocking dependencies inline:
```
○ bd-a1b2 [P1] [task] - Set up database
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
```
## Find ready work
```bash
bd ready
```
Output:
```
Ready work (1 issues with no active blockers):
1. [P1] bd-1: Set up database
```
Only bd-1 is ready because bd-2 and bd-3 are blocked.
**Understanding why:** Use `--explain` to see the full graph reasoning:
```bash
bd ready --explain
```
Output:
```
Ready Work Explanation
● Ready (1 issues):
bd-1 [P1] Set up database
Reason: no blocking dependencies
Unblocks: 1 issue(s)
● Blocked (2 issues):
bd-2 [P2] Create API
← blocked by bd-1: Set up database [open]
bd-3 [P2] Add authentication
← blocked by bd-2: Create API [open]
─ Summary: 1 ready, 2 blocked
```
**Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work.
## Work the queue
```bash
# Start working on bd-1
bd update bd-1 --claim
# Complete it
bd close bd-1 --reason "Database setup complete"
# Check ready work again
bd ready
```
Now bd-2 is ready.
## Track progress
```bash
# See blocked issues
bd blocked
# View statistics
bd stats
```
## Team sync
Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs. In repos with `origin`, `bd init` configures that Dolt remote automatically.
```bash
# Verify the remote, or add one if the repo had no origin during init
bd dolt remote list
bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed
# Push your issues
bd dolt push
# Pull teammates' changes
bd dolt pull
```
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`.
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration, see [Dolt architecture](/architecture/dolt); for federation, see [federation](/multi-agent/federation).
## Optional: Notion sync
If you keep project issues in Notion, supply an integration token first:
```bash
export NOTION_TOKEN=<your-token>
# or, if .beads/config.yaml is not tracked by git:
bd config set notion.token <your-token>
```
`bd config set` never writes the token to the Dolt database, so `bd dolt push` does not send it to a remote. It writes the token to `.beads/config.yaml` instead, and refuses when that file is tracked by git, as it is after `bd init` in a git repository.
Then either create a new Beads database under a parent page or connect to an existing target:
```bash
bd notion init --parent <page-id>
# or
bd notion connect --url <notion-database-or-data-source-url>
```
Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
Check which auth source is active and whether the target schema is ready:
```bash
bd notion status
bd notion status --json
```
Preview or run sync:
```bash
bd notion sync --dry-run
bd notion sync
bd notion sync --pull
bd notion sync --push
```
## Database location
By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
In server mode, data is managed by the external `dolt sql-server`.
## Migrating databases
After upgrading bd, use `bd migrate` to check for and migrate old database files:
```bash
# Inspect migration plan (AI agents)
bd migrate --inspect --json
# Check schema and config
bd info --schema --json
# Preview migration changes
bd migrate --dry-run
# Migrate old databases to beads.db
bd migrate
# Migrate and clean up old files
bd migrate --yes
```
**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
## Database maintenance
As your project accumulates closed issues, the database grows. Manage size with these commands:
```bash
# View compaction statistics
bd admin compact --stats
# Preview compaction candidates (30+ days closed)
bd admin compact --analyze --json
# Apply agent-generated summary
bd admin compact --apply --id bd-42 --summary summary.txt
# Immediately delete closed issues (CAUTION: permanent!)
bd admin cleanup --force
```
**When to compact:**
- Database file > 10MB with many old closed issues
- After major project milestones when old issues are no longer relevant
- Before archiving a project phase
**Note:** Compaction is permanent graceful decay. Original content is discarded but recoverable via `bd restore <id>` (from the pre-compaction snapshot, with Dolt history as fallback).
## Next steps
- Add labels: `bd create "Task" -l "backend,urgent"`
- Filter ready work: `bd ready --priority 1`
- Explain the graph: `bd ready --explain`
- Check graph integrity: `bd graph check`
- Search issues: `bd list --status open`
- Detect cycles: `bd dep cycles`
- Gates for PR/CI sync: [`bd gate`](/cli-reference/gate)
- More sync scenarios: [`bd dolt`](/cli-reference/dolt)
- Full command list: [CLI Reference](/cli-reference/index)
See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.