# Tasks: SDK Publish-Ready Documentation

**Input**: Design documents from `/specs/001-sdk-publish-ready/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/

**Tests**: No explicit test tasks - this feature fixes existing test compilation issues and verifies quality.

**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.

## Format: `[ID] [P?] [Story] Description`

- **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
- Include exact file paths in descriptions

## Path Conventions

- **Single project**: `src/`, `tests/`, `examples/` at repository root
- All paths are relative to repository root

---

## Phase 1: Setup (Shared Infrastructure)

**Purpose**: Create missing external documentation files and verify baseline

- [x] T001 Create CHANGELOG.md in repository root with Keep a Changelog format
- [x] T002 [P] Create CONTRIBUTING.md in repository root with contribution guidelines
- [x] T003 [P] Run `cargo clippy --all-features` and document all warnings to fix

**Checkpoint**: ✅ External documentation files exist, clippy baseline captured

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Fix test compilation and clippy warnings that block CI

**⚠️ CRITICAL**: No user story work can begin until this phase is complete

### Fix Test Compilation (Critical Blocker)

- [x] T004 Fix `request_credential` call in `contract_request_credential_returns_response_on_success` in tests/contract_idp_client.rs (add bearer_token arg)
- [x] T005 [P] Fix `request_credential` call in `contract_request_credential_returns_400_for_invalid_policy` in tests/contract_idp_client.rs
- [x] T006 [P] Fix `request_credential` call in `contract_request_credential_returns_401_for_invalid_dpop` in tests/contract_idp_client.rs
- [x] T007 [P] Fix `request_credential` call in `contract_request_credential_returns_rate_limited_for_429` in tests/contract_idp_client.rs
- [x] T008 [P] Fix `request_credential` call in `contract_request_credential_returns_network_error_for_failures` in tests/contract_idp_client.rs
- [x] T009 Run `cargo test --all-features` to verify tests compile and pass

### Fix Clippy Warnings

- [x] T010 [P] Fix "unnested or-patterns" warning (identify file and fix pattern matching)
- [x] T011 [P] Fix "assigning Clone::clone()" inefficiency (replace with .clone())
- [x] T012 [P] Fix "casting u64 to f64 precision loss" warning (add explicit cast or use alternative)
- [x] T013 [P] Fix "casting f64 to u64 may truncate" warning (add bounds check or use saturating_cast)
- [x] T014 [P] Fix "this could be a const fn" warnings (add const where appropriate)
- [x] T015 [P] Fix "item in documentation is missing backticks" (3 instances - add backticks around code items)
- [x] T016 [P] Fix "variables can be used directly in format!" (2 instances - use format!("{x}") syntax)
- [x] T017 [P] Fix "continue expression is redundant" (2 instances - remove or restructure)
- [x] T018 Run `cargo clippy --all-features -- -D warnings` to verify zero warnings

### Fix Example Warnings

- [x] T019 [P] Fix warning in examples/employment_verification.rs
- [x] T020 [P] Fix warnings (2) in examples/age_verification.rs
- [x] T021 [P] Fix warning in examples/trust_credential.rs
- [x] T022 Run `cargo build --examples` to verify zero warnings

**Checkpoint**: ✅ Foundation ready - all tests compile, clippy passes, examples clean

---

## Phase 3: User Story 1 - First-Time Integration (Priority: P1) 🎯 MVP

**Goal**: Ensure developers can discover, install, and use the SDK within 15 minutes using only documentation.

**Independent Test**: Have a developer unfamiliar with the SDK attempt integration using only docs.rs documentation.

### Implementation for User Story 1

- [x] T023 [US1] Verify src/lib.rs crate-level documentation includes complete Quick Start guide
- [x] T024 [P] [US1] Verify README.md installation instructions work for native (Linux/macOS/Windows)
- [x] T025 [P] [US1] Verify README.md feature flags table matches Cargo.toml features section
- [x] T026 [P] [US1] Verify all module-level docs in src/*/mod.rs have //! documentation explaining purpose
- [x] T027 [US1] Run `cargo doc --no-deps --all-features` and verify zero warnings
- [x] T028 [US1] Run `cargo run --example base_credential` to verify quick start example works

**Checkpoint**: A developer can get started with the SDK using only published documentation

---

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

**Goal**: Developers understand which policy to use and how to configure it for their use case.

**Independent Test**: Documentation clearly explains all 8 policy types with working examples.

### Implementation for User Story 2

- [x] T029 [US2] Verify src/policies/mod.rs has decision guide explaining when to use each policy type
- [x] T030 [P] [US2] Verify src/policies/base.rs has complete rustdoc with usage example
- [x] T031 [P] [US2] Verify src/policies/persona.rs documents all PersonaField variants
- [x] T032 [P] [US2] Verify src/policies/verified_email.rs documents domain constraint configuration
- [x] T033 [P] [US2] Verify src/policies/verified_phone.rs has complete documentation
- [x] T034 [P] [US2] Verify src/policies/verified_persona.rs documents VerificationLevel options
- [x] T035 [P] [US2] Verify src/policies/employment.rs documents EmploymentField and EmploymentStatus
- [x] T036 [P] [US2] Verify src/policies/trust.rs documents TrustLevel variants
- [x] T037 [P] [US2] Verify src/policies/age_proof.rs documents AgeComparison operators
- [x] T038 [US2] Verify all 8 examples in examples/ run successfully with `cargo run --example <name>`

**Checkpoint**: All policy types are fully documented with working examples

---

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

**Goal**: Error messages are actionable and documentation explains common issues.

**Independent Test**: All error variants have descriptive messages and troubleshooting guidance.

### Implementation for User Story 3

- [x] T039 [US3] Verify src/error.rs LastIDError has comprehensive rustdoc for each variant
- [x] T040 [P] [US3] Verify HttpError variants in src/error.rs document retry behavior
- [x] T041 [P] [US3] Verify TrustRegistryError variants in src/error.rs explain causes
- [x] T042 [P] [US3] Verify all error Display implementations provide actionable messages
- [x] T043 [US3] Add troubleshooting section to src/error.rs module documentation listing common errors and fixes

**Checkpoint**: Errors are self-explanatory and debugging is straightforward

---

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

**Goal**: Developers understand platform-specific setup for WASM and mobile.

**Independent Test**: WASM documentation is complete and examples compile for wasm32 target.

### Implementation for User Story 4

- [x] T044 [US4] Verify README.md has WASM installation instructions with correct feature flags
- [x] T045 [P] [US4] Verify src/wasm/mod.rs has complete module documentation explaining platform differences
- [x] T046 [P] [US4] Verify Cargo.toml documents which features are platform-specific in comments
- [x] T047 [US4] Run `cargo build --target wasm32-unknown-unknown --features wasm` to verify WASM compilation

**Checkpoint**: WASM developers can successfully integrate the SDK

---

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

**Goal**: Developers have guidance for production security and performance tuning.

**Independent Test**: Security documentation exists and configuration options are explained.

### Implementation for User Story 5

- [x] T048 [US5] Verify src/config/mod.rs documents production vs development configuration recommendations
- [x] T049 [P] [US5] Verify src/crypto/secrets.rs documents secret handling best practices
- [x] T050 [P] [US5] Verify src/config/cache.rs documents cache TTL tradeoffs
- [x] T051 [P] [US5] Verify src/config/retry.rs documents retry strategy options
- [x] T052 [US5] Add security considerations section to src/lib.rs crate documentation

**Checkpoint**: Production deployment guidance is complete

---

## Phase 8: Polish & Cross-Cutting Concerns

**Purpose**: Final verification and cleanup

- [x] T053 Run full CI verification: `cargo fmt --check && cargo clippy --all-features -- -D warnings && cargo test --all-features && cargo doc --no-deps --all-features`
- [x] T054 [P] Verify CHANGELOG.md has complete v0.1.0 entry with all features listed
- [x] T055 [P] Verify CONTRIBUTING.md references constitution and code quality requirements
- [x] T056 Run `cargo llvm-cov --all-features` and verify 95%+ coverage maintained
- [x] T057 Preview documentation with `cargo doc --open` and verify no broken links
- [x] T058 Update docs/project_notes/issues.md with completion status

**Checkpoint**: SDK is publish-ready

---

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

**Goal**: Automated multi-platform builds and publishing when a GitHub release is created.

**Independent Test**: Create a test release and verify all artifacts are produced correctly.

### Create Release Workflow

- [x] T059 [US6] Create .github/workflows/release.yml with release trigger (`on: release: types: [created]`)
- [x] T060 [P] [US6] Add validate job to release.yml that runs cargo check, clippy, test, and doc
- [x] T061 [P] [US6] Add cargo-publish job to release.yml that publishes to crates.io (needs CARGO_REGISTRY_TOKEN secret)

### Native Binary Builds

- [x] T062 [US6] Add build-linux-gnu job for x86_64-unknown-linux-gnu target
- [x] T063 [P] [US6] Add build-linux-musl job for x86_64-unknown-linux-musl target (static binary)
- [x] T064 [P] [US6] Add build-macos-intel job for x86_64-apple-darwin target
- [x] T065 [P] [US6] Add build-macos-arm job for aarch64-apple-darwin target (Apple Silicon)
- [x] T066 [P] [US6] Add build-windows job for x86_64-pc-windows-msvc target

### WASM and npm Publishing

- [x] T067 [US6] Add wasm-build job that runs wasm-pack build --release (web, nodejs, bundler targets)
- [x] T068 [P] [US6] Add npm artifact packaging (creates .tgz for local npm install)
- [ ] T069 [P] [US6] Add npm-publish job to publish to npm registry (needs NPM_TOKEN secret) - DEFERRED for local testing first

### Release Assets and Checksums

- [x] T070 [US6] Add upload-assets job that attaches all binaries to GitHub Release
- [x] T071 [P] [US6] Generate SHA256 checksums for all artifacts
- [x] T072 [P] [US6] Name artifacts consistently: lastid-sdk-{target}.{ext}

### Documentation

- [x] T073 [US6] Document required secrets in CONTRIBUTING.md (CARGO_REGISTRY_TOKEN, NPM_TOKEN)
- [x] T074 [P] [US6] Document release process in CONTRIBUTING.md (how to create a release)
- [x] T075 [P] [US6] Add installation instructions to README.md for all distribution channels

### Verification

- [x] T076 [US6] Test release workflow with dry-run (cargo publish --dry-run)
- [x] T077 [US6] Verify workflow triggers ONLY on release creation, not on push/PR

**Checkpoint**: Release automation complete - creating a GitHub release publishes to all channels

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies - can start immediately
- **Foundational (Phase 2)**: Depends on Phase 1 - BLOCKS all user stories
- **User Stories (Phase 3-7)**: All depend on Phase 2 completion
  - User stories CAN proceed in parallel after Phase 2
  - Recommended: Sequential for documentation consistency
- **Polish (Phase 8)**: Depends on all user stories being complete
- **Release Automation (Phase 9)**: Can proceed in parallel with Phase 3-8
  - Does NOT block documentation work
  - SHOULD be complete before first release

### User Story Dependencies

- **User Story 1 (P1)**: Can start after Phase 2 - No dependencies on other stories
- **User Story 2 (P2)**: Can start after Phase 2 - Independent of US1
- **User Story 3 (P2)**: Can start after Phase 2 - Independent of US1/US2
- **User Story 4 (P3)**: Can start after Phase 2 - Independent
- **User Story 5 (P3)**: Can start after Phase 2 - Independent

### Within Each Phase

- Tasks marked [P] can run in parallel
- Non-[P] tasks should run sequentially
- Verification tasks (Run `cargo...`) depend on prior tasks in that phase

### Parallel Opportunities

- Phase 1: T002, T003 can run in parallel
- Phase 2: T005-T008 (test fixes), T010-T017 (clippy fixes), T019-T021 (example fixes) can all run in parallel
- Phase 3+: All [P] tasks within a user story can run in parallel
- Cross-story: Once Phase 2 completes, different team members can work different user stories

---

## Parallel Example: Phase 2 (Foundational)

```bash
# Launch all test fixes in parallel:
Task: "Fix request_credential in contract_request_credential_returns_400_for_invalid_policy in tests/contract_idp_client.rs"
Task: "Fix request_credential in contract_request_credential_returns_401_for_invalid_dpop in tests/contract_idp_client.rs"
Task: "Fix request_credential in contract_request_credential_returns_rate_limited_for_429 in tests/contract_idp_client.rs"
Task: "Fix request_credential in contract_request_credential_returns_network_error_for_failures in tests/contract_idp_client.rs"

