fix: stop publishing agent working files on the public docs site

[GeiserX]

Found while researching the docs-navigation bead. This is live right now, which is why it is a fix rather than a bead.

What is public today

MkDocs builds every file in docs_dir, whether or not it appears in nav. Three agent scratch files sat there, so they were published:

https://geiserx.github.io/CashPilot/GOAL/               -> HTTP 200
https://geiserx.github.io/CashPilot/AUTOPILOT-WORKLOG/  -> HTTP 200

Neither appears in any menu. Between them they publish:

• This project's internal planning, verbatim — including a directive quoted word-for-word and design decisions attributed by name
• A real Mysterium node identity address (0x55fd…), which links this public repository to a specific earning node
• 489 lines of agent worklog, including which PRs were awaiting review and why

That last one is the reason I did not just file this: an on-chain identity is not a secret, but publishing it next to the repo that describes the fleet it belongs to is a linkage that did not exist before.

It also contradicts the project's own documentation rule, that docs state intent rather than quoting or attributing what any person said.

Why --strict would not have saved us

This is the counterintuitive part and worth recording. MkDocs reports the orphans — but at INFO:

INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
   - growth-strategy.md
   - guides/proxybase-xyz.md
   - research/idle-network-traffic.md
   - research/per-ip-device-limits.md

validation.nav.omitted_files defaults to info, and --strict only promotes warn to an error. So a --strict build stays green with these published. Exclusion has to be explicit.

(Note what else that output reveals: guides/proxybase-xyz.md is orphaned too — and the catalog marks that service active. Tracked separately in the docs-nav bead.)

The change

An exclude_docs block, with the reasoning recorded beside it so a later tidy-up does not delete it as unexplained.

Evidence

Built the site for real (mkdocs 1.6.1, from docs/requirements-docs.txt):

pages built	64
GOAL, AUTOPILOT-WORKLOG, DEFERRED-QUESTIONS	excluded
homepage, getting-started, guides/honeygain	intact

Negative control: removing the exclude_docs block and rebuilding makes all three reappear in the output — so the block is what is doing the work, not an accident of the build.

9 regression tests. The guard is not "these three names are listed" — it also fails for any new agent-looking file dropped into docs/ (*WORKLOG*, *-STATE, NOTES, …), so the next one is caught rather than published. Removing the block fails all 9.

Gates: ruff clean, 3287 passed, 95.44% coverage.

Not done here, deliberately

The files are excluded from the site, not deleted from the repo — that is a separate decision about whether agent artifacts belong in docs/ at all, and deleting content is not something to do quietly inside a publishing fix.

Summary by CodeRabbit

• Documentation
  • Removed internal planning/worklog documents from the published docs set.
  • Updated site configuration so these files are no longer exposed in the documentation output.
• Tests
  • Added checks to ensure internal agent-related files stay out of published docs and aren’t accidentally committed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f7ade590-9728-4a8f-8223-41ae08c1e1b4

📥 Commits

Reviewing files that changed from the base of the PR and between 325ee40 and ca89a15.

📒 Files selected for processing (5)

• .gitignore
• docs/AUTOPILOT-WORKLOG.md
• docs/GOAL.md
• mkdocs.yml
• tests/test_docs_never_publish_agent_files.py

💤 Files with no reviewable changes (2)

• docs/AUTOPILOT-WORKLOG.md
• docs/GOAL.md

---

📝 Walkthrough

Walkthrough

The change removes agent working documents, ignores related files, excludes them from MkDocs output, and adds tests for publication, Git tracking, and exclusion documentation.

Changes

Agent artifact controls

Layer / File(s)	Summary
Repository and publication boundaries .gitignore, docs/GOAL.md, docs/AUTOPILOT-WORKLOG.md, mkdocs.yml	Agent working documents are removed from docs/. Matching files are ignored by Git and excluded from MkDocs output.
Automated artifact enforcement tests/test_docs_never_publish_agent_files.py	Tests parse exclude_docs, check known and newly added agent files, verify Git ignore and tracking state, and require documentation of the exclusion rule.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing agent working files from appearing on the public documentation site.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/stop-publishing-agent-scratch-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}