# Task Recon: Create User Documentation

**Task ID:** 38
**Status:** pending
**Generated:** 2026-01-31
**Agent:** claude-opus-4-5-20251101

---

## Task Summary

Write comprehensive user documentation including installation, configuration, and command reference. Create documentation in `docs/` directory:

- `README.md` (project root) - Quick start guide, installation, basic usage examples
- `docs/installation.md` - Prerequisites, pip install, configuration setup
- `docs/configuration.md` - config.toml structure, tenant profiles, environment variables
- `docs/commands.md` - Full CLI reference generated from Typer, examples
- `docs/troubleshooting.md` - Common errors, debug logging, API permission issues

### Dependencies
- Task 11: Root CLI App with Global Options (done)
- Task 12: Auth CLI Commands (done)
- Task 14: Tenants CLI Commands (done)
- Task 16: Locations CLI Commands (done)
- Task 18: Users CLI Commands (done)
- Task 22: Numbers CLI Commands Read Operations (done)
- Task 23: Numbers Assign/Unassign CLI Commands (done)
- Task 25: Policies CLI Commands (done)
- Task 42: Validation Checkpoint 4 (done)

### Acceptance Criteria
- All 6 command groups documented with examples
- Installation instructions tested on clean system
- Configuration options fully described
- Common workflows documented
- Troubleshooting guide covers all error types

---

## Insights from Previous Tasks

### Dependency Task Notes
| Task ID | Title | Key Insight |
|---------|-------|-------------|
| 11 | Root CLI App with Global Options | Context uses `CLIContext` dataclass, global options: `--json`, `--verbose`, `--tenant`, `--no-color`, `--debug-log` |
| 12 | Auth CLI Commands | Commands: status, login, logout, refresh. Simplified login (no --method override currently) |
| 14 | Tenants CLI Commands | 6 commands: list, current, switch, test, remove, add. Non-interactive add with required args |
| 16 | Locations CLI Commands | Reads from CSV cache (`~/.teams-phone/cache/locations.csv`). Staleness warning > 30 days |
| 18 | Users CLI Commands | Async pattern with `_run_async()`. Default limit 50. SearchField enum for --field |
| 22 | Numbers CLI Commands | Filter values use exact API enum names (unassigned, userAssigned, callingPlan, directRouting) |
| 23 | Numbers Assign/Unassign | Progress spinner for async ops. E911 location validation for Calling Plan numbers |
| 25 | Policies CLI Commands | Policy type aliases (calling -> TeamsCallingPolicy). Sync service for cache-only ops |
| 42 | Validation Checkpoint 4 | AsyncOperation model fix for polling. Bulk operations validated with 24-row CSV |

### Reusable Patterns from Dependencies
- **Error handling**: `try/except TeamsPhoneError` with `formatter.error(e.message, remediation=e.remediation)` then `raise typer.Exit(e.exit_code)` - see `src/teams_phone/cli/auth.py:47-49`
- **Async bridging**: `asyncio.run()` with async context manager for GraphClient - see `users.py:42-70`
- **Progress display**: Rich `console.status()` for spinner during async operations - see `numbers.py`

### Warnings and Gotchas
- **Exit code 2**: Typer returns exit code 2 for missing arguments (not 1)
- **CSV cache staleness**: CLI warns if cache > 30 days old
- **ANSI escape codes**: Rich adds color codes to numeric strings in output, use `--no-color` for scripting
- **TeamsVoicemailPolicy**: Not supported in batch assignment endpoint, recommend PowerShell fallback

### Open Items Inherited
- None affecting documentation

---

## Architecture Context

### Relevant Design Decisions
- **Hybrid data source**: Graph API for real-time data + PowerShell CSV export for locations/policies
- **Certificate-based auth**: Recommended over client-secret for security
- **Strict Pydantic models**: Fail-fast on API contract changes (ContractError exit code 8)
- **Exponential backoff retry**: 3 retries for 429/503 responses

### Module Structure
Documentation should reflect the layered architecture:
```
src/teams_phone/
├── cli/            # Typer commands (document all commands here)
├── services/       # Business logic (internal, not user-facing)
├── infrastructure/ # Graph API client, cache manager, config manager
├── models/         # Pydantic models
├── constants.py    # Exit codes (document in troubleshooting)
├── exceptions.py   # Exception hierarchy (document error types)
└── utils.py        # Phone number normalization
```

### Conventions to Follow
- Use imperative voice for command descriptions
- Include exit codes in error documentation
- Show both table and JSON output formats
- Include E.164 phone number format examples (+12065551234)

---

## Related Code References

### Primary References (Must Read)
| File | Lines | Purpose |
|------|-------|---------|
| `src/teams_phone/cli/main.py` | 25-99 | Main app definition, global options, command group registration |
| `src/teams_phone/exceptions.py` | 10-138 | Exception hierarchy with exit codes |
| `pyproject.toml` | 1-62 | Project metadata, dependencies, scripts entry point |
| `scripts/README.md` | 1-202 | PowerShell export setup (reference for CSV cache setup) |

### Secondary References (Helpful Context)
| File | Lines | Purpose |
|------|-------|---------|
| `.taskmaster/docs/cli-specification/command-summary.md` | 1-40 | Command quick reference table |
| `.taskmaster/docs/cli-specification/global-options.md` | 1-15 | Global option definitions |
| `.taskmaster/docs/cli-specification/error-handling.md` | 1-68 | Exit codes and Graph API error mapping |
| `.taskmaster/docs/cli-specification/logging-diagnostics.md` | 1-32 | Debug log format |
| `.taskmaster/docs/cli-specification/configuration-file.md` | 1-34 | config.toml structure |
| `.taskmaster/docs/prd/appendix-a-exit-code-reference.md` | 1-14 | Exit code reference |
| `.taskmaster/docs/prd/appendix-b-required-graph-api-permissions.md` | 1-14 | Required permissions |

### Code Patterns to Follow

```python
# Entry point pattern (pyproject.toml:31)
[project.scripts]
teams-phone = "teams_phone.cli.main:app"
```

```python
# Exception with exit code (src/teams_phone/exceptions.py:47-57)
class AuthenticationError(TeamsPhoneError):
    """Authentication failure (exit code 2)."""
    exit_code: int = ExitCode.AUTH_ERROR
```

---

## Dependencies

### Internal Modules
- All documentation content extracted from existing specs and code
- No new code dependencies

### External Packages
- None needed for documentation

### New Dependencies Needed
- None required

---

## Testing Guidance

### Test File Location
N/A - Documentation task, no code tests

### Test Strategy
- Review documentation for completeness
- Verify all commands are documented
- Test installation instructions on clean system
- Cross-reference command examples with actual CLI help output

### Manual Validation Steps
1. Run `python -m teams_phone --help` and verify all command groups documented
2. Run each command with `--help` and compare with docs
3. Follow installation instructions from scratch
4. Test example commands from documentation

---

## Risks and Blockers

### Technical Risks
- [ ] **Documentation drift**: CLI may have evolved beyond spec docs. Mitigation: Cross-reference actual `--help` output
- [ ] **Windows path differences**: Use platform-agnostic paths where possible (`~/.teams-phone/` works cross-platform)

### Dependency Risks
- [ ] None - all dependency tasks are complete

### Open Questions
- [ ] Should README.md replace existing CLAUDE.md or coexist? (Recommend: README.md for users, CLAUDE.md for AI agents)
- [ ] Include version number in docs? (pyproject.toml shows 0.1.0)

---

## Implementation Recommendations

### Suggested Approach
1. Create `docs/` directory structure
2. Write `docs/installation.md` first (prerequisites, install steps)
3. Write `docs/configuration.md` (config.toml, tenants, environment)
4. Write `docs/commands.md` (full CLI reference from specs)
5. Write `docs/troubleshooting.md` (errors, debug logging)
6. Write `README.md` (quick start, link to docs/)
7. Verify all examples work with actual CLI

### Files to Create/Modify
| Action | File | Reason |
|--------|------|--------|
| Create | `docs/installation.md` | Prerequisites and install instructions |
| Create | `docs/configuration.md` | Config file and tenant setup |
| Create | `docs/commands.md` | Full CLI reference |
| Create | `docs/troubleshooting.md` | Error handling and debugging |
| Create | `README.md` | Project overview and quick start |

### Quick Wins
- Start with installation.md - straightforward, well-defined requirements
- Configuration.md can largely be copied from existing spec docs
- Commands.md can be generated from existing CLI specification docs

---

## Cheat Sheet

### Key Information Sources
```
# CLI specification docs (comprehensive)
.taskmaster/docs/cli-specification/

# Architecture docs
.taskmaster/docs/architecture/

# Exit codes
.taskmaster/docs/prd/appendix-a-exit-code-reference.md

# Required permissions
.taskmaster/docs/prd/appendix-b-required-graph-api-permissions.md

# PowerShell script docs (for CSV cache setup)
scripts/README.md
```

### Exit Codes (for troubleshooting.md)
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Authentication error |
| 3 | Authorization error |
| 4 | Not found |
| 5 | Validation error |
| 6 | Rate limit exceeded |
| 7 | Configuration error |
| 8 | Contract error (API mismatch) |

### Command Groups
- `users` - list, show, search
- `numbers` - list, show, search, assign, unassign, update, bulk-assign
- `policies` - list, show, assign, bulk-assign
- `locations` - list, show, search
- `tenants` - list, current, switch, add, remove, test
- `auth` - login, logout, status, refresh
- `api-check` - Validate API contracts

### Global Options
| Option | Short | Description |
|--------|-------|-------------|
| `--tenant <name>` | `-t` | Override default tenant |
| `--json` | `-j` | JSON output format |
| `--verbose` | `-v` | Detailed output |
| `--no-color` | | Disable colors |
| `--debug-log <path>` | | JSON diagnostic logs |

### Required Permissions
| Permission | Purpose |
|------------|---------|
| `TeamsUserConfiguration.Read.All` | Read user voice config |
| `TeamsTelephoneNumber.Read.All` | Read phone inventory |
| `TeamsTelephoneNumber.ReadWrite.All` | Assign/unassign numbers |
| `TeamsPolicyUserAssign.ReadWrite.All` | Assign policies |
| `User.Read.All` | Read user profiles |
| `Directory.Read.All` | Read tenant info |
| `RoleManagement.Read.Directory` | Required as of Sept 2025 |
| `GroupMember.Read.All` | Required as of Sept 2025 |

### Config File Location
- `~/.teams-phone/config.toml`
- Cache: `~/.teams-phone/cache/`

---

*Generated by task-recon (claude-opus-4-5-20251101) | Ready for implementation*
