Reduce documentation redundancy while keeping security visible

Applied "Single Source of Truth with Contextual Pointers" pattern:

README.md changes:
- Simplified "Security Note" section to brief warning + bullets
- Removed detailed file list (now only in SECURITY.md)
- Kept inline warning in Quick Start (contextual, at point of use)
- Added bullets describing what SECURITY.md covers
- Result: Brief, clear, points to authoritative source

Documentation strategy:
- SECURITY.md = single source of truth (all details)
- Other docs = brief inline warnings + links to SECURITY.md
- Inline warnings kept at critical moments (e.g., creating config.yaml)
- Platform-specific notes stay in platform guides

Added .maintenance-notes.md:
- Documents the documentation strategy
- Explains what goes where and why
- Provides guidance for future updates
- Helps prevent redundancy creep

Benefits:
- Easier to maintain (update SECURITY.md, others just link)
- Still highly visible (warnings at critical steps)
- No loss of information (everything in SECURITY.md)
- Clear ownership (each file owns specific info)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.maintenance-notes.md

@@ -0,0 +1,116 @@
+# 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)

README.md

@@ -131,15 +131,15 @@ See `constitution.md` for an example based on Social.coop's bylaws.
 - **[SECURITY.md](SECURITY.md)** - Credential management and security best practices
 - **[constitution.md](constitution.md)** - Example governance constitution
 
-## Security Note
+## Security
 
-**Never commit these files** (already in `.gitignore`):
-- `config/config.yaml` - Contains your credentials
-- `govbot.db` - Your governance database
-- `.env` files - Environment variables
-- `*.token`, `*.key`, `*.secret` files
+⚠️ **Important**: Never commit `config/config.yaml` or other files containing credentials. All sensitive files are automatically protected by `.gitignore`.
 
-See [SECURITY.md](SECURITY.md) for complete security guide.
+**See [SECURITY.md](SECURITY.md) for:**
+- Complete list of protected files
+- Where to store credentials
+- Best practices for development and production
+- What to do if secrets are accidentally committed
 
 ## Development Status