trimble-connect covers 25 of 188 Trimble Connect Core API operations — 163 remain (views, releases, shares, tags, groups, file check-in/out, permissions, comments, clash sets, …) plus BCF viewpoint detail #691

Summary

The trimble-connect agent (manifest 0.5.0 on main at 65ffbb1de, CLI 0.158.0) now has 46 commands. It covers what floless.app#2184 needed, and the main day-to-day surface:

• folders and files: create, find, list, list by path, rename or move, copy, delete, versions, upload, download;
• projects (read), the signed-in user and project members;
• BCF 2.1 topics, comments, viewpoints and snapshots, document references, related topics, BCF documents and extensions;
• ToDos and ToDo types;
• region-aware routing.

Trimble's published Core API 2.0 definition has 188 operations. The agent covers 25 of them, so 163 remain. This issue tracks them, grouped by area, so they can be picked up later. Each item can be ticked off as it lands.

Observed (verified)

1. Source of truth: Trimble Connect Core API 2.0, https://api.swaggerhub.com/apis/Trimble-Connect/tcps/2.0 (OpenAPI 3.0, downloaded 2026-10-11).
2. Coverage is computed, not estimated:
   • Every METHOD path in the "REST translation" blocks of 20-agents/aeco/construction/trimble-connect/commands/*.md on main (46 docs) was matched against the definition's paths.
   • Path parameters are normalised to {} and query strings dropped.
   • Anything unmatched is listed below.
3. BCF is outside that count. The BCF 2.1 endpoints (/bcf/2.1/...) are a separate API, served from the region-aware BCF base (feat(trimble-connect): BCF 2.1 topics, comments, viewpoints, document references + ToDos (floless.app#2184) #686, feat(trimble-connect): region-aware Core routing (floless.app#2184) #690). See "BCF gaps" below.

Remaining Core API 2.0 operations (163)

Rough priority for AECO workflows, highest first:

1. File lifecycle: files check-in/check-out, permissions, processing status, formats, export.
2. Collaboration: comments (file and folder comments, not BCF) with attachments and reactions; todos attachments; shares; releases.
3. Organisation: tags, groups, project users (invite, role, remove), project create/update/settings.
4. Viewer and model: views, views2d, viewgroups, clashsets, objectlink, file alignment.
5. Admin and long tail: companies, activities, search, users/* preferences, the /2.1/... project-scoped list variants (these duplicate covered folder and file listings), folders permissions, versions and async force-delete with job status.

BCF gaps (outside the Core count)

These come from the agent's own skills/topics.md and skills/viewpoints.md. Verify them against Trimble's BCF API definition before building, because those skills were ported, not generated:

• PUT /bcf/2.1/projects/{projectId}/topics/{topicId}/document_references/{referenceId}: update a document reference
• GET …/viewpoints/{viewpointId}/bitmap
• GET …/viewpoints/{viewpointId}/selection: selected components
• GET …/viewpoints/{viewpointId}/coloring: colored components
• GET …/viewpoints/{viewpointId}/visibility
• GET / PUT …/topics/{topicId}/bim_snippet
• GET /bcf/2.1/projects/{projectId}/topics_events and …/comments_events: change tracking

Proposal / conventions to keep

New commands should follow what #685 to #690 established:

• Kind of command:
  • Declarative REST for plain reads: the {status, headers, body} envelope, plus a range header input on lists.
  • The runtime handlers (cli/src/runtime/trimble_ops.rs, trimble_bcf.rs, trimble_files.rs) for anything needing camelCase bodies, If-Match, multi-step flows or binary data.
• Inputs and outputs: kebab-case inputs, and every emitted key declared in the manifest schema. The guard tests in trimble_ops.rs enforce both and must be extended.
• Writes: mode: write on every write, so --dry-run stubs it.
• Verification: the source of truth is the API definition, not the ported skills. Run unit tests against a wire mock, a real-CLI E2E, and a live pass on the maintainer's test project ("Take 5"), cleaning up whatever it creates.
• Runtime gate: the release that ships new handler commands must raise minimum-cli-version and mark them status: requires-runtime, as in the google-workspace 2.2.0 precedent.

Split the work by area: one PR per group, or two or three related groups. Don't build all of it in one change.

Why it matters

FloLess and any other app on AWARE can automate Trimble Connect only as far as the agent exposes it. The current set handles moving files and tracking issues. The gaps above are the next workflows people reach for: check-out and check-in before an edit, releases and transmittals, sharing, tagging, file comments, 3D views and clash sets.

References

• pawellisowski/floless.app#2184: the user request ("full supported Trimble Connect API coverage")
• feat(trimble-connect): folder creation + full folder/file management (floless.app#2184) #685: folders and files; feat(trimble-connect): BCF 2.1 topics, comments, viewpoints, document references + ToDos (floless.app#2184) #686: BCF and ToDos; feat(trimble-connect): region-aware Core routing (floless.app#2184) #690: region-aware routing; feat(trimble-connect): related topics, comment edit/delete, viewpoints, BCF documents, ToDo types + one retry contract (floless.app#2184) #689: related topics, comment edits, viewpoints, BCF documents
• Structured rate-limit error for agent handlers (trimble-connect error.rate-limit-exceeded) #688: structured rate-limit error for agent handlers (open, related)
• trimble-connect: wire upload/download as REST (multipart/binary, multi-step) — follow-up to #196 #200, first-party trimble-connect agent is unrunnable: CLI-first to a non-existent aware-trimble-connect binary; REST path lacks auth: and per-command method/path #196: earlier upload/download and REST wiring