docs: restructure quickstart user journey with sbx CLI as primary path #41

Problem

The current quickstart documentation has two approaches (Docker Desktop UI vs. standalone sbx CLI) commingled throughout, causing confusion for users. Assessment participants and first-time users struggle to understand which instructions apply to them.

Key Issues Identified

1. Conflicting recommendations: Lines 52 and 128 both say "Recommended" for different methods
2. Interleaved instructions: Users must mentally filter which steps apply to their chosen method
3. Missing secret management: sbx secret barely documented (only in tables)
4. No decision tree: Users must read everything to pick a method
5. Terminology inconsistent: "Docker Sandboxes" vs "Docker sandbox" vs "SBX"
6. README too long: 366 lines with both paths mixed together

Proposed Solution

1. Make sbx CLI the Recommended Path

• Better for federal automation and audit trails
• sbx secret provides secure keychain-backed credential storage
• Policy controls more granular
• Aligns with infrastructure-as-code principles

2. Restructure Documentation

Lean README.md (~150 lines):

• Brief intro and ecosystem context
• 5-minute quickstart (sbx CLI, copy-paste commands)
• Link to full quickstart guide for details
• Link to Docker Desktop alternative

New docs/QUICKSTART_SBX.md:

• Full sbx CLI setup with secret management
• USAi-focused configuration
• Detailed explanations

New docs/QUICKSTART_DOCKER_DESKTOP.md:

• Docker Desktop UI approach
• For users who prefer GUI
• Clear that this is the alternative path

Updated docs/SBX_QUICKSTART.md:

• Rename or consolidate with new structure
• Comprehensive reference (keep 907 lines)

3. Add Secret Management Documentation

• Full tutorial on sbx secret set/ls/rm
• Comparison: sbx secret vs shell export
• Supported services table
• Non-interactive setup for CI/CD

4. Add Decision Tree

• Clear guidance on when to use each method
• Federal compliance considerations

Implementation Plan

• Create lean README.md with 5-minute quickstart
• Create docs/QUICKSTART_SBX.md (primary path)
• Create docs/QUICKSTART_DOCKER_DESKTOP.md (alternative)
• Add secret management sections to both guides
• Update cross-references in existing docs
• Fix terminology inconsistencies
• Update KNOWN_FAILURE_MODES.md if needed

Success Criteria

1. First-time user can get working sandbox in <5 minutes
2. Clear guidance on sbx CLI vs Docker Desktop
3. sbx secret fully documented
4. No conflicting "Recommended" labels
5. Terminology consistent throughout
6. Assessment participants have clear path

Research Completed

• Analyzed current README.md (366 lines, 17 sections)
• Analyzed docs/SBX_QUICKSTART.md (907 lines)
• Researched Docker official docs (https://docs.docker.com/ai/sandboxes/)
• Documented full sbx CLI command reference
• Identified 10 major confusion points

Related

Based on assessment participant feedback and user journey analysis.

Control Mapping: SA-5 (System Documentation)