decision: choose canonical HUMMBL Mintlify docs source-of-record

[hummbl-dev]

Problem

hummbl-dev/docs and hummbl-dev/mintlify-docs both exist as public docs surfaces, but source-of-record authority is not explicit.

Decision needed

Select one operating model:

1. docs is canonical; mintlify-docs becomes redirect-only or archived.
2. mintlify-docs is canonical; migrate docs content and workflows here.
3. Dual-repo model (only if split is explicit and durable).

Deliverables

• Document decision in mintlify-docs/README.md.
• Document the relationship in hummbl-dev/docs/README.md.
• Confirm owner/review lane and change-control path.

Acceptance criteria

• Canonical source-of-record is explicitly chosen.
• Non-canonical repo disposition is defined (redirect/archive/limited scope).
• Future docs work has an unambiguous target repo.

[hummbl-dev]

---

Automated triage run (2026-07-24)

• Category: governance
• Priority: P1
• Severity: high
• Staleness: fresh
• Recommended next action: Make the canonical docs source-of-record decision now — this blocks all 5 other issues in this repo (docs-bootstrap: add Mintlify config and initial nav skeleton #4, migration: port core pages from hummbl-dev/docs (conditional) #5, ci: add docs validation checks for Mintlify PRs (conditional) #6, governance: define docs contribution and review policy (conditional) #7, decommission: archive or redirect-only posture for mintlify-docs (conditional) #8 are all conditional). Document the decision in both mintlify-docs/README.md and hummbl-dev/docs/README.md.

Notes: The dual-repo ambiguity (docs vs mintlify-docs) creates contributor confusion and risks content drift. Option 1 (docs canonical, mintlify-docs archived/redirect) is likely lowest-friction if Mintlify adoption is not yet committed; option 2 only if Mintlify is the strategic docs platform.

[hummbl-dev]

Operator decision (2026-07-24)

hummbl-dev/docs is canonical — it already deploys via Mintlify and contains the full public docs surface (docs.json, 20+ MDX pages across api/base120/compliance/primitives/tools, CI validation workflow, CONTRIBUTING, SECURITY, CLAIM_LEDGER, scripts).

mintlify-docs is staging/experimental and will be archived after unique content migration.

Content reconciliation

Both repos were compared file-by-file. No unique, still-valid content was found in mintlify-docs — everything is either already present in docs (in a more complete form) or is repo-specific governance:

mintlify-docs file	Status	Disposition
README.md	Repo-specific (staging disposition)	Stays; updated at archive time
DOCTRINE.md	Older subset of docs/DOCTRINE.md	Stale — docs version is a superset
CHANGELOG.md	Generic placeholder	Duplicate — docs has its own
.github/CODEOWNERS	Identical pattern	Repo-specific
docs/adr/.gitkeep, _receipts/.gitkeep	Empty placeholders	Already exist in docs
docs/issue-promotions/issue-1...	Stale draft scaffold for closed issue #1	Not migrated (stale)

Migration PRs

None required — no unique content to migrate. The docs repo is already ahead on every axis:

• docs-bootstrap: add Mintlify config and initial nav skeleton #4 (Mintlify config + nav skeleton) → already exists in docs (docs.json + full nav)
• migration: port core pages from hummbl-dev/docs (conditional) #5 (port core pages) → already done (20+ MDX pages live in docs)
• ci: add docs validation checks for Mintlify PRs (conditional) #6 (CI validation checks) → already exists (.github/workflows/validate-docs.yml)
• governance: define docs contribution and review policy (conditional) #7 (contribution/review policy) → already exists (CONTRIBUTING.md in docs)

Next steps

1. Close docs-bootstrap: add Mintlify config and initial nav skeleton #4, migration: port core pages from hummbl-dev/docs (conditional) #5, ci: add docs validation checks for Mintlify PRs (conditional) #6, governance: define docs contribution and review policy (conditional) #7 as N/A (conditional on mintlify-docs being canonical — no longer applicable).
2. decommission: archive or redirect-only posture for mintlify-docs (conditional) #8 (decommission) — operator to archive mintlify-docs after confirming no further staging use. README already points to docs as canonical.
3. Update docs/README.md "Related surfaces" line after archival.

Note: GitHub Actions billing concern is resolved — no longer a factor in this decision.

---

Co-authored-by: Devin (devin@hummbl.dev)