socktop-webterm/docs/DOCUMENTATION_CORRECTIONS.md

# Documentation Corrections Summary

This document lists all corrections made to the socktop documentation to align with the actual implementation as documented in the official README.

## Date: 2025-01-XX

## Critical Corrections Made

### 1. Missing GPU Dependencies ✅ FIXED

**Issue:** Documentation failed to mention required GPU support libraries.

**Fix:** Added `libdrm-dev` and `libdrm-amdgpu1` to:
- `docs/src/installation/prerequisites.md`
- `docs/src/installation/quick-start.md`
- `docs/src/installation/apt.md`
- `docs/src/installation/cargo.md`

**Reason:** These libraries are explicitly required in the README for GPU metrics support on Raspberry Pi, Ubuntu, and PopOS.

---

### 2. TLS Certificate Auto-Generation ✅ FIXED

**Issue:** Documentation incorrectly instructed users to manually generate certificates with OpenSSL.

**Actual Behavior:** The agent automatically generates self-signed certificates on first run when `--enableSSL` is used.

**Files Updated:**
- `docs/src/security/tls.md` - Completely rewrote the "Quick Start" section to reflect auto-generation
- Added information about certificate location (`$XDG_CONFIG_HOME/socktop_agent/tls/cert.pem`)
- Added information about `SOCKTOP_AGENT_EXTRA_SANS` environment variable
- Updated certificate renewal section to explain simple deletion and restart process

**Key Changes:**
- Changed from manual OpenSSL commands to simple `socktop_agent --enableSSL --port 8443`
- Documented that certificate is auto-generated and location is printed on first run
- Updated expiry information (~397 days)
- Moved manual generation to "Manual Certificate Generation" section for advanced users only

---

### 3. Fabricated Command-Line Options ✅ FIXED

**Issue:** Documentation extensively referenced non-existent options.

**Fabricated Options:**
- `--refresh-rate` (does not exist)
- `--ca-cert` (actual flag is `--tls-ca`)
- `--no-verify-tls` (does not exist in this form)

**Correct Options:**
- `--metrics-interval-ms` (default: 500ms) - Controls fast metrics polling
- `--processes-interval-ms` (default: 2000ms) - Controls process list polling
- `--tls-ca` - Specify CA certificate for TLS verification
- `--verify-hostname` - Enable strict hostname verification

**Files Updated:**
- `docs/src/usage/general.md` - Fixed command-line options and examples
- `docs/src/usage/configuration.md` - Fixed interval examples
- `docs/src/usage/connection-profiles.md` - Fixed override examples
- `docs/src/security/tls.md` - Fixed TLS option references
- `docs/src/security/token.md` - Fixed CA cert flag

---

### 4. Profile Format Fabrication ✅ FIXED

**Issue:** Documentation claimed profiles are stored in TOML format.

**Actual Format:** Profiles are stored as JSON in `~/.config/socktop/profiles.json`

**Correct Structure:**
```json
{
  "profiles": {
    "prod": {
      "url": "ws://prod-host:3000/ws",
      "tls_ca": "/path/to/cert.pem",
      "metrics_interval_ms": 500,
      "processes_interval_ms": 2000
    }
  },
  "version": 0
}
```

**Files Updated:**
- `docs/src/usage/connection-profiles.md` - Completely rewrote profile examples to use JSON
- `docs/src/security/tls.md` - Fixed profile examples
- `docs/src/security/token.md` - Fixed profile examples and file paths

**Note:** Many examples in connection-profiles.md still need updating (see "Remaining Issues" below).

---

### 5. Protocol Description ✅ FIXED

**Issue:** Documentation claimed WebSocket protocol uses Protocol Buffers.

**Actual Protocol:** JSON over WebSocket (as stated in README: "Remote monitoring via WebSocket (JSON over WS)")

**Files Updated:**
- `docs/src/introduction.md` - Changed "Protocol Buffers" to "JSON"

---

### 6. Demo Mode Documentation ✅ ADDED

**Issue:** Documentation did not mention the built-in demo mode feature.

**Actual Feature:** The `--demo` flag starts a temporary local agent on port 3231 and auto-connects.

**Files Updated:**
- `docs/src/installation/quick-start.md` - Added "Option 3: Demo Mode" section
- `docs/src/usage/general.md` - Added "Demo Mode" as first usage option
- `docs/src/introduction.md` - Added demo mode to features and quick start section

**Key Information Added:**
- `socktop --demo` launches temporary agent on port 3231
- Agent stops automatically when you quit
- Interactive profile selection menu includes built-in `demo` option
- Perfect for testing, learning, and demos without agent setup

---

## Remaining Issues (Known)

### Connection Profiles Documentation

The file `docs/src/usage/connection-profiles.md` still contains many TOML examples that should be JSON:

- Lines ~233-243: Production server examples
- Lines ~265-274: Refresh rate examples (also using wrong option names)
- Lines ~280-287: Environment variable examples
- Lines ~293-302: Template examples
- Lines ~309-319: Raspberry Pi cluster examples
- Lines ~329-339: AWS examples
- Lines ~349-359: Datacenter examples
- Lines ~372-401: Troubleshooting section references

**Recommendation:** These should be converted to JSON format or removed in favor of simpler examples.

### Configuration Documentation

The file `docs/src/usage/configuration.md` may reference TOML in the configuration hierarchy section (line ~9).

---

## Verification Checklist

Before deploying documentation:

- [ ] All `--refresh-rate` references removed
- [ ] All `--ca-cert` changed to `--tls-ca`
- [ ] All `--no-verify-tls` references updated to explain proper behavior
- [ ] All TOML profile examples converted to JSON
- [ ] All file paths reference `.json` not `.toml`
- [ ] GPU dependencies mentioned in all installation paths
- [ ] TLS documentation explains auto-generation as primary method
- [ ] Protocol description says JSON, not Protocol Buffers

---

## Testing Recommendations

1. **Verify actual command-line options:**
   ```bash
   socktop --help
   socktop_agent --help
   ```

2. **Verify profile format:**
   - Create a profile using `--profile` flag
   - Check `~/.config/socktop/profiles.json` format

3. **Verify TLS auto-generation:**
   - Run `socktop_agent --enableSSL --port 8443` on a fresh system
   - Confirm certificate is auto-generated
   - Check certificate location matches documentation

4. **Verify GPU dependencies:**
   - Test installation without `libdrm-dev libdrm-amdgpu1`
   - Confirm whether GPU metrics fail or if they're truly required

---

## Lessons Learned

1. **Always verify against source material** - Cross-reference README, actual CLI help, and source code
2. **Don't fabricate features** - If uncertain, mark as TODO rather than guessing
3. **Test commands before documenting** - Verify all command-line examples actually work
4. **Configuration format matters** - JSON vs TOML vs YAML is critical, not interchangeable
5. **Auto-generated features should be documented as such** - Don't make users do manual work when automation exists

---

## References

- Official README: https://github.com/jasonwitty/socktop/blob/master/README.md
- Actual implementation should always take precedence over documentation