# Story 4.33: Documentation Cleanup

**Status:** Complete  
**Priority:** Critical  
**Depends on:** None  
**Effort:** 0.5 days

---

## Problem Statement

The documentation audit revealed several obsolete, incorrect, or orphaned documentation files that need cleanup.

### Issues Found

#### 1. Obsolete File: `docs/env-vars.md.old`

This file contains the **old environment variable format** that is no longer used:

```markdown
# Old format in env-vars.md.old

FAPILOG_QUEUE**MAX_SIZE
FAPILOG_BATCH**MAX_EVENTS
FAPILOG_BACKPRESSURE\_\_\*
```

The current format uses `FAPILOG_CORE__*`, `FAPILOG_HTTP__*`, etc. This file should be deleted.

#### 2. Incorrect References: `IntegrityPlugin` and `load_integrity_plugin`

**File: `docs/api-reference/plugins/index.md` (lines 172-180)**

````markdown
## Enterprise Plugins

For enterprise features like tamper-evident logging, fapilog provides an integrity plugin hook:

```python
from fapilog.plugins import IntegrityPlugin, load_integrity_plugin

# Load an integrity plugin by entry point name
plugin = load_integrity_plugin("fapilog-tamper")
```
````

````

**Problem:** Neither `IntegrityPlugin` nor `load_integrity_plugin` exist in the codebase. This was removed in Story 4.20a. The correct approach is to use standard plugin configuration.

#### 3. Orphaned File: `docs/FUTURE-CLI.md`

Contains future CLI plans but:
- Not linked from any navigation
- Not in any toctree
- Status unclear (is this still planned?)

#### 4. Out-of-Scope File: `docs/INFRASTRUCTURE_SETUP.md`

Contains infrastructure setup instructions that are application-specific, not library-specific. A library should not include deployment infrastructure docs.

---

## Implementation Plan

### Phase 1: Delete Obsolete File

**Delete:** `docs/env-vars.md.old`

This file is obsolete and could confuse users who find it via search.

### Phase 2: Fix Incorrect API References

**File: `docs/api-reference/plugins/index.md`**

Replace the incorrect "Enterprise Plugins" section:

```markdown
## Enterprise Plugins

For enterprise features like tamper-evident logging, install the `fapilog-tamper` add-on
and configure it via standard plugin settings:

```python
from fapilog import Settings

settings = Settings(
    core__enrichers=["runtime_info", "integrity"],
    core__sinks=["sealed"],
    enricher_config__integrity={
        "algorithm": "HMAC-SHA256",
        "key_provider": "env",
        "key_id": "audit-key",
    },
)
````

See [Tamper-Evident Logging](../../addons/tamper-evident-logging.md) for full configuration options.

````

### Phase 3: Handle Orphaned Files

**Option A: Archive FUTURE-CLI.md**

Move to `docs/prd/future-cli-design.md` and update to indicate it's a design document, not current functionality.

**Option B: Delete FUTURE-CLI.md**

If CLI is not on the roadmap, delete entirely.

**Recommendation:** Option A - Archive with clear status.

**File: `docs/FUTURE-CLI.md`**

Add header and move:

```markdown
# Future CLI Design (Not Implemented)

> **Status:** Design Document - Not Implemented
>
> This document captures a potential CLI design for future consideration.
> There is no timeline for implementation.

[... rest of content ...]
````

Move to `docs/prd/future-cli-design.md`.

### Phase 4: Handle Infrastructure File

**File: `docs/INFRASTRUCTURE_SETUP.md`**

**Option A: Delete** - Not appropriate for a library

**Option B: Move to examples** - If useful, move to `docs/examples/deployment/`

**Recommendation:** Review content. If it's fapilog-specific configuration, move to examples. If it's generic infrastructure, delete.

---

## Acceptance Criteria

- [x] `docs/env-vars.md.old` deleted
- [x] `docs/api-reference/plugins/index.md` updated with correct enterprise plugin usage
- [x] `docs/FUTURE-CLI.md` either archived with clear status or deleted
- [x] `docs/INFRASTRUCTURE_SETUP.md` reviewed and appropriately handled
- [x] Documentation builds without warnings
- [x] No broken internal links

---

## Files Changed

| File                                  | Action                                           |
| ------------------------------------- | ------------------------------------------------ |
| `docs/env-vars.md.old`                | DELETE                                           |
| `docs/api-reference/plugins/index.md` | Update enterprise plugins section                |
| `docs/FUTURE-CLI.md`                  | Move to `docs/prd/` with status header OR delete |
| `docs/INFRASTRUCTURE_SETUP.md`        | Review and move/delete as appropriate            |

---

## Verification

After changes, run:

```bash
cd docs
make linkcheck  # Verify no broken links
make html       # Verify builds without warnings
```
