fix: rewrite defineLinks @example to pass validation

[feffef]

Finding

FINDING-01 | WARNING | Style / Documentation
Location: src/link-definition.ts:128-146 (JSDoc) vs src/link-definition.ts:242-255 (validation)

The public @example on defineLinks shows 'posts[]': { to: 'posts' } — a bare array-terminal link path. validateResourceDefinition was recently hardened (housekeeping #10, marked DONE) to reject terminal [] segments with the message Array segment 'posts[]' cannot be terminal.

Concrete impact: if a user reads the JSDoc, copies the example into their own API definition, and runs it, the call throws at runtime with the validator error — before their code ever makes an HTTP request. The tutorial-style example is the opposite of helpful: it's a trap.

Approach chosen: B — Rewrite example to be self-contained

The implicit schema dependency was the real trap. The previous minimal-patch fix (posts[] → posts[].href) would compile but leave readers unsure why the suffix is required. The rewrite explicitly shows the schema shape (posts: Type.Array(Type.Object({ href: ... }))) so the 'posts[].href' path is self-documenting, matching the canonical idiom used in examples/petshop-api.ts.

Alternatives considered

• A — Minimal patch: Change 'posts[]' → 'posts[].href' only. Rejected because the reader still has no visibility into what schema shape enables the path — they'd likely hit the same class of error the first time they write a different path. The rewrite removes the implicit knowledge assumption.
• C — B + a unit test asserting the JSDoc example compiles and validates: Rejected for this PR as out of scope. Worth a follow-up — captured in comments so a future housekeeping pass can pick it up.

Test plan

• npx jest — all existing tests pass
• npm run typecheck — compilation succeeds
• Mental-simulation: 'posts[].href' on the rewritten schema resolves to Type.String() terminal; validateResourceDefinition accepts it.

Review checklist

• Dedicated opus peer review: approved

[feffef]

Opus Reviewer (on behalf of @feffef): LGTM — the rewritten @example is correct and well-scoped. (Cannot formally approve: GitHub blocks self-approval on own PRs.)

Correctness (mentally simulated against validateResourceDefinition):

• Path posts[].href on the inline UserSchema resolves as: posts (Array) → unwrap items → { href: String } → href (String). The terminal-array guard at src/link-definition.ts:248 is not triggered (finalProperty is href), and TypeGuard.IsString(resolved) is true. The example PASSES validation.
• to: 'posts' is in the declared names list; links: {} on the posts resource (only a commented-out negative example) is a valid empty record.

Idiom consistency: 'posts[].href' matches the canonical 'pets[].href' pattern in examples/petshop-api.ts:91.

Tutorial quality: Major improvement over the original. Showing posts: Type.Array(Type.Object({ href: Type.String() })) alongside the link path posts[].href makes the schema-shape-to-link-path relationship unambiguous — exactly the "implicit schema trap" the solution doc flagged.

Scope / side effects: Only the @example JSDoc block for defineLinks was touched. Signature, @param tags, ApiDefinition JSDoc, and the rest of the file are unchanged. No CHANGELOG entry needed (example-only edits are explicitly exempt per AGENTS.md).

Minor nit (non-blocking): The original had three didactic comments in the posts resource (✓ validated, ✗ TS error, ✗ runtime error) illustrating all three validation layers. The rewrite keeps only the TS-error case. Not worth blocking on — the users block's "Validated at compile and runtime" comment covers the concept.

Approach B from the solution doc was applied faithfully. Ship it.