Document moving a card to another card table in its project directly

Merged
JE
8d ago
+229-96

Agents read the SDK docs as saying a wormhole is how to move a card between card tables. They create one, move the card through it, then delete it. Within a project that's never needed. bc3's Kanban::Cards::MovesController#set_column looks up column_id among every column in the card's bucket, on any card table, and Kanban::Moves::CardMove only checks that the destination is a list or an on-hold section. A wormhole is needed only to reach another project, and that move is queued: the card arrives under a new id, the old id 404s, and position doesn't apply.

Doc strings only, with the same wording as basecamp/basecamp-mcp-server#262:

  • Smithy (spec/basecamp.smithy):
    • MoveCard and its column_id member: any column in the card's project, including on another card table, or a wormhole id to send the card to another project (queued, new id, position ignored).
    • CreateWormhole, UpdateWormhole, DeleteWormhole and the Wormhole shape: a wormhole is a standing shortcut, not a per-move step. Delete now says it's permanent; bc3's WormholesController#destroy calls deleted!, not trash.
    • CardTable.wormholes: a new doc comment with the same framing.
  • Go (go/pkg/basecamp): CardsService.Move, CardTable.Wormholes, Wormhole, and WormholesService.Create/Update/Delete.
  • Regenerated with make generate: openapi.json, the Go catalog and client, and the generated TypeScript, Ruby, Python, Kotlin, Swift and Rust services and types.

Tests:

  • make -k check on Linux (thelio) passes except the four *-test-verb-refusal targets. Those exit 127 only because thelio has no shasum, and all four pass on macOS.
  • Swift swift-check and swift-check-drift pass on macOS.
  • go test ./pkg/basecamp and go-check-drift pass locally, and the regenerated tree has no drift.

Downstream: basecamp-cli vendors openapi.json at internal/mcpserver/model/, so the new wording reaches it on its next SDK bump.

Summary by cubic

Clarifies the SDK docs on card moves and wormholes so agents no longer create a throwaway wormhole for moving a card between card tables in the same project.

  • MoveCard now documents that column_id can be any column in the card's project, on any card table there; a wormhole id is needed only to send a card to another project, and that move is queued (new card id, old id 404s). It must be a linked wormhole; position, if sent, must still be positive even though it doesn't set placement. The summary line carries both cases since the TypeScript, Ruby, and Kotlin generators keep only a doc's first line.
  • Frames wormholes as standing shortcuts on CreateWormhole, UpdateWormhole, DeleteWormhole, the Wormhole shape, and CardTable.wormholes, with wording matching basecamp-mcp-server#262. CardTable.wormholes lists only the wormholes whose destination the requester can reach.
  • Documents that deleting a wormhole is permanent — it does not go to trash and cannot be restored.
  • Regenerated all clients (openapi.json, Go, TypeScript, Ruby, Python, Kotlin, Rust, Swift) from spec/basecamp.smithy via make generate; no behavioral or API shape changes.

Migration

  • DeleteWormhole was already permanent in bc3 (it calls deleted!); this only documents that behavior.
  • basecamp-cli vendors openapi.json; the new wording reaches it on its next SDK bump.