[MRegra]

Summary

• The repo layout (fedora-maintenance/, system-health/, soft-reboot/, system-audit/, local-ai-agent/, bug-bounty-agent/, scripts/) is already correctly reflected in README.md/CLAUDE.md/docs/runbook.md from the prior docs pass (fix: Docs pass for fedora-workstation-scripts (2026-10-04) #6) — verified against the actual directory tree, nothing to fix there.
• Found a real gap: the portfolio status page recorded that both the fedora-maintenance and system-health systemd user units on the owner's workstation were failing with status=203/EXEC because their ExecStart= still pointed at the pre-reorg flat script paths, not the current fedora-maintenance//system-health/ subdirectory paths. The repo's own runbook only had this as a generic hypothetical row, not a known issue grounded in what was actually observed.
• Added a "Known issues" section to docs/runbook.md documenting this concretely (what failed, why current README examples avoid it, and the fix), linked it from the README's "Operating the scripts" section, and recorded it in CHANGELOG.md.

Test plan

• Diffed repo layout against README.md/CLAUDE.md claims — matches
• Reviewed all ExecStart=/ln -s references across README.md, CLAUDE.md, docs/runbook.md, fedora-maintenance/README.md, system-health/README.md for internal consistency
• Docs-only change (git diff --stat: CHANGELOG.md, README.md, docs/runbook.md)

🤖 Generated with Claude Code

---

Fleet item F-1159 · owner maya · risk low

Tests run by the implementer

• git diff --stat (3 files, docs only)
• ls fedora-maintenance system-health soft-reboot system-audit local-ai-agent bug-bounty-agent scripts docs/adr .github/workflows — verified actual layout matches README/CLAUDE.md claims
• grep -rn ExecStart across repo — verified README/runbook/CLAUDE.md systemd examples are internally consistent and use the symlink indirection

🤖 Generated with Claude Code

[MRegra]

fleet review

reviewer: PASS

Docs-only PR adds a 'Known issues' section to docs/runbook.md (plus matching CHANGELOG entry and a one-line README pointer update) documenting that systemd units created before the fedora-maintenance/ / system-health/ reorg can still point ExecStart= at the old flat repo paths and fail with status=203/EXEC. Verified every factual claim against actual repo state: fedora-maintenance/ and system-health/ subdirectories exist with their scripts; both subdir READMEs have a '## Setup (symlinks)' section; scripts/test-smoke.sh exists and is the F-0024 regression guard already referenced elsewhere in the runbook; root README's 'Quick setup (symlinks)' section matches the fix described. Acceptance criterion 1 (README/docs reflect current directory layout) was already satisfied by the prior PR (#6, already merged) — this PR adds the remaining piece, criterion 2 (known-issue doc). Criterion 3 (docs-only PR) holds: diff touches only CHANGELOG.md, README.md, docs/runbook.md. CI (shellcheck, actionlint, gitleaks, script smoke test) is green on the PR. No regression test applies since this is prose documentation of an operational known issue, not a behavior change, consistent with fleet:documentation guidance for docs-only changes.

attempted

• git diff origin/main...HEAD and --stat
• ls fedora-maintenance/ system-health/ to confirm subdirectory layout
• grep for 'Setup (symlinks)' headings in both subdir READMEs
• grep for F-0024/203/EXEC/ExecStart references across scripts/test-smoke.sh, docs/runbook.md, CHANGELOG.md
• read README.md in full to confirm directory-layout and symlink-setup sections already present pre-PR
• gh pr checks 7 -R MRegra/fedora-workstation-scripts (all 4 jobs pass)
• attempted bash scripts/test-smoke.sh locally - denied by sandbox ('don't ask mode'); not needed since CI already ran and passed this exact check

adversary: PASS

I couldn't break this. The PR only touches docs: README.md, docs/runbook.md and CHANGELOG.md. All three acceptance criteria are met: the README matches the current layout, the pre-reorg ExecStart issue is written up as a known issue, and nothing outside docs changed. Every cross-reference in the new text points at something that exists: both subdirectory READMEs have "Setup (symlinks)" and "Automation" sections, the root README has "## Quick setup (symlinks)", and the documented units start the scripts through the /usr/local/bin symlinks. The main risk was the smoke test, because scripts/test-smoke.sh reads every *.md file for ^ExecStart= lines and ln -s lines. The new text quotes ExecStart=.../fedora-workstation-scripts/fedora-maintenance.sh, but only indented inside backticks, so the /^ExecStart=/ pattern doesn't pick it up and it adds no ln -s lines. CI should parse the docs the same as before. I could not run the smoke test itself because the sandbox refused to run scripts, so that conclusion comes from reading the regexes. Reverting the merge is safe since no code changes. I found two accuracy nits and no blocker or major issues.

• nit The 'old README' wording doesn't match the history; the real old install (fedora-hygiene) isn't covered (docs/runbook.md)
  Line 50 says stale units may have been "hand-written against an old README". No README in the git history ever documented an ExecStart that runs .../fedora-workstation-scripts/fedora-maintenance.sh directly. The README just before the reorg commit (5951800^:README.md) installed a copy with sudo install -m 0755 .../update-system.sh /usr/local/bin/fedora-hygiene and used fedora-hygiene@.service units with ExecStart=/usr/local/bin/fedora-hygiene %i. Someone who followed that README won't get 203/EXEC. They'll quietly keep running an old copy of the script under a different name, and the new known-issue doesn't mention that. Suggestion: drop the 'old README' clause, or add one line about leftover fedora-hygiene installs.
  proof

`git log --all --oneline -S "fedora-workstation-scripts/fedora-maintenance.sh"` returns only 4ac1ec3 (this PR) and 5cebcbb (the smoke-test comment), never a README. `git show 5951800^:README.md` shows `sudo install -m 0755 /home/marcelo/dev/fedora-workstation-scripts/update-system.sh /usr/local/bin/fedora-hygiene` and `ExecStart=/usr/local/bin/fedora-hygiene %i`.

- **nit** The fix steps don't cover a broken symlink that is still in place (`docs/runbook.md`) The fix says to point ExecStart at the symlink and to 're-create the symlink if missing' using the root README's `ln -s` lines. A symlink made by hand before the reorg is not missing. It is broken: it still exists but points at the old flat path. The README's `ln -s` (no `-f`) then fails with 'File exists', and the unit keeps failing with 203/EXEC through the broken link. Suggestion: say 're-create the symlink if it is missing or broken (`ln -sfn ...`)'. Impact is low because no README ever told anyone to create such a symlink.

proof

Pointed out from the text, not run (the sandbox refused to run scripts). README.md:25-33 use plain `ln -s`, and plain `ln -s` refuses to replace an existing destination, including a broken symlink.

attempted

• Read the full diff (3 files, docs only, no scripts/workflows touched)
• Checked the new runbook/README/CHANGELOG text against scripts/test-smoke.sh: Grep for ^ExecStart= and ln +-[A-Za-z]*s in the changed files found no new matches, so the README-driven systemd checks see the same input as before
• Tried bash scripts/test-smoke.sh, but the sandbox refused to run it, so I checked the parsing statically instead
• Verified the cross-references: fedora-maintenance/README.md and system-health/README.md both have 'Setup (symlinks)' and 'Automation' sections, every documented ExecStart uses /usr/local/bin/, and the root README has '## Quick setup (symlinks)'
• Went through git history (5951800 reorg, 0a216b1, 5951800^:README.md) to check the claims about the old flat paths and old README; both nits come from this
• Rollback: a revert is safe because the change is docs only
• Security: no secrets, no workflow, permission or CI changes

Approvals: 2/2 on 4ac1ec3

🤖 Generated with Claude Code