UNOFFICIAL/EXPERIMENTAL
Use this log when an agent or maintainer gets confused by the repo. Record the problem and the fix.
2026-06-30
Task: create the first agent/operator documentation layer for helm-expt.
Observed friction:
- Agent/operator guidance existed in several places but had no canonical start point under
docs/. - The public website was at risk of becoming cluttered with agent instructions.
- The catalog is large enough that agents need a read-only guide before touching generated chart evidence.
docs:verifyintentionally rejected new Markdown directories until the location was added to the verifier and doc map.
Fix:
- Created
docs/agent/with task, recovery, verification, catalog, and terms guides. - Recorded the rule that website pages stay for users and agent material lives in repo Markdown.
- Left catalog pages and generated chart evidence untouched.
Follow-up in the same pass:
- Added a Docs/FAQ website link to
docs/agent/README.mdso agents arriving through the public site can find the repo operating notes. - Added
docs/agent/human-agent-doctrine.mdto keep human and agent pages aligned without duplicating each other.
Follow-up:
- Improve verifier recovery messages in scripts.
- Add docs linting only after more real agent failures are observed.