agentic-govbot/.maintenance-notes.md

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:

# 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)