# Launch all clippy fixes in parallel:
Task: "Fix unnested or-patterns warning"
Task: "Fix assigning Clone::clone() inefficiency"
Task: "Fix casting u64 to f64 precision loss warning"
# ... etc
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup (create CHANGELOG, CONTRIBUTING)
2. Complete Phase 2: Foundational (fix tests, clippy, examples)
3. Complete Phase 3: User Story 1 (first-time integration docs)
4. **STOP and VALIDATE**: Run full CI, verify docs render correctly
5. SDK is usable for basic integration

### Incremental Delivery

1. Complete Setup + Foundational → CI passes
2. Add User Story 1 → First-time integration works (MVP!)
3. Add User Story 2 → Policy documentation complete
4. Add User Story 3 → Error handling clear
5. Add User Story 4 → WASM developers supported
6. Add User Story 5 → Production guidance complete
7. Add User Story 6 → Release automation ready (can parallelize with 2-6)
8. Polish → Ready to publish

### Release Automation (Phase 9) - Can Run in Parallel

Phase 9 tasks have no dependency on documentation tasks (Phases 3-7).
Recommended parallel assignment:
- Dev A: Documentation (Phases 3-7)
- Dev B: Release automation (Phase 9)
- Both: Polish (Phase 8) after all other phases

### Parallel Team Strategy

With multiple developers:

1. Dev A: Complete Phase 1 + Phase 2 test fixes
2. Dev B: Complete Phase 2 clippy fixes + example fixes
3. After Phase 2:
   - Dev A: User Stories 1, 3, 5 (documentation)
   - Dev B: User Stories 2, 4 (documentation) + User Story 6 (release automation)
4. Both: Phase 8 polish

With three developers:

1. Dev A: Phase 1 + Phase 2 test fixes
2. Dev B: Phase 2 clippy + example fixes
3. After Phase 2:
   - Dev A: User Stories 1, 3 (first-time integration, error handling)
   - Dev B: User Stories 2, 4, 5 (policies, cross-platform, production)
   - Dev C: User Story 6 (release automation - entirely independent)

---

## Notes

- [P] tasks = different files, no dependencies
- [Story] label maps task to specific user story for traceability
- This is primarily a verification and polish task, not new code
- Most tasks are "Verify X documentation exists" rather than "Write X"
- Fix tasks in Phase 2 require actual code changes
- Commit after each task or logical group
- Stop at any checkpoint to validate incrementally

### Release Workflow Notes

- **Required Secrets**: CARGO_REGISTRY_TOKEN (crates.io), NPM_TOKEN (npm registry)
- **Artifact Naming**: `lastid-sdk-{version}-{target}.tar.gz` (Unix) or `.zip` (Windows)
- **Targets**:
  - `x86_64-unknown-linux-gnu` - Linux with glibc (most common)
  - `x86_64-unknown-linux-musl` - Linux static binary (no glibc dependency)
  - `x86_64-apple-darwin` - macOS Intel
  - `aarch64-apple-darwin` - macOS Apple Silicon (M1/M2/M3)
  - `x86_64-pc-windows-msvc` - Windows 64-bit
- **npm Package**: Published as WASM with JS/TS bindings via wasm-pack
- **Version Consistency**: GitHub release tag (v0.1.0) should match Cargo.toml version (0.1.0)
