docs: complete remaining public guide pages

| `architecture/DOCUMENTATION_EVOLUTION_PLAN.md` | Historical evolution snapshot. |

| `architecture/DX_PLATFORM_VISION.md` | Broader platform vision, useful for long-term planning. |

| `architecture/parity/*` | Maintainer architecture/reference, not primary user learning path. |

| `CLIENT_CONTRACT.md` | Maintainer contract reference; possibly summarized in Maintain section. |

| `CLIENT_CONTRACT.md` | Maintainer contract reference; not surfaced in public SDK navigation. |

| `EXPERIMENTAL_CLIENT.md` | Maintainer/migration reference; user docs should mention only supported usage and link if needed. |

| `MIGRATION_MATRIX.md` | Maintainer migration/reference; not first-run docs. |

| `MIGRATION_STATUS.md` | Maintainer migration/reference; not first-run docs. |

  under `public/api/`;

- `.gitlab-ci.yml` adds a `docs:check` validation job and a default-branch

  `pages` deployment job using `public/` as the Pages artifact;

- `site/maintain/workflows.md` records maintainer validation, CI, Pages and

  TypeDoc-warning-baseline workflows.

- public `site/` navigation is SDK-user focused; maintainer validation, CI, Pages and generated-artifact ownership remain in `guide/maintainer-workflows.md` and architecture files rather than public SDK navigation.

Deliverables:

Priority order:

1. Replace the remaining lower-priority public placeholders when they become user-facing priorities: `site/guides/publish-content.md`, `site/guides/social-actions.md`, `site/guides/read-models.md`, `site/guides/handle-errors.md` and `site/learn/assets-operations-transactions.md`.

2. Replace maintainer-section placeholders with short pointer pages to the canonical root architecture files, rather than duplicating those files.

3. Decide whether `guide/README.md` should become a package-included legacy guide index or be explicitly marked as migration/source material after the public site is complete.

4. Add package README public-link validation if broken external README links become a recurring release risk.

5. Continue TypeDoc/JSDoc remediation, but do not duplicate API signatures in VitePress to compensate for weak JSDoc.

6. Consider grouping historical root migration documents later only if maintainers find the root noisy; do not move them just for tidiness.

1. Decide whether `guide/README.md` should become a package-included legacy guide index or be explicitly marked as migration/source material after the public site is complete.

2. Add package README public-link validation if broken external README links become a recurring release risk.

3. Continue TypeDoc/JSDoc remediation, but do not duplicate API signatures in VitePress to compensate for weak JSDoc.

4. Consider grouping historical root migration documents later only if maintainers find the root noisy; do not move them just for tidiness.

### Stable-document transition

- Create authority/key guide.

- Establish blockchain queries vs broadcast operations workflow page.

- Replace the highest-traffic guide placeholders with production task pages for chain data, Nexus social data, broadcast safety, runtime/browser, RPC failover and TypeScript.

- Replace remaining public placeholders with production pages for assets/operations/transactions, publish content, social actions, read models and error handling.

- Document blockchain parsing as a first-class SDK workflow through `client.blockchain` block/operation iterators and streams.

- Create concept-first API surface chooser.

- Start splitting the blockchain model into digestible concept pages through `site/learn/blurt-mental-model.md`.

Remaining:

- Replace remaining lower-priority planned VitePress guide placeholders where the current pages are still migration shells: publish content, social actions, read models, error handling and assets/operations/transactions.

- Write “For Hive/Steem developers” orientation.

- Continue splitting blockchain model into focused concept pages where useful.

- Expand error handling, operation builder philosophy, read models and deprecation/compatibility guidance where the current pages are still thin or placeholder-backed.

- Expand deprecation/compatibility guidance where future reviews show current pages are too thin.

### TypeDoc backlog

Resolved so far:

1. **VitePress source root:** `site/` is the target VitePress source root. `guide/` remains the migration source until pages are migrated or retired.

2. **Architecture document visibility:** architecture documents may be surfaced through the VitePress Maintain section, but they are not part of the first-time developer journey. Root migration/parity documents stay where they are until a later maturity cleanup.

2. **Architecture document visibility:** architecture and migration references are maintainer-scoped and stay in root `architecture/`, `guide/maintainer-workflows.md` and repository workflow files rather than the public SDK documentation navigation.

