Docs improvement initiative: roadmap (Phases 1–4)

[ajile-in]

Tracking issue for the CREDEBL Docs improvement initiative. Each phase ships as its own PR linked below.

---

🗺️ Phases

✅ Phase 1: Quality triage — COMPLETED → PR #7

Fixes every critical/high issue found in the docs audit:

• Add 3 orphaned pages to navigation (SUMMARY.md) — OID4VC Issuer API, OID4VP Verifier API, Ecosystem & Trust Service (also makes them discoverable via the site's llms.txt agent index)
• Fix 7 broken links (dead app.gitbook.com revision URLs, stale anchors #credebl-saas / Keycloak #top, GitBook revision link, nonexistent http://nextauth.js, mislabeled Getting Started card, absolute docs-site URL → relative)
• Vendor 5 SendGrid screenshots from expiring Google Docs CDN into .gitbook/assets/sendgrid/
• Correct reversed Studio version gates (older = >v2.1.0 → before v2.1.0)
• Make cliConfig.json sample valid JSON (comments removed, double comma, missing token value & polygon-mainnet comma); fix documented field name referringlabel → label
• Repair garbled consent-notice sentence + prune stale TOC entries (3.3 Template, 4 Cross-Ecosystem Access) in Ecosystem doc
• Rewrite mangled Copyright & License markdown
• Typos & grammar sweep (Keycloak, PostgreSQL, phishing-resistant, Endorser, merged bullets, truncated API-access step, etc.)
• Repoint OID4VC cross-references from removed per-file docs to in-page sections

⬜ Phase 2: Repo hygiene

• AGENTS.md at repo root (structure map, SUMMARY completeness rule, conventions — for coding agents & contributors)
• CONTRIBUTING.md mirror of the how-to-contribute page (surfaces on GitHub PR UI)
• CI: markdownlint + Vale style checks + lychee link checker

⬜ Phase 3: Release machinery

• git-cliff config generating CHANGELOG.md at tag time (tolerates direct-to-main GITBOOK-* commits)
• Tag docs-vX.Y.Z → GitHub Release workflow (notes auto-generated)
• Release-page template for references/releases/vX.Y.Z.md (links back to GH Release + compare URL)
• Backfill first tag docs-v2.1.0

⬜ Phase 4: Agent surface

• Verify/enable published-site MCP server (docs.credebl.id/~gitbook/mcp via Site customization → Page actions)
• Confirm llms.txt completeness after orphaned pages merge (unblocked by PR docs: quality triage — broken links, orphaned pages, content fixes (Phase 1 of #8) #7)
• OpenAPI spec drafting — deferred to a separate initiative per team decision

---

🔒 Locked decisions

Decision	Choice
Docs versioning	Independent docs-vX.Y.Z tags
GitBook sync flow	Keep direct-to-main (GITBOOK-* commits untouched)
Changelog tooling	git-cliff generated at tag time
OpenAPI specs	Deferred — separate future effort

📝 Open questions

• GET /v1/ecosystem/invitations?orgId={ecosystemId} — param name vs documented value mismatch; needs platform-team confirmation of the real contract (flagged in PR docs: quality triage — broken links, orphaned pages, content fixes (Phase 1 of #8) #7, intentionally not changed).

[ajile-in]

🗺️ Planning decisions for this initiative now live in Wayfinder map #9 (tickets as child issues). This issue remains the execution checklist — Phase checkboxes get ticked here as builds ship.