Document highest-impact new-user documentation gaps in roadmap

[Copilot]

This issue asks for a focused audit of README.md, AGENTS.md, and the docs structure, then a clear list of the biggest documentation gaps blocking new-user adoption. This PR adds that audit output directly into existing docs (no new Markdown files).

• Added: prioritized gap inventory (new-user adoption blockers)

  • Introduced a new section in docfiles/project/roadmap.rst:
    • Documentation Gaps Blocking New-User Adoption
  • Captures the highest-impact blockers:
    • conflicting example-count claims across README/AGENTS/docs
    • stale onboarding example paths that no longer match current examples/ layout
    • no single canonical “start here” path across README/docs/tutorials
    • advanced-first README flagship snippet before minimal first-success flow
    • unclear audience boundary for AGENTS.md vs beginner docs
    • no documented single source of truth for drift-prone docs metadata (counts/path maps)

• Made findings actionable

  • Added explicit file-level references for mismatches and stale paths.
  • Added observation-date context to claim comparisons to reduce ambiguity during follow-up edits.

Documentation Gaps Blocking New-User Adoption
---------------------------------------------

After reviewing ``README.md``, ``AGENTS.md``, and the current docs tree, these are the highest-impact documentation gaps for first-time users:
...

---

⌨️ Start Copilot coding agent tasks without leaving your editor — available in VS Code, Visual Studio, JetBrains IDEs and Eclipse.