JSDoc-type contributing note + explore broader lint coverage

Context

#13426 / PR #13428 shipped a catharsis-scan CI lint over src/ai/examples/apps/docs/app and fixed the build-breaking no-space record-union types, so npm run generate-docs-json (the last build all step) runs clean again — the goal is met. @tobiu sanctioned this follow-up to capture the deferred exploration that would have over-scoped #13428: the lint is a parser-based backstop; this ticket is about the proactive guidance + the broader hardening questions around it.

The Problem

• No proactive guide. Authors only learn the valid JSDoc/Closure type forms when the lint (or the build) rejects their type. A short contributing-docs note would let them write valid types up front.
• The failure space isn't documented. #13426 nailed one catharsis-rejected pattern — a bare union inside a record value with no space after the colon ({a:Object|null}). Other TS-isms the team reaches for are likely rejected too, but that's unverified.
• Scope edges. #13428's scope (src/ai/examples/apps/docs/app, per operator directive) deliberately excludes buildScripts/ and test/ .mjs, which also carry JSDoc — worth a deliberate keep/extend decision.

The Architectural Reality

buildScripts/docs/jsdocx.mjs → jsdoc-x → catharsis (the Closure/JSDoc type grammar — NOT TypeScript). The lint runs catharsis.parse(expr, {jsdoc:true}) on every /**-block type tag; see buildScripts/util/check-jsdoc-types.mjs + the catharsis spacing-quirk evidence in PR #13428.

The Exploration

1. Survey catharsis-rejected patterns. Run the TS-isms the team tends to write through catharsis.parse(…, {jsdoc:true}) and document which fail + the valid rewrite. Candidates to verify (not asserted): TS object-literal types, unsupported generics, optional key?: props, arrow-function types, Record<…>. The no-space-union is the confirmed one.
2. Author a contributing-docs note (under learn/ or a CONTRIBUTING surface) on valid JSDoc type syntax — parenthesize in-record unions, no TS object-literals-with-bare-union, @typedef for complex shapes, the no-space quirk. Link it from the lint's failure message.
3. Decide lint scope edges: keep or extend check-jsdoc-types.mjs to buildScripts/ + test/, with rationale.
4. Sitemap /* member-docs gap (flagged during #13426): src/sitemap/Component.mjs documents class-config members with single-star /* blocks jsdoc ignores (so they're undocumented), plus a malformed @member {String[} typo. Resolve or explicitly defer here.

Decision Record impact

none — docs + build-tooling hardening; no ADR governs the docs-build type grammar.

Contract Ledger

Not applicable — exploration + a contributing note; no consumed API / MCP tool / error-code / config-key surface change (same disposition as #13426).

Acceptance Criteria

• A contributing-docs note on valid JSDoc type syntax exists and is linked from the check-jsdoc-types failure message (or the docs-build doc).
• The catharsis-rejected-pattern survey is documented (here or in the note), each entry V-B-A'd against catharsis.parse.
• A keep/extend decision on the lint scope (buildScripts/ + test/) is recorded with rationale.
• The src/sitemap/Component.mjs /*-member-docs + {String[} gap is resolved or explicitly deferred.

Out of Scope

• Re-litigating #13428's lint scope — settled per operator directive (src/ai/examples/apps/docs/app, a source-quality gate broader than the build).
• Changing/forking catharsis.

Related

• #13426 (parent — the lint + the no-space-union fix), PR #13428, #12899 (the original parser-hardening that deferred the lint).

Release classification

post-release (hardening + docs — non-blocking; the build-clean goal is delivered in #13428). Boardless.

Retrieval Hint: query_raw_memories "catharsis JSDoc type lint contributing note broader patterns"; anchors buildScripts/util/check-jsdoc-types.mjs, buildScripts/docs/jsdocx.mjs.

Authored by Claude Opus 4.8 (Claude Code), @neo-opus-vega (Vega).