docs: improve documentation quality and add CI checks (#10204)

* docs: improve documentation quality and add CI checks

Add automated documentation quality checks and fix existing issues across
the codebase documentation.

Workflow changes:
- Add `docs-check.yml` workflow with link checking (lychee), spell checking
  (codespell), and markdown linting (markdownlint)
- Workflow follows project conventions: pinned action SHAs, per-job
  permissions, aggregator job pattern

Documentation fixes:
- Fix markdown linting issues (MD040 code block language specifiers,
  MD059 descriptive link text)
- Fix spelling errors across documentation files
- Add missing ARCHITECTURE.md for high-level codebase overview
- Add new developer documentation: onboarding guide, crate architecture
- Add ecosystem integration guide for users
- Add architectural decision records (ADRs) for Tower, verification, RocksDB
- Update CI/CD documentation with workflow diagram

Configuration:
- Add `.lychee.toml` for link checker configuration
- Add `.lycheecache` to `.gitignore`
- Update `.codespellrc` with domain-specific terminology

Note: Some URLs are excluded in `.lychee.toml` that require review:
- zips.z.cash PDF links (404 but linked from official Zcash site)
- Deprecated doc sites (doc.zebra.zfnd.org, doc-internal.zebra.zfnd.org)
- zcash/zips master branch links (pending main migration)
- New zebra.zfnd.org pages (pending book deployment)

* fix(ci): add markdownlint config and fix alls-green SHA

- Add .trunk/configs/.markdownlint.yaml to repo (was gitignored)
- Fix re-actors/alls-green SHA: use commit hash, not tag object hash

* fix(ci): disable additional markdownlint rules for existing docs

Disable MD001, MD028, MD036 rules that flag intentional formatting
patterns in existing RFC and book documentation.

* fix(docs): update stale URLs and remove RFC implementation notes

- Fix nginx URL migration (nginxinc -> nginx organization)
- Fix zcash/zips URLs (master -> main, new /zips/ directory structure)
- Fix docs.rs URL (config/struct.Config -> config/rpc/struct.Config)
- Fix internal docs URLs (doc-internal.zebra.zfnd.org -> zebra.zfnd.org/internal)
- Fix zfnd.org blog URLs (removed /blog/ path segment)
- Remove Implementation Notes from RFCs (RFCs should be static historical records)
- Clean up lychee.toml exclusions for now-working URLs
- Add CHANGELOG.md to exclude_path (contains historical dead links)

* fix(docs): resolve markdownlint errors in observability docs and CHANGELOGs

- Add language specifier to fenced code blocks (MD040)
- Add blank lines around lists (MD032)
- Add blank lines around fenced code blocks (MD031)
- Remove multiple consecutive blank lines (MD012)

Author: gustavovalverde

.codespellrc

@@ -1,4 +1,4 @@
 [codespell]
-ignore-words-list = crate,Sur,inout,Groth,groth,re-use,abl,
+ignore-words-list = crate,Sur,inout,Groth,groth,re-use,abl,zcash,zcashd,zebrad,zebra,utxo,utxos,nullifier,nullifiers,sapling,orchard,sprout,backpressure,proptest,thiserror,rocksdb,libsecp,fullnode,peerset,threadsafe,unrepresentable,getblocktemplate,syncer,Actix,Akka,mermaid,println,eprintln,usize,nocapture,Parallelizable,invis,UTXO,Zcash,Zaino,Zallet,librustzcash,Mainnet,Testnet,mainnet,testnet,idents,reentrancy,serializable,deserializable,deserialization,zkSNARK,zkSNARKs,lightwalletd,statics,ser,endianity,aranges
 exclude-file = book/mermaid.min.js
-skip = ./zebra-rpc/qa/rpc-tests,./supply-chain
+skip = ./zebra-rpc/qa/rpc-tests,./supply-chain,./target

.github/ISSUE_TEMPLATE/release.md

@@ -1,10 +1,9 @@
 ---
 name: "🚀 Zebra Release"
-about: 'Zebra team use only'
-title: 'Publish next Zebra release: (version)'
-labels: 'A-release, C-exclude-from-changelog, P-Medium :zap:'
-assignees: ''
-
+about: "Zebra team use only"
+title: "Publish next Zebra release: (version)"
+labels: "A-release, C-exclude-from-changelog, P-Medium :zap:"
+assignees: ""
 ---
 
 # Prepare for the Release
@@ -19,14 +18,16 @@ To check consensus correctness, we want to test that the state format is valid a
 - [ ] Make sure there has been [at least one successful full sync test](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-tests.yml?query=event%3Aschedule) since the last state change, or
 - [ ] Start a manual workflow run with a Zebra and `lightwalletd` full sync.
 
-State format changes can be made in `zebra-state` or `zebra-chain`. The state format can be changed by data that is sent to the state, data created within the state using `zebra-chain`, or serialization formats in `zebra-state` or `zebra-chain`. 
+State format changes can be made in `zebra-state` or `zebra-chain`. The state format can be changed by data that is sent to the state, data created within the state using `zebra-chain`, or serialization formats in `zebra-state` or `zebra-chain`.
 
 After the test has been started, or if it has finished already:
+
 - [ ] Ask for a state code freeze in Slack. The freeze lasts until the release has been published.
 
 ## Checkpoints
 
 For performance and security, we want to update the Zebra checkpoints in every release.
+
 - [ ] You can copy the latest checkpoints from CI by following [the zebra-checkpoints README](https://github.com/ZcashFoundation/zebra/blob/main/zebra-utils/README.md#zebra-checkpoints).
 
 ## Missed Dependency Updates
@@ -36,6 +37,7 @@ Sometimes `dependabot` misses some dependency updates, or we accidentally turned
 This step can be skipped if there is a large pending dependency upgrade. (For example, shared ECC crates.)
 
 Here's how we make sure we got everything:
+
 - [ ] Run `cargo update` on the latest `main` branch, and keep the output
 - [ ] If needed, [add duplicate dependency exceptions to deny.toml](https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/continuous-integration.md#fixing-duplicate-dependencies-in-check-denytoml-bans)
 - [ ] If needed, remove resolved duplicate dependencies from `deny.toml`
@@ -47,12 +49,14 @@ Here's how we make sure we got everything:
 Follow the steps in the [release checklist](https://github.com/ZcashFoundation/zebra/blob/main/.github/PULL_REQUEST_TEMPLATE/release-checklist.md) to prepare the release:
 
 Release PR:
+
 - [ ] Update Changelog
 - [ ] Update README
 - [ ] Update Zebra Versions
 - [ ] Update End of Support Height
 
 Publish Release:
+
 - [ ] Create & Test GitHub Pre-Release
 - [ ] Publish GitHub Release
 - [ ] Publish Rust Crates

.github/ISSUE_TEMPLATE/usability_testing_plan.md

@@ -1,10 +1,9 @@
 ---
 name: "📋 Usability Testing Plan"
 about: Create a Usability Testing Plan
-title: 'Usability Testing Plan'
+title: "Usability Testing Plan"
 labels: C-research
-assignees: ''
-
+assignees: ""
 ---
 
 # Usability Testing Plan
@@ -53,7 +52,6 @@ assignees: ''
 
 <!-- What needs to happen for the participant to successfully complete the task -->
 
-
 ## Session Outline and timing
 
 <!-- The following sections provide some space to plan out the script and tasks for your participants -->
@@ -81,4 +79,3 @@ assignees: ''
 ## Required documentation
 
 <!-- List the documents you will need to produce and bring to the usability testing sessions, e.g consent forms, usability testing script, questionnaires, etc... -->
-

.github/PULL_REQUEST_TEMPLATE/hotfix-release-checklist.md

@@ -1,10 +1,9 @@
 ---
-name: 'Hotfix Release Checklist Template'
-about: 'Checklist to create and publish a hotfix Zebra release'
-title: 'Release Zebra (version)'
-labels: 'A-release, C-exclude-from-changelog, P-Critical :ambulance:'
-assignees: ''
-
+name: "Hotfix Release Checklist Template"
+about: "Checklist to create and publish a hotfix Zebra release"
+title: "Release Zebra (version)"
+labels: "A-release, C-exclude-from-changelog, P-Critical :ambulance:"
+assignees: ""
 ---
 
 A hotfix release should only be created when a bug or critical issue is discovered in an existing release, and waiting for the next scheduled release is impractical or unacceptable.
@@ -55,7 +54,7 @@ follow semver, depending on the thing being fixed.
 ## Test the Pre-Release (if Zebra hotfix)
 
 - [ ] Wait until the Docker binaries have been built on the hotfix release branch, and the quick tests have passed:
-    - [ ] [ci-tests.yml](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-tests.yml)
+  - [ ] [ci-tests.yml](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-tests.yml)
 - [ ] Wait until the [pre-release deployment machines have successfully launched](https://github.com/ZcashFoundation/zebra/actions/workflows/zfnd-deploy-nodes-gcp.yml?query=event%3Arelease)
 
 ## Publish Release (if Zebra hotfix)

.github/PULL_REQUEST_TEMPLATE/release-checklist.md

@@ -1,10 +1,9 @@
 ---
-name: 'Release Checklist Template'
-about: 'Checklist to create and publish a Zebra release'
-title: 'Release Zebra (version)'
-labels: 'A-release, C-exclude-from-changelog, P-Critical :ambulance:'
-assignees: ''
-
+name: "Release Checklist Template"
+about: "Checklist to create and publish a Zebra release"
+title: "Release Zebra (version)"
+labels: "A-release, C-exclude-from-changelog, P-Critical :ambulance:"
+assignees: ""
 ---
 
 # Prepare for the Release
@@ -14,6 +13,7 @@ assignees: ''
 # Checkpoints
 
 For performance and security, we want to update the Zebra checkpoints in every release.
+
 - [ ] You can copy the latest checkpoints from CI by following [the zebra-checkpoints README](https://github.com/ZcashFoundation/zebra/blob/main/zebra-utils/README.md#zebra-checkpoints).
 
 # Missed Dependency Updates
@@ -23,6 +23,7 @@ Sometimes `dependabot` misses some dependency updates, or we accidentally turned
 This step can be skipped if there is a large pending dependency upgrade. (For example, shared ECC crates.)
 
 Here's how we make sure we got everything:
+
 - [ ] Run `cargo update` on the latest `main` branch, and keep the output
 - [ ] If needed, [add duplicate dependency exceptions to deny.toml](https://github.com/ZcashFoundation/zebra/blob/main/book/src/dev/continuous-integration.md#fixing-duplicate-dependencies-in-check-denytoml-bans)
 - [ ] If needed, remove resolved duplicate dependencies from `deny.toml`
@@ -41,11 +42,12 @@ Once you are ready to tag a release, copy the draft changelog into `CHANGELOG.md
 We use [the Release Drafter workflow](https://github.com/marketplace/actions/release-drafter) to automatically create a [draft changelog](https://github.com/ZcashFoundation/zebra/releases). We follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
 To create the final change log:
+
 - [ ] Copy the [**latest** draft
-  changelog](https://github.com/ZcashFoundation/zebra/releases) into
-  `CHANGELOG.md` (there can be multiple draft releases)
+      changelog](https://github.com/ZcashFoundation/zebra/releases) into
+      `CHANGELOG.md` (there can be multiple draft releases)
 - [ ] Delete any trivial changes
-    - [ ] Put the list of deleted changelog entries in a PR comment to make reviewing easier
+  - [ ] Put the list of deleted changelog entries in a PR comment to make reviewing easier
 - [ ] Combine duplicate changes
 - [ ] Edit change descriptions so they will make sense to Zebra users
 - [ ] Check the category for each change
@@ -56,12 +58,14 @@ To create the final change log:
 README updates can be skipped for urgent releases.
 
 Update the README to:
+
 - [ ] Remove any "Known Issues" that have been fixed since the last release.
 - [ ] Update the "Build and Run Instructions" with any new dependencies.
       Check for changes in the `Dockerfile` since the last tag: `git diff <previous-release-tag> docker/Dockerfile`.
 - [ ] If Zebra has started using newer Rust language features or standard library APIs, update the known working Rust version in the README, book, and `Cargo.toml`s
 
 You can use a command like:
+
 ```sh
 fastmod --fixed-strings '1.58' '1.65'
 ```
@@ -88,20 +92,11 @@ This check runs automatically on pull requests with the `A-release` label. It mu
 
 Zebra follows [semantic versioning](https://semver.org). Semantic versions look like: MAJOR.MINOR.PATCH[-TAG.PRE-RELEASE]
 
-Choose a release level for `zebrad`. Release levels are based on user-visible changes:
+Choose a release level for `zebrad`. Release levels are based on user-visible changes from the changelog:
 
-- Major release: breaking changes to RPCs (fields changed or removed), config files (fields
-  changed or removed), command line (arguments changed or removed), features
-  (features changed or removed), environment variables (changed or removed)
-  or any other external interface of Zebra
-- Minor release: new features are `minor` releases
-- Patch release: otherwise
-
-Update the version using:
-
-```
-cargo release version --verbose --execute --allow-branch '*' -p zebrad patch # [ major | minor ]
-```
+- Mainnet Network Upgrades are `major` releases
+- significant new features or behaviour changes; changes to RPCs, command-line, or configs; and deprecations or removals are `minor` releases
+- otherwise, it is a `patch` release
 
 ## Update Crate Versions and Crate Change Logs
 
@@ -144,6 +139,7 @@ cargo release replace --verbose --execute --allow-branch '*' -p <crate>
 
 The end of support height is calculated from the current blockchain height:
 
+- [ ] Find where the Zcash blockchain tip is now by using a [Zcash Block Explorer](https://mainnet.zcashexplorer.app/) or other tool.
 - [ ] Replace `ESTIMATED_RELEASE_HEIGHT` in [`end_of_support.rs`](https://github.com/ZcashFoundation/zebra/blob/main/zebrad/src/components/sync/end_of_support.rs) with the height you estimate the release will be tagged.
 
 <details>
@@ -160,7 +156,6 @@ The end of support height is calculated from the current blockchain height:
 
 - [ ] Push the version increments and the release constants to the release branch.
 
-
 # Publish the Zebra Release
 
 ## Create the GitHub Pre-Release
@@ -182,7 +177,7 @@ The end of support height is calculated from the current blockchain height:
 ## Test the Pre-Release
 
 - [ ] Wait until the Docker binaries have been built on `main`, and the quick tests have passed:
-    - [ ] [zfnd-ci-integration-tests-gcp.yml](https://github.com/ZcashFoundation/zebra/actions/workflows/zfnd-ci-integration-tests-gcp.yml?query=branch%3Amain)
+  - [ ] [zfnd-ci-integration-tests-gcp.yml](https://github.com/ZcashFoundation/zebra/actions/workflows/zfnd-ci-integration-tests-gcp.yml?query=branch%3Amain)
 - [ ] Wait until the [pre-release deployment machines have successfully launched](https://github.com/ZcashFoundation/zebra/actions/workflows/zfnd-deploy-nodes-gcp.yml?query=event%3Arelease)
 
 ## Publish Release

.github/workflows/README.md

@@ -73,7 +73,7 @@ graph TB
   class PR,Push,Schedule,Manual trigger
 ```
 
-*The diagram above illustrates the parallel execution patterns in our CI/CD system. All triggers can initiate the pipeline concurrently, unit tests run in parallel after the Docker image build, and integration tests follow a mix of parallel and sequential steps. The infrastructure components support their respective workflow parts concurrently.*
+_The diagram above illustrates the parallel execution patterns in our CI/CD system. All triggers can initiate the pipeline concurrently, unit tests run in parallel after the Docker image build, and integration tests follow a mix of parallel and sequential steps. The infrastructure components support their respective workflow parts concurrently._
 
 ## Core Infrastructure
 
@@ -93,8 +93,8 @@ graph TB
 
 #### Docker-based Testing
 
-- Most tests run in containers defined by our [Dockerfile](http://../../docker/Dockerfile)
-- The [entrypoint script](http://../../docker/entrypoint.sh) manages:
+- Most tests run in containers defined by our [Dockerfile](../../docker/Dockerfile)
+- The [entrypoint script](../../docker/entrypoint.sh) manages:
   - Test execution
   - Environment configuration
   - Resource cleanup
@@ -130,12 +130,12 @@ graph TB
 
 ### 5. Queue Management
 
-[Mergify](https://mergify.yml)
+[Mergify](https://mergify.com)
 
 - Automated PR merging and queue-based testing
 - Priority management
 - Ensures code quality before merge
-- See our [`.mergify.yml`](http://../../.mergify.yml) for configuration
+- See our [`.mergify.yml`](../../.mergify.yml) for configuration
 
 ## Workflow Organization
 
@@ -165,7 +165,7 @@ graph TB
 
 ### Test Orchestration with Nextest
 
-Our test execution is centralized through our Docker [entrypoint script](http://../../docker/entrypoint.sh) and orchestrated by `cargo nextest`. This provides a unified and efficient way to run tests both in CI and locally.
+Our test execution is centralized through our Docker [entrypoint script](../../docker/entrypoint.sh) and orchestrated by `cargo nextest`. This provides a unified and efficient way to run tests both in CI and locally.
 
 #### Nextest Profile-driven Testing
 
@@ -191,7 +191,6 @@ Our tests are organized into different categories:
 
 Each test category has specific profiles that can be run individually using the `NEXTEST_PROFILE` environment variable.
 
-
 ### Pull Request Testing
 
 #### Continuous Validation