Documentation review ? 5 September 2026 ? Local working tree
Clearer guidance, checked quick starts, repaired examples
The review corrected source/documentation mismatches in the SDK, reference wallets and SaaS setup guide. Implemented local examples now run successfully. This is a documentation validation report, not a new production-readiness score.
Coverage boundary: 326 Markdown files contain 2,390 inventoried Kotlin blocks, including 206 historical blocks. Three quick-start blocks are synchronized exactly with one executed source example. The other fragments have not all been compiled independently. Nine scenario tasks are placeholders, now explicitly documented. Passing the checks does not certify every snippet or a hosted provider.
Corrections made
| Area | Result |
|---|---|
| First-run experience | One source-backed example now creates real DIDs, issues and verifies a credential, registers its JSON-LD vocabulary locally and closes services. Its imports and output were checked by execution. |
| Versions and commands | Current SDK instructions use Kotlin 2.3.21, JDK 21 and the Gradle 9.5.0 wrapper. Example task paths and missing extension imports were corrected. Current source version is distinguished from artifact availability. |
| Navigation and contracts | Broken relative links were repaired. Guidance now distinguishes result-returning operations from throwing APIs, signature validity from issuer trust, and wallet deployment policy from general provider readiness. |
| Wallet custody and recovery | README now describes IndexedDB non-extractable keys, public localStorage data, credential-only backups and replacement/reissuance after key loss. Passkey and managed custody adapters are experimental and not wired into the wallet UI; native device validation is not claimed. |
| SaaS startup | README reflects Kotlin 2.3.10, local PostgreSQL 15 and selectable billing. The PowerShell helper starts infrastructure; backend and frontend startup requirements are explicit. |
| Runnable example failures | Fixed missing wallet factories, invalid wallet-query casts, a JVM main return type, missing claim contexts and unused KMS configuration. DID demos now use the intended KMS for P-256. Repaired Base and Arbitrum service-provider registration names exposed by Indy discovery. |
| Misleading demonstrations | Replaced the anchoring placeholder with asserted in-memory write/read round trips. Marked unfinished schema, revocation and delegation steps as skipped; clarified local simulations and unverified institutional design goals. |
| Regression protection | Added a documentation checker with six tests, exact source synchronization, maintained relative-link checks and fence/API checks. CI runs the 11 implemented local examples and generated capability-documentation drift checks. |
Validation evidence
| Check | Outcome |
|---|---|
python scripts/check-documentation.py | Passed: 326 files, 3 synchronized examples, zero reported errors. Full block inventory. |
python -m unittest discover -s scripts -p test_check_documentation.py | 6 tests passed: source drift, matching source, missing links, fenced examples, unclosed fences and historical/API scope. |
:distribution:examples:checkDocumentationExamples | 11 implemented local demos passed: documentation quick start, original quick start, Earth Observation, Academic, Professional, Spatial Web, National Education, Indy, did:key, did:jwk and local anchoring. |
| Generated capability docs and PowerShell snippet guard | Both passed; four legacy snippet rules checked. |
| Formatting | Gradle script lint and whitespace diff checks passed. Full examples-module lint failed on extensive source formatting, wildcard and unused-import findings. No blanket lint-clean claim is made. |
| SDK/SaaS source alignment | Reviewed local fingerprint recorded and verified; two fingerprint-checker tests passed. This does not create an immutable coordinated release commit. |
Local logs: docs-examples-passed.log (successful execution and Gradle-script lint), docs-final-validation.log (full module lint findings). Console-label-only clarifications followed the successful execution; no runtime logic changed afterward.
What remains unverified
- All remaining narrative snippets need source extraction, fixtures and compilation before they can be guaranteed copy-paste correct. The inventory identifies their locations; 153 blocks contain a main function, which alone does not establish completeness.
- Placeholder scenario programs do not implement their guides. Professional schema validation and some comprehensive/delegation steps remain unfinished and explicitly labeled.
- External URL availability and Markdown anchor targets are outside the local-link checker. Historical designs and prior reviews are preserved rather than rewritten as current API documentation.
- Hosted Accountly/provider execution, physical passkey/HSM recovery and native device behavior were not validated in this documentation pass.
- Full examples-module lint remains open. Passing demo processes is execution coverage, not exhaustive assertion coverage of each workflow.
Start here
Checked quick start ? Example coverage and commands ? Wallet setup and custody limits ? Previous code review