diff --git a/.github/scripts/docs-render-check.sh b/.github/scripts/docs-render-check.sh new file mode 100755 index 000000000..0a6575e9d --- /dev/null +++ b/.github/scripts/docs-render-check.sh @@ -0,0 +1,136 @@ +#!/usr/bin/env bash +# +# docs-render-check.sh — baseline-aware Mintlify broken-link check for CI. +# +# Runs `mint broken-links` on the HEAD docs tree. When the HEAD has broken +# page links, materializes the BASE docs tree (via git archive) and reports +# only NET-NEW breakage — links that the PR introduced, not pre-existing ones. +# Static-asset refs (.png/.svg/.jpg/.gif) are excluded: mint over-reports +# in-tree images the published build serves fine. +# +# Usage: +# docs-render-check.sh [] +# +# The base branch/sha to compare against (default: origin/main). +# Enables baseline-aware net-new detection. +# +# Exit codes: +# 0 — no net-new page-link regressions +# 1 — net-new page-link regressions found; details on stdout +# +# Requires: git, npx (Node.js), jq +# +set -euo pipefail + +DOCS_DIR="docs" +DOCS_CONFIG="$DOCS_DIR/docs.json" +BASE_REF="${1:-origin/main}" +MINT_CMD="${MINT_CMD:-npx --yes mint@latest}" + +WORK_TMP="$(mktemp -d)" +trap 'rm -rf "$WORK_TMP"' EXIT + +# Verify we have a Mintlify docs tree. +if [[ ! -f "$DOCS_CONFIG" ]]; then + echo "docs-render-check: no docs/docs.json found — skipping" >&2 + exit 0 +fi + +# --- extract_page_links ----------------------------------- +# Parse `mint broken-links` output lines. Each broken link looks like: +# [broken-links] tutorials/01-beads.md -> /tutorials/01-beads.md +# or +# ✗ /tutorials/01-beads.md +# We capture only page links (no static-asset extensions). +ASSET_EXTS='\.png$|\.svg$|\.jpg$|\.jpeg$|\.gif$|\.ico$|\.webp$|\.woff2?$|\.ttf$|\.eot$' + +extract_page_links() { + local file="$1" + grep -oE '[^ ]+\.[a-z]+$|/[^ ]+' "$file" 2>/dev/null \ + | grep -vE "$ASSET_EXTS" \ + | sort -u || true +} + +# Alternative simpler extraction: just lines with the broken-links marker. +parse_mint_broken_links() { + local file="$1" + # mint outputs lines like: " ✗ /path/to/page" or " ✗ page-slug" + # or with indentation. Grab any token that looks like a link (starts with /). + grep -E '✗|broken|BROKEN|error|ERROR' "$file" 2>/dev/null \ + | grep -oE '[/][^ )]+' \ + | grep -vE "$ASSET_EXTS" \ + | sort -u || true +} + +# --- run_mint → exit code ------------------------- +run_mint() { + local root="$1" + local out="$2" + cd "$root" + if $MINT_CMD broken-links >"$out" 2>&1; then + cd - >/dev/null + return 0 + fi + cd - >/dev/null + return 1 +} + +HEAD_OUT="$WORK_TMP/head-mint.txt" +BASE_OUT="$WORK_TMP/base-mint.txt" +BASE_TREE="$WORK_TMP/base-docs" + +# --- HEAD check -------------------------------------------------------------- +HEAD_EXIT=0 +run_mint "." "$HEAD_OUT" || HEAD_EXIT=$? + +if [[ $HEAD_EXIT -eq 0 ]]; then + echo "docs-render-check: no broken links in HEAD — PASS" >&2 + exit 0 +fi + +HEAD_LINKS="$WORK_TMP/head-links.txt" +parse_mint_broken_links "$HEAD_OUT" | sort -u >"$HEAD_LINKS" + +if [[ ! -s "$HEAD_LINKS" ]]; then + # mint exited non-zero but no links we care about. Pass. + echo "docs-render-check: mint non-zero but no page-link regressions detected — PASS" >&2 + exit 0 +fi + +# --- BASE check (baseline-aware) -------------------------------------------- +mkdir -p "$BASE_TREE" +if git archive "$BASE_REF" -- "$DOCS_DIR" 2>/dev/null | tar -x -C "$BASE_TREE"; then + BASE_EXIT=0 + run_mint "$BASE_TREE" "$BASE_OUT" || BASE_EXIT=$? + BASE_LINKS="$WORK_TMP/base-links.txt" + parse_mint_broken_links "$BASE_OUT" | sort -u >"$BASE_LINKS" + # Net-new = in HEAD but NOT in BASE. + NEW_LINKS="$WORK_TMP/new-links.txt" + comm -23 "$HEAD_LINKS" "$BASE_LINKS" >"$NEW_LINKS" +else + echo "docs-render-check: could not materialize base tree from $BASE_REF — checking HEAD only" >&2 + cp "$HEAD_LINKS" "$WORK_TMP/new-links.txt" + NEW_LINKS="$WORK_TMP/new-links.txt" +fi + +if [[ ! -s "$NEW_LINKS" ]]; then + echo "docs-render-check: broken links exist but none are net-new — PASS (pre-existing baseline)" >&2 + exit 0 +fi + +# --- NET-NEW regressions found — fail with explanation -------------- +echo "" +echo "::error::docs-render-check: net-new broken Mintlify page links detected" +echo "" +echo "The following page links are newly broken by this PR:" +while IFS= read -r link; do + echo " $link" +done <"$NEW_LINKS" +echo "" +echo "──────────────────────────────────────────────────────────────────────────" +echo "docs/ is authored for the Mintlify site (the beads Mintlify site)," +echo "not for direct GitHub viewing. These paths/links are intentional —" +echo "please don't reformat them for GitHub. If something is genuinely broken" +echo "on the live site, note it in the PR and we'll fix it Mintlify-side." +echo "──────────────────────────────────────────────────────────────────────────" +exit 1 diff --git a/.github/workflows/docs-mintlify.yml b/.github/workflows/docs-mintlify.yml new file mode 100644 index 000000000..5975c254d --- /dev/null +++ b/.github/workflows/docs-mintlify.yml @@ -0,0 +1,53 @@ +name: Docs (Mintlify) checks + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + paths: + - 'docs/**' + - 'test/docsync/**' + - 'mint.sh' + - '.github/scripts/docs-render-check.sh' + - '.github/workflows/docs-mintlify.yml' + +permissions: + contents: read + +concurrency: + group: docs-mintlify-${{ github.event.pull_request.number }} + cancel-in-progress: true + +jobs: + docsync: + name: Docs nav/link sync (go test ./test/docsync) + runs-on: ubuntu-latest + if: github.event.pull_request.draft == false + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6 + + - name: Set up Go + uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6 + with: + go-version-file: 'go.mod' + + - name: Run docsync guard + run: go test ./test/docsync + + broken-links: + name: Mintlify broken-links (baseline-aware) + runs-on: ubuntu-latest + if: github.event.pull_request.draft == false + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v6 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 + with: + node-version: 22 + + - name: Run baseline-aware broken-link check + env: + BASE_REF: origin/${{ github.base_ref }} + run: .github/scripts/docs-render-check.sh "$BASE_REF" diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 580f057a6..54a16e9aa 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -171,14 +171,6 @@ jobs: ./scripts/check-doc-flags.sh ./bd ./scripts/check-doc-freshness.sh - # Website doc mirrors (website/docs/... and, when applicable, - # website/versioned_docs/version-/...) are a pure text - # transform of their docs/ sources, so this needs no bd build and no - # merge-base attribution: it just fails if scripts/sync-website-docs.sh - # produces any diff against the committed mirrors. - - name: Validate website doc mirrors - run: ./scripts/check-website-docs-drift.sh - # When the drift check fails, it writes the exact regenerated-docs fix # (produced with CI's canonical build) so contributors can apply it with # `git apply` instead of reproducing CI's environment locally. The diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md index 4161cb09e..7c6b5e65c 100644 --- a/AGENT_INSTRUCTIONS.md +++ b/AGENT_INSTRUCTIONS.md @@ -106,9 +106,9 @@ bd hooks install **Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No export/import round-trip needed for normal sync. -**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md). +**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/reference/protected-branches.md](docs/reference/protected-branches.md). -**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md). +**Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/reference/advanced.md](docs/reference/advanced.md). **Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution. @@ -509,7 +509,7 @@ still works as a one-off, shell-scoped override. - Check existing issues: `bd list` - Look at recent commits: `git log --oneline -20` -- Read the docs: README.md, ADVANCED.md, docs/CONFIG.md +- Read the docs: README.md, ADVANCED.md, docs/reference/configuration.md - Create an issue if unsure: `bd create "Question: ..." -t task -p 2` ## Important Files diff --git a/FEDERATION-SETUP.md b/FEDERATION-SETUP.md index 008551fc7..e1b45db46 100644 --- a/FEDERATION-SETUP.md +++ b/FEDERATION-SETUP.md @@ -1,6 +1,6 @@ # Federation Setup Guide -The canonical federation guide is [docs/FEDERATION.md](docs/FEDERATION.md). +The canonical federation guide is [docs/multi-agent/federation.md](docs/multi-agent/federation.md). This root-level file remains only as a stable pointer for existing links (website quickstart pages, `llms-full.txt`). diff --git a/Makefile b/Makefile index b79fed083..eddca57ce 100644 --- a/Makefile +++ b/Makefile @@ -252,6 +252,11 @@ check-docs: @CGO_ENABLED=0 go build -tags "$(BUILD_TAGS)" -ldflags="-X main.Build=$(GIT_BUILD)" -o $(BUILD_DIR)/bd ./cmd/bd @./scripts/check-doc-flags.sh ./bd @./scripts/check-doc-freshness.sh + @go test ./test/docsync + +# Live preview of the Mintlify docs site (docs/) at http://localhost:3000 +docs-dev: + ./mint.sh dev # Ensure -short is not used as an implicit CI tier boundary. check-testing-short: diff --git a/README.md b/README.md index 7c1db5178..08c439a97 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ bd setup factory # Factory.ai Droid - creates/updates AGENTS.md **Note:** Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project. -`bd init` creates or updates `AGENTS.md` by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass `--skip-agents` or `--stealth`. Use `bd setup --list` to see supported integrations, including `bd setup codex`, `bd setup factory`, `bd setup claude`, `bd setup mux`, `bd setup cursor`, and more. See [Agent and IDE setup](docs/SETUP.md). +`bd init` creates or updates `AGENTS.md` by default so agents can discover the beads workflow, and also installs project Claude/Codex integrations unless you pass `--skip-agents` or `--stealth`. Use `bd setup --list` to see supported integrations, including `bd setup codex`, `bd setup factory`, `bd setup claude`, `bd setup mux`, `bd setup cursor`, and more. See [Agent and IDE setup](docs/getting-started/ide-setup.md). Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun `bd init`/`bd setup`, or custom instruction files. In those cases, run `bd onboard` and paste the printed snippet into the file your agent reads. @@ -90,9 +90,9 @@ brew install beads # macOS / Linux (recommended) npm install -g @beads/bd # Node.js users ``` -**Other methods:** [install script](docs/INSTALLING.md#quick-install-script-all-platforms) | [go install](docs/INSTALLING.md#a-note-on-go-install-capability) | [from source](docs/INSTALLING.md#build-dependencies-contributors-only) | [Windows](docs/INSTALLING.md#windows-11) | [Arch AUR](docs/INSTALLING.md#linux) +**Other methods:** [install script](docs/getting-started/installation.md#quick-install-script-all-platforms) | [go install](docs/getting-started/installation.md#a-note-on-go-install-capability) | [from source](docs/getting-started/installation.md#build-dependencies-contributors-only) | [Windows](docs/getting-started/installation.md#windows-11) | [Arch AUR](docs/getting-started/installation.md#linux) -**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/INSTALLING.md](docs/INSTALLING.md) for complete installation guide. +**Requirements:** macOS, Linux, Windows, or FreeBSD. See [docs/getting-started/installation.md](docs/getting-started/installation.md) for complete installation guide. **Upgrading?** Replacing the binary is not always the whole story. Short version: sync remote-backed databases with your current `bd`, back up with @@ -102,7 +102,7 @@ migration on a remote-backed database, exactly one designated clone runs `bd migrate --force` and `bd dolt push`; other clones install the new binary and run `bd bootstrap`. See the full [upgrade guide](https://gastownhall.github.io/beads/docs/getting-started/upgrading) -or [docs/INSTALLING.md](docs/INSTALLING.md#updating-bd). +or [docs/getting-started/installation.md](docs/getting-started/installation.md#updating-bd). ### Security And Verification @@ -112,7 +112,7 @@ The install scripts verify release checksums before install. For manual installs On macOS, `scripts/install.sh` preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via `BEADS_INSTALL_RESIGN_MACOS=1`. -See [docs/ANTIVIRUS.md](docs/ANTIVIRUS.md) for Windows AV false-positive guidance and verification workflow. +See [docs/reference/antivirus.md](docs/reference/antivirus.md) for Windows AV false-positive guidance and verification workflow. ## 💾 Storage Modes @@ -213,9 +213,9 @@ branches, commit history, working-set state, or non-issue tables. Use ## 🌐 Community Tools -See [docs/COMMUNITY_TOOLS.md](docs/COMMUNITY_TOOLS.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps. +See [docs/community-tools.md](docs/community-tools.md) for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps. -See [docs/RELATED_PROJECTS.md](docs/RELATED_PROJECTS.md) for adjacent or complementary projects that solve different problems in the same neighborhood. +See [docs/related-projects.md](docs/related-projects.md) for adjacent or complementary projects that solve different problems in the same neighborhood. ## 🚀 Git-Free Usage @@ -250,5 +250,5 @@ For daemon mode without git, use `bd daemon start --local` ## 📝 Documentation -* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/INSTALLING.md) | [Sync Concepts](docs/SYNC_CONCEPTS.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/COPILOT_CLI_INTEGRATION.md) | [Copilot VS Code MCP](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md) +* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/getting-started/installation.md) | [Sync Concepts](docs/core-concepts/sync-concepts.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/integrations/copilot-cli.md) | [Copilot VS Code MCP](docs/integrations/github-copilot.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/reference/protected-branches.md) | [Troubleshooting](docs/reference/troubleshooting.md) | [FAQ](docs/reference/faq.md) * [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads) diff --git a/SECURITY.md b/SECURITY.md index f2f8e1cf6..7eb557e86 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -141,7 +141,7 @@ Once version 1.0 is released, we will support the latest major version and one p 2. **Review before sharing** - Check issue content before sharing project details 3. **Use private repos** - If your issues contain proprietary information, use private git repositories 4. **Validate git hooks** - If using automated export/import hooks, review them for safety -5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/INSTALLING.md](docs/INSTALLING.md). +5. **Regular updates** - Keep bd updated with your package manager, or re-run the install script from [docs/getting-started/installation.md](docs/getting-started/installation.md). ## Known Limitations diff --git a/cmd/bd/state.go b/cmd/bd/state.go index edbef56a9..af0412a39 100644 --- a/cmd/bd/state.go +++ b/cmd/bd/state.go @@ -1,6 +1,6 @@ // Package main implements the bd CLI state management commands. // These commands provide convenient access to the labels-as-state pattern -// documented in docs/LABELS.md. +// documented in docs/core-concepts/labels.md. package main import ( diff --git a/docs/SYNC_CONCEPTS.md b/docs/SYNC_CONCEPTS.md new file mode 100644 index 000000000..ba2426b3a --- /dev/null +++ b/docs/SYNC_CONCEPTS.md @@ -0,0 +1,6 @@ +# Sync Concepts + +This guide moved to [core-concepts/sync-concepts.md](core-concepts/sync-concepts.md) +as part of the Mintlify docs site under `docs/`. This pointer stays because +`bd init`'s agent instruction templates link to `docs/SYNC_CONCEPTS.md` on +GitHub. diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index 542c8df97..8f420df43 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -69,8 +69,8 @@ irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex brew upgrade beads ``` - +{/* Canonical Homebrew tap-migration snippet. The installation page links + here; keep the two in sync. */} If you still have the old tap formula installed as `bd`, switch to the Homebrew core formula: @@ -227,7 +227,7 @@ lost — that is why step 1 publishes everything first. If a clone was instead migrated independently and `bd dolt pull` later fails with `cannot merge because table dependencies has different primary keys in its common ancestor`, the schema has already forked — follow the recovery playbook: -[RECOVERY.md#pk-fork-refused](https://github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused). +[the pk-fork-refused runbook](/recovery/init-safety#pk-fork-refused). In **server mode**, `bd doctor` adds a migration-content-skew check that flags a diff --git a/docs/integrations/copilot-cli.md b/docs/integrations/copilot-cli.md index 1a7e7fb5b..d8212fd8f 100644 --- a/docs/integrations/copilot-cli.md +++ b/docs/integrations/copilot-cli.md @@ -77,7 +77,7 @@ bd setup copilot --remove - `plugins/beads/copilot_manifest.go` - Embedded manifest source used by `bd setup copilot` - `internal/recipes/recipes.go` - Lightweight `copilot` recipe definition - `internal/recipes/template.go` - Static Copilot instructions template used by `bd setup` -- `docs/COPILOT_INTEGRATION.md` - VS Code MCP integration +- [GitHub Copilot integration](/integrations/github-copilot) - VS Code MCP integration ## References diff --git a/engdocs/CLAUDE.md b/engdocs/CLAUDE.md index f7a9afa3a..df2b145e9 100644 --- a/engdocs/CLAUDE.md +++ b/engdocs/CLAUDE.md @@ -86,8 +86,8 @@ generation. - **AGENTS.md** - Complete workflow and development guide (READ THIS!) - **README.md** - User-facing documentation - **ADVANCED.md** - Advanced features (rename, merge, compaction) -- **docs/LABELS.md** - Complete label system guide -- **docs/CONFIG.md** - Configuration system +- **docs/core-concepts/labels.md** - Complete label system guide +- **docs/reference/configuration.md** - Configuration system ## When Adding Features diff --git a/engdocs/COLLISION_MATH.md b/engdocs/COLLISION_MATH.md index 6cd875994..c9db82f58 100644 --- a/engdocs/COLLISION_MATH.md +++ b/engdocs/COLLISION_MATH.md @@ -142,5 +142,5 @@ This generates the tables above and shows adaptive scaling strategy for any thre ## Related Documentation -- [ADAPTIVE_IDS.md](ADAPTIVE_IDS.md) - Configuration and usage guide -- [CONFIG.md](CONFIG.md) - All configuration options +- [ADAPTIVE_IDS.md](../docs/core-concepts/adaptive-ids.md) - Configuration and usage guide +- [CONFIG.md](../docs/reference/configuration.md) - All configuration options diff --git a/engdocs/CONTRIBUTOR_NAMESPACE_ISOLATION.md b/engdocs/CONTRIBUTOR_NAMESPACE_ISOLATION.md index 64b4aa394..fcd52d89a 100644 --- a/engdocs/CONTRIBUTOR_NAMESPACE_ISOLATION.md +++ b/engdocs/CONTRIBUTOR_NAMESPACE_ISOLATION.md @@ -142,8 +142,8 @@ accordingly: Creates `~/.beads-planning/` and configures routing. 5. **Documentation**: - - `docs/ROUTING.md` - Auto-routing mechanics - - `docs/MULTI_REPO_MIGRATION.md` - Contributor workflow guide + - `docs/multi-agent/routing.md` - Auto-routing mechanics + - `docs/multi-agent/multi-repo-migration.md` - Contributor workflow guide ### What's NOT Implemented (Gaps) diff --git a/engdocs/ICU-POLICY.md b/engdocs/ICU-POLICY.md index 9a709228d..d6a77da2d 100644 --- a/engdocs/ICU-POLICY.md +++ b/engdocs/ICU-POLICY.md @@ -134,7 +134,7 @@ The dolthub maintainers have made clear the upstream default will not flip: *"We ### How `go install` is handled now -Two supported modes, documented in [INSTALLING.md](INSTALLING.md): +Two supported modes, documented in [INSTALLING.md](../docs/getting-started/installation.md): 1. **`CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest`** produces a **server-mode-only** binary. Works on any Go-capable box with no C compiler. Users must run an external `dolt sql-server` and use `bd init --server`. @@ -172,6 +172,6 @@ No fork, no replace directive, no upstream patch required. The tradeoff is that ## See Also -- [INSTALLING.md](INSTALLING.md) -- user-facing build dependency docs -- [DOLT.md](DOLT.md) -- embedded Dolt architecture +- [INSTALLING.md](../docs/getting-started/installation.md) -- user-facing build dependency docs +- [DOLT.md](../docs/architecture/dolt.md) -- embedded Dolt architecture - [CONTRIBUTING.md](../CONTRIBUTING.md) -- contributor guidelines diff --git a/engdocs/INTEGRATION_CHARTER.md b/engdocs/INTEGRATION_CHARTER.md index ce3e38323..e288f72cb 100644 --- a/engdocs/INTEGRATION_CHARTER.md +++ b/engdocs/INTEGRATION_CHARTER.md @@ -87,6 +87,6 @@ When adding support for a new tracker or extending an existing one: ## Related Documents - [Project Charter](PROJECT_CHARTER.md) - Overall product scope and boundaries -- [CLI Reference](CLI_REFERENCE.md) — Full command documentation +- [CLI Reference](../docs/CLI_REFERENCE.md) — Full command documentation - [SECURITY.md](../SECURITY.md) — Security considerations for tracker tokens - [CONTRIBUTING.md](../CONTRIBUTING.md) — How to contribute new integrations diff --git a/engdocs/INTERNALS.md b/engdocs/INTERNALS.md index 2d6f37a95..b66d03363 100644 --- a/engdocs/INTERNALS.md +++ b/engdocs/INTERNALS.md @@ -2,7 +2,7 @@ This document describes internal implementation details of bd, with particular focus on concurrency guarantees and data consistency. -For the overall architecture (data model, sync mechanism, component overview), see [ARCHITECTURE.md](ARCHITECTURE.md). +For the overall architecture (data model, sync mechanism, component overview), see [ARCHITECTURE.md](../docs/architecture/index.md). ## Auto-Flush Architecture diff --git a/engdocs/PERFORMANCE_TESTING.md b/engdocs/PERFORMANCE_TESTING.md index c9d7fcb96..a2aa3395f 100644 --- a/engdocs/PERFORMANCE_TESTING.md +++ b/engdocs/PERFORMANCE_TESTING.md @@ -261,5 +261,5 @@ rm -rf /tmp/beads-bench-cache/ ## See Also - [TESTING.md](TESTING.md) - General testing guide -- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture +- [ARCHITECTURE.md](../docs/architecture/index.md) - System architecture - [INTERNALS.md](INTERNALS.md) - Implementation details diff --git a/engdocs/PROJECT_CHARTER.md b/engdocs/PROJECT_CHARTER.md index 712a1e89c..7dcc70175 100644 --- a/engdocs/PROJECT_CHARTER.md +++ b/engdocs/PROJECT_CHARTER.md @@ -110,7 +110,7 @@ absorb, transform, or reroute the useful part. ## Related Documents - [Integration Charter](INTEGRATION_CHARTER.md) - tracker integration scope -- [Issue Metadata](METADATA.md) - metadata extension point -- [Architecture](ARCHITECTURE.md) - data model and storage architecture +- [Issue Metadata](../docs/core-concepts/metadata.md) - metadata extension point +- [Architecture](../docs/architecture/index.md) - data model and storage architecture - [Maintainer PR Guidelines](../PR_MAINTAINER_GUIDELINES.md) - PR triage and contributor handling diff --git a/engdocs/REPO_CONTEXT.md b/engdocs/REPO_CONTEXT.md index d7a807a7d..52ef4b93e 100644 --- a/engdocs/REPO_CONTEXT.md +++ b/engdocs/REPO_CONTEXT.md @@ -243,9 +243,9 @@ func TestSomething(t *testing.T) { ## Related Documentation -- [WORKTREES.md](WORKTREES.md) - Git worktree integration -- [ROUTING.md](ROUTING.md) - Multi-repository routing -- [CONFIG.md](CONFIG.md) - BEADS_DIR and environment variables +- [WORKTREES.md](../docs/reference/worktrees.md) - Git worktree integration +- [ROUTING.md](../docs/multi-agent/routing.md) - Multi-repository routing +- [CONFIG.md](../docs/reference/configuration.md) - BEADS_DIR and environment variables ## Implementation Notes diff --git a/engdocs/design/otel/otel-architecture.md b/engdocs/design/otel/otel-architecture.md index 220b3346c..66d211ed8 100644 --- a/engdocs/design/otel/otel-architecture.md +++ b/engdocs/design/otel/otel-architecture.md @@ -310,7 +310,7 @@ OTel SDK uses dot-notation internally. Prometheus-compatible backends (VictoriaM | `DOLT_REMOTE_USER` | Push/pull auth user | | `DOLT_REMOTE_PASSWORD` | Push/pull auth password | -> **Note**: Dolt-specific configuration variables are documented in [DOLT.md](../../DOLT.md) and are out of scope for OTEL design documentation. +> **Note**: Dolt-specific configuration variables are documented in [DOLT.md](../../../docs/architecture/dolt.md) and are out of scope for OTEL design documentation. --- @@ -480,8 +480,8 @@ FROM dolt_conflicts; ## Related Documentation - [OTel Data Model](otel-data-model.md) — Complete event schema -- [OBSERVABILITY.md](../../OBSERVABILITY.md) — Quick reference for metrics -- [Dolt Backend](../../DOLT.md) — Dolt configuration and usage +- [OBSERVABILITY.md](../../../docs/reference/observability.md) — Quick reference for metrics +- [Dolt Backend](../../../docs/architecture/dolt.md) — Dolt configuration and usage - [Dolt Concurrency](../dolt-concurrency.md) — Concurrency model and transactions ## Backends Compatible with OTLP diff --git a/engdocs/messaging.md b/engdocs/messaging.md index fedd2cdb2..bd0b13f6a 100644 --- a/engdocs/messaging.md +++ b/engdocs/messaging.md @@ -121,5 +121,5 @@ target was not persisted do not produce hooks. ## See Also -- [Graph Links](graph-links.md) - relates_to, duplicates, supersedes, replies_to -- [CLI Reference](CLI_REFERENCE.md) - All commands +- [Graph Links](../docs/core-concepts/graph-links.md) - relates_to, duplicates, supersedes, replies_to +- [CLI Reference](../docs/CLI_REFERENCE.md) - All commands diff --git a/engdocs/staged-for-removal/DOLT-BACKEND.md b/engdocs/staged-for-removal/DOLT-BACKEND.md index 1c2850aa4..616327217 100644 --- a/engdocs/staged-for-removal/DOLT-BACKEND.md +++ b/engdocs/staged-for-removal/DOLT-BACKEND.md @@ -121,7 +121,7 @@ export BEADS_DOLT_SHARED_SERVER=1 Shared server state lives in `~/.beads/shared-server/` and uses port 3308 by default (avoiding conflict with the orchestrator on 3307). Each project's data remains isolated in its -own database (named by project prefix). See [DOLT.md](../DOLT.md) for details. +own database (named by project prefix). See [DOLT.md](../../docs/architecture/dolt.md) for details. ## Central Dolt Server (macOS) @@ -328,7 +328,7 @@ If upgrading from an older version that used SQLite: > scripts/migrate-jsonl-to-dolt.sh > ``` > -> See [Troubleshooting](../TROUBLESHOOTING.md#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration. +> See [Troubleshooting](../../docs/reference/troubleshooting.md#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration. ### Option 2: Fresh Start @@ -484,7 +484,7 @@ federation: ## Migrating Between Backends Use `bd backup` to migrate data between embedded and server mode. Both -directions preserve full Dolt commit history. See [DOLT.md](../DOLT.md#migrating-between-backends) +directions preserve full Dolt commit history. See [DOLT.md](../../docs/architecture/dolt.md#migrating-between-backends) for step-by-step instructions. **Quick reference:** @@ -512,6 +512,6 @@ bd list ## See Also -- [DOLT.md](../DOLT.md) - Dolt backend overview, federation, and mode details -- [Troubleshooting](../TROUBLESHOOTING.md) - General troubleshooting +- [DOLT.md](../../docs/architecture/dolt.md) - Dolt backend overview, federation, and mode details +- [Troubleshooting](../../docs/reference/troubleshooting.md) - General troubleshooting - [Dolt Documentation](https://docs.dolthub.com/) - Official Dolt docs diff --git a/examples/bd-example-extension-go/README.md b/examples/bd-example-extension-go/README.md index 10643db32..ee994ebd0 100644 --- a/examples/bd-example-extension-go/README.md +++ b/examples/bd-example-extension-go/README.md @@ -2,7 +2,7 @@ This legacy example demonstrates how to extend SQLite-backed bd databases with custom tables for application-specific orchestration. -> **Note:** Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call `bd --json` commands or use `bd query` for SQL access. See [Extensible Database](../../docs/ADVANCED.md#extensible-database) for the current guidance. +> **Note:** Custom SQLite table extensions are a legacy pattern. Current Dolt-backed beads workflows should prefer standalone integration tools that call `bd --json` commands or use `bd query` for SQL access. See [Extensible Database](../../docs/reference/advanced.md#extensible-database) for the current guidance. ## What This Example Shows diff --git a/examples/contributor-workflow/README.md b/examples/contributor-workflow/README.md index 3a100ac37..98dd7c8a8 100644 --- a/examples/contributor-workflow/README.md +++ b/examples/contributor-workflow/README.md @@ -223,6 +223,6 @@ bd config set routing.default . # Default to current repo ## See Also -- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md) +- [Multi-Repo Migration Guide](../../docs/multi-agent/multi-repo-migration.md) - [Team Workflow Example](../team-workflow/) - [Protected Branch Setup](../protected-branch/) diff --git a/examples/linear-workflow/README.md b/examples/linear-workflow/README.md index 12484b9e1..dd0048506 100644 --- a/examples/linear-workflow/README.md +++ b/examples/linear-workflow/README.md @@ -484,7 +484,7 @@ For large projects, initial sync fetches all issues. Subsequent syncs are increm ## See Also -- [CONFIG.md](../../docs/CONFIG.md) - Full configuration documentation +- [CONFIG.md](../../docs/reference/configuration.md) - Full configuration documentation - [Jira Sync](../../README.md) - Similar integration for Jira (`bd jira sync`) - [Linear GraphQL API](https://developers.linear.app/docs/graphql/working-with-the-graphql-api) diff --git a/examples/multiple-personas/README.md b/examples/multiple-personas/README.md index 9f0b93514..f5cd7b55e 100644 --- a/examples/multiple-personas/README.md +++ b/examples/multiple-personas/README.md @@ -662,4 +662,4 @@ bd dep add bd-uat1 bd-review1 --type blocks - [Multi-Phase Development](../multi-phase-development/) - Organize work by phase - [Team Workflow](../team-workflow/) - Collaborate across personas - [Contributor Workflow](../contributor-workflow/) - External contributions -- [Labels Documentation](../../docs/LABELS.md) - Label management guide +- [Labels Documentation](../../docs/core-concepts/labels.md) - Label management guide diff --git a/examples/protected-branch/README.md b/examples/protected-branch/README.md index f76e58bcf..fb9755a97 100644 --- a/examples/protected-branch/README.md +++ b/examples/protected-branch/README.md @@ -274,6 +274,6 @@ jobs: ## See Also -- [docs/PROTECTED_BRANCHES.md](../../docs/PROTECTED_BRANCHES.md) - Complete guide +- [docs/reference/protected-branches.md](../../docs/reference/protected-branches.md) - Complete guide - [AGENTS.md](../../AGENTS.md) - Agent integration instructions - [docs/QUICKSTART.md](../../docs/QUICKSTART.md) - `bd dolt push` / `bd dolt pull` usage diff --git a/examples/team-workflow/README.md b/examples/team-workflow/README.md index 2f112162b..42513440c 100644 --- a/examples/team-workflow/README.md +++ b/examples/team-workflow/README.md @@ -368,7 +368,7 @@ bd sql "CALL dolt_conflicts_resolve('--ours')" bd dolt push ``` -See [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md) for details. +See [GIT_INTEGRATION.md](../../docs/reference/git-integration.md) for details. ### Issue: Issues not syncing @@ -390,5 +390,5 @@ bd validate --checks=conflicts - [Protected Branch Setup](../protected-branch/) - [Contributor Workflow](../contributor-workflow/) -- [Multi-Repo Migration Guide](../../docs/MULTI_REPO_MIGRATION.md) -- [Git Integration Guide](../../docs/GIT_INTEGRATION.md) +- [Multi-Repo Migration Guide](../../docs/multi-agent/multi-repo-migration.md) +- [Git Integration Guide](../../docs/reference/git-integration.md) diff --git a/internal/config/agent_profile.go b/internal/config/agent_profile.go index 0b392ac3e..3985ddafd 100644 --- a/internal/config/agent_profile.go +++ b/internal/config/agent_profile.go @@ -5,7 +5,7 @@ import "strings" // AgentProfile represents the explicit policy profile that controls agent // git/commit authority (gh#3423, follow-up to #4220's PROFILE_VOCABULARY doc). // -// See docs/SETUP.md "Policy Profiles" for the full description of each value. +// See docs/getting-started/ide-setup.md "Policy Profiles" for the full description of each value. type AgentProfile string const ( diff --git a/internal/config/config.go b/internal/config/config.go index e99ae9d45..e2d310420 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -209,7 +209,7 @@ func Initialize() error { // Agent profile configuration (gh#3423, follow-up to #4220) // Explicit runtime knob for the policy profile (git/commit authority) - // documented in docs/SETUP.md. `bd prime` uses this to select its + // documented in docs/getting-started/ide-setup.md. `bd prime` uses this to select its // close-protocol wording. Values: conservative | minimal | team-maintainer. // Invalid values fall back to "conservative" (see GetAgentProfile). v.SetDefault("agent.profile", string(ProfileConservative)) diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.go index a5fd1ff62..46d6db38c 100644 --- a/internal/telemetry/telemetry.go +++ b/internal/telemetry/telemetry.go @@ -22,7 +22,7 @@ // VictoriaLogs :9428 — future log storage // Grafana :9429 — dashboards // -// See docs/OBSERVABILITY.md for the full reference. +// See docs/reference/observability.md for the full reference. package telemetry import ( diff --git a/mint.sh b/mint.sh new file mode 100755 index 000000000..f6920ddfa --- /dev/null +++ b/mint.sh @@ -0,0 +1,62 @@ +#!/usr/bin/env bash +# Local preview for the Mintlify docs site under docs/. +# Usage: ./mint.sh [dev|broken-links|...] (defaults to dev) +set -euo pipefail + +repo_dir=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) +docs_dir="$repo_dir/docs" +args=("$@") +if [[ ${#args[@]} -eq 0 ]]; then + args=(dev) +fi + +node_major() { + node -p 'process.versions.node.split(".")[0]' 2>/dev/null || true +} + +find_node22_bin() { + local prefix + for prefix in /opt/homebrew/opt/node@22 /usr/local/opt/node@22; do + if [[ -x "$prefix/bin/node" ]]; then + printf '%s/bin\n' "$prefix" + return 0 + fi + done + + if command -v brew >/dev/null 2>&1; then + prefix=$(brew --prefix node@22 2>/dev/null || true) + if [[ -n "$prefix" && -x "$prefix/bin/node" ]]; then + printf '%s/bin\n' "$prefix" + return 0 + fi + fi + + return 1 +} + +major=$(node_major) +if [[ "$major" =~ ^[0-9]+$ ]] && (( major < 25 )); then + cd "$docs_dir" + exec npx --yes mint@latest "${args[@]}" +fi + +if node22_bin=$(find_node22_bin); then + export PATH="$node22_bin:$PATH" + cd "$docs_dir" + exec npx --yes mint@latest "${args[@]}" +fi + +cat >&2 </... plus -# website/versioned_sidebars/version--sidebars.json) from their -# source files in docs/. Unlike the CLI reference docs, this mirroring is a -# pure text transform of files already committed in this repo — no bd binary -# build and no blame-scoped attribution across a merge-base is needed. The -# check simply runs the sync script and fails if it produces any diff -# (tracked or untracked), then restores the working tree so the check itself -# is side-effect-free. -# -# Usage: check-website-docs-drift.sh - -set -euo pipefail -export LC_ALL=C - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" - -cd "$PROJECT_ROOT" - -# All paths sync-website-docs.sh can write to. Checked, backed up, diffed, -# and restored as a set. -CHECK_PATHS=(website/docs website/versioned_docs website/versioned_sidebars) - -if [ -n "$(git status --porcelain -- "${CHECK_PATHS[@]}" 2>/dev/null)" ]; then - echo "WARN: working tree has uncommitted changes under ${CHECK_PATHS[*]};" - echo " this check compares against the working tree as-is and will" - echo " restore it to its pre-check state on exit." -fi - -TMP_BACKUP="$(mktemp -d)" -mkdir -p "$TMP_BACKUP/website" -cp -Rf website/docs "$TMP_BACKUP/website/docs" -if [ -d website/versioned_docs ]; then - cp -Rf website/versioned_docs "$TMP_BACKUP/website/versioned_docs" -fi -if [ -d website/versioned_sidebars ]; then - cp -Rf website/versioned_sidebars "$TMP_BACKUP/website/versioned_sidebars" -fi - -restore_tree() { - rm -rf website/docs website/versioned_docs website/versioned_sidebars - cp -Rf "$TMP_BACKUP/website/docs" website/docs - if [ -d "$TMP_BACKUP/website/versioned_docs" ]; then - cp -Rf "$TMP_BACKUP/website/versioned_docs" website/versioned_docs - fi - if [ -d "$TMP_BACKUP/website/versioned_sidebars" ]; then - cp -Rf "$TMP_BACKUP/website/versioned_sidebars" website/versioned_sidebars - fi - rm -rf "$TMP_BACKUP" -} -trap restore_tree EXIT - -"$SCRIPT_DIR/sync-website-docs.sh" - -# git diff alone misses drift where sync-website-docs.sh recreates a mirror -# file that isn't currently tracked (e.g. a committed mirror was deleted, or -# a new sync target was never committed): the recreated file is untracked -# and invisible to `git diff`. Treat any new untracked file under the -# checked paths as drift too. -UNTRACKED="$(git ls-files --others --exclude-standard -- "${CHECK_PATHS[@]}")" - -if git diff --quiet -- "${CHECK_PATHS[@]}" && [ -z "$UNTRACKED" ]; then - echo "PASS: committed website doc mirrors are fresh (sync-website-docs.sh produces no changes)." - exit 0 -fi - -echo "FAIL: website doc mirrors are out of sync with their source docs." -echo "Run: ./scripts/sync-website-docs.sh" -echo "" -if ! git diff --quiet -- "${CHECK_PATHS[@]}"; then - git diff --stat -- "${CHECK_PATHS[@]}" | sed 's/^/ /' - echo "" - git diff -- "${CHECK_PATHS[@]}" | sed -n '1,200p' -fi -if [ -n "$UNTRACKED" ]; then - echo "" - echo "New (untracked) mirror files sync-website-docs.sh produced:" - echo "$UNTRACKED" | sed 's/^/ /' -fi -exit 1 diff --git a/scripts/ci/website.sh b/scripts/ci/website.sh index 00a3ff634..838216948 100755 --- a/scripts/ci/website.sh +++ b/scripts/ci/website.sh @@ -25,18 +25,12 @@ generate_llms_full() { ./scripts/generate-llms-full.sh } -sync_website_docs() { - cd "$REPO_ROOT" - ./scripts/sync-website-docs.sh -} - website_build() { cd "$WEBSITE_DIR" npm run build } ci_time "website npm ci" -- website_npm_ci -ci_time "sync website docs" -- sync_website_docs ci_time "website typecheck" -- website_typecheck ci_time "generate llms-full" -- generate_llms_full ci_time "website build" -- website_build diff --git a/scripts/install.sh b/scripts/install.sh index fb3cae6d0..feb7d256a 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -470,7 +470,7 @@ verify_binary_has_cgo() { # Tries CGO_ENABLED=1 first for an embedded-capable binary. If that fails # (host lacks C toolchain or transitive Dolt deps' headers), falls back to # CGO_ENABLED=0 which yields a server-mode-only binary that still works on -# any Go-capable box. See engdocs/ICU-POLICY.md and docs/INSTALLING.md. +# any Go-capable box. See engdocs/ICU-POLICY.md and docs/getting-started/installation.md. install_with_go() { log_info "Installing bd using 'go install'..." diff --git a/scripts/sync-website-docs.sh b/scripts/sync-website-docs.sh deleted file mode 100755 index 85af2636c..000000000 --- a/scripts/sync-website-docs.sh +++ /dev/null @@ -1,126 +0,0 @@ -#!/usr/bin/env bash -# Mirror selected root documentation into the Docusaurus website tree. - -set -euo pipefail - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" - -write_doc() { - local source="$1" - local target="$2" - local id="$3" - local title="$4" - local slug="$5" - - if [[ ! -f "$source" ]]; then - echo "missing source doc: $source" >&2 - exit 1 - fi - - mkdir -p "$(dirname "$target")" - { - cat < "$target" -} - -rewrite_links() { - local source="$1" - - case "${source#$REPO_ROOT/}" in - docs/LABELS.md) - sed \ - -e 's@](CLI_REFERENCE.md#state-labels-as-cache)@](/cli-reference/set-state)@g' \ - -e 's#](../README.md#](https://github.com/gastownhall/beads/blob/main/README.md#g' \ - -e 's#](../AGENTS.md#](https://github.com/gastownhall/beads/blob/main/AGENTS.md#g' \ - -e 's#](ADVANCED.md#](/reference/advanced#g' \ - "$source" - ;; - docs/METADATA.md) - sed \ - -e 's#](../engdocs/PROJECT_CHARTER.md#](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#g' \ - "$source" - ;; - *) - cat "$source" - ;; - esac -} - -doc_specs=( - "docs/SYNC_CONCEPTS.md|website/docs/core-concepts/sync-concepts.md|sync-concepts|Sync Concepts|/core-concepts/sync-concepts" - "docs/LABELS.md|website/docs/core-concepts/labels.md|labels|Labels|/core-concepts/labels" - "docs/METADATA.md|website/docs/core-concepts/metadata.md|metadata|Issue Metadata|/core-concepts/metadata" - "docs/UNINSTALLING.md|website/docs/recovery/uninstalling.md|uninstalling|Uninstalling|/recovery/uninstalling" - "docs/ANTIVIRUS.md|website/docs/reference/antivirus.md|antivirus|Antivirus False Positives|/reference/antivirus" - "docs/COMMUNITY_TOOLS.md|website/docs/community-tools.md|community-tools|Community Tools|/community-tools" -) - -for spec in "${doc_specs[@]}"; do - IFS='|' read -r source target id title slug <<<"$spec" - write_doc \ - "$REPO_ROOT/$source" \ - "$REPO_ROOT/$target" \ - "$id" \ - "$title" \ - "$slug" -done - -latest_version="$(grep -oE '"[0-9][^"]*"' "$REPO_ROOT/website/versions.json" 2>/dev/null | head -1 | tr -d '"' || true)" -if [[ -n "$latest_version" && -d "$REPO_ROOT/website/versioned_docs/version-$latest_version" ]]; then - for spec in "${doc_specs[@]}"; do - IFS='|' read -r source target id title slug <<<"$spec" - versioned_target="${target#website/docs/}" - write_doc \ - "$REPO_ROOT/$source" \ - "$REPO_ROOT/website/versioned_docs/version-$latest_version/$versioned_target" \ - "$id" \ - "$title" \ - "$slug" - done - - sidebar="$REPO_ROOT/website/versioned_sidebars/version-$latest_version-sidebars.json" - if [[ -f "$sidebar" ]]; then - node - "$sidebar" <<'JS' -const fs = require('fs'); - -const sidebarPath = process.argv[2]; -const data = JSON.parse(fs.readFileSync(sidebarPath, 'utf8')); -const items = data.docsSidebar; - -function category(label) { - return items.find(item => item && typeof item === 'object' && item.label === label); -} - -function insertAfter(list, after, id) { - if (list.includes(id)) return; - const index = list.indexOf(after); - list.splice(index === -1 ? list.length : index + 1, 0, id); -} - -insertAfter(category('Core Concepts').items, 'core-concepts/hash-ids', 'core-concepts/sync-concepts'); -insertAfter(category('Core Concepts').items, 'core-concepts/sync-concepts', 'core-concepts/labels'); -insertAfter(category('Core Concepts').items, 'core-concepts/labels', 'core-concepts/metadata'); -insertAfter(category('Recovery').items, 'recovery/sync-failures', 'recovery/uninstalling'); -insertAfter(category('Reference').items, 'reference/troubleshooting', 'reference/antivirus'); - -if (!items.includes('community-tools')) { - const referenceIndex = items.findIndex( - item => item && typeof item === 'object' && item.label === 'Reference' - ); - const insertAt = referenceIndex === -1 ? items.length : referenceIndex; - items.splice(insertAt, 0, 'community-tools'); -} - -fs.writeFileSync(sidebarPath, `${JSON.stringify(data, null, 2)}\n`); -JS - fi -fi diff --git a/test/docsync/docsync_test.go b/test/docsync/docsync_test.go new file mode 100644 index 000000000..06062e882 --- /dev/null +++ b/test/docsync/docsync_test.go @@ -0,0 +1,391 @@ +// Package docsync keeps the Mintlify site under docs/ and its navigation in +// docs/docs.json in exact correspondence, and keeps local markdown links +// resolving across the documentation trees. +// +// Modeled on the Gas City docsync guard: nav entries must point at real +// files, every published page must be in the nav (no orphans), and links are +// checked with the convention of the tree they live in — docs/ links are +// root-relative and extensionless (Mintlify routes), while engdocs/ and root +// markdown are GitHub-viewed and need exact file paths. +package docsync + +import ( + "encoding/json" + "io/fs" + "os" + "path/filepath" + "regexp" + "runtime" + "sort" + "strings" + "testing" +) + +func repoRoot() string { + _, filename, _, _ := runtime.Caller(0) + return filepath.Join(filepath.Dir(filename), "..", "..") +} + +var markdownLinkRE = regexp.MustCompile(`\[[^][]*\]\(([^)]+)\)`) + +// docsPublishExemptions lists markdown files under docs/ that are allowed to +// exist without a docs.json navigation entry. Keep this list tiny: a file +// belongs here only if it must stay at a stable GitHub path (released bd +// binaries print it, or old deep links target it) or is generated for GitHub +// consumption. Engineering docs belong in engdocs/, not here. +var docsPublishExemptions = map[string]bool{ + "CLI_REFERENCE.md": true, // generated single-file reference (bd help --all) + "QUICKSTART.md": true, // pointer stub; kept for old deep links + "DOLT-BACKEND.md": true, // pointer stub; kept for old deep links + "DOLT.md": true, // pointer stub; bd doctor output references it + "STORAGE-BACKENDS.md": true, // pointer stub; bd init --backend help references it + "PLUGIN.md": true, // pointer stub; bd doctor output references it + "RECOVERY.md": true, // pointer stub; bd dolt output references its runbook anchors + "JSON_SCHEMA.md": true, // pointer stub; bd schema-migration output references it +} + +// rootDocFiles are the curated root-level markdown files whose local links +// are checked GitHub-style. CHANGELOG.md is deliberately absent: its +// historical entries reference files that no longer exist. +var rootDocFiles = []string{ + "README.md", + "AGENTS.md", + "AGENT_INSTRUCTIONS.md", + "CONTRIBUTING.md", + "CLAUDE.md", + "RELEASING.md", + "PR_MAINTAINER_GUIDELINES.md", +} + +func collectMintPages(v any, out *[]string) { + switch x := v.(type) { + case map[string]any: + for k, child := range x { + if k == "pages" { + if arr, ok := child.([]any); ok { + for _, item := range arr { + if s, ok := item.(string); ok { + *out = append(*out, s) + } + } + } + } + collectMintPages(child, out) + } + case []any: + for _, child := range x { + collectMintPages(child, out) + } + } +} + +func mintNavPages(t *testing.T) []string { + t.Helper() + data, err := os.ReadFile(filepath.Join(repoRoot(), "docs", "docs.json")) + if err != nil { + t.Fatalf("reading docs.json: %v", err) + } + var decoded map[string]any + if err := json.Unmarshal(data, &decoded); err != nil { + t.Fatalf("parsing docs.json: %v", err) + } + var pages []string + collectMintPages(decoded, &pages) + sort.Strings(pages) + return pages +} + +func collectMarkdownFiles(root string) ([]string, error) { + var files []string + err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error { + if err != nil { + return err + } + if d.IsDir() { + if name := d.Name(); path != root && (strings.HasPrefix(name, ".") || name == "node_modules") { + return filepath.SkipDir + } + return nil + } + if ext := filepath.Ext(path); ext == ".md" || ext == ".mdx" { + files = append(files, path) + } + return nil + }) + if err != nil { + return nil, err + } + sort.Strings(files) + return files, nil +} + +func extractMarkdownLinks(content string) []string { + matches := markdownLinkRE.FindAllStringSubmatchIndex(content, -1) + var links []string + for _, m := range matches { + start := m[0] + if start > 0 && content[start-1] == '!' { + continue // image + } + target := strings.TrimSpace(content[m[2]:m[3]]) + target = strings.Trim(target, "<>") + if target == "" { + continue + } + if idx := strings.Index(target, ` "`); idx >= 0 { + target = target[:idx] + } + links = append(links, target) + } + return links +} + +// stripCodeFences removes fenced code blocks so links inside examples are +// not checked. +func stripCodeFences(content string) string { + lines := strings.Split(content, "\n") + var out []string + inFence := false + for _, line := range lines { + if strings.HasPrefix(strings.TrimSpace(line), "```") { + inFence = !inFence + continue + } + if !inFence { + out = append(out, line) + } + } + return strings.Join(out, "\n") +} + +func isExternalLink(target string) bool { + switch { + case strings.HasPrefix(target, "http://"), + strings.HasPrefix(target, "https://"), + strings.HasPrefix(target, "mailto:"), + strings.HasPrefix(target, "tel:"), + strings.HasPrefix(target, "#"): + return true + default: + return false + } +} + +func hasMdSuffix(target string) bool { + path := target + if idx := strings.IndexAny(path, "#?"); idx >= 0 { + path = path[:idx] + } + ext := filepath.Ext(path) + return ext == ".md" || ext == ".mdx" +} + +// routeExists reports whether a root-relative extensionless Mintlify route +// (e.g. /getting-started/quickstart) resolves to a page under docs/. +func routeExists(docsRoot, route string) bool { + rel := filepath.FromSlash(strings.TrimPrefix(route, "/")) + if rel == "" { + rel = "index" + } + for _, try := range []string{ + filepath.Join(docsRoot, rel+".md"), + filepath.Join(docsRoot, rel+".mdx"), + filepath.Join(docsRoot, rel, "index.md"), + filepath.Join(docsRoot, rel, "index.mdx"), + filepath.Join(docsRoot, rel), // static assets (images) + } { + if info, err := os.Stat(try); err == nil && !info.IsDir() { + return true + } + } + return false +} + +// TestMintNavigationPagesExist: every docs.json navigation entry points at a +// real page under docs/. +func TestMintNavigationPagesExist(t *testing.T) { + root := repoRoot() + var missing []string + for _, page := range mintNavPages(t) { + path := filepath.Join(root, "docs", filepath.FromSlash(page)) + if filepath.Ext(path) == "" { + path += ".md" + } + if _, err := os.Stat(path); err != nil { + mdx := strings.TrimSuffix(path, ".md") + ".mdx" + if _, err2 := os.Stat(mdx); err2 != nil { + missing = append(missing, page) + } + } + } + if len(missing) > 0 { + t.Errorf("docs.json references missing pages:") + for _, page := range missing { + t.Errorf(" %s", page) + } + } +} + +// TestEveryDocsPageIsPublished: docs/ holds only published pages — every +// markdown file must appear in docs.json navigation (or the tiny stub +// allowlist). Engineering docs belong in engdocs/. +func TestEveryDocsPageIsPublished(t *testing.T) { + root := repoRoot() + docsRoot := filepath.Join(root, "docs") + + navPages := make(map[string]bool) + for _, p := range mintNavPages(t) { + navPages[strings.TrimSuffix(filepath.ToSlash(p), filepath.Ext(p))] = true + } + + files, err := collectMarkdownFiles(docsRoot) + if err != nil { + t.Fatalf("collecting docs markdown: %v", err) + } + + var orphans []string + for _, path := range files { + rel, err := filepath.Rel(docsRoot, path) + if err != nil { + t.Fatal(err) + } + rel = filepath.ToSlash(rel) + if docsPublishExemptions[rel] { + continue + } + pageForm := strings.TrimSuffix(rel, filepath.Ext(rel)) + if !navPages[pageForm] { + orphans = append(orphans, rel) + } + } + + if len(orphans) > 0 { + t.Errorf("docs/ markdown files not referenced in docs.json navigation.\n" + + "docs/ publishes via Mintlify, so every page must be in the nav.\n" + + "Add the file to docs/docs.json navigation (published page) or move it\n" + + "under engdocs/ (engineering doc):") + for _, o := range orphans { + t.Errorf(" docs/%s", o) + } + } +} + +// TestDocsSiteLinks: published docs/ pages use Mintlify link conventions — +// internal links are root-relative and extensionless, and every route +// resolves. Pointer stubs (GitHub-viewed) use exact relative paths instead. +func TestDocsSiteLinks(t *testing.T) { + root := repoRoot() + docsRoot := filepath.Join(root, "docs") + + files, err := collectMarkdownFiles(docsRoot) + if err != nil { + t.Fatalf("collecting docs markdown: %v", err) + } + + var broken []string + for _, path := range files { + rel, _ := filepath.Rel(docsRoot, path) + rel = filepath.ToSlash(rel) + isStub := docsPublishExemptions[rel] + + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("reading %s: %v", path, err) + } + for _, target := range extractMarkdownLinks(stripCodeFences(string(data))) { + if isExternalLink(target) { + continue + } + if isStub { + // GitHub-viewed pointer stub: relative path must exist. + resolved := target + if idx := strings.IndexAny(resolved, "#?"); idx >= 0 { + resolved = resolved[:idx] + } + if resolved == "" { + continue + } + abs := filepath.Clean(filepath.Join(filepath.Dir(path), filepath.FromSlash(resolved))) + if _, err := os.Stat(abs); err != nil { + broken = append(broken, "docs/"+rel+" -> "+target) + } + continue + } + if hasMdSuffix(target) { + broken = append(broken, "docs/"+rel+" -> "+target+" (.md suffix breaks Mintlify routes; link extensionless)") + continue + } + if !strings.HasPrefix(target, "/") { + broken = append(broken, "docs/"+rel+" -> "+target+" (published pages use root-relative links)") + continue + } + route := target + if idx := strings.IndexAny(route, "#?"); idx >= 0 { + route = route[:idx] + } + if !routeExists(docsRoot, route) { + broken = append(broken, "docs/"+rel+" -> "+target) + } + } + } + + if len(broken) > 0 { + sort.Strings(broken) + t.Errorf("broken or misconvention links in docs/ (%d):", len(broken)) + for _, b := range broken { + t.Errorf(" %s", b) + } + } +} + +// TestEngdocsAndRootMarkdownLinks: engdocs/ and curated root markdown are +// GitHub-viewed, so local links must be exact file paths. +func TestEngdocsAndRootMarkdownLinks(t *testing.T) { + root := repoRoot() + + var files []string + engdocs, err := collectMarkdownFiles(filepath.Join(root, "engdocs")) + if err != nil { + t.Fatalf("collecting engdocs markdown: %v", err) + } + files = append(files, engdocs...) + for _, name := range rootDocFiles { + path := filepath.Join(root, name) + if _, err := os.Stat(path); err == nil { + files = append(files, path) + } + } + + var broken []string + for _, path := range files { + data, err := os.ReadFile(path) + if err != nil { + t.Fatalf("reading %s: %v", path, err) + } + for _, target := range extractMarkdownLinks(stripCodeFences(string(data))) { + if isExternalLink(target) { + continue + } + resolved := target + if idx := strings.IndexAny(resolved, "#?"); idx >= 0 { + resolved = resolved[:idx] + } + if resolved == "" { + continue + } + abs := filepath.Clean(filepath.Join(filepath.Dir(path), filepath.FromSlash(resolved))) + if _, err := os.Stat(abs); err != nil { + relPath, _ := filepath.Rel(root, path) + broken = append(broken, filepath.ToSlash(relPath)+" -> "+target) + } + } + } + + if len(broken) > 0 { + sort.Strings(broken) + t.Errorf("broken local markdown links (%d) — engdocs/ and root files are GitHub-viewed and need exact paths:", len(broken)) + for _, b := range broken { + t.Errorf(" %s", b) + } + } +}