Commit graph

5 commits

Author SHA1 Message Date
CI Bot
a82e688953 docs: document ado.reconcile_interval and inventory every storage span
Both files had their Last reviewed markers refreshed today without the content
gaps being closed, so the freshness signal is currently green on two docs that
are missing real material.

azure-devops.md — `ado.reconcile_interval` is undocumented. It is real,
user-tunable config (internal/ado/reconcile.go, default 10) setting how many
syncs pass between automatic reconciliation scans, and the doc already documents
the `--reconcile` flag that forces one. Adds a Reconciliation section, and notes
that `ado.syncs_since_reconcile` is beads' own counter rather than a setting.

otel-data-model.md — claims a complete schema but lists 7 of 111 storage spans,
so the issueops role surface is invisible to anyone instrumenting from it.
Rather than 100+ prose sections that would drift again, state the rule the code
follows — span name is "storage." + operation name, which is also the
db.operation attribute (InstrumentedStorage.op) — and inventory both families:
72 direct storage.<Method> spans and 39 storage.<Role>.<Method> spans.

Also records why the families do not double-count: the role decorators wrap the
UNINSTRUMENTED store (IssueLifecycle calls Unwrap() before wrapping), so one
logical operation emits one span on either path and the counters stay
comparable.

No behaviour change; documentation catching up to the code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-07 21:20:41 +00:00
Steve Yegge
f215b312cf
docs: re-review and bump the three 90-day-stale freshness markers (#5394)
* docs: re-review and bump the three 90-day-stale freshness markers

azure-devops.md, json-schema.md, and otel-data-model.md all carried
Last reviewed: 2026-05-08 — exactly 91 days old today, so the doc-flags
freshness gate went red on every branch at once. Each doc was genuinely
re-reviewed against its Freshness source paths on main; drift found and
fixed:

- azure-devops.md: proxied-server mode note (ado sync/status/projects
  hard-error there); --parent and --project flags documented; duplicate
  --issues row dropped; real ado.org error text quoted; ado.pat's
  yaml-only secret storage noted. Source bug found during review filed
  separately: the cmd-level config reader cannot see a yaml-only PAT,
  so the documented Quick Start fails on main (bd-wvf77).

- json-schema.md: bd show/close/update --json return top-level ARRAYS
  (contract-test-pinned); jq recipes fixed accordingly; envelope
  pagination key documented; show's always-present revision field and
  import's unchanged counter added; error envelope (optional code/hint,
  envelope-mode shape, stdout paths, exit 1) corrected; deprecation
  notice's tty-only condition noted.

- otel-data-model.md: hard opt-in via BD_OTEL_ENABLED + standard OTel
  SDK env vars (BD_OTEL_* legacy); console-only trace export; dolt span
  attrs (shared doltSpanAttrs, dolt.remote, dolt.force_push,
  dolt.conflicts, dolt.merge_with_strategy); facade-wave storage role
  spans; seven new Dolt metrics; AI attrs (bd.ai.duration_ms, 4-attempt
  retry); appendix re-pinned to current main.

scripts/check-doc-freshness.sh passes locally.

* docs(otel): complete claim_verify_lost op label enumeration; qualify retry policy as compact-only

Review findings on #5394: op also takes guarded-update
(claim_verify.go:113) and ready-claim (issues.go:439); the retry-policy
sentence describes compact's loop, find_duplicates makes one unretried
call.
2026-08-07 02:35:11 -07:00
Chris Sells
69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00
Chris Sells
5f6bd2c87a docs: fix integration-page fact errors; restore three lost source edits
A second adversarial fact-check pass (372 claims across the 21 integration
and remaining getting-started pages: 291 verified, 22 contradicted) drove
these corrections, each reproduced against the binary or repo source:

- junie.md: the recipe-written MCP config invokes `bd mcp`, which does not
  exist in current builds — the page now warns about that and points at
  the working standalone beads-mcp server config. (The recipe itself,
  cmd/bd/setup/junie.go, still writes the dead config — recorded as a
  product follow-up, out of docs scope.)
- claude-code-plugin.md: the plugin (v1.1.0 manifest) ships skills,
  commands, and hooks — no MCP server. Removed the bundled-server claims,
  uv prerequisite, phantom `init` tool, stale 0.9.2 version pin, and the
  unverified env-var list; MCP guidance now points at the standalone
  server. installation.md's plugin-MCP troubleshooting entry updated to
  the same reality.
- upgrading.md: `bd migrate --cleanup` doesn't exist; the doctor
  migration-skew note was inverted (the check DOES run in embedded mode —
  cmd/bd/doctor/migration_skew.go); `dolt sql-server --stop` is not a
  flag.
- sync-setup.md: `bd vc log` doesn't exist (vc has commit/merge/status);
  use `bd history`.
- azure-devops.md: sync flag table listed phantom --label/--status/--type
  (real: --states/--types/--issues); error strings now quote the actual
  binary messages (MDX-safe).
- github-copilot.md: beads-mcp has no --version flag; verify with
  pip show beads-mcp. aider.md's config sample now matches the generated
  file byte-for-byte.

Also restores three source edits that a mid-script failure silently
dropped from the earlier printed-paths commit (whose message claimed
them): bd mol pour's help no longer says molecules are "synced with git",
the claude recipe's stale ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json), and the shared
recipe template's quickstart URL. CLI docs regenerated accordingly.

Gates: docsync, docsmint, recipes tests, generate-cli-docs.sh --check,
mint broken-links (no broken links), vet — all pass.
2026-07-12 10:37:18 -07:00
Chris Sells
a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.

git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).

Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.

Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2026-07-12 10:37:07 -07:00
Renamed from docs/ADO_CONFIG.md (Browse further)