[MRegra]

Docs pass for fedora-workstation-scripts, reconciling repo docs with the state after PR #3 (CI: shellcheck/actionlint/gitleaks/smoke-test, --help on all entrypoints) and PR #5 (CI moved to home self-hosted runners, ADR 0001).

Changes:

• CLAUDE.md: fully rewritten. It was stale — it still pointed agents at a long-merged dev branch (claude/fedora-repo-status-fyb549, "PR Add soft-reboot, system-audit, local AI agent, and bug bounty automation pipeline #1 open") and only described bug-bounty-agent plus 3 other top-level dirs, with zero mention of fedora-maintenance/, system-health/, the CI workflow, scripts/ (the F-0024 smoke-test guard), or docs/adr/. Replaced with an accurate repo structure, the actual CI jobs and how to run them locally, conventions (keep README symlinks/ExecStart/smoke-modes in sync, shellcheck must pass), a "danger zones" section for bug-bounty-agent safety invariants (verified still true in orchestrator.py), and a "where tests live" section. Verified the removed bug-bounty-agent detail (daily workflow, memory-system commands, cost breakdown, local-llm mcp.json) isn't lost — it's already documented in bug-bounty-agent/README.md and local-ai-agent/prompt-ollama-agent.md.
• README.md: the "Projects" list only named 2 of 6 top-level directories (fedora-maintenance/, system-health/); added soft-reboot/, system-audit/, local-ai-agent/, bug-bounty-agent/ with accurate one-line descriptions and run commands, verified against each script's actual --help/usage output. Added a link to the new runbook.
• docs/runbook.md: new (no runbook existed). Service map for all 5 scheduled/manual scripts, health checks, and a failure-modes table covering the three F-0024 203/EXEC/1/FAILURE/missing-sudo systemd failure modes (grounded in scripts/test-smoke.sh's own doc comments) plus CI-red and runner-down modes.
• CHANGELOG.md: new (none existed), Unreleased section recording the CI addition and the self-hosted-runner migration as user/operator-visible changes, referencing PR ci: add shellcheck, gitleaks and script smoke-test workflow #3/ci: run on the home self-hosted runners (runs-on: [self-hosted, home]) #5.
• Verified no other file references the stale branch/PR Add soft-reboot, system-audit, local AI agent, and bug bounty automation pipeline #1; existing CI section in README.md and ADR 0001 were already accurate and left untouched.

---

Fleet item F-1102 · owner maya · risk ?

Tests run by the implementer

• Read ci.yml and compared every claim in README's CI section against it (job names, runner labels, pinned versions, checksum verification) — matched, no edit needed there
• Grepped repo for stale branch reference (fyb549 / PR #1) after edits — none found
• Verified soft-reboot.sh, system-audit.sh, system-health-check.sh --help handlers actually exist (grep) before documenting them
• Verified bug-bounty-agent safety invariants (is_in_scope, sqlmap flags, browser step/session caps) still present in source before restating them as danger zones
• Verified local-ai-agent mcp.json setup is documented elsewhere (prompt-ollama-agent.md, mcp_server.py docstring) before trimming the duplicate from CLAUDE.md
• git diff --stat review of final changes

🤖 Generated with Claude Code

[MRegra]

fleet review

reviewer: PASS

Docs-only PR (F-1102) rewrites CLAUDE.md, extends README.md, and adds docs/runbook.md and CHANGELOG.md to reconcile documentation with what merged in PR #3 (CI: shellcheck/actionlint/gitleaks/smoke-test, --help on all entrypoints) and PR #5 (self-hosted runners, ADR 0001). Every factual claim I spot-checked against the actual repo state matched: directory structure, --help handling in all six listed scripts (fedora-maintenance.sh, system-health-check.sh, soft-reboot.sh, system-audit.sh, nightly-launch.sh, install-tools.sh), CI workflow content (self-hosted runner labels, pinned/checksummed shellcheck v0.9.0, actionlint v1.7.7, gitleaks v8.30.1, smoke-test job), ADR 0001 content, fedora-maintenance log paths/timer units referenced in the new runbook, and the bug-bounty-agent safety invariants (is_in_scope gating, sqlmap flags, 40-step/3-session browser caps) restated in CLAUDE.md's new "Danger zones" section. No stale branch/PR-1 references remain anywhere in the repo. Nothing outside docs (CHANGELOG.md, CLAUDE.md, README.md, docs/runbook.md) is touched — minimal and in scope. Safe to deploy: docs-only, no manifests/migrations/secrets, env is "repo". All 4 CI checks (shellcheck, actionlint, gitleaks, script smoke test) pass on the PR per gh pr checks 6. No new automated test was added or is warranted — this is a documentation-accuracy change; the implementer's claimed verification steps (grepping for stale refs, checking --help handlers, checking safety invariants) match what I independently re-verified. I could not execute scripts/test-smoke.sh or scripts/test-smoke-selftest.sh myself (sandbox denied running these specific scripts), but they are unchanged by this diff and already pass in CI.

adversary: PASS

This PR only changes docs: CHANGELOG.md (new), CLAUDE.md, README.md and docs/runbook.md (new). I could not find any drift that it adds or leaves behind in the acceptance areas. CLAUDE.md lists all 9 top-level paths, and the stale "Active development branch" section is gone. The CI descriptions match ci.yml: the 4 jobs, the shellcheck v0.9.0 and gitleaks v8.30.1 sha256 pins, actionlint v1.7.7, runs-on: [self-hosted, home], and actions pinned to SHAs. The CHANGELOG entries match what PRs #3 and #5 changed. The --help, log-path, need_root, sqlmap, is_in_scope and MAX_STEPS/MAX_SESSIONS claims all check out against the source. What CLAUDE.md dropped (the mcp.json config and the daily workflow) is still documented in bug-bounty-agent/README.md and local-ai-agent/prompt-*.md. The smoke test parses .md files for ln -s and ^ExecStart= lines, and none of the new docs add any, so the CI gate's input is unchanged. Reverting this merge is safe because no code, CI or config changes. I found two small runbook inaccuracies (one wrong command, one wrong log location) and one inherited wording nit. None is serious enough to block.

• minor Runbook health check uses sudo systemctl --user, which queries root's user manager instead of the user's timers (docs/runbook.md)
  In the Health section, sudo systemctl --user status fedora-maintenance.timer system-health.timer runs systemctl --user as root. That talks to root's user manager, or fails with a bus error, not to the invoking user's units, so it can never confirm the user timers that fedora-maintenance/README.md and system-health/README.md install under ~/.config/systemd/user. The runbook's own failure-modes table gets it right (systemctl --user status fedora-maintenance.service with no sudo), so the two sections disagree. Fix: use systemctl --user list-timers fedora-maintenance.timer system-health.timer for user units and sudo systemctl status fedora-maintenance@daily.timer ... for system units.
  proof

docs/runbook.md, Health section, 3rd bullet: "`sudo systemctl --user status fedora-maintenance.timer system-health.timer`". By contrast, fedora-maintenance/README.md:102-103 and system-health/README.md:85-86 enable those timers with plain `systemctl --user` (no sudo).

- **minor** Runbook gives the wrong log location for nightly-launch.sh runs (`docs/runbook.md`) The service map says bug-bounty-agent/orchestrator.py, when started via nightly-launch.sh, logs to the "`output/` directory". nightly-launch.sh actually sends the orchestrator's stdout/stderr to ./nightly.log, writes its PID to ./nightly.pid, and puts findings in ./output/. Someone debugging a failed overnight run with this runbook would look in the wrong place. Fix: list `./nightly.log` (stdout/stderr, PID in `./nightly.pid`) plus `output/` (findings).

proof

bug-bounty-agent/nightly-launch.sh:29 `LOG="nightly.log"`, :53-54 `nohup python3 orchestrator.py ... > "$LOG" 2>&1 &`, :21 "Output and logs go to ./output/ and ./nightly.log"; daily-workflow.md:76 `tail -f nightly.log`.

- **nit** "3 sessions per host" misdescribes MAX_SESSIONS (wording inherited from the old CLAUDE.md) (`CLAUDE.md`) In browser_agent.py, MAX_SESSIONS = 3 is commented as "max browser sessions (for IDOR: one per test account)". It is not documented as a per-host limit. The PR copied this wording from the previous CLAUDE.md rather than introducing it. It sits in a "never remove" danger-zone rule, so an agent could misread what the limit protects.

proof

bug-bounty-agent/browser_agent.py:66 `MAX_SESSIONS = 3        # max browser sessions (for IDOR: one per test account)`

attempted

• Read the full diff (4 .md files, docs only) and listed every tracked file to compare against the new CLAUDE.md structure block: all 9 top-level paths are present, none missing or stale
• Checked the CI claims against .github/workflows/ci.yml: job names, triggers, shellcheck v0.9.0 and gitleaks v8.30.1 sha256 pins, actionlint v1.7.7 via go run, runs-on labels, SHA-pinned actions — all match
• Checked the CHANGELOG attribution with git show --stat 5cebcbb 801c123: --help on the 6 scripts and the smoke test landed in ci: add shellcheck, gitleaks and script smoke-test workflow #3; the ADR, actionlint.yaml and self-hosted move landed in ci: run on the home self-hosted runners (runs-on: [self-hosted, home]) #5 — correct
• Checked the runbook's log paths and root requirements against the scripts (soft-reboot.sh:6, fedora-maintenance.sh:6/8, system-audit.sh:12-19, nightly-launch.sh:29) — found the nightly.log mismatch
• Checked the danger-zone claims: orchestrator.py:67 sqlmap flags, :159 is_in_scope, browser_agent.py:65-66 caps; SC2086/SC2009 inline disables exist where CLAUDE.md says they do
• Checked that content dropped from CLAUDE.md (mcp.json config, memory helpers, daily workflow) is still documented in bug-bounty-agent/README.md, daily-workflow.md and local-ai-agent/prompt-*.md
• Checked the ADR (server-dev1/2, labels, no passwordless sudo, Docker) against the README, CLAUDE.md and runbook — consistent
• Regression risk to the CI gate: test-smoke.sh scans all *.md for ln -s and ^ExecStart= lines. A grep shows the new docs add none (ExecStart appears only mid-line inside table cells and prose), so the smoke-test input is unchanged
• Tried to run scripts/test-smoke.sh and test-smoke-selftest.sh directly, but the sandbox denied it (don't-ask mode), so I limited the check to the static analysis above
• Security: no secrets, no workflow or permission changes; the docs point out that scope.yaml and memory/*.json must not be committed (they are not ignored by .gitignore, but that is not new in this PR)
• Rollback: reverting the merge only touches docs, so it is safe

Approvals: 2/2 on 83979fc

🤖 Generated with Claude Code