feat(trimble-connect): related topics, comment edit/delete, viewpoints, BCF documents, ToDo types + one retry contract (floless.app#2184)

20-agents/aeco/construction/trimble-connect/commands/delete-comment.md

@@ -0,0 +1,60 @@
+# `trimble-connect.delete-comment` — delete a comment
+
+Write command.
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+| `topic-id` | string | Topic guid. |
+| `comment-id` | string | Comment guid. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+comment-id: string
+deleted: bool
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. DELETE {bcf}/topics/{topic-id}/comments/{comment-id}   (Bearer)  → 204
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.create-comment](./create-comment.md)

20-agents/aeco/construction/trimble-connect/commands/delete-viewpoint.md

@@ -0,0 +1,60 @@
+# `trimble-connect.delete-viewpoint` — delete a viewpoint
+
+Write command.
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+| `topic-id` | string | Topic guid. |
+| `viewpoint-id` | string | Viewpoint guid. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+viewpoint-id: string
+deleted: bool
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. DELETE {bcf}/topics/{topic-id}/viewpoints/{viewpoint-id}   (Bearer)  → 204
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.create-viewpoint](./create-viewpoint.md)

20-agents/aeco/construction/trimble-connect/commands/download-bcf-document.md

@@ -0,0 +1,64 @@
+# `trimble-connect.download-bcf-document` — a project BCF document's bytes
+
+Stateless read. TC answers with a `302` to a pre-signed file-service URL (seen live);
+that one hop is followed — https only, and **without** the token, as `download` does.
+Max 256 MiB.
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+| `document-id` | string | Document guid. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+bytes: string
+encoding: string
+size-kb: number
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. GET {bcf}/documents/{document-id}   (Bearer)  → 302 Location: https://…
+2. GET <pre-signed URL>                (no auth) → bytes
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… without an https Location` | TC redirected somewhere unexpected | Report it; nothing was fetched |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.upload-bcf-document](./upload-bcf-document.md)

20-agents/aeco/construction/trimble-connect/commands/get-project-extensions.md

@@ -0,0 +1,66 @@
+# `trimble-connect.get-project-extensions` — the project's BCF extension values
+
+Stateless read. Topic types, statuses, labels, priorities and stages are per-project BCF
+extensions: `create-topic` / `update-topic` accept only these values (anything else is a
+`400 … is not defined in the project extension`). Read them here first. The raw
+extensions object (with colours, defaults and the allowed actions) is under `extensions`.
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+topic-types: array
+topic-statuses: array
+topic-labels: array
+priorities: array
+stages: array
+extensions: object
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. GET {bcf}/extensions?includeUsers=false   (Bearer)
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.create-topic](./create-topic.md)
+- [trimble-connect.update-topic](./update-topic.md)

20-agents/aeco/construction/trimble-connect/commands/get-viewpoint.md

@@ -0,0 +1,63 @@
+# `trimble-connect.get-viewpoint` — one viewpoint
+
+Stateless read. The viewpoint as TC returns it — cameras, lines, clipping planes,
+components, and its snapshot (TC returns a JPEG thumbnail here; use
+`get-viewpoint-snapshot` for the full image).
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+| `topic-id` | string | Topic guid. |
+| `viewpoint-id` | string | Viewpoint guid. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+viewpoint-id: string
+viewpoint: object
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. GET {bcf}/topics/{topic-id}/viewpoints/{viewpoint-id}   (Bearer)
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.get-viewpoint-snapshot](./get-viewpoint-snapshot.md)
+- [trimble-connect.list-viewpoints](./list-viewpoints.md)

20-agents/aeco/construction/trimble-connect/commands/list-bcf-documents.md

@@ -0,0 +1,64 @@
+# `trimble-connect.list-bcf-documents` — the project's BCF documents
+
+Stateless read; every page is read (`next` links followed). On Trimble Connect a BCF document is a project file (verified live):
+its `guid` is the file's id in the Files API, and it is what `create-document-reference`
+takes as `document-id`.
+
+## Lifecycle
+
+`single` — one call, one response
+
+## Inputs
+
+| Field | Type | Description |
+|---|---|---|
+| `region` | string (optional) | The project's `location` (`europe`, `unitedKingdom`, …) — routes the call to that region's host. Omitted: the project's own `location` is looked up. See [Regions](../skills/projects.md#regions). |
+| `project-id` | string | Project id. |
+
+The agent authenticates with the single `trimble-connect` credential from
+`aware connect trimble-connect` (the token is refreshed automatically, #198).
+
+## Outputs
+
+Handled in-process by the runtime (`cli/src/runtime/trimble_bcf.rs`, floless.app#2184).
+BCF lives on Trimble's regional Topics API, not under the agent's Core base, so every
+BCF command first resolves the project's region — `GET {core}/projects/{project-id}`
+gives its `location`, and the public `GET {core}/regions` maps that to the region's
+`topic-api` — and sends the token only to one of the five published Topics hosts
+(`open11` / `open21` / `open22` / `open31` / `open32` `.connect.trimble.com`). Redirects
+are never followed. A non-2xx **fails the node** with the step, the status and TC's own
+message — it is not returned as data.
+
+```yaml
+region:    string            # the location the call was routed to, when known
+items:
+  type: array
+  items:
+    guid: string
+    filename: string
+```
+
+## REST translation
+
+```http
+0. GET {core}/projects/{project-id}   (Bearer)  → location
+   GET {core}/regions                 (no auth) → topic-api for that location
+   {bcf} = {topic-api}bcf/2.1/projects/{project-id}
+1. GET {bcf}/documents   (Bearer)  → [{"guid", "filename"}]
+```
+
+## Failure modes
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `missing required input …` / `… must be …` | Bad input — refused before any request | Fix the node config |
+| `BCF region: project: HTTP 404 …` | No such project, or no access | Check `project-id` with `list-projects` |
+| `BCF region: … not a known Trimble Connect Topics host` | TC named a Topics URL outside the published five | Report it; the token was not sent |
+| `… redirects are not followed` | TC answered 3xx | Report it |
+| `… HTTP 401 …` | Token expired and could not be refreshed | `aware connect trimble-connect --refresh` |
+
+## See also
+
+- [topics.md](../skills/topics.md) — the API reference
+- [trimble-connect.upload-bcf-document](./upload-bcf-document.md)
+- [trimble-connect.create-document-reference](./create-document-reference.md)