docs: improve documentation quality and add CI checks

[gustavovalverde]

Motivation

Improve documentation quality across the Zebra codebase by adding automated checks and fixing existing issues. This ensures consistent, well-formatted, and accurate documentation going forward.

Solution

New CI Workflow (docs-check.yml)

Adds automated documentation quality checks that run on PRs and pushes affecting markdown files:

• Link checking (lychee): Validates all URLs in documentation are accessible
• Spell checking (codespell): Catches common typos and spelling errors
• Markdown linting (markdownlint): Enforces consistent formatting

The workflow follows project conventions:

• Pinned action SHAs with version comments
• Per-job permissions (least privilege)
• Aggregator job pattern (docs-check-success)
• Validated with actionlint and zizmor

Documentation Fixes

Fixed issues across ~100 files:

• MD040: Added language specifiers to fenced code blocks
• MD059: Replaced bare URLs with descriptive link text
• Spelling corrections for domain-specific terminology
• Updated outdated references and links

New Documentation

• ARCHITECTURE.md: High-level codebase overview
• book/src/dev/onboarding.md: Developer onboarding guide
• book/src/dev/crates.md: Crate architecture documentation
• book/src/user/ecosystem-integration.md: Integration guide for wallets/exchanges
• ADRs for Tower service architecture, three-level verification, and RocksDB storage

Configuration Files

• .lychee.toml: Link checker configuration with exclusion patterns
• .codespellrc: Updated with Zcash-specific terminology
• .gitignore: Added .lycheecache exclusion

URLs Excluded in Lychee (Require Review)

The following URL patterns are excluded and should be reviewed for potential fixes:

Pattern	Reason	Action Needed
zips.z.cash/protocol/*.pdf	Returns 404 but linked from official Zcash site	Check with Zcash team
doc.zebra.zfnd.org, doc-internal.zebra.zfnd.org	Deprecated documentation sites	Remove references or update URLs
github.com/zcash/zips/blob/master/	Pending master → main migration	Update when zcash/zips migrates
zebra.zfnd.org/dev/crates.html (and others)	New pages not yet deployed	Will resolve after book deployment
www.zfnd.org/blog/futures-batch-verification/	Blog post removed/reorganized	Find new URL or remove reference
github.com/nginxinc/docker-nginx/issues/490	Issue deleted or made private	Remove or update reference

Tests

• Ran codespell --config .codespellrc locally - passes
• Ran markdownlint "**/*.md" --config .trunk/configs/.markdownlint.yaml locally - passes
• Ran lychee --config .lychee.toml "**/*.md" locally - passes with exclusions
• Validated workflow with actionlint and zizmor - no errors

Specifications & References

• Lychee link checker
• Codespell
• Markdownlint

Follow-up Work

• Review excluded URLs in .lychee.toml and fix where possible
• Update links when zcash/zips completes master → main migration
• New documentation pages will be live after book deployment

PR Checklist

• The PR name is suitable for the release notes.
• The PR follows the contribution guidelines.
• The library crate changelogs are up to date.
• The solution is tested.
• The documentation is up to date.

[daira]

zips.z.cash/protocol/*.pdf — Returns 404 but linked from official Zcash site

It's possible this 404 was during a short time when the protocol spec links were broken. The exclusion should be removed.

[conradoplg]

Mixing formatting changes with content changes and additions makes this PR very difficult to review since those require totally different levels of detail.

Would you mind splitting those up if possible? Thinking about it, I think it's easier to merge this soon and fix things later if needed

There are also conflicts - feel free to ping me when you solve them so I can approve this quickly and avoid more conflicts

[conradoplg]

This is wrong

Suggested change

	# Run on Testnet
	cargo run --release -- --network testnet

[conradoplg]

Thinking about it, I think it's easier to merge this soon and fix things later if needed