[Docs]: Fix stale references, incomplete content, and benchmark number mismatches

[membphis]

Background

During a review of project-authored documentation, three issues were identified:

1. CLAUDE.md references a nonexistent README section. Lines 42 and 100 of CLAUDE.md point to a "Roadmap / Deferred" section in README.md that doesn't exist. This stale reference could mislead contributors about where to park deferred decisions.

2. AGENTS.md has an incomplete Speckit placeholder. The file contains only a Speckit HTML comment with the sentence "read the current plan" — but no plan file is named or linked. This is an unfilled template placeholder.

3. Mismatched benchmark numbers between docs/benchmarks.md and README.md. The modify+encode throughput tables show diverging numbers. For example, at 60 KB "modify nested": benchmarks.md reports 134,590 ops/s while README.md shows 196,386 ops/s. Same payload, different numbers — confusing for readers.

Goal

Ensure project documentation is internally consistent: remove the stale "Roadmap / Deferred" reference from CLAUDE.md, fill in the incomplete Speckit placeholder in AGENTS.md, and reconcile the divergent benchmark numbers between docs/benchmarks.md and README.md.

Acceptance Criteria

• CLAUDE.md no longer references a nonexistent "Roadmap / Deferred" section in README.md — the stale reference is either removed or pointed to the correct location
• AGENTS.md contains a meaningful pointer to the plan or is replaced with proper content
• docs/benchmarks.md and README.md agree on modify+encode throughput numbers for any shared scenario
• No regressions in markdown formatting, links, or readability

Task Checklist

1. Fix CLAUDE.md stale reference

• 1.1 Remove or update the "Roadmap / Deferred" reference at CLAUDE.md:42 (the cargo fmt context sentence)
• 1.2 Remove or update the "Roadmap / Deferred" reference at CLAUDE.md:100 (the conventions paragraph)
• 1.3 Review CLAUDE.md for any other references to nonexistent README sections

2. Fix AGENTS.md incomplete placeholder

• 2.1 Replace the incomplete Speckit sentence with a meaningful pointer to the actual plan file, or remove it if no longer needed

3. Reconcile benchmark numbers

• 3.1 Identify which file is the source of truth for modify+encode numbers (benchmarks.md or the most recent run)
• 3.2 Update the stale file to match the authoritative numbers across all shared payload sizes
• 3.3 Add a note explaining which benchmark run the numbers came from if not already present

4. Validation

• 4.1 Read all three files end-to-end to confirm no remaining stale references or mismatches
• 4.2 Run make lint if any code comments were touched

[coderabbitai]

🔗 Related PRs

#43 - test: add cjson and simdjson fixture coverage [merged]
#51 - perf: skip redundant validation in eager decode, inline depth check [closed]
#54 - perf: Lua encode + cache + scanner + validation stack optimizations [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!