Documentation audit (post-v1.3.33, pre-public)¶

Status: Read-only audit produced 2026-04-26. Maps every documentation surface against the v1.3.20-v1.3.33 feature reality. Output drives the v1.3.34 doc-refresh release scope.

TL;DR¶

The good news: the release-process discipline shipped clean. Every tag has a release-notes file; the CHANGELOG covers every release. The bad news: the user-facing surfaces (README, the docs portal's overview + features + reference, the screenshots) all lag the past 13 releases by 1-2 weeks of intense feature work. Pre-public refresh is non-trivial.

Section 1 — Inventory¶

1.1 README.md¶

• Path: /README.md
• Last edit: 2026-04-20 (commit 137d424 — BSL license + GitHub repo metadata)
• Size: 11587 bytes
• Status line: "v1.0.0 — first stable release" (badge link works; status text 12+ releases stale)
• Phase-language: still present (Phase 4, Phase 6 — pre-stable terminology)
• v1.3.X mentions: zero
• Quickstart functionality: looks correct (docker compose up -d); not re-verified since v1.0
• Verdict: STALE-CRITICAL for public release

1.2 docs/ tree (97 files)¶

docs/
├── index.md                          (overview, hero shot)
├── overview.md                        (mode matrix)
├── phase1-dns.md                      (legacy; not in nav)
├── CONTRIBUTING.md
├── architecture/  (4 pages)           (last touch 2026-04-20)
├── features/      (14 pages)          (last touch 2026-04-25 = v1.3.19)
├── getting-started/ (3 pages)         (last touch 2026-04-21)
├── internals/     (2 pages)           (deep-dives, not nav)
├── operations/    (11 pages)          (last touch 2026-04-26 = v1.3.32)
├── planning/      (3 pages)           (deferred features; not in nav)
├── reference/     (4 pages)           (last touch 2026-04-21)
├── release-notes/ (40+ files)         (100% tag coverage)
├── screenshots/   (23 PNGs + README)
├── tls/           (1 page)
└── workflows/     (7 pages)           (last touch 2026-04-21)

1.3 CHANGELOG.md¶

• Format: Keep a Changelog v1.1.0; valid 34 entries
• v1.3.20-v1.3.33 entries: ALL present
• Special markings preserved: v1.3.20 - INCOMPLETE FIX (audit trail of the failed first attempt at country-block) — good
• Verdict: OK

1.4 docs/release-notes/¶

100% coverage of every git tag. Verified files for: v1.0.0, v1.0.1, v1.1.0, v1.1.1, v1.2.0, v1.3.0 through v1.3.33, v1.3.27.1, plus prereleases under prereleases/. Verdict: OK.

1.5 Screenshots¶

23 files in docs/screenshots/ (the duplicates in site/screenshots/ are mkdocs build artifacts):

22/23 are real, 1 is the documented placeholder. Verdict for freshness: every one captures a UI surface from pre-v1.3.20. None of the post-v1.3.20 features (drift indicators, Scenarios tab tooltip, AppSec tuning tab, true_detect_mode checkbox, async country expansion progress bar, reconciler state column, scenario descriptions ⓘ glyph) is photographed.

1.6 CLAUDE.md¶

• Path: /CLAUDE.md
• Last edit: 2026-04-18 (commit 44f5c3c — initial scaffolding, phase 0 architecture)
• Phase-language: "Si estamos en Fase 0..." — pre-stable
• References: "Lee ARCHITECTURE.md antes de cualquier cambio estructural" — but /ARCHITECTURE.md does not exist at root anymore
• v1.3 features mentioned: zero
• Eight-strike pattern: not surfaced
• Reverse-sentinel pattern: not surfaced
• Async-job pattern: not surfaced
• Verdict: STALE-CRITICAL for future Claude sessions (memory system in ~/.claude/projects/.../memory/MEMORY.md IS up-to-date, but CLAUDE.md is the human-facing project brief that any new Claude session reads first)

1.7 Architecture diagrams¶

4 pages in docs/architecture/, all last edited 2026-04-20: - components.md (3 containers, 1 docker network) — PRE-DATES the panel sub-services that shipped after: drift detector goroutine, country JobRunner, country Reconciler. The "what runs inside the panel container" picture is incomplete. - request-flow.md — should still be roughly correct (request hits Caddy → bouncer → AppSec → upstream); doesn't reflect the reverse-sentinel data flow nor the panel-side reconciler ticks. - storage.md — covers the SQLite tables; MISSING country_expansion_jobs (v1.3.31), country_ban_expansions.state column (v1.3.33), appsec.scenarios.drift_state / appsec.tuning.drift_state settings rows (v1.3.27). - threat-model.md — should be roughly correct; the eight-strike-pattern lessons learned about LAPI shape collisions could fit here as "operational caveats".

All four contain mermaid blocks; the diagrams need re-render for the v1.3.20-v1.3.33 additions.

Section 2 — Gap analysis (feature → doc coverage)¶

Smoke scripts as documentation¶

13 smoke scripts in scripts/smoke/ — each carries an extensive header comment documenting what it tests, the EFFECT it verifies, the env vars, exit codes, and reproduction instructions. Verdict: well-documented at the script level. Cross-reference from a docs/operations/smoke-suite.md would help discovery, but the in-script docs are sufficient for the operator who finds them.

docs/reference/api.md (the single biggest gap)¶

Result: docs/reference/api.md is roughly v1.3.20-era and needs a full sweep to add v1.3.21-v1.3.33 endpoints + remove the (likely-stale) sync-shape POST /api/security/countries/expand entry that v1.3.31 replaced.

Section 3 — Screenshot inventory (UI surface → has-screenshot)¶

Net new captures needed for v1.3.34: ~10 (the missing rows above). Net re-takes for stale-shape: ~3 (host-form, appsec-status, threats-decisions).

Section 4 — Priority recommendations¶

CRITICAL (blocker for public release)¶

1. README.md rewrite [M, ~1-2h]
2. Status line: drop "v1.0.0 first stable release"; replace with a feature-list paragraph that mentions drift detection, async country expansion, true_detect_mode, scenario descriptions, async-job pattern.
3. Drop phase-language; the project shipped v1.3.33 weeks ago.
4. Add a short feature matrix or bullet list pointing at the docs portal sections.

5. Verify quickstart still works with current .env.example.

6. CLAUDE.md refresh [S, ~30min]

7. Drop "Fase 0" language; project is at v1.3.33.
8. Drop the "Lee ARCHITECTURE.md" line (file doesn't exist).

9. Surface the eight-strike pattern + reverse-sentinel + async-job patterns at one-line-each density. Cross-link to the project memory in ~/.claude/.../memory/MEMORY.md for the full writeups.

10. docs/reference/api.md sweep [L, ~2-3h]

11. Add v1.3.25-v1.3.33 endpoints (scenarios, appsec-tuning, drift, countries/{cc}/expand, jobs).
12. Remove or correct the v1.3.20-era body-based country expand entry (replaced by path-based in v1.3.31).
13. Verify every documented response shape against the current handler. The note at the top says "Authoritative source: backend/internal/server/server.go" -- that's still the contract, but docs/reference/api.md should not lag the code.

HIGH (quick post-public win, days/weeks)¶

1. docs/architecture/components.md update [M, ~1h]
2. Add the panel-side sub-services (drift detector goroutine, country JobRunner + worker mutex, country Reconciler 5-min ticker).

3. Mermaid diagram refresh.

4. docs/architecture/storage.md update [S, ~30min]

5. Add country_expansion_jobs (v1.3.31).
6. Add country_ban_expansions.state column (v1.3.33).

7. Add settings keys for drift state (v1.3.27).

8. New docs/features/drift-detection.md [M, ~1h]

9. 60s reconciler ticker.
10. GET /api/security/drift response shape.
11. DriftBanner + per-tab dots UI.

12. Operator action when drift detected.

13. New docs/features/country-bans.md [M, ~1h]

14. Path-based POST endpoint.
15. 202 + job-polling flow.
16. Reconciler state field.

17. Operator workflow + the v1.3.31-era flush-cap caveat (now resolved by v1.3.33).

18. Re-take ~10 missing screenshots [M, manual; ~1-2h elapsed]

19. Banned IPs / Whitelist / Activity / Scenarios / AppSec tabs in /security.
20. Drift indicators (induce drift via cscli mutation).
21. Country bans async progress bar (mid-expansion shot).
22. Host edit modal with true_detect_mode checkbox.

23. DETECT badge on the hosts list.

24. Update docs/features/crowdsec.md for new scope [S, ~30min]

25. Note the LAPI WAL config (v1.3.28).
26. Mention the country reconciler.
27. Cross-link the alert-shape lesson (v1.3.33).

LOW (eventual polish)¶

1. docs/operations/smoke-suite.md [S, ~30min]

   • Cross-reference all 13 smoke scripts in one page so operators discover them without scanning the directory.
   • Each entry: smoke name, what it asserts, when to run it.

2. docs/internals/patterns.md [M, ~1h]

   • Reverse-sentinel pattern (v1.3.30).
   • Async-job pattern (v1.3.31).
   • Eight-strike upstream-behaviour memo (excerpted from ~/.claude/.../memory/).

3. Re-take host-form.png + threats-decisions.png + appsec-status.png [S, manual]

   • Stale-shape captures of UI that meaningfully changed.

Suggested v1.3.34 doc-refresh release scope¶

Option A — single bundled release (recommended): - Items 1, 2, 3 (the three CRITICAL items) — ~4-6h - Items 4, 5, 6, 7 (HIGH architecture + 2 new feature pages) — ~3-4h - Item 8 (screenshots — ~10 captures) — ~1-2h elapsed (operator-mediated) - Item 9 (crowdsec.md polish) — ~30min

Total estimated effort: ~10-12h focused work + ~2h operator-mediated screenshot capture. Single ship v1.3.34, tagged as a "documentation refresh" release with no panel binary change (precedent: v1.3.27.1).

Option B — split (if preferred for incremental rollout): - v1.3.34: items 1, 2, 3 (CRITICAL only) — ~4-6h. Public release unblocked. - v1.3.35: items 4, 5, 6, 7, 8, 9 (HIGH + screenshots) — ~5-7h + 2h. Post-public polish.

Recommendation: Option A. The three CRITICAL items and the HIGH items overlap substantially — once you're in the API reference rewriting, you're 60% of the way through the features/ pages they reference. Bundling preserves momentum + keeps the public-release narrative consistent ("the docs match v1.3.33" rather than "the docs match v1.3.33 except for these gaps").

What this audit does NOT cover¶

• Internationalisation (the docs are English-only; no translation coverage)
• SEO / portal styling
• Per-page word-count for readability
• Mobile responsiveness of the mkdocs-material theme
• Frontend in-app help text / tooltips
• API client SDKs (none exist; argos doesn't ship one)

Recommendation: ready for public after v1.3.34?¶

The three CRITICAL items are blockers. Once they ship, the public-facing surface is consistent: README points at a docs portal whose API reference matches the binary, and CLAUDE.md guides future Claude sessions accurately. The HIGH items are post-public quality-of-life; the LOW items are polish.

Proposed sequence:

1. Ship v1.3.34 doc-refresh (items 1-9 bundled per Option A).
2. Tag, the v1.3.27.1 release workflow auto-publishes.
3. Operator does the 10-screenshot capture pass; commit as a single "docs(screenshots): post-v1.3.34 captures" commit.
4. Repo flips to public via gh repo edit --visibility public.
5. LOW items become open issues on the public repo.