Clean up community schema docs after the community-ids contract change

[johnworth]

Documentation/cleanup follow-up to #101. No wire-shape changes — request/response schemas are observably identical; only doc text and dead vars change.

Fixes

1. Bulk-DELETE docs drift. The bulk DELETE /apps/{app-id}/communities routes in apps and terrain bind AppCommunityListRequest but still referenced AppCommunityMetadataDeleteSummary/Docs, whose prose described only the old AVU envelope. The text of those exact vars is rewritten to describe both accepted shapes (community_ids, with the legacy avus list still accepted), so both consumers pick up accurate docs with zero route changes.

2. Dead exports. AppCommunityMetadataAddSummary and AppCommunityMetadataAddDocs are deleted, superseded by AppCommunityAddSummary/Docs from Add a community-list request schema for app community tags #101. See Release ordering below — they are unreferenced on the epic branches, but not on main.

3. Stale param description. AppCommunityGroupNameParam claimed the community listing routes take "the full group name"; the services now resolve an ID, a plain name, or a legacy colon-delimited group path. Description corrected to match.

   Re-verified end to end against apps groups-service: GET /apps/categories/communities/{id}/apps → listings/list-apps-in-community → filter-app-ids-by-community → groups/lookup-community, which branches exactly three ways and gates all of them on group_type = "community". Two details the description elides: the ID form must match ^[0-9a-f]{32}$, and an arbitrary colon path does not resolve — only one whose second-to-last segment is communities.

4. DRY. AppCommunityListRequest restated (-> AvuListRequest (->optional-param :avus)), which is exactly SetAvuRequest; it now derives from SetAvuRequest. Verified in a REPL that the resulting schema and its :json-schema metadata are identical (the final describe overrides the intermediate description either way).

5. Contract, not migration state, in the published docs. AppCommunityMetadataDeleteDocs described the AVU fallback as a temporary accommodation "while stale clients remain in circulation". That condition has no expiry and the string renders into the published Swagger, so a later reader cannot tell whether avus was removed or is permanently supported. Both docstrings now state the contract instead: the ID lives in community_ids, and avus is a deprecated alternative. AppCommunityAddDocs previously named neither field, so a client author implementing the add route had to read the delete route's docs to learn what to send; it now carries the same sentence.

Release ordering

The AppCommunityMetadataAdd* deletion in item 2 was justified on the grounds that nothing references those vars. That holds for the epic branches — apps #303 and terrain #333 both use AppCommunityAddSummary/Docs — but main on apps and terrain still :refer the deleted names, and a missing :refer fails at namespace load, i.e. a hard startup break rather than a doc glitch.

This is not a merge gate. apps and terrain both pin 3.4.23 on every branch, and the deletion is in no released version, so merging this PR breaks nothing. It only breaks if a release containing this PR is cut and a mainline apps or terrain bumps to it before #303/#333 land. Cutting the release after those merge avoids the question entirely.

Follow-up

The Add and Delete halves of the same route pair are now named asymmetrically: AppCommunityAddSummary/Docs cover the bulk add, while the bulk delete still uses AppCommunityMetadataDeleteSummary/Docs. That is deliberate here — AppCommunityDeleteSummary/Docs are singular ("Remove an App from a Community") and already belong to the path-param route, so there is no accurate plural name to move to, and inventing one is a second breaking change.

Adding an AppCommunityRemoveSummary/AppCommunityRemoveDocs pair mirroring the Add ones is the follow-up that lets apps' bulk DELETE /apps/{app-id}/communities stop advertising AVUs. AppCommunityGroupNameParam is worth renaming in the same pass — after item 3 it no longer describes a group name.

lein check passes; clj-kondo --lint src/ reports 0 errors and the 3 pre-existing unused-:refer warnings in categories.clj, unchanged. This repo has no test suite, so lein test proves nothing either way. Version is 3.4.26-SNAPSHOT.

🤖 Generated with Claude Code