Wayfinder map: CREDEBL Docs improvements (infra + new content)

[ajile-in]

Destination

CREDEBL Docs has decided-and-shipped process infrastructure — repo-hygiene CI, tag-based release machinery, agent-consumption surface (MCP/llms.txt) — plus a decided, ranked set of new content pages with agreed shapes, such that every remaining build can be handed off as a fully-specified slice with no open decisions left.

Notes

• Domain: this entire repo is a GitBook-published docs site synced with main. Every content page must appear in SUMMARY.md; commits are DCO signed-off; PR titles follow conventional commits. See AGENTS.md at repo root.
• Tracker: GitHub Issues per docs/agents/issue-tracker.md. The execution checklist for this initiative lives in Docs improvement initiative: roadmap (Phases 1–4) #8 (Phases 1–4); this map owns the planning decisions. Phase 1 shipped as PR docs: quality triage — broken links, orphaned pages, content fixes (Phase 1 of #8) #7 (pending merge at charting time).
• Skills: ticket work defaults to /grilling + /domain-modeling; AFK research runs via /research subagents.
• Standing decisions made before this map (treat as fixed constraints, not tickets):
  • Independent docs-vX.Y.Z version tags — not tied to platform releases
  • Direct-to-main GitBook sync stays untouched (GITBOOK-* commits land on main)
  • Changelog generated by git-cliff at tag time
  • Decide-only map: resolutions hand off builds to later sessions

Decisions so far

• Research: enabling GitBook MCP + AI surfaces for docs.credebl.id — already live: MCP at /docs/~gitbook/mcp (3 tools) and /docs/llms.txt; nothing to enable; content freshness lags Git Sync publish.
• Research: git-cliff config for mixed conventional + GITBOOK-* history — filter_unconventional = true + ^GITBOOK skip parser drops bot commits; tag_pattern = "docs-v[0-9]+\.[0-9]+\.[0-9]+.*" in [git]; repo has zero tags so set [bump] initial_tag; releases via tag-triggered workflow with git cliff --latest --strip all.

Not yet specified

• What are the docs release-versioning rules? — first tag docs-v2.1.0; independent from there; feat:→minor, fix:→patch, human-cut tags, cliff-generated notes.

• How deep should docs CI go? — lean & blocking: markdownlint (defaults − 4 GitBook exceptions), lychee internal links, SUMMARY-completeness all block PRs; external links via weekly warn-only run; Vale skipped.

• Prototype: outline the quickstart tutorial — outline shipped as-is: 10-section skeleton (auth → org → ecosystem → issuer onboarding → schema → issue), uniform step beat, 10-request Postman inventory (Swagger paths to confirm during build). Implementation handed off as an execution slice.

• Which new content pages does CREDEBL need first? — quickstart tutorial only (self-hoster audience, local Docker, issue-only happy path, Postman collection built in-scope); other three candidates rejected.

• Agent-surface completeness verdict (do llms.txt + MCP expose everything an integrating agent needs?) — becomes decidable once the MCP toggles are flipped and docs: quality triage — broken links, orphaned pages, content fixes (Phase 1 of #8) #7 merges.

Out of scope

• Vale prose linting — skipped by How deep should docs CI go? #13; revisit once content-heavy pages exist.

• OpenAPI spec authoring — deferred by explicit pre-map decision; separate future effort.

• Studio end-user guide + screenshot walkthroughs — ruled out when naming the destination (2026-08-23).

• GitBook multi-space / versioned docs — declined during earlier roadmap discussion (Docs improvement initiative: roadmap (Phases 1–4) #8).

• GET /v1/ecosystem/invitations orgId parameter confirmation — owned by the platform team; tracked as the open question on Docs improvement initiative: roadmap (Phases 1–4) #8.