Skip to content

v1.3.34 -- Documentation refresh (zero binary change)

A focused doc-refresh release. Closes the audit findings from docs/operations/documentation-audit.md (the v1.3.32 audit). Zero panel binary change; argosVersion and frontend/package.json deliberately stay at 1.3.33. Reuses the v1.3.27.1 / v1.3.32 precedent: tag-without-rebuild for tooling or doc-only changes.

Why

The audit found three CRITICAL surfaces stale: README.md (still said "v1.0.0 first stable release"), CLAUDE.md (still referenced nonexistent ARCHITECTURE.md and Phase 0 framing), docs/reference/api.md (zero mentions of any v1.3.27-v1.3.33 endpoint). Plus six HIGH items: the architecture pages didn't include the drift detector / country reconciler / JobRunner sub-services; two new features (drift detection v1.3.27, country bans v1.3.21+v1.3.31+v1.3.33) had no dedicated feature pages; features/crowdsec.md lagged the v1.3.25 scenarios management UI + the v1.3.28 WAL knob.

All eight items shipped in this release. The tenth audit item (screenshots) is the only deferred one — operator runs a dedicated capture session post-tag and commits as a follow-up.

What ships

Two new feature pages

docs/features/drift-detection.md. Full v1.3.27 walkthrough: how the 60s reconciler ticker works, the /api/security/drift response shape, the persisted appsec.scenarios.drift_state and appsec.tuning.drift_state settings rows, the DriftBanner + per-tab dot UI behaviour, the operator-action protocol when drift surfaces, what this replaced (the v1.3.25 mark-applied buttons), limitations. Cross-links to the drift-detection.sh smoke + the reconcilers-verify-what subsection in components.md.

docs/features/country-bans.md. Unified v1.3.21+v1.3.31+v1.3.33 narrative covering: why argos doesn't use scope=Country directly (the upstream-strike-#2 plugin gap), the v1.3.33 CAPI alert shape (1 alert with N decisions inside, vs the pre-v1.3.33 N-alerts-with-1-decision shape that hit flush.max_items: 5000), the v1.3.31 async submit+poll model with single-worker mutex + boot-time recovery, the v1.3.33 reconciler health check + state column, operator workflow, chunk-size tuning, MMDB-version drift caveat. Cross-links to the three smokes that verify each layer.

Four substantial rewrites

  • README.md — drops the stale v1.0.0 status line and the phase-language framing; replaces the long inline OIDC setup walkthrough with feature-list pointers to the docs portal. Adds explicit <!-- TODO: post-v1.3.34 capture session --> comments where screenshots will go.
  • CLAUDE.md — rewritten as v1.3.33-aware Claude Code onboarding. The eight-strike upstream-behaviour pattern, the reverse-sentinel pattern, the async-job pattern, bind-mount-inode discipline, the working-agreement + smoke-suite all surface as inline rules with cross-links to the full project memory entries. Drops the nonexistent-ARCHITECTURE.md reference.
  • docs/architecture/storage.md — adds country_expansion_jobs, country_ban_expansions.state, appsec.*.drift_state settings rows, v1.3.18+ hosts columns. New "Out-of-band sentinels" section documents both the v1.3.19+ panel→script direction and the v1.3.30 reverse-sentinel direction.
  • docs/architecture/components.md — internal-subsystems mermaid diagram now includes the drift detector + country JobRunner + country reconciler + public-IP detector. New "Reconcilers verify what" subsection. New "Smoke verification" subsection cross-references the per-feature smokes.

One swept reference page