3. **Hive/Steem audience strength:** Hive/Steem developers are a secondary but explicit audience. They need orientation and comparison, but the primary learning path remains Blurt/dblurt-first and blockchain query-first.

4. **Minimum quality bar for future public API additions:** new public API docs must identify the canonical owner, include TypeDoc/JSDoc for exact signatures, add or update concept/task docs when the feature changes developer mental models, and include executable/compilable examples when the feature introduces a new workflow.

5. **TypeDoc integration mode:** TypeDoc remains a separate generated HTML reference for now. VitePress links to a future `/api/` mount point and does not embed TypeDoc Markdown during this phase.

### ADR-DOC-007 — Architecture and migration references stay maintainer-scoped

Decision: current architecture documents may be linked from the VitePress Maintain section. Root migration/parity documents remain at their current paths for now and should not be surfaced in first-time user navigation.

Decision: architecture, inventory, release and documentation-product process pages do not provide clear value to normal SDK users, so the public VitePress Maintain section was removed. Root migration/parity documents remain at their current paths for maintainer use and should not be surfaced in first-time user navigation.

Status: accepted after Phase 1/3 validation; relocation deferred to maturity cleanup.

Status: superseded by the public Maintain-section removal after maturity review.

---

| Install or make the first safe call | [guide](https://dblurt.beblurt.com/start/getting-started.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html) | Start with `Client` and a safe blockchain query. |

| Choose the right helper namespace | [guide](https://dblurt.beblurt.com/start/choose-your-path.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html) | Route by task before naming methods. |

| Read accounts, blocks, witnesses or chain properties | [guide](https://dblurt.beblurt.com/guides/read-chain-data.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html#condenser) | Layer 1 chain reads normally start with `client.condenser`. |

| Parse block ranges or operation history | [guide](https://dblurt.beblurt.com/guides/parse-blockchain-history.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Blockchain.html) | Use `client.blockchain` iterators and streams with explicit checkpoints. |

| Build social feeds, posts, communities or notifications | [guide](https://dblurt.beblurt.com/guides/use-nexus-social-data.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Nexus.html) | Nexus is indexed/social Layer 2 data, not consensus truth. |

| Build post, reply, follow, reblog or community operations | [guide](https://dblurt.beblurt.com/guides/publish-content.html) | [reference](https://dblurt.beblurt.com/api/functions/index.buildPostOperation.html) | Builders create operations; broadcasting is a separate safety decision. |

| Sign or broadcast a transaction | [guide](https://dblurt.beblurt.com/guides/broadcast-safely.html) | [reference](https://dblurt.beblurt.com/api/classes/index.Client.html#broadcast) | Read authority and key guidance first. |

- [`client.condenser`](https://dblurt.beblurt.com/api/classes/index.Client.html#condenser): Common Layer 1 reads such as accounts, content, witnesses and chain properties.

- [`client.database`](https://dblurt.beblurt.com/api/classes/index.Client.html#database): Appbase database API calls.

- [`client.blockchain`](https://dblurt.beblurt.com/api/classes/index.Client.html#blockchain): Block ranges, block streams and operation iteration.

- [`Blockchain`](https://dblurt.beblurt.com/api/classes/index.Blockchain.html): Layer 1 block and operation parsing helpers.

- [`Nexus` / `client.nexus`](https://dblurt.beblurt.com/api/classes/index.Nexus.html): Nexus indexed/social views for posts, communities, profiles and notifications.

- [`ReadModels` / `client.read`](https://dblurt.beblurt.com/api/classes/index.ReadModels.html): Higher-level account, witness, vote and social summaries.

- [`buildPostOperation`](https://dblurt.beblurt.com/api/functions/index.buildPostOperation.html): Construct a post operation without signing or broadcasting.

- [Read chain data](https://dblurt.beblurt.com/guides/read-chain-data.html): Use Layer 1 helpers for accounts, blocks, witnesses and chain properties.

- [Use Nexus social data](https://dblurt.beblurt.com/guides/use-nexus-social-data.html): Build social/community views using indexed data.

- [Parse blockchain history](https://dblurt.beblurt.com/guides/parse-blockchain-history.html): Iterate block ranges, full blocks and operation streams.

- [Publish content](https://dblurt.beblurt.com/guides/publish-content.html): Build content operations before deciding how to broadcast them.

- [Social actions](https://dblurt.beblurt.com/guides/social-actions.html): Build follow, mute, reblog and community action operations.

- [Broadcast safely](https://dblurt.beblurt.com/guides/broadcast-safely.html): Sign and broadcast with explicit key and side-effect boundaries.

- [Recipes index](https://dblurt.beblurt.com/recipes/): Task-oriented workflows and safety levels.

- [Read account summary](https://dblurt.beblurt.com/recipes/read-account-summary.html): Read account, stake and social summary data.

- [Parse recent blocks](https://dblurt.beblurt.com/recipes/parse-recent-blocks.html): Bounded block parsing with `client.blockchain.getBlocks()`.

- [Build post operation](https://dblurt.beblurt.com/recipes/build-post-operation.html): Construct content operations without broadcasting.

- [Handle retryable errors](https://dblurt.beblurt.com/recipes/handle-retryable-errors.html): Classify timeout, transport and RPC errors.

- [Executable examples catalog](https://gitlab.com/beblurt/dblurt/-/blob/main/examples/README.md): Repository examples with metadata and validation status.

  ['Install or make the first safe call', `${siteUrl}/start/getting-started.html`, `${siteUrl}/api/classes/index.Client.html`, 'Start with `Client` and a safe blockchain query.'],

  ['Choose the right helper namespace', `${siteUrl}/start/choose-your-path.html`, `${siteUrl}/api/classes/index.Client.html`, 'Route by task before naming methods.'],

  ['Read accounts, blocks, witnesses or chain properties', `${siteUrl}/guides/read-chain-data.html`, `${siteUrl}/api/classes/index.Client.html#condenser`, 'Layer 1 chain reads normally start with `client.condenser`.'],

  ['Parse block ranges or operation history', `${siteUrl}/guides/parse-blockchain-history.html`, `${siteUrl}/api/classes/index.Blockchain.html`, 'Use `client.blockchain` iterators and streams with explicit checkpoints.'],

  ['Build social feeds, posts, communities or notifications', `${siteUrl}/guides/use-nexus-social-data.html`, `${siteUrl}/api/classes/index.Nexus.html`, 'Nexus is indexed/social Layer 2 data, not consensus truth.'],

  ['Build post, reply, follow, reblog or community operations', `${siteUrl}/guides/publish-content.html`, `${siteUrl}/api/functions/index.buildPostOperation.html`, 'Builders create operations; broadcasting is a separate safety decision.'],

  ['Sign or broadcast a transaction', `${siteUrl}/guides/broadcast-safely.html`, `${siteUrl}/api/classes/index.Client.html#broadcast`, 'Read authority and key guidance first.'],

  ['`client.condenser`', `${siteUrl}/api/classes/index.Client.html#condenser`, 'Common Layer 1 reads such as accounts, content, witnesses and chain properties.'],

  ['`client.database`', `${siteUrl}/api/classes/index.Client.html#database`, 'Appbase database API calls.'],

  ['`client.blockchain`', `${siteUrl}/api/classes/index.Client.html#blockchain`, 'Block ranges, block streams and operation iteration.'],

  ['`Blockchain`', `${siteUrl}/api/classes/index.Blockchain.html`, 'Layer 1 block and operation parsing helpers.'],

  ['`Nexus` / `client.nexus`', `${siteUrl}/api/classes/index.Nexus.html`, 'Nexus indexed/social views for posts, communities, profiles and notifications.'],

  ['`ReadModels` / `client.read`', `${siteUrl}/api/classes/index.ReadModels.html`, 'Higher-level account, witness, vote and social summaries.'],

  ['`buildPostOperation`', `${siteUrl}/api/functions/index.buildPostOperation.html`, 'Construct a post operation without signing or broadcasting.'],

    entries: [

      ['Read chain data', 'site/guides/read-chain-data.md', `${siteUrl}/guides/read-chain-data.html`, 'Use Layer 1 helpers for accounts, blocks, witnesses and chain properties.'],

      ['Use Nexus social data', 'site/guides/use-nexus-social-data.md', `${siteUrl}/guides/use-nexus-social-data.html`, 'Build social/community views using indexed data.'],

      ['Parse blockchain history', 'site/guides/parse-blockchain-history.md', `${siteUrl}/guides/parse-blockchain-history.html`, 'Iterate block ranges, full blocks and operation streams.'],

      ['Publish content', 'site/guides/publish-content.md', `${siteUrl}/guides/publish-content.html`, 'Build content operations before deciding how to broadcast them.'],

      ['Social actions', 'site/guides/social-actions.md', `${siteUrl}/guides/social-actions.html`, 'Build follow, mute, reblog and community action operations.'],

      ['Broadcast safely', 'site/guides/broadcast-safely.md', `${siteUrl}/guides/broadcast-safely.html`, 'Sign and broadcast with explicit key and side-effect boundaries.'],

    entries: [

      ['Recipes index', 'site/recipes/index.md', `${siteUrl}/recipes/`, 'Task-oriented workflows and safety levels.'],

      ['Read account summary', 'site/recipes/read-account-summary.md', `${siteUrl}/recipes/read-account-summary.html`, 'Read account, stake and social summary data.'],

      ['Parse recent blocks', 'site/recipes/parse-recent-blocks.md', `${siteUrl}/recipes/parse-recent-blocks.html`, 'Bounded block parsing with `client.blockchain.getBlocks()`.'],

      ['Build post operation', 'site/recipes/build-post-operation.md', `${siteUrl}/recipes/build-post-operation.html`, 'Construct content operations without broadcasting.'],

      ['Handle retryable errors', 'site/recipes/handle-retryable-errors.md', `${siteUrl}/recipes/handle-retryable-errors.html`, 'Classify timeout, transport and RPC errors.'],

      ['Executable examples catalog', 'examples/README.md', `${repoUrl}/examples/README.md`, 'Repository examples with metadata and validation status.']

  'site/learn/layer-1-and-nexus.md',

  'site/learn/accounts-and-authorities.md',

  'site/learn/blockchain-queries-vs-broadcast-operations.md',

  'site/learn/assets-operations-transactions.md',

  'site/guides/read-chain-data.md',

  'site/guides/use-nexus-social-data.md',

  'site/guides/parse-blockchain-history.md',

  'site/guides/publish-content.md',

  'site/guides/social-actions.md',

  'site/guides/broadcast-safely.md',

  'site/recipes/read-account-summary.md',

  'site/recipes/list-account-posts.md',

  'site/recipes/estimate-vote-value.md',

  'site/recipes/parse-recent-blocks.md',

  'site/recipes/build-post-operation.md',

  'site/recipes/sign-and-broadcast-vote.md',

  'site/recipes/handle-retryable-errors.md',

      { text: 'Learn', link: '/learn/blurt-mental-model' },

      { text: 'Guides', link: '/guides/read-chain-data' },

      { text: 'Recipes', link: '/recipes/' },

      { text: 'Reference', link: '/reference/api' },

      { text: 'Maintain', link: '/maintain/documentation-product' }

      { text: 'Reference', link: '/reference/api' }

    ],

    sidebar: [

      {

        items: [

          { text: 'Read chain data', link: '/guides/read-chain-data' },

          { text: 'Use Nexus social data', link: '/guides/use-nexus-social-data' },

          { text: 'Parse blockchain history', link: '/guides/parse-blockchain-history' },

          { text: 'Publish content', link: '/guides/publish-content' },

          { text: 'Social actions', link: '/guides/social-actions' },

          { text: 'Broadcast safely', link: '/guides/broadcast-safely' },

          { text: 'Read account summary', link: '/recipes/read-account-summary' },

          { text: 'List account posts', link: '/recipes/list-account-posts' },

          { text: 'Estimate vote value', link: '/recipes/estimate-vote-value' },

          { text: 'Parse recent blocks', link: '/recipes/parse-recent-blocks' },

          { text: 'Build post operation', link: '/recipes/build-post-operation' },

          { text: 'Sign and broadcast vote', link: '/recipes/sign-and-broadcast-vote' },

          { text: 'Handle retryable errors', link: '/recipes/handle-retryable-errors' }

          { text: 'Errors', link: '/reference/errors' },

          { text: 'Package exports', link: '/reference/package-exports' }

        ]

      },

      {

        text: 'Maintain',

        items: [

          { text: 'Documentation product', link: '/maintain/documentation-product' },

          { text: 'Documentation inventory', link: '/maintain/documentation-inventory' },

          { text: 'Maintainer workflows', link: '/maintain/workflows' },

          { text: 'Release process', link: '/maintain/release' },

          { text: 'Architecture', link: '/maintain/architecture' }

        ]

      }

    ],

    socialLinks: [