Code comments cite a design document that is gitignored and therefore unresolvable

[rajarshidattapy]

Severity: Low
Files: .gitignore:10, src/tools/index.ts:6, src/lib/errors.ts:2, src/tools/schemas.ts:16, src/lib/bolna-client.ts:23

Description

Four source files reference a design document by name and section number as the
authority for their behavior:

• src/tools/index.ts:6 — "vs. bolna-mcp-tool-design.md §3–§4. Corrections
  applied in read.ts/write.ts", followed by nine entries keyed to §3.1–§4.4
• src/lib/errors.ts:2 — "Error handling per bolna-mcp-tool-design.md §5"
• src/tools/schemas.ts:16 — "§5: page_size default 10, hard cap 50"
• src/lib/bolna-client.ts:23 — "per §5's no-conversation-data-collection rule"

That file is excluded from the repository:

# .gitignore:10
bolna-mcp-tool-design.md

The references are load-bearing, not decorative. index.ts's comment block is
the only record of which endpoint paths were verified against the live API and
which spec assumptions turned out wrong — and it is written as a diff against a
document no reader can open. README.md:13-15 points contributors at that same
comment block as the canonical explanation of endpoint corrections.

Impact

For an MIT-licensed, publicly listed project (server.json registers it in the
MCP registry), every outside contributor hits a dead reference on first read.
There is no way to check whether a proposed change violates a §-numbered
requirement, and no way to tell whether the document still says what the comments
claim. In practice the comments become unfalsifiable: they cite an authority
nobody can consult.

Suggested fix

Pick one:

1. Commit the design document if it contains nothing private. It is the natural
   home for the endpoint-verification history and the §5 rules the code keeps
   invoking.
2. Inline the requirements the comments depend on — the pagination defaults, the
   error-mapping table, the no-conversation-data rule — so each comment stands on
   its own, and drop the § references.

Option 2 is smaller and removes the dependency entirely; option 1 preserves the
verification history, which has already proven useful once.