Add OCLIF README auto-generation markers for single source of truth documentation

[aaronlippold]

Problem Statement

Current State:

• README.md is manually maintained for all 40+ commands
• High risk of documentation drift when code changes but README doesn't get updated
• Error-prone: Must remember to update README after every command change
• Inconsistent: Different commands have different documentation quality

Recent Example: Threshold refactoring (#2196) added 7 new flags - had to manually update README to stay in sync.

---

Solution: OCLIF Auto-Generation

OCLIF can automatically generate command documentation from source code using npx oclif readme.

Requirements: README must have these markers:

# Commands
<!-- commands -->
(OCLIF auto-generates command list here)
<!-- commandsstop -->

# Usage
<!-- usage -->
(OCLIF auto-generates usage here)
<!-- usagestop -->

Source of Truth: Command class definitions (static description, static examples, static flags)

---

Benefits

1. ✅ Never out of sync - README always matches code
2. ✅ Automatic - Run npx oclif readme before committing
3. ✅ Consistent - All commands documented the same way
4. ✅ Less maintenance - Update command code, README updates automatically
5. ✅ CI/CD integration - Can verify README is current in GitHub Actions

---

Implementation Plan

Step 1: Add Markers to README

Find the Commands section (around line 1437) and add OCLIF markers while preserving custom content:

## Commands

<!-- commands -->
<!-- commandsstop -->

### Workflow Examples
(Keep manual sections for tutorials and workflows)

Step 2: Test Generation

npx oclif readme --readme-path README.md --dry-run

Review the output to ensure quality.

Step 3: Add CI Check

Verify README stays current:

# .github/workflows/verify-docs.yml
- name: Verify README is up to date
  run: |
    npx oclif readme --readme-path README.md
    git diff --exit-code README.md || (echo "README out of sync. Run: npx oclif readme" && exit 1)

Step 4: Update Contributing Docs

Document the process:

• Developers update command code
• Run npx oclif readme before committing
• CI verifies it was done

---

Risks & Mitigation

Risk: Auto-generated format may not match current style
Mitigation: Use threshold command as reference (recently updated with best practices)

Risk: Losing custom explanations/workflows
Mitigation: Keep manual sections, only auto-gen command reference

Risk: Breaking existing links
Mitigation: Review all internal README links after generation

---

Success Criteria

• ✅ All 40+ commands documented consistently
• ✅ README updates automatically when commands change
• ✅ CI verifies README is current
• ✅ No manual sync required for command changes
• ✅ Threshold commands serve as quality example

---

Estimated Impact

Time Saved per Command Update:

• Current: 15-30 min manual README update
• With auto-gen: 0 min (automated)

For 40+ Commands:

• Manual maintenance: ~10-20 hours per major update
• Auto-gen: ~1 hour (review generated docs)

ROI: Pays for itself after 2-3 command updates

---

Priority

HIGH - Should be next PR after threshold refactoring (#2196)

Rationale:

• Makes all future command changes easier
• Threshold refactoring serves as gold standard example
• Will benefit summary refactoring and other upcoming work

---

Additional Context

• OCLIF readme command: https://oclif.io/docs/features/
• Example markers: https://github.com/oclif/oclif/blob/main/docs/readme.md
• Threshold PR (Fix Threshold Capability, reorganize, properly document, type etc. - aka 'the Summary Treatment' please #2196) demonstrates the problem this solves

---

Related Opportunities

oclif-plugin-mcp-server Integration

What: https://github.com/npjonath/oclif-plugin-mcp-server
Purpose: Expose SAF CLI to Claude Code via MCP protocol

Potential:

• Claude could discover and call SAF commands programmatically
• Auto-generate InSpec profiles in interactive sessions
• Convert security tool outputs on the fly

Timeline: Consider after core refactoring work complete