# Documentation Maintenance Notes

## Documentation Strategy

We follow a **"Single Source of Truth with Contextual Pointers"** pattern to minimize redundancy while keeping security visible.

### Pattern

```
README.md:        Brief inline warnings → Link to SECURITY.md
QUICKSTART.md:    Brief inline warnings → Link to SECURITY.md
MASTODON_SETUP:   Platform-specific notes → Link to SECURITY.md
SECURITY.md:      ← SINGLE SOURCE OF TRUTH (all details)
```

### What Goes Where

**SECURITY.md** (single source of truth):
- Complete list of all protected files
- Detailed explanations of where secrets are stored
- Best practices for development and production
- What to do if secrets are accidentally committed
- Pre-commit hooks and scripts
- Security audit checklist
- All the "how" and "why" details

**README.md** (overview):
- Brief security warning in Quick Start (inline, at point of use)
- Security section: short warning + bullet list of what SECURITY.md covers
- Links to SECURITY.md for details
- NO detailed file lists (that's in SECURITY.md)

**QUICKSTART.md** (hands-on guide):
- Security warning box when copying config.yaml (critical moment)
- Link to SECURITY.md
- Brief contextual notes (e.g., "API keys go in ~/.llm/keys.json")

**MASTODON_SETUP.md** (platform-specific):
- Prominent link to SECURITY.md at top of security section
- Mastodon-specific security notes (OAuth files, scopes, etc.)
- Link to SECURITY.md for general best practices

### What's NOT Redundant (Keep It)

✅ **Inline security warnings at critical steps** (QUICKSTART when creating config)
✅ **Brief reminders in context** (README: "config.yaml is gitignored")
✅ **Platform-specific notes** (MASTODON_SETUP: Mastodon OAuth files)
✅ **Links to SECURITY.md** (everywhere - that's the point!)

### What IS Redundant (Removed)

❌ Detailed file lists in multiple places → Only in SECURITY.md
❌ Lengthy explanations of .gitignore → Only in SECURITY.md
❌ Duplicate best practices → Only in SECURITY.md

## Updating Documentation

### If You Change Something Security-Related

1. **Update SECURITY.md first** (it's the source of truth)
2. **Check if inline warnings need updates** (usually they don't, unless big change)
3. **Don't duplicate details** - just ensure links to SECURITY.md are present

### Examples

**Adding a new protected file pattern:**
- ✅ Add to .gitignore
- ✅ Document in SECURITY.md (protected files section)
- ✅ Test the pattern
- ❌ Don't add to README or QUICKSTART (they link to SECURITY.md)

**Changing where secrets are stored:**
- ✅ Update SECURITY.md (detailed explanation)
- ✅ Update inline context if needed (e.g., QUICKSTART: "edit config.yaml")
- ❌ Don't duplicate the explanation everywhere

**Adding a new platform:**
- ✅ Create platform-specific setup guide (like MASTODON_SETUP.md)
- ✅ Link to SECURITY.md at top of security section
- ✅ Add platform-specific security notes
- ❌ Don't duplicate general security advice

## Testing for Redundancy

Before committing docs, check:

```bash
# Find where a term appears
grep -n "config.yaml" README.md QUICKSTART.md MASTODON_SETUP.md SECURITY.md

# Are the mentions:
# - Contextual/inline warnings? → OK
# - Links to SECURITY.md? → OK
# - Detailed duplicate explanations? → REMOVE
```

## File Ownership

| File | Owns This Information |
|------|----------------------|
| SECURITY.md | Complete security guidance, file lists, best practices |
| README.md | High-level overview, links to details |
| QUICKSTART.md | Step-by-step with inline warnings |
| MASTODON_SETUP.md | Mastodon-specific security |
| PLATFORMS.md | Platform implementation (references SECURITY.md) |

## Current State (Post-Consolidation)

✅ README.md: Simplified "Security" section to brief warning + bullets about what's in SECURITY.md
✅ QUICKSTART.md: Contextual warning at critical moment
✅ MASTODON_SETUP.md: Platform-specific notes + link to SECURITY.md
✅ SECURITY.md: Complete authoritative guide

Redundancy: Minimal (only intentional inline warnings)
Maintenance: Easy (update SECURITY.md, others just link)
Visibility: High (warnings at critical steps)