Align Trail Commands with Updated API · Entire

Check all the trail commands/parameters and check whether they are functional. The API has slightly changed so you best check that and compare.

Summary: most `trail` commands still match the API; `trail finding add` is broken

✅ Still functional (paths + bodies match the current spec)

Command	API call	Status
`entire trail` (show) / `trail list`	`GET /api/v1/trails/{host}/{owner}/{repo}`	✅ matches `getApiV1TrailsByHostByOwnerByRepo`
`trail create`	`POST /api/v1/trails/{host}/{owner}/{repo}`	✅ body matches (`title`,`body`,`branch_name`,`base`,`status`,`assignees`,`labels`,`priority`). CLI also sends `type` but never sets it, so it's omitted — harmless.
`trail watch`	`GET /api/v1/trails/{id}/reviews/events`	✅ matches `getApiV1TrailsByTrailIdReviewsEvents`
`trail finding` / `finding list` (read/dashboard)	`GET /api/v1/trails/{id}/reviews/comments`	✅ matches. (Spec gained an optional `review_id` query param the CLI doesn't send — fine.)
`finding show` / `apply`	`GET /api/v1/trails/{id}/reviews/{reviewId}`	✅ matches `getApiV1TrailsByTrailIdReviewsById`
`finding resolve` / `dismiss` / `reopen`	`PATCH /api/v1/trails/{id}/reviews/{reviewId}/comments/{commentId}`	✅ matches; CLI sends `{status,status_reason}`, both valid.

❌ Broken: `entire trail finding add`

The create-finding endpoint changed shape entirely. The CLI (trail_review_cmd.go → createTrailReviewComment / trailReviewCreateCommentPath) does:

Path:POST /api/v1/trails/{trailID}/reviews/comments
Body: a single flat object {title?, body, severity?, confidence?, client_id?, location, suggested_changes:[…]}
Decodes response into: a single TrailReviewComment

The current API has no POST on /reviews/comments (it's GET-only). Creating now requires a review and a batch:

POST /api/v1/trails/{trail_id}/reviews ("Start a review") → returns review_id (+ code_version_id, event_stream_url, etc.). The CLI never does this handshake.
POST /api/v1/trails/{trail_id}/reviews/{id}/comments ("Post a batch of comments to a review") with body { "comments": [ … ] } (required), where each item is:
- client_id REQUIRED (CLI sends it optionally)
- title removed (CLI still sends it)
- suggested_change singular object — not suggested_changes (array) as the CLI sends
- location required, body/severity/confidence/status/status_reason optional
Response is { "results": [ … ] }, not a single comment — so even if the path matched, the CLI's decode into TrailReviewComment would silently yield an empty result.

⚠️ Worth verifying: `trail update` (and `trail` detail lookups)

runTrailUpdate PATCHes trailsBasePath(...) + "/" + found.ID — i.e. it puts the trail ID in the last path segment. The current spec names that segment {number} (patchApiV1TrailsByHostByOwnerByRepoByNumber, "Update trail metadata") and the GET/DELETE siblings are all …ByNumber. The param is typed string, so the server may accept an id-or-number lookup — but the operationId/summary indicate it's keyed by trail number. This is the one spot I can't confirm without a live call (your login expired — entire auth status reports the token for us.auth.entire.io is no longer valid). If the server is strict, the fix is trivial: send strconv.Itoa(found.Number) instead of found.ID.

Note on what I couldn't run:

The token is expired, so I compared against the published OpenAPI doc rather than live calls. If you run ! entire login, I can exercise the commands end-to-end to confirm the {number} behavior and the finding add failure directly.

Want me to fix trail finding add to the new review→batch flow (start-review handshake, {comments:[…]} body with required client_id, suggested_change singular, {results} decode) and switch trail update to use the trail number? I'd update the api/trail_review_types.go request/response types alongside it.

How I verified

Your CLI token is expired and login is an interactive device flow I can't drive, and the API returns 401 before routing (so unauthenticated route-probing can't tell 404 from 405). So I verified against the running server's own published contract — https://entire.io/api/openapi.json ("Entire API 0.1.0"), the authoritative source — and confirmed each fix with build + unit tests + lint.

What was broken vs. the current API

Comparing every trail path/body against the spec, exactly one command was structurally broken:

entire trail finding add — the create-finding endpoint changed entirely:

Old CLI: POST /reviews/comments with a single flat comment body, decoding a single comment back.
Current API: no POST on /reviews/comments. You must start a review (POST /reviews) and post a batch (POST /reviews/{id}/comments with {comments:[…]}), and read back {results:[…]}. Per-item, client_id is now required, title was removed, and it's suggested_change (singular object) not suggested_changes (array).

Everything else still matches: trail list/create/watch, and finding dashboard/list/show/apply/resolve/dismiss/reopen/watch all use paths and shapes the spec still serves (the /reviews/{id} state endpoint still returns the suggested_changes array that apply/show rely on).

What I changed

api/trail_review_types.go: replaced TrailReviewCommentCreateRequest with the new contract — TrailReviewStartRequest/StartResponse (+Limits), TrailReviewCommentBatchRequest, TrailReviewCommentInput (client_id required, singular suggested_change, no title), and TrailReviewCommentBatchResponse/Result/Error.
trail_review_cmd.go: finding add now starts a review (sending current HEAD as head_sha so the finding pins to what you see) then posts a one-item batch, generating a client_id (UUID) when --client-id is omitted, surfacing a per-result status:error. Removed the now-rejected --title flag; split the path helpers (trailReviewStartPath, trailReviewBatchCommentsPath, trailReviewListCommentsPath).
Updated/added tests for the build-input, generated client-id, start-then-batch flow, and batch-error surfacing.

mise run fmt && mise run lint → 0 issues; full cmd/entire/cli/... suite passes.

One thing I could not verify (and deliberately did not change)

entire trail update PATCHes …/trails/{host}/{owner}/{repo}/{found.ID}, but the spec names that segment {number} (…ByNumber). The param is typed string, which strongly implies the server accepts an id-or-number lookup — so the ID the CLI sends likely works. I left this working code untouched rather than risk breaking it on a guess. If you run ! entire login, I'll exercise trail update (and the new finding add flow) end-to-end to settle it.

Summary: most trail commands still match the API; trail finding add is broken