docs: document compile-time limits

[nightcityblade]

What this changes, and why

Documents the three public compile-time capacity limits and makes explicit that they are currently fixed rather than CMake-configurable.

Evidence

The documented values match kMaxPathKnots, kMaxWaypoints, and kMaxObstacles in the public headers. git diff --check passes; CMake tests could not run because CMake is unavailable on this host.

Risk

Documentation-only change; stale values would be visible by comparison with the public constants.

---

Confirm before requesting review:

• bash scripts/format.sh --check passes — CMake/tooling unavailable on this host
• Tests added for the behaviour this changes — documentation only
• Public API has doc comments; no API changed
• CHANGELOG.md updated under Unreleased, if behaviour or API changed — N/A
• New realtime-callable functions have an allocation test — N/A
• ADR added or updated, if a decision here would otherwise have to be reverse-engineered later — N/A; existing fixed behavior is documented

Fixes #4

[Onwcan]

Hi @nightcityblade

Thanks for the PR, the documentation itself looks good.

Before merging, I'd like to make this a little more robust against the exact maintenance risk you mentioned in the PR description: these values can become stale if the constants change later.

Could you please add a small automated consistency check that verifies the documented limits still match the public constants?

It doesn't need to be anything heavyweight. A small test or script integrated into the existing test/CI flow would be enough. Ideally it should cover:

• kMaxPathKnots
• kMaxWaypoints
• kMaxObstacles
• failure when a documented value no longer matches the corresponding constant

Also, please add the defining header for each constant to the README table so users can easily find the authoritative declaration.

That way this section becomes more than a snapshot of the current values — CI will prevent the documentation from silently drifting out of sync with the API.

Once that's in, I'll take another look. Thanks!

[Onwcan]

Thanks for the contribution. I'm marking this as changes requested so it's clear that the items in my previous comment are blockers before merge.

In addition to those points, please also adjust the README section hierarchy. Compile-time limits is currently a ### heading under the ## Build section, but these limits are public API/design constraints rather than build configuration. Please make it a top-level README section (## Compile-time limits) or place it under an equivalent API/design section.

So before the next review, please address:

the automated consistency check for the three documented constants,
the defining header/source location in the README table,
the README heading hierarchy for the compile-time limits section.

Once those are updated, ping me and I'll review the new revision. Thanks!

[nightcityblade]

Addressed all requested follow-up in a98fc5f:

• moved Compile-time limits to a top-level README section
• added each constant’s defining public header to the table
• added a CTest consistency check that reads the declarations and fails when the README value or header mapping drifts

Validation: debug build succeeded; all 228 tests passed, including readme_limits; scripts/format.sh --check passed (36 files). Please take another look when convenient.

[Onwcan]

CI is green as well. Nice work, and thanks for following through on the review feedback.