fix: usage errors for stray flags, named parse failures, duplicate sources, spec-aligned broken links

[akeemjenkins]

Fixes the four open bug reports against v0.4.0. Every change has a regression test that was written first and failed before the fix, including a new end-to-end suite in cmd/okf that builds the binary and checks JSON envelopes and exit codes.

#31 index and list report an unknown flag as an I/O error

Commands that take no flags (index, list, graph, show, backlinks, init, and the bundle argument of search) now reject any dash-prefixed argument as a usage error: exit 4, code: 400, kind: usage, message unknown <cmd> flag: --nope. This matches what validate and lint already did.

#27 a markdown file without frontmatter fails the bundle with no filename

• The loader returns a typed bundle.ParseError carrying the bundle-relative path. Filesystem failures stay plain I/O errors.
• The CLI maps a parse failure to a validation error (exit 1) because OKF §11 requires every non-reserved .md file to carry frontmatter. The message now reads load bundle demo: parse README.md: no YAML frontmatter block found, and the envelope carries a hint pointing at §11.
• I/O and internal envelopes now fold the wrapped cause into message. The envelope only ever printed the outer message, so any cause that named a file was dropped.
• Hidden .md files are skipped the same way hidden directories already are.
• okf index loads the bundle before writing. Previously it wrote index files, swallowed the load error, and reported count: 0.

#29 duplicate sources id and duplicate footnote definition go unreported

Two new warning rules, both listed in okf schema output and SARIF rule metadata:

• okf/sources/id-duplicate for a sources[].id declared more than once
• okf/sources/footnote-duplicate for a [^label]: defined more than once

#26 broken links as ERROR, and footnotes inside code spans

• okf/links/broken is now a warning. Spec §6.1 says consumers MUST tolerate broken links and §11 says a bundle MUST NOT be rejected for them, so valid and the exit code no longer flip on one. The finding still surfaces for repair. README and exit-code docs updated to match.
• Footnote scanning masks fenced code blocks and inline code spans before matching, so documentation that shows [^id] as an example is no longer reported as a dangling reference. Masking preserves byte offsets, so line-start detection for definitions is unaffected.

Verification

go vet ./... && go test -race ./... && golangci-lint run ./...

All pass locally. Each issue's repro script was rerun against the built binary and produces the expected envelope and exit code.

Closes #26
Closes #27
Closes #29
Closes #31

Drafted with Claude Code, reviewed and tested locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DwzDaurgXen8UC19AeN6tU