docs: reconcile AGENTS.md hub guidance + add when-not-to-anchor caveat#134
Merged
Conversation
The guide had two adjacent, contradictory sections — "keep them separate" immediately followed by "you can fold claims in". Merge into one "Where claims can live" section that leads with the general rule (claims can live in any file added to the glob), then presents both approaches with the central hubs/ directory flagged as recommended. Also correct the frontmatter note: agent runners generally load AGENTS.md/CLAUDE.md as raw text and do NOT strip YAML frontmatter, so the anchors block is visible to the agent — framed as a real downside of the inline approach, not a non-issue. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
"Any file can be a hub" invites anchoring marketing prose. Add a subsection explaining why a README is a poor fit: coarse claims that over-anchor, duplication of hub prose, and GitHub rendering frontmatter as a metadata table above the pitch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #133. Those two commits landed on the branch after #133 merged, so they never reached
main; this PR brings them in cleanly off currentmain.Summary
#133 left the authoring guide with two adjacent, contradictory sections — "keep hubs and
AGENTS.mdseparate" immediately followed by "you can fold claims intoAGENTS.md". This reconciles them and adds a "when not to anchor" caveat.What changed
docs/guides/authoring-hubs.md— merged the two sections into one "Where claims can live" that leads with the general rule (claims can live in any file added to the glob), then presents both approaches with a centralhubs/directory flagged as the recommended default (### Recommended) vs. the inline option (### Alternative). Added a### When *not* to anchor a filesubsection usingREADME.mdas the counter-example: coarse claims that over-anchor, duplication of hub prose, and GitHub rendering YAML frontmatter as a metadata table above the pitch.docs/reference/configuration.md— broadened the wording to the general "claims can live in any file" principle and updated the cross-reference anchor to the renamed section.Frontmatter correction
#133 claimed "most agent runners ignore [frontmatter]". That's not reliably true — runners generally load
AGENTS.md/CLAUDE.mdas raw text and don't strip YAML frontmatter, so theanchors:block is visible to the agent. The guide now frames that as a real downside of the inline approach rather than a non-issue.Verification
cargo fmt --all --check— passsurf lint— 0 errors (13 pre-existing advisory coverage warnings, unrelated)surf check— all anchored spans match their stored hashes🤖 Generated with Claude Code