Commit graph

26 commits

Author SHA1 Message Date
matt wilkie
f942cc4922
docs: fix broken docs/EXTENDING.md xref to docs/CONFIG.md (#4526)
The configuration reference pointed compact_* tuning at docs/EXTENDING.md,
which has never existed in the repo, so the link broke immediately.
Compaction settings are actually documented in docs/CONFIG.md. Redirect
the reference there, matching the existing CONFIG.md link style, across
the live doc, all three versioned snapshots, and regenerate
website/static/llms-full.txt so no broken xref to docs/EXTENDING.md
remains anywhere in the repo.

Fixes mybd-q71.

Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
2026-07-03 21:44:16 -07:00
matt wilkie
cea892d43f
docs: publish community tools on website (#4299)
* docs: publish community tools on website

Mirror docs/COMMUNITY_TOOLS.md into Docusaurus so the Pages build publishes it for the default released docs and unreleased docs without relying on manual copy steps.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* docs: publish core support docs on website

Mirror Sync Concepts, Labels, Metadata, Uninstalling, and Antivirus docs into Docusaurus and include them in the default released snapshot and LLM bundle.

Clarify that agent execution and verification metadata are examples of metadata as a schema extension point, not native issue fields.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie

* docs: clarify metadata examples

Replace local verification queue metadata with a tracker round-trip example so public metadata docs show upstream-aligned schema extension patterns.

Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
---------
2026-06-03 13:44:47 -07:00
Medhat Galal
99565c0d25 Merge remote-tracking branch 'upstream/main' into AI/import-path-config-upstream
# Conflicts:
#	cmd/bd/config.go
#	cmd/bd/init_templates.go
#	docs/CLI_REFERENCE.md
#	docs/CONFIG.md
#	website/docs/cli-reference/config.md
#	website/versioned_docs/version-1.0.0/cli-reference/config.md
#	website/versioned_docs/version-1.0.4/cli-reference/config.md
2026-05-22 00:40:02 -04:00
matt wilkie
3988db7e0d
fix(init): make JSONL auto-export opt-in (#4063)
* fix(init): make JSONL auto-export opt-in

Default export.auto and export.git-add to false for new repos, make the init prompt opt-in, and update docs/tests to describe JSONL as an optional viewer/interchange/backup export rather than core sync behavior.

Fixes GH#4062

* refactor(auto-export): check commit before throttle

Move cheap Dolt commit change detection ahead of the auto-export throttle and extract the throttle decision into a tested helper. This keeps the default-off design while carrying the compatible part of Jeremy Longshore's GH#4061 refactor.

Based-on: 313e1f8258

Co-authored-by: jeremylongshore <jeremylongshore@users.noreply.github.com>

* docs: regenerate versioned CLI references
* docs: call out JSONL export opt-in change

---------

_codex-gpt-5.5-medium on behalf of CI Bot_
_codex-gpt-5.5-high on behalf of matt wilkie_
Co-authored-by: CI Bot <ci@beads.test>
2026-05-21 16:21:00 -07:00
Medhat Galal
eea1cce5ab Merge remote-tracking branch 'upstream/main' into AI/import-path-config-upstream
# Conflicts:
#	docs/CONFIG.md
2026-05-21 02:05:29 -04:00
matt wilkie
39f3148fc2
docs: clarify export versus database backup (#4048)
* docs: clarify export versus database backup
* docs: remove remaining JSONL backup wording
2026-05-20 16:19:23 -07:00
Medhat Galal
b1c968e91f Document import path portability 2026-05-19 16:34:17 -04:00
matt wilkie
551b1118e0
docs: clarify config routing for tool settings (#3954)
_codex-gpt-5- on behalf of maphew_
2026-05-15 23:58:48 -07:00
matt wilkie
0c47b3c5ac
fix(init): use git origin as default Dolt remote (#3909)
* fix(init): wire git origin as Dolt remote

Default bd init now treats a git origin as the Dolt remote, persists sync.remote, and still skips synthesis in --stealth. JSONL auto-export/import paths now warn or skip based on sync.remote so exports do not masquerade as cross-machine sync.

Docs and generated agent/CLI references now state that Dolt is canonical, refs/dolt/data is the sync channel, and .beads/issues.jsonl is export/interchange/backup only.

_codex-gpt-5-xhigh on behalf of maphew_

* test: keep embedded command stderr out of parsed stdout

Embedded command tests parse IDs and JSON from command output. The new auto-export warnings correctly go to stderr, but several tests used CombinedOutput and treated warnings as stdout, which broke CI shards that parse issue IDs or JSON lists. Capture stdout separately on success while preserving combined output for error diagnostics.\n\n_codex-gpt-5-medium on behalf of CI Bot_

---------

Co-authored-by: CI Bot <ci@beads.test>
2026-05-13 07:02:39 -07:00
Harry Miller
f3b54fc00f
Merge pull request #3749 from maphew/fix/0nr-stale-config-toml-doc
docs(website): config.toml → config.yaml in git-integration.md
2026-05-06 11:09:21 -07:00
CI Bot
a6f2d8d2d3 fix(config): remove dead dolt.idle-timeout key (GH#2452-followup)
The dolt.idle-timeout config key has had no consumer in the tree since
GH#2452 (commit 4df17ca34, in v0.60.0) removed the idle-monitor and
activity-signal daemon infrastructure. There is:
- No SetDefault for it in internal/config/config.go
- No GetString/GetDuration/viper consumer anywhere in cmd/ or internal/
- Only references are docs, the YamlOnlyKeys entry, and a validator case

The validator case (yaml_config.go:521) and YamlOnlyKeys entry served
no purpose since the value was never read. Remove both, plus the
'time' import that becomes unused, and update docs.

Out of scope: docs/DOLT-BACKEND.md:467 has 'idle_timeout: "30s"' under
Dolt server lock-retry settings — that's a different idle_timeout from
the upstream Dolt server config, not the removed beads key. Untouched.

Discovered while reviewing PR #3714 (mybd-b5q).

Amp-Thread-ID: https://ampcode.com/threads/T-019dfe19-17ae-713e-bc3a-d7c9da6a117d
Co-authored-by: Amp <amp@ampcode.com>
2026-05-06 09:50:01 -07:00
CI Bot
56cc30e127 docs(website): config.toml → config.yaml in git-integration.md (GH#3683-followup)
Live config has been YAML since v1.0.0 (per mybd-hxq investigation /
PR #3714: `git show v1.0.0:internal/config/config.go` → SetConfigType("yaml")).
The .beads/ tree diagram on line 23 in both the live and v1.0.0
versioned snapshots still showed config.toml. Same wholly-stale pattern
as PR #3714, smaller blast radius.

Other .toml references in website/docs and website/versioned_docs all
refer to .formula.toml (formulas legitimately use TOML) and are correct.

Out of scope (separate issue mybd-ssn): website/static/llms-full.txt
also has stale config.toml references at lines 11074-11075 and 11196.
That file is generated and is being brought under a freshness gate.

Amp-Thread-ID: https://ampcode.com/threads/T-019dfe19-17ae-713e-bc3a-d7c9da6a117d
Co-authored-by: Amp <amp@ampcode.com>
2026-05-06 09:47:00 -07:00
matt wilkie
67f6d96137
docs: fix wholly-stale configuration.md (TOML/BEADS_* → YAML/BD_*) (#3714)
The published reference page documented `.beads/config.toml` and `BEADS_*`
env vars, but the live implementation has used YAML config (`config.yaml`)
and the `BD_*` env prefix for some time — the site has been misleading
newcomers ever since. Rewritten against `internal/config/config.go` and
`internal/config/yaml_config.go` to match live behavior.

Updates both `website/docs/reference/configuration.md` and the
`version-1.0.0` versioned snapshot, since v1.0.0 itself shipped with
the YAML/BD_* implementation (`SetConfigType("yaml")` and
`SetEnvPrefix("BD")` are present in the v1.0.0 source).

Tracks: mybd-hxq
Refs: GH#3683 (newcomer trust-gap pattern), PR #3706
(mybd-p71 doc inventory that surfaced this).

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 13:42:27 -07:00
matt wilkie
57a4cab9f0
docs: fix broken xref to docs/EXTENDING.md in extension example (#3713)
* docs: fix broken xref to docs/EXTENDING.md in extension example

The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.

Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.

Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.

Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo

Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.

Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):

- docs/ADVANCED.md (3 refs):
  * Note in Extensible Database section: drop trailing "See
    EXTENDING.md for details" — the surrounding sentence about
    Dolt-era alternatives stands on its own.
  * Bold "See EXTENDING.md for complete documentation" line:
    redirect to the canonical working example
    (examples/bd-example-extension-go).
  * Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
  * Namespace doc for compact_*: replace "(see EXTENDING.md)" with
    "(used by `bd admin compact`)" — the doc itself describes the
    keys, no external reference needed.
  * See Also bullet: replace with link to docs/ADVANCED.md
    (Extensible Database section).
- examples/library-usage/README.md (1 ref):
  * See Also bullet: replace EXTENDING.md link with link to the
    sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
  * Custom Tables section: replace EXTENDING.md link with link to
    the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
  * Same fix as the live docs. EXTENDING.md was deleted before
    v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
    so this versioned snapshot has been broken since cut and a fix
    here doesn't violate frozen-in-time correctness — the link was
    never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
  * Updated to match the corrected source so the on-disk artifact
    isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
  * Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
    pointer to examples/bd-example-extension-go. These were real
    broken pointers in published Go source comments.

CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).

Verification:
  grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.

Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 13:18:43 -07:00
matt wilkie
e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
2026-04-25 11:30:19 -07:00
Ben Madore
3b39ce577a
docs: update user-facing URLs from steveyegge/beads to gastownhall/beads
Co-authored-by: Ben Madore <823868+madorb@users.noreply.github.com>
2026-04-24 08:17:42 -07:00
matt wilkie
7fe590d637
fix(docs): repair broken links failing Deploy Documentation CI (#3103)
- architecture/index.md: /docs/DOLT.md → #dolt-server-mode anchor
- core-concepts/index.md: /core-concepts/dolt-server and /dolt-sync → anchor links (pages never existed)
- reference/configuration.md: /docs/CONFIG.md → GitHub source link
- deploy-docs.yml: add lychee --remap to strip /beads/ baseUrl prefix from internal links
- Apply same fixes to versioned_docs/version-1.0.0/

Amp-Thread-ID: https://ampcode.com/threads/T-019d68c4-3efa-71bf-aa9d-6e25fc48fb9a

Co-authored-by: Amp <amp@ampcode.com>
2026-04-07 10:17:55 -07:00
coffeegoddd☕️✨
9134355618 /{README.md,cmd,docs,internal,website}: doc updates 2026-03-28 13:47:20 -07:00
coffeegoddd☕️✨
33eed5d14f /{docs,website}: wip, updating docs 2026-03-28 13:47:20 -07:00
Joseph Turian
6f0e2208ec Add backup fetch-git and git snapshot follow-ups (bd-mtqql) 2026-03-14 23:12:47 -04:00
cwalv
e31428f053 docs: replace "git-backed" with "Dolt-powered", add git-free usage guide
Beads' storage backend is Dolt, not git. Git integration (hooks, repo
discovery, identity) is optional — `BEADS_DIR` + `--stealth` provides
fully functional git-free operation with zero git calls.

Changes across 15 files:
- Replace all "git-backed" references with "Dolt-powered" or "Dolt-backed"
- Add "Git-Free Usage" section to README.md documenting BEADS_DIR + --stealth
- Fix stale "JSONL" storage reference in llms-full.txt
- Update SKILL.md to mark git as optional prerequisite

Complements GH#2522 (stale command cleanup) — that PR fixed removed
commands, this one fixes misleading storage backend framing.
2026-03-13 11:44:50 -07:00
Amp
a333dcaa75 fix(docs): purge stale bd sync/import/--branch refs + add CI doc validation (GH#2522)
Systematic cleanup of stale documentation references left over from the
Dolt migration:

- Replace all 'bd sync' → 'bd dolt push' / 'bd dolt pull' across 40+ files
- Replace all 'bd import' → 'bd init --from-jsonl' or remove
- Replace 'bd init --branch' → note about refs/dolt/data separation
- Fix AGENT_INSTRUCTIONS.md (highest impact: agents read this directly)
- Fix npm-package, claude-plugin, integrations, examples, website docs

Add scripts/check-doc-flags.sh to catch stale doc references:
- Checks for removed commands (bd sync, bd import)
- Checks for removed flags (bd init --branch)
- Warns on legacy SQLite/beads.db references
- Compares CLI_REFERENCE.md against bd help --all

Add CI job (check-doc-flags) and Makefile target (check-docs) to gate
PRs against doc freshness.

Prior art: feat/help-doc-generator branch has bd help --doc/--list for
generating docs FROM CLI output. This script validates docs AGAINST CLI
output — complementary approaches.

Amp-Thread-ID: https://ampcode.com/threads/T-019cde77-0722-7353-b63a-1779a5773ca6
Co-authored-by: Amp <amp@ampcode.com>
2026-03-11 13:25:40 -07:00
Giulio Mecocci
87f32865cf
feat: support issue_id_mode=counter for sequential IDs (#2013)
* feat: support issue_id_mode=counter for sequential IDs (GH#2002)

When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`,
`bd create` now assigns monotonically increasing integer IDs instead of
hash-based IDs. The counter is stored in a new `issue_counter` table (one row
per prefix) and incremented atomically within the same transaction as the issue
insert.

- Add `issue_counter` table to schema (version bumped to 5)
- Add migration 006 to create `issue_counter` table on existing databases
- Add `GetNextIssueCounter()` to queries.go (standalone transaction, for
  callers outside CreateIssue)
- Modify `generateIssueID()` to check `issue_id_mode` config and use counter
  path when set to "counter"; hash mode remains the default when unset
- Explicit `--id` flag continues to take precedence over counter mode
- Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes,
  TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter,
  TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable

* docs: document issue_id_mode=counter feature (GH#2002)

Add documentation for the sequential counter ID mode across all relevant docs:
- docs/CONFIG.md: new issue_id_mode namespace entry and full example section
  with tradeoff table, migration guidance, and per-prefix counter isolation
- .beads/BD_GUIDE.md: counter mode section with when-to-use, migration
  considerations, and explicit --id override behavior
- docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference
  to CONFIG.md
- website/docs/reference/configuration.md: issue_id_mode under ID Generation
  with comparison table

* fix: seed counter from existing issues when enabling counter mode (GH#2002)

When issue_id_mode=counter is enabled on a repo that already has manually-created
sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1,
causing immediate collisions.

Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the
highest numeric suffix for the given prefix, and seeds the issue_counter table
from there. The function is idempotent (skips if a counter row already exists)
and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2).

The seeding is called at first counter use: in generateIssueID() (issues.go) and
GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix.

Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric
IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress).

* feat: add bd config schema and describe commands for agent discoverability (GH#2002)

Adds machine-readable config schema so agents can programmatically discover
all available configuration keys without reading source code.

- internal/config/schema.go: new ConfigKeyDef struct and Schema slice with
  43 entries covering core, sync, routing, jira, linear, gitlab, team, mail,
  and YAML-only keys; includes type, default, valid values, description, and
  storage location per key
- cmd/bd/config.go: adds 'bd config schema' (table + --json) and
  'bd config describe <key>' (single-key detail + --json) subcommands

Usage:
  bd config schema
  bd config schema --json | jq '.[] | select(.key == "issue_id_mode")'
  bd config describe issue_id_mode
  bd config describe jira.url --json

* refactor: remove overengineered config schema (keep docs only)

Remove the configSchemaCmd and configDescribeCmd subcommands added in
the previous commit, along with internal/config/schema.go (390 lines of
config key definitions). These are out of scope for GH#2002.
2026-02-22 23:49:46 -08:00
beads/crew/elinor
90da8f6028 docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4)
Replace JSONL storage/sync references with Dolt-native equivalents across
documentation, plugin resources, website docs, agent instructions, and
example READMEs. Preserves legitimate JSONL references (bd import/export
commands, CHANGELOG history, routes.jsonl/interactions.jsonl concepts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 22:18:02 -08:00
topaz
062aedbed7 docs: remove stale daemon references from all documentation (GH#1982)
Sweep 65 markdown files across docs/, website/, claude-plugin/, examples/,
integrations/, and root to replace removed `bd daemon` references with
current Dolt server mode equivalents. CHANGELOG.md preserved per policy.

Key replacements:
- `bd daemon start/stop/status` → `bd dolt start/stop` / `bd doctor`
- `bd daemons killall/health/logs` → `bd dolt stop` / `bd doctor`
- `--no-daemon` flag → removed (embedded mode is default)
- `BEADS_NO_DAEMON` / `BEADS_DAEMON_MODE` env vars → removed
- `.beads/bd.sock` → removed
- "daemon mode" / "direct mode" → "server mode" / "embedded mode"
- daemon.pid/daemon.log → .beads/dolt/sql-server.pid/.log

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

Executed-By: beads/polecats/topaz
Rig: beads
Role: polecats
2026-02-22 17:57:53 -08:00
Steve Yegge
584608a14e feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml
from joyshmitz's PR. Fixed workflow to trigger on main branch instead of
docs/docusaurus-site.

Features:
- Docusaurus documentation site with llms.txt support
- Environment-variable driven config (defaults to steveyegge org)
- Automated llms-full.txt generation from docs
- GitHub Pages deployment workflow

Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Executed-By: beads/crew/dave
Rig: beads
Role: crew
2025-12-30 18:27:50 -08:00