# Feature Specification: SDK Publish-Ready Documentation

**Feature Branch**: `001-sdk-publish-ready`
**Created**: 2026-01-17
**Status**: Draft
**Input**: Make SDK customer-ready with full documentation, examples, and 10/10 DX for publishing

## User Scenarios & Testing *(mandatory)*

### User Story 1 - First-Time Integration (Priority: P1)

A developer discovers the LastID SDK on crates.io or docs.rs and wants to integrate identity verification into their application. They need to understand what the SDK does, install it, and make their first credential request within 15 minutes.

**Why this priority**: First impressions determine adoption. If developers cannot get started quickly, they will abandon the SDK for alternatives.

**Independent Test**: Can be fully tested by having a developer unfamiliar with the SDK attempt integration using only published documentation and examples.

**Acceptance Scenarios**:

1. **Given** a developer viewing the crate on docs.rs, **When** they read the crate-level documentation, **Then** they understand the SDK's purpose, see a working code example, and know how to proceed.
2. **Given** a developer adding the crate to Cargo.toml, **When** they follow the Quick Start guide, **Then** they can make a credential request within 15 minutes.
3. **Given** a developer reading module documentation, **When** they click any public type or function, **Then** they find complete documentation with examples.

---

### User Story 2 - Policy Selection and Configuration (Priority: P2)

A developer needs to verify specific user attributes (age, email, employment, trust level) and must choose the correct credential policy with appropriate configuration options.

**Why this priority**: Policy selection is the core SDK functionality. Developers must understand which policy to use and how to configure it correctly.

**Independent Test**: Can be tested by verifying that documentation clearly explains each policy type, when to use it, and provides working examples for all 8 credential types.

**Acceptance Scenarios**:

1. **Given** a developer needing age verification, **When** they search the documentation, **Then** they find the AgeProofPolicy with clear explanation of comparison operators and threshold configuration.
2. **Given** a developer implementing employment verification, **When** they read the EmploymentPolicy docs, **Then** they understand which fields are available and how to require specific employment statuses.
3. **Given** a developer unsure which policy to use, **When** they read the policies module documentation, **Then** they find a decision guide explaining when to use each policy type.

---

### User Story 3 - Error Handling and Debugging (Priority: P2)

A developer encounters an error during SDK integration and needs to understand what went wrong, why, and how to fix it.

**Why this priority**: Errors are inevitable during integration. Clear error messages and troubleshooting guidance directly impact developer productivity and SDK adoption.

**Independent Test**: Can be tested by verifying all error variants have descriptive messages, documentation explains common causes, and troubleshooting guides exist for frequent issues.

**Acceptance Scenarios**:

1. **Given** a developer receiving a configuration error, **When** they read the error message, **Then** they understand the specific problem and how to resolve it.
2. **Given** a developer encountering a network error, **When** they check the error documentation, **Then** they find guidance on retry strategies and timeout configuration.
3. **Given** a developer debugging a trust registry error, **When** they examine the error variant, **Then** they understand whether the issue is with their configuration or the IDP.

---

### User Story 4 - Cross-Platform Development (Priority: P3)

A developer building for multiple platforms (web, mobile, desktop) needs to understand platform-specific considerations, feature flags, and configuration differences.

**Why this priority**: Multi-platform support is a key differentiator. Developers targeting web (WASM) or mobile need clear guidance on platform-specific setup.

**Independent Test**: Can be tested by verifying WASM examples compile and run, platform-specific documentation exists, and feature flag combinations are clearly explained.

**Acceptance Scenarios**:

1. **Given** a developer building for WASM, **When** they read the platform documentation, **Then** they understand the required feature flags and any API differences.
2. **Given** a developer using the SDK in a mobile app via FFI, **When** they check the documentation, **Then** they find guidance on async runtime considerations.
3. **Given** a developer choosing feature flags, **When** they read the features documentation, **Then** they understand which features are default, optional, and platform-specific.

---

### User Story 5 - Production Deployment (Priority: P3)

A developer preparing to deploy to production needs to understand security best practices, configuration for production environments, and performance tuning options.

**Why this priority**: Production readiness guidance ensures developers use the SDK safely and efficiently in real-world applications.

**Independent Test**: Can be tested by verifying security documentation exists, production configuration examples are provided, and performance considerations are documented.

**Acceptance Scenarios**:

1. **Given** a developer configuring for production, **When** they read the configuration documentation, **Then** they find recommended settings for production vs development.
2. **Given** a developer concerned about security, **When** they check security documentation, **Then** they understand how secrets are handled and best practices for DPoP keys.
3. **Given** a developer tuning performance, **When** they read cache and retry configuration docs, **Then** they understand the tradeoffs and can make informed decisions.

---

### User Story 6 - Release and Distribution (Priority: P1)

A maintainer creates a GitHub release and expects the SDK to be automatically published to all distribution channels with proper artifacts and checksums.

**Why this priority**: Without automated release, every publish requires manual intervention across multiple platforms, increasing the risk of errors and version inconsistencies.

**Independent Test**: Create a test release (e.g., v0.0.0-test) and verify all artifacts are produced and checksums match.

**Acceptance Scenarios**:

1. **Given** a maintainer creates a GitHub release, **When** the release workflow runs, **Then** the crate is published to crates.io.
2. **Given** a maintainer creates a GitHub release, **When** the release workflow completes, **Then** pre-built binaries for all 5 platforms are attached to the release.
3. **Given** a maintainer creates a GitHub release, **When** the release workflow completes, **Then** the WASM package is published to npm.
4. **Given** a user downloads a release artifact, **When** they verify the checksum, **Then** the SHA256 matches the published SHA256SUMS.txt.
5. **Given** a release workflow fails validation, **When** tests or lints fail, **Then** no packages are published to any registry.

---

### Edge Cases

- What happens when a developer uses incompatible feature flag combinations? Documentation MUST clearly state which combinations are valid.
- How does the documentation handle deprecated or experimental features? Use standard rustdoc attributes (#[deprecated], feature gates).
- What guidance exists for developers migrating from a previous SDK version? CHANGELOG MUST document breaking changes with migration paths.
- How are platform-specific limitations communicated (e.g., WASM cannot use filesystem config)? Platform docs MUST note limitations clearly.
- What happens if crates.io publish succeeds but npm publish fails? Release workflow MUST NOT fail silently; failed jobs MUST be clearly reported.
- What if the version in Cargo.toml doesn't match the GitHub release tag? Workflow SHOULD validate version consistency before publishing.
- How are pre-release versions (alpha, beta, rc) handled? Use semver pre-release tags (e.g., v0.1.0-alpha.1) and publish with appropriate npm tags.

## Requirements *(mandatory)*

### Functional Requirements

#### Documentation Completeness

- **FR-001**: Every public type, function, method, and module MUST have rustdoc documentation with at least one sentence describing its purpose.
- **FR-002**: Every public function that can fail MUST document its error conditions in the rustdoc.
- **FR-003**: Complex types (builders, policies) MUST include usage examples in their rustdoc.
- **FR-004**: The crate-level documentation MUST include a Quick Start guide with working code.
- **FR-005**: Module-level documentation MUST explain the module's purpose and guide developers to relevant types.

#### Examples

- **FR-006**: Working examples MUST exist for all 8 credential policy types.
- **FR-007**: Examples MUST be self-contained and runnable with `cargo run --example`.
- **FR-008**: Each example MUST include header comments explaining what it demonstrates, prerequisites, and how to run it.
- **FR-009**: Examples MUST demonstrate error handling, not just happy paths.

#### Code Quality

- **FR-010**: All source files MUST have zero TODO, FIXME, XXX, HACK comments in production code.
- **FR-011**: Test fixtures MAY contain placeholder data that is clearly documented as test-only.
- **FR-012**: All public APIs MUST pass `cargo doc --no-deps` with zero warnings.
- **FR-013**: Code MUST pass all lints defined in the constitution (clippy pedantic, nursery, cargo).

#### README and External Documentation

- **FR-014**: README.md MUST accurately reflect current API surface and feature flags.
- **FR-015**: README.md MUST include installation instructions for all supported platforms.
- **FR-016**: A CHANGELOG.md MUST exist documenting version history and breaking changes.
- **FR-017**: A CONTRIBUTING.md MUST exist with contribution guidelines.

#### Release Automation

- **FR-021**: A GitHub Actions workflow MUST exist that triggers ONLY on release creation (not push/PR).
- **FR-022**: The release workflow MUST publish to crates.io using `cargo publish`.
- **FR-023**: The release workflow MUST build native binaries for: Linux (x86_64 glibc + musl), macOS (x86_64 + aarch64), Windows (x86_64 MSVC).
- **FR-024**: The release workflow MUST build WASM and publish to npm registry.
- **FR-025**: The release workflow MUST attach all build artifacts to the GitHub Release with SHA256 checksums.
- **FR-026**: The release workflow MUST generate a checksum file (SHA256SUMS.txt) for all artifacts.
- **FR-027**: The release workflow MUST validate CI passes before publishing to any registry.

#### Error Messages

- **FR-018**: All error types MUST implement Display with human-readable messages.
- **FR-019**: Error messages MUST be actionable, explaining what went wrong and suggesting fixes where possible.
- **FR-020**: Error documentation MUST list common causes and resolutions.

### Key Entities

- **Public API Surface**: All types, traits, functions, and methods exported from `lib.rs` that external developers will use.
- **Documentation Artifacts**: Rustdoc comments, README, CHANGELOG, CONTRIBUTING, example files.
- **Feature Flags**: Cargo features that enable/disable SDK functionality (base-policy, wasm, tracing, etc.).
- **Error Types**: LastIDError, HttpError, TrustRegistryError and their variants.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: A developer unfamiliar with the SDK can complete a credential request following only published documentation within 15 minutes.
- **SC-002**: 100% of public types, functions, and modules have rustdoc documentation.
- **SC-003**: Zero warnings produced by `cargo doc --no-deps --all-features`.
- **SC-004**: Zero TODO, FIXME, or placeholder comments in non-test source files.
- **SC-005**: Working examples exist and compile successfully for all 8 credential policy types.
- **SC-006**: All examples demonstrate error handling in addition to success paths.
- **SC-007**: README accurately describes all feature flags with clear guidance on when to use each.
- **SC-008**: Error messages answer "what happened" and "how to fix it" for common error scenarios.
- **SC-009**: Documentation renders correctly on docs.rs preview without broken links or formatting issues.
- **SC-010**: Test coverage remains at 95%+ after documentation improvements (no regression).
- **SC-011**: Release workflow successfully publishes to crates.io when a GitHub release is created.
- **SC-012**: Release workflow produces downloadable binaries for all 5 target platforms (Linux glibc, Linux musl, macOS Intel, macOS ARM, Windows).
- **SC-013**: Release workflow publishes WASM package to npm under the correct package name.
- **SC-014**: All release artifacts have accompanying SHA256 checksums for verification.

## Assumptions

- The current codebase has substantial rustdoc coverage (1500+ item comments, 223 module comments) that needs audit and completion, not creation from scratch.
- Examples exist for 8 credential types and compile successfully.
- The API surface is stable and no breaking changes are planned during this documentation effort.
- Test fixtures containing placeholder signatures are acceptable as they are clearly documented and gated behind test-utils feature.
- The SDK targets docs.rs as the primary documentation hosting platform.