docs/reference/api.md — old /api/threats/* table removed. New /api/security/* table is the consolidated surface for v1.3.21-v1.3.33: banned IPs, whitelist, activity, scenarios management (with description-tooltip enrichment from v1.3.30), AppSec tuning, drift detection, country bans (path-based v1.3.31 shape), top-level job polling. Hosts section gains v1.3.18+ field documentation (lan_only, true_detect_mode, tls_acme_ca_url, tls_challenge, tls_dns_provider). Mark-applied endpoints documented as retired.

One polished page

docs/features/crowdsec.md — updated panel role description; new "Scenarios management" subsection (v1.3.25 disable + sentinel + reload flow + drift detection); new "LAPI tuning" subsection (v1.3.28 WAL knob + the v1.3.31→v1.3.33 alert-shape lesson, with the explicit "v1.3.33 makes flush.max_items bumps unnecessary" note).

Two new feature pages and the documentation-audit page added to mkdocs.yml's nav so the docs portal renders them at:

  • /features/country-bans/
  • /features/drift-detection/
  • /operations/documentation-audit/

Smoke gate

This release ships no behavioural change so the standard live- stack smoke suite is N/A. The doc-refresh-specific gate is:

  • mkdocs build --strict — clean (the three planning-notes outside nav are intentional, same as prior releases)
  • scripts/check-no-personal-data.sh — clean (one operator- domain leak in CLAUDE.md caught + replaced during the pre-tag verification)
  • All cross-references in the two new pages resolve to existing anchors (added #reconcilers-verify-what anchor in components.md to support the cross-link)
  • README renders correctly in the GitHub UI preview (operator will visually confirm post-push)

Mid-impl gotchas (caught + fixed pre-tag)

  • Anchor mismatch with em-dashes. mkdocs-material's slugifier does not produce double-hyphen anchors from em-dashes (—). The first draft of the components.md ### Reconciler + drift-detector + JobRunner — what they verify heading produced an anchor that the cross-links from the two new feature pages didn't match. Fix: renamed the heading to ### Reconcilers verify what (anchor: #reconcilers-verify-what) — clean ASCII, predictable slugification.
  • Sanitization caught one CLAUDE.md operator-domain leak. The first draft of the sanitization rule paragraph used the operator's literal domain inline as an example of what NOT to use, which the sanitizer correctly flagged (recursion- paradox: a rule against operator-domain mentions cannot itself name the operator domain). Replaced with the generic phrasing "NO operator-specific domains/IPs/usernames in archivos committed".

Files changed

  • README.md (rewritten)
  • CLAUDE.md (rewritten)
  • docs/features/drift-detection.md (new)
  • docs/features/country-bans.md (new)
  • docs/features/crowdsec.md (polished)
  • docs/architecture/storage.md (table catalog + sentinels section updated)
  • docs/architecture/components.md (mermaid + reconcilers + smoke-verification subsections updated)
  • docs/reference/api.md (security/* swept)
  • docs/release-notes/v1.3.34.md (this file)
  • CHANGELOG.md, mkdocs.yml

NOT changed: backend/cmd/argos/main.go argosVersion stays at 1.3.33; frontend/package.json version stays at 1.3.33; no backend code; no frontend code; no migrations; no smokes.

Upgrade

This is a doc-only release. Operator action:

cd ~/argos-edge
git pull
# No make sync-prod required; no panel rebuild required.
# Optional: rebuild the docs portal locally to preview:
mkdocs serve

The docs portal at cmos486.github.io/argos-edge rebuilds automatically via the existing docs.yml workflow on the push to main; the release.yml workflow auto-publishes the v1.3.34 GitHub release object using this file as the body.

Known gap (audit item #8 — deferred)

Ten screenshots remain pre-v1.3.20 and need re-capture:

  1. /security/banned (Banned IPs tab)
  2. /security/whitelist
  3. /security/activity
  4. /security/scenarios (with the description tooltip ⓘ glyph)
  5. /security/appsec (threshold sliders)
  6. Drift indicators (banner + per-tab amber dot)
  7. Country bans Settings section (with async progress bar visible mid-expansion)
  8. Host edit modal showing the true_detect_mode checkbox
  9. DETECT badge on the hosts list (next to a host with true_detect_mode=true)
  10. SelfBlockBanner v2 (operator-IP banned scenario)

Plus three re-takes for stale-shape captures:

  • host-form.png (modal layout updated post-v1.3.29)
  • appsec-status.png (pre-v1.3.25 tuning UI)
  • threats-decisions.png (pre-v1.3.24 tab move; the screenshot still references the retired /threats URL)

The capture session is operator-mediated; ship as a follow-up commit titled docs(screenshots): post-v1.3.34 captures. The docs portal renders correctly without the captures (alt text documents what each image will show), so the screenshot gap is NOT a public-release blocker.

What this enables

After v1.3.34 + the screenshot follow-up commit, the repo is ready for gh repo edit cmos486/argos-edge --visibility public. The verification report (v1.3.32) attests to feature correctness; this release attests to documentation correctness. Together they close the public-launch gate.