# Story 10.14: Extras Documentation Accuracy

**Status:** Complete
**Priority:** High
**Depends on:** None

---

## Context / Background

The GPT-5.2 audit identified a mismatch between documented extras and actual extras in `pyproject.toml`.

**Current state in `docs/install-and-update.md:25-47`:**

```bash
pip install "fapilog[enterprise]"  # Does not exist
pip install "fapilog[fastapi]"     # Exists
pip install "fapilog[loki]"        # Does not exist
pip install "fapilog[cloud]"       # Does not exist
pip install "fapilog[siem]"        # Does not exist
```

**Actual extras in `pyproject.toml:49-114`:**

| Extra | Dependencies | Documented? |
|-------|--------------|-------------|
| `fastapi` | fastapi>=0.115.0 | ✅ Yes |
| `http` | httpx>=0.24.0 | ❌ No |
| `aws` | boto3>=1.26.0 | ❌ No |
| `metrics` | prometheus-client>=0.17.0 | ❌ No |
| `system` | psutil>=5.9.0 | ❌ No |
| `mqtt` | asyncio-mqtt>=0.16.0 | ❌ No |
| `postgres` | asyncpg>=0.28.0 | ❌ No |
| `dev` | development tools | ✅ Yes |
| `docs` | sphinx, etc. | ✅ Yes |
| `all` | all of the above | ✅ Yes |

**Problem:**

- Users trying `pip install fapilog[enterprise]` get an error
- Real extras like `http`, `aws`, `postgres` are undiscoverable
- Documentation doesn't match reality, eroding trust

---

## Scope (In / Out)

### In Scope

- Update `docs/install-and-update.md` to list only real extras
- Add descriptions for each extra explaining what it enables
- Remove references to non-existent extras throughout docs

### Out of Scope

- Creating new extras (enterprise, loki, cloud, siem)
- Changing pyproject.toml extras structure

---

## Acceptance Criteria

### AC1: Documentation Lists Only Real Extras

**Description:** Install docs reference only extras that exist in pyproject.toml.

**Validation:**

```bash
# Extract extras from docs
grep -oE 'fapilog\[[a-z]+\]' docs/install-and-update.md | sort -u

# Should only show: fastapi, http, aws, metrics, system, mqtt, postgres, dev, docs, all
# Should NOT show: enterprise, loki, cloud, siem
```

### AC2: All Real Extras Documented

**Description:** Every extra in pyproject.toml is mentioned in install docs.

**Validation:**

```python
# All these should appear in docs/install-and-update.md:
extras = ["fastapi", "http", "aws", "metrics", "system", "mqtt", "postgres", "dev", "docs", "all"]
```

### AC3: Extras Have Descriptions

**Description:** Each extra includes a brief description of what it enables.

**Validation:**

```markdown
# Expected format in docs:

| Extra | Description |
|-------|-------------|
| `fastapi` | FastAPI middleware integration |
| `http` | Remote HTTP sink (webhook) via httpx |
| `aws` | AWS CloudWatch sink via boto3 |
| `metrics` | Prometheus metrics export |
| `system` | System metrics enricher (CPU, memory) |
| `mqtt` | MQTT sink for IoT logging |
| `postgres` | PostgreSQL sink via asyncpg |
| `dev` | Development tools (pytest, ruff, mypy) |
| `docs` | Documentation build (Sphinx) |
| `all` | All optional dependencies |
```

### AC4: No Broken Extras References Elsewhere

**Description:** Search docs for references to non-existent extras.

**Validation:**

```bash
grep -r "fapilog\[enterprise\]\|fapilog\[loki\]\|fapilog\[cloud\]\|fapilog\[siem\]" docs/
# Should return no matches
```

---

## Implementation Notes

### File Changes

```text
docs/install-and-update.md (MODIFIED - fix extras list)
```

### Updated Content

Replace lines 25-47 with:

```markdown
### Enable Optional Features via Extras

The project publishes optional integrations via extras. Choose only what you need:

| Extra | Description | Install |
|-------|-------------|---------|
| `fastapi` | FastAPI middleware integration | `pip install "fapilog[fastapi]"` |
| `http` | Remote HTTP sink via httpx | `pip install "fapilog[http]"` |
| `aws` | AWS CloudWatch sink via boto3 | `pip install "fapilog[aws]"` |
| `metrics` | Prometheus metrics export | `pip install "fapilog[metrics]"` |
| `system` | System metrics enricher (psutil) | `pip install "fapilog[system]"` |
| `mqtt` | MQTT sink for IoT logging | `pip install "fapilog[mqtt]"` |
| `postgres` | PostgreSQL sink via asyncpg | `pip install "fapilog[postgres]"` |
| `dev` | Development tools | `pip install "fapilog[dev]"` |
| `docs` | Documentation build tools | `pip install "fapilog[docs]"` |
| `all` | All optional dependencies | `pip install "fapilog[all]"` |

Combine extras as needed:

```bash
pip install "fapilog[fastapi,http,metrics]"
```
```

---

## Tasks

### Phase 1: Fix Install Docs

- [ ] Remove non-existent extras (enterprise, loki, cloud, siem)
- [ ] Add missing extras (http, aws, metrics, system, mqtt, postgres)
- [ ] Add description table

### Phase 2: Search and Replace

- [ ] Search all docs for references to non-existent extras
- [ ] Update or remove any found references

### Phase 3: Validation

- [ ] Verify all documented extras exist in pyproject.toml
- [ ] Verify all pyproject.toml extras are documented

---

## Tests

### Manual Verification

```bash
# Verify documented extras match pyproject.toml
grep -E '^\w+ = \[' pyproject.toml | grep -v 'requires\|dynamic\|authors'

# Verify no non-existent extras in docs
grep -rE 'fapilog\[(enterprise|loki|cloud|siem)\]' docs/ && echo "FAIL" || echo "OK"
```

---

## Definition of Done

### Code Complete

- [x] Non-existent extras removed from docs
- [x] All real extras documented with descriptions
- [x] No broken extras references in docs

### Quality Assurance

- [x] Documentation renders correctly
- [x] All listed extras actually work when installed

### Documentation

- [x] CHANGELOG updated

---

## Risks / Rollback

### Risks

1. **Risk:** Users expect removed extras to exist
   - **Mitigation:** Those extras never worked anyway

### Rollback Plan

If issues occur:

1. Revert docs/install-and-update.md

---

## Related Stories

- **Related:** Story 10.13 - README stability claims accuracy (documentation accuracy theme)

---

## Change Log

| Date       | Change        | Author |
|------------|---------------|--------|
| 2026-01-16 | Initial draft | Claude |
