docs(registry): write MkDocs API documentation with examples for Package Registry Client (Epic #22) #51

New issue

Closed

opened 2026-06-12 22:00:59 +00:00 by CoreRasurae · 1 comment

CoreRasurae commented

2026-06-12 22:00:59 +00:00

Member

Metadata

Commit Message: docs(registry): add MkDocs API documentation and usage examples for Package Registry Client
Branch: feature/m1-registry-docs

Background and context

Epic #22 delivered a complete Package Registry Standard v1.0.0 client across 8 feature tickets (#23–#30). The implementation spans src/cleveractors/registry/ with 6 modules (types, client, canonical, resolver, exceptions, cache), plus template system alignment. Currently there is no user-facing API documentation for any of these modules — users must read source code or issue bodies to understand usage.

We need navigable, well-structured MkDocs-formatted documentation under docs/ covering every public API surface from the registry subsystem, illustrated with real-life constructive examples that demonstrate both individual API calls and multi-step integration workflows.

Part of Epic: Package Registry Client — Support Package Registry Standard v1.0.0 (#22)

Expected behavior

Documentation structure (`docs/registry/`)

docs/
└── registry/
    ├── index.md                      # Overview, architecture, quickstart
    ├── types.md                      # PackageType, PackageId, PackageReference, PackageContent
    ├── client.md                     # RegistryClient — all 4 endpoints + auth + error mapping
    ├── canonical.md                   # Canonicalizer — NFC, RFC-8785, SHA-1
    ├── resolver.md                    # ReferenceResolver — 3 schemes, version aliases
    ├── exceptions.md                  # RegistryError hierarchy — all 8 types
    ├── cache.md                       # RegistryCache — LRU, TTL, tamper detection
    └── integration.md                 # End-to-end workflow examples (multi-module)

Each page must:

Document all public classes, methods, and attributes with type signatures
Include at least one real-life constructive example per page
Cross-link to related modules (e.g. client.md links to exceptions.md for error types)
Follow MkDocs material theme conventions (admonitions, code blocks with language annotation, tables)

Example quality requirements

All code examples must be real-life constructive examples — not trivial one-liners but meaningful scenarios drawn from actual use cases. Examples should demonstrate:

Individual API call usage: each major method shown with realistic arguments
Multi-step workflows: end-to-end scenarios combining multiple modules (e.g. parse reference → resolve → fetch → cache → instantiate)
Error handling: examples that show catching and handling specific exception types
Async patterns: all RegistryClient examples must use async/await

Example use cases to illustrate:

Electronic component ordering pipeline: register a supplier agent that uses registry.example.com:acme/order-validator@v1.0.0 to validate part numbers in purchase orders
Email categorization system: resolve a categorization template from registry, fetch tool packages for domain-specific agents, cache for repeated use
Multi-tenant SaaS provisioning: resolve agent templates per-tenant namespace, validate content integrity via SHA-1, detect tampered cache entries
CI/CD pipeline actor verification: canonicalize an actor config, compare hashes across environments, detect drift

Acceptance criteria

Documentation completeness

docs/registry/index.md exists with architecture overview, module map, and quickstart
docs/registry/types.md documents PackageType enum, PackageId, PackageReference, PackageContent with all fields and immutability guarantees
docs/registry/client.md documents RegistryClient with all 4 endpoints, auth modes, error mapping, async patterns
docs/registry/canonical.md documents Canonicalizer with NFC, RFC-8785, SHA-1 pipeline, lifecycle field stripping
docs/registry/resolver.md documents ReferenceResolver with all 3 schemes (registry:, ID:, local:) and version alias resolution
docs/registry/exceptions.md documents the full RegistryError hierarchy (8 typed exceptions) with HTTP status code mapping
docs/registry/cache.md documents RegistryCache with LRU eviction, TTL, tamper detection, statistics API
docs/registry/integration.md contains 3+ end-to-end workflows combining multiple modules

Example coverage

Every docs/registry/*.md page (except index) includes at least 1 real-life constructive example
integration.md includes 3+ multi-step examples (electronic ordering, email categorization, CI/CD verification)
All examples use async/await where RegistryClient is involved
Examples show proper error handling with typed exceptions
Examples are self-contained and copy-paste-runnable (aside from registry server URL)

mkdocs.yml updated with docs/registry/ in the nav tree
All pages cross-link to related modules
nox -s docs builds without errors

Quality gates

Verify docs build cleanly: nox -s docs
Verify coverage >= 97%: nox -s coverage_report
Run nox (all default sessions), fix any errors

Subtasks

Create docs/registry/index.md — overview, architecture, module map, quickstart
Create docs/registry/types.md — PackageType, PackageId, PackageReference, PackageContent + examples
Create docs/registry/client.md — RegistryClient endpoints, auth, error mapping, async patterns + examples
Create docs/registry/canonical.md — Canonicalizer pipeline, NFC, RFC-8785, SHA-1 + examples
Create docs/registry/resolver.md — ReferenceResolver, 3 schemes, version aliases + examples
Create docs/registry/exceptions.md — RegistryError hierarchy, HTTP mapping, 8 typed errors + examples
Create docs/registry/cache.md — RegistryCache LRU, TTL, tamper detection, statistics + examples
Create docs/registry/integration.md — 3+ end-to-end workflow examples
Update mkdocs.yml nav tree with docs/registry/ entries
Verify nox -s docs builds without errors
Verify nox -s coverage_report >= 97%
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in Metadata exactly.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The commit is submitted as a PR to master, reviewed, and merged.

## Metadata Commit Message: docs(registry): add MkDocs API documentation and usage examples for Package Registry Client Branch: feature/m1-registry-docs ## Background and context Epic #22 delivered a complete Package Registry Standard v1.0.0 client across 8 feature tickets (#23–#30). The implementation spans `src/cleveractors/registry/` with 6 modules (types, client, canonical, resolver, exceptions, cache), plus template system alignment. Currently there is no user-facing API documentation for any of these modules — users must read source code or issue bodies to understand usage. We need navigable, well-structured MkDocs-formatted documentation under `docs/` covering every public API surface from the registry subsystem, illustrated with real-life constructive examples that demonstrate both individual API calls and multi-step integration workflows. Part of Epic: Package Registry Client — Support Package Registry Standard v1.0.0 (#22) ## Expected behavior ### Documentation structure (`docs/registry/`) ``` docs/ └── registry/ ├── index.md # Overview, architecture, quickstart ├── types.md # PackageType, PackageId, PackageReference, PackageContent ├── client.md # RegistryClient — all 4 endpoints + auth + error mapping ├── canonical.md # Canonicalizer — NFC, RFC-8785, SHA-1 ├── resolver.md # ReferenceResolver — 3 schemes, version aliases ├── exceptions.md # RegistryError hierarchy — all 8 types ├── cache.md # RegistryCache — LRU, TTL, tamper detection └── integration.md # End-to-end workflow examples (multi-module) ``` Each page must: - Document all public classes, methods, and attributes with type signatures - Include at least one real-life constructive example per page - Cross-link to related modules (e.g. `client.md` links to `exceptions.md` for error types) - Follow MkDocs material theme conventions (admonitions, code blocks with language annotation, tables) ### Example quality requirements All code examples must be **real-life constructive examples** — not trivial one-liners but meaningful scenarios drawn from actual use cases. Examples should demonstrate: - **Individual API call usage**: each major method shown with realistic arguments - **Multi-step workflows**: end-to-end scenarios combining multiple modules (e.g. parse reference → resolve → fetch → cache → instantiate) - **Error handling**: examples that show catching and handling specific exception types - **Async patterns**: all RegistryClient examples must use `async`/`await` Example use cases to illustrate: 1. **Electronic component ordering pipeline**: register a supplier agent that uses `registry.example.com:acme/order-validator@v1.0.0` to validate part numbers in purchase orders 2. **Email categorization system**: resolve a categorization template from registry, fetch tool packages for domain-specific agents, cache for repeated use 3. **Multi-tenant SaaS provisioning**: resolve agent templates per-tenant namespace, validate content integrity via SHA-1, detect tampered cache entries 4. **CI/CD pipeline actor verification**: canonicalize an actor config, compare hashes across environments, detect drift ## Acceptance criteria ### Documentation completeness - [ ] `docs/registry/index.md` exists with architecture overview, module map, and quickstart - [ ] `docs/registry/types.md` documents PackageType enum, PackageId, PackageReference, PackageContent with all fields and immutability guarantees - [ ] `docs/registry/client.md` documents RegistryClient with all 4 endpoints, auth modes, error mapping, async patterns - [ ] `docs/registry/canonical.md` documents Canonicalizer with NFC, RFC-8785, SHA-1 pipeline, lifecycle field stripping - [ ] `docs/registry/resolver.md` documents ReferenceResolver with all 3 schemes (`registry:`, `ID:`, `local:`) and version alias resolution - [ ] `docs/registry/exceptions.md` documents the full RegistryError hierarchy (8 typed exceptions) with HTTP status code mapping - [ ] `docs/registry/cache.md` documents RegistryCache with LRU eviction, TTL, tamper detection, statistics API - [ ] `docs/registry/integration.md` contains 3+ end-to-end workflows combining multiple modules ### Example coverage - [ ] Every `docs/registry/*.md` page (except index) includes at least 1 real-life constructive example - [ ] `integration.md` includes 3+ multi-step examples (electronic ordering, email categorization, CI/CD verification) - [ ] All examples use `async`/`await` where RegistryClient is involved - [ ] Examples show proper error handling with typed exceptions - [ ] Examples are self-contained and copy-paste-runnable (aside from registry server URL) ### Navigation and structure - [ ] `mkdocs.yml` updated with `docs/registry/` in the nav tree - [ ] All pages cross-link to related modules - [ ] `nox -s docs` builds without errors ### Quality gates - [ ] Verify docs build cleanly: `nox -s docs` - [ ] Verify coverage >= 97%: `nox -s coverage_report` - [ ] Run nox (all default sessions), fix any errors ## Subtasks - [ ] Create `docs/registry/index.md` — overview, architecture, module map, quickstart - [ ] Create `docs/registry/types.md` — PackageType, PackageId, PackageReference, PackageContent + examples - [ ] Create `docs/registry/client.md` — RegistryClient endpoints, auth, error mapping, async patterns + examples - [ ] Create `docs/registry/canonical.md` — Canonicalizer pipeline, NFC, RFC-8785, SHA-1 + examples - [ ] Create `docs/registry/resolver.md` — ReferenceResolver, 3 schemes, version aliases + examples - [ ] Create `docs/registry/exceptions.md` — RegistryError hierarchy, HTTP mapping, 8 typed errors + examples - [ ] Create `docs/registry/cache.md` — RegistryCache LRU, TTL, tamper detection, statistics + examples - [ ] Create `docs/registry/integration.md` — 3+ end-to-end workflow examples - [ ] Update `mkdocs.yml` nav tree with `docs/registry/` entries - [ ] Verify `nox -s docs` builds without errors - [ ] Verify `nox -s coverage_report` >= 97% - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The commit is submitted as a PR to master, reviewed, and merged.

CoreRasurae added this to the v2.1.0 milestone

2026-06-12 22:00:59 +00:00

CoreRasurae added the

labels

2026-06-12 22:00:59 +00:00

CoreRasurae commented