docs(ci): add Mintlify preview, docsync guard, and broken-links workflow

- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
  (Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
  correspondence — every nav entry has a file, every page is in the nav
  (tiny stub allowlist for paths released bd binaries print), published
  pages use root-relative extensionless links that resolve, and engdocs/
  plus curated root markdown keep exact GitHub-style paths. Wired into
  make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
  mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
  mirrored files now live once in the Mintlify site; the committed
  Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
  npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
  pointer stub (bd's agent templates print that path). Runtime strings in
  cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
  old paths — covered by stubs, flagged in the PR.
This commit is contained in:
Chris Sells 2026-07-10 18:00:00 -07:00
commit 3198395a32
42 changed files with 717 additions and 289 deletions

136
.github/scripts/docs-render-check.sh vendored Executable file
View file

@ -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 [<base-ref>]
#
# <base-ref> 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 <mint-output-file> -----------------------------------
# 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 <docs-root> <output-file> → 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

53
.github/workflows/docs-mintlify.yml vendored Normal file
View file

@ -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"

View file

@ -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-<latest>/...) 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

View file

@ -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

View file

@ -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`).

View file

@ -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:

View file

@ -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)

View file

@ -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

View file

@ -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 (

6
docs/SYNC_CONCEPTS.md Normal file
View file

@ -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.

View file

@ -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; docs/INSTALLING.md mirrors this block. Keep all three in sync. -->
{/* 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).
<Note>
In **server mode**, `bd doctor` adds a migration-content-skew check that flags a

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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)

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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/)

View file

@ -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)

View file

@ -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

View file

@ -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

View file

@ -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)

View file

@ -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 (

View file

@ -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))

View file

@ -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 (

62
mint.sh Executable file
View file

@ -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 <<EOF
Mintlify does not support Node 25+.
Use Node 22 LTS to preview the docs. For example:
nvm use 22
fnm use 22
volta install node@22
On macOS with Homebrew:
brew install node@22
cd "$repo_dir"
PATH="/opt/homebrew/opt/node@22/bin:\$PATH" ./mint.sh dev
EOF
exit 1

View file

@ -101,9 +101,9 @@ For complete documentation, see the [beads GitHub repository](https://github.com
- [Complete README](https://github.com/gastownhall/beads#readme)
- [Quick Start (documentation site)](https://gastownhall.github.io/beads/getting-started/quickstart) · [repo pointer](https://github.com/gastownhall/beads/blob/main/docs/QUICKSTART.md)
- [Installation Guide](https://github.com/gastownhall/beads/blob/main/docs/INSTALLING.md)
- [FAQ](https://github.com/gastownhall/beads/blob/main/docs/FAQ.md)
- [Troubleshooting](https://github.com/gastownhall/beads/blob/main/docs/TROUBLESHOOTING.md)
- [Installation Guide](https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md)
- [FAQ](https://github.com/gastownhall/beads/blob/main/docs/reference/faq.md)
- [Troubleshooting](https://github.com/gastownhall/beads/blob/main/docs/reference/troubleshooting.md)
## Why npm Package vs WASM?

View file

@ -85,10 +85,10 @@ Multi-clone, multi-branch workflows:
- Hash-based IDs (`bd-abc`) eliminate collision across clones
- Each clone syncs independently via git
- See [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/WORKTREES.md) for comprehensive guide
- See [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/worktrees.md) for comprehensive guide
## External References
- **Official Docs**: [github.com/gastownhall/beads/docs](https://github.com/gastownhall/beads/tree/main/docs)
- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/gastownhall/beads/blob/main/docs/PROTECTED_BRANCHES.md)
- **Worktrees**: [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/WORKTREES.md)
- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/protected-branches.md)
- **Worktrees**: [WORKTREES.md](https://github.com/gastownhall/beads/blob/main/docs/reference/worktrees.md)

View file

@ -255,7 +255,7 @@ This allows releases to work before a certificate is acquired.
Windows code signing helps reduce antivirus false positives that affect Go binaries.
Kaspersky and other AV software commonly flag unsigned Go executables as potentially
malicious due to heuristic detection. See `docs/ANTIVIRUS.md` for details.
malicious due to heuristic detection. See `docs/reference/antivirus.md` for details.
---

View file

@ -1,85 +0,0 @@
#!/bin/bash
# check-website-docs-drift.sh — Freshness check for committed website doc mirrors.
#
# scripts/sync-website-docs.sh regenerates the Docusaurus mirrors of selected
# root docs (website/docs/..., and, when a versioned snapshot exists,
# website/versioned_docs/version-<latest>/... plus
# website/versioned_sidebars/version-<latest>-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

View file

@ -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

View file

@ -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'..."

View file

@ -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 <<EOF
---
id: $id
title: $title
slug: $slug
---
EOF
rewrite_links "$source"
} > "$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

View file

@ -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)
}
}
}