Add --visible-to-clients to docs/uploads create (Fixes #556)

[jeremy]

Wires create-time client visibility for docs create and uploads create
(plus the top-level upload shortcut), closing the create-side gap left by
#554. After this, all six SDK create inputs that accept visible_to_clients
are consumed by the CLI.

Why these two were deferred

Documents and uploads target an arbitrary folder via --vault/--folder, and
Basecamp only honors create-time visible_to_clients in the project's
docked/root Docs & Files vault. For a nested folder the server ignores
the param and inherits the folder's visibility — and the client-visibility
endpoint 403s for nested docs/uploads afterward, so there's no post-hoc
remediation (recordings visibility doesn't work for them). Exposing the flag
unconditionally would make it a silent no-op for nested targets.

Approach

A shared resolveVaultClientVisibility helper resolves the *bool before any
mutating request:

• Flag not passed → nil (server default preserved; tri-state).
• Root target (no --vault/--folder) → the value, no fetch needed.
• Explicit folder → inspected via Vaults().Get; a non-nil Parent (nested) is
  a hard error raised before anything is staged (no attachment POST, no
  inline-image upload, no create). The remediation advises creating in the root
  folder or changing the eligible top-level ancestor that controls the folder's
  visibility.

An explicit --visible-to-clients=false reaches the wire; omitting the flag
keeps the context-dependent server default (client-authenticated callers always
create client-visible records).

Tests

files_test.go gains a method+path mock that counts every POST and tracks the
vault-inspection GET, covering both commands and the shortcut: flag presence,
default omission, root true/false, explicit-root vault, nested rejection
(with zero POSTs, including for =false), and the unchanged nested path (no
flag → vault GET not called, create succeeds).

Docs

• skills/basecamp/SKILL.md — Files & Documents section, root-only note.
• API-COVERAGE.md — uploads/documents rows note --visible-to-clients (root vault).
• .surface regenerated.

bin/ci green.

---

Summary by cubic

Adds --visible-to-clients to docs create, uploads create, and the top-level upload. The flag works only in the project’s root Docs & Files; using it on a nested folder now errors before anything is uploaded.

• New Features
  • Tri-state behavior: omit → server default; pass true/false → value sent.
  • Root target needs no vault fetch; explicit --vault is checked and nested targets with the flag are rejected with a clear hint.
  • Tests cover root/explicit/nested cases for docs, uploads, and the shortcut; docs and API coverage updated; .surface regenerated.

^{Written for commit 5365d71. Summary will update on new commits.}

[Copilot]

Pull request overview

Adds create-time client visibility support for Files uploads and documents by wiring a new --visible-to-clients flag into files uploads create, files doc(s) create, and the top-level upload shortcut, while correctly rejecting nested-folder targets where Basecamp would silently ignore the parameter (and later remediation is not possible).

Changes:

• Add --visible-to-clients (tri-state via Flags().Changed + *bool request field) to uploads/documents create and the upload shortcut.
• Introduce resolveVaultClientVisibility to gate the flag to the root Docs & Files vault (errors early for nested folders, before any POSTs).
• Extend unit tests to cover omission, explicit true/false, explicit root vault, and nested-vault rejection (ensuring zero mutating requests on rejection), and update docs/API coverage + .surface.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/basecamp/SKILL.md	Documents root-only behavior and adds examples for --visible-to-clients on uploads/docs create.
internal/commands/files.go	Adds the flag to relevant commands and implements the root-vault gating helper + request wiring.
internal/commands/files_test.go	Adds a purpose-built transport and test matrix verifying tri-state behavior and “no POSTs on rejection”.
API-COVERAGE.md	Notes create support for --visible-to-clients on uploads/documents (root vault only).
.surface	Regenerates CLI surface snapshot to include the new flags across aliases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

No issues found across 5 files

_{Re-trigger cubic}