docs: correct the parse_declared ordering claim

The doc said callers could pair the result positionally with `discover`'s
specs for the same file. They cannot: `resolve_spec` returns `Ok(None)` for
any node failing `looks_like_spec`, so specs are a subset of parsed nodes.
`validate` never pairs positionally, so this is a doc fix only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
agent-session-id: 8464a883-6285-4cd0-a9ec-3eba09830300
agent-tool: Claude Code
agent-tool-version: 2.1.220
agent-model: claude-opus-5
agent-runtime-profile: /nix/store/i8y8b542cyqi385ywcjw5fvsq24f75v4-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/i81qxhzlrzcxrrdwpp6i8hagka2gby8y-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

Author: schickling-assistant

crates/agent-spec/src/discovery.rs

@@ -110,7 +110,8 @@ pub struct Declared {
 /// Read the declared (pre-lowering) values of every agent in a file — one per `agent` node for KDL,
 /// 0-or-1 for TOML/JSON, empty for a non-spec extension.
 ///
-/// Order matches [`discover`]'s specs for the same file, so a caller can pair them up positionally.
+/// One entry per parsed node, *including* nodes [`discover`] skips as non-specs, so this is not
+/// positionally paired with that file's [`Discovered::specs`].
 pub fn parse_declared(path: &Path) -> anyhow::Result<Vec<Declared>> {
     Ok(parse_raw_file(path)?
         .into_iter()