chore(docs): README truth-up against landed PRs — counts, stale claims, missing rows

[thewrz]

Summary

In-depth validation of every factual README claim against the repo state and merged PR history. Every count, PR number, endpoint, tool name, table name, and referenced path was independently verified; this PR fixes the eight discrepancies found.

Fixed inaccuracies

• UFGS corpus is 666 SEC files, not 665 — 665 *.SEC + 1 lowercase 01_42_00.sec (in the corpus since the initial commit). The README said 665 in two places while itself claiming 666 seeded section records.
• seed:corpus silently skipped the lowercase file — the glob was case-sensitive, so "load all" loaded 665 of 666. Second glob pattern added to package.json; the claim is now true (verified: 665 + 1 = 666 matched).
• Phase 2b-iv cited "PR feat(lib): universal file loader — bulk-ingest any format (.SEC, .docx, .txt) into library #58" — feat(lib): universal file loader — bulk-ingest any format (.SEC, .docx, .txt) into library #58 is a closed issue; the feature merged as PR feat(lib): universal file loader — bulk ingest any format, seed:corpus preset #60.
• Status table omitted landed work — added rows for 2c-i style_templates/style_rules schema (PR feat(db): Phase 2c-i — style_templates + style_rules + default style_rules seed #87) and 4a revit_parameter_mappings schema (PR feat(db): Phase 4a — Revit parameter mapping schema + migrations #86), both merged 2026-05-19.
• Stale "Not Yet Built" bullet — persistTree/persistSpec consolidation landed in PR refactor(api): consolidate persist path onto persistParsedSpec (fixes silent ref loss on POST /parse) #88 (src/api/parse.ts persists refs via persistParsedSpec); removed.
• DB schema list corrected — versions → paragraph_versions; added missing spec_sections, style_templates, style_rules, revit_parameter_mappings.
• .mcp.json wording — it is gitignored (*.mcp.json), not "in the repo root"; reworded to "create".
• Parsing section now covers PR fix(parser): decode XML entities in SEC text — O&M rendered as O&M #112 (SEC XML entity decoding) and PR fix(parser): additional DOCX structure inference — numbering-generated PART headings, specifier notes, sanity warnings #113 (numbering-generated PART headings, specifier-note detection, sanity post-pass).

Verified accurate (no change needed)

All 11 API endpoints vs src/api/router.ts; all 7 MCP tools + 2 resources vs src/mcp/; seed counts recounted from corpus (666 distinct records / 239 Level 4/5 suffixed / 31 divisions — exact match); migration-013 CHECK constraint claims; every other phase-table PR number (17, 21, 76, 66, 70, 75, 72, 74, 69, 71, 24, 26, 51, 55, 114–117 — all MERGED with matching titles); Node 22; /mcp rate limiting; piscina pool; all 9 referenced doc paths.

Test Plan

• pnpm lint — clean (verified locally)
• pnpm test — 588 passed (verified locally)
• node -e "..." glob check: 'docs/references/UFGS/**/*.SEC' + 'docs/references/UFGS/**/*.sec' together match 666 files (verified locally: 665 + 1)
• Spot-check README claims against src/api/router.ts and src/mcp/tools.ts

Out of scope: any src/ behavior change beyond the one-line seed:corpus glob; renaming 01_42_00.sec; ARCHITECTURE.md audit.

Summary by CodeRabbit

• Documentation

  • Updated project roadmap and Phase 2c progression status
  • Enhanced feature documentation with details on PART heading recognition and SEC file parsing behavior
  • Updated setup and configuration instructions including newly supported schema components
  • Updated corpus reference documentation

• Chores

  • Updated build scripts to support multiple reference file format variants

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e598518-ec16-4e7d-9e4e-54048daf49b9

📥 Commits

Reviewing files that changed from the base of the PR and between a99298e and 9956667.

📒 Files selected for processing (2)

• README.md
• package.json

---

📝 Walkthrough

Walkthrough

This PR updates SpecR project documentation and configuration to reflect Phase 2c-i database schema completion, expands "What Works Today" feature documentation, updates setup instructions with additional schema components, and modifies the seed:corpus script to load UFGS reference files in both uppercase and lowercase formats.

Changes

Documentation and Configuration Updates

Layer / File(s)	Summary
Project Roadmap and Status README.md	Phase 2c status text updated to specify Phase 2c-i DB schema completion, and roadmap table reordered to insert Phase 2c-i as completed and adjust surrounding phase entries.
Feature Capabilities and Documentation README.md	"What Works Today" section expanded with bullets describing PART heading detection with hidden NOTE TO SPECIFIER handling and SEC XML character entity decoding, while removing obsolete persistTree/persistSpec consolidation note.
Setup Instructions and Reference Data README.md, package.json	Database schema components expanded to include paragraph_versions, style_templates/style_rules, and revit_parameter_mappings; seed:corpus script updated to load both .SEC and .sec UFGS files; UFGS corpus reference count adjusted to 666 files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• wrzonance/SpecR#77: Adds the persistTree/persistSpec consolidation note in the "follow-up" section that this PR removes, and similarly updates "What Works Today" documentation regarding DOCX/parsing behavior.

Poem

🐰 The roadmap marches onward bright,
Phase 2c-i schema shines with light,
New features bloom in docs so clear,
Case-insensitive files appear,
The setup guide now greets us right! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main purpose of this PR: updating the README documentation to correct inaccuracies, update counts, fix stale claims, and add missing rows in tables. The title directly reflects the content validated in the PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/readme-validation

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}