Improve `posit connect api ...` ux

[mconflitti-pbc]

posit connect api <path> already provides authenticated, gh api-style raw requests. Improve it with on-demand OpenAPI metadata so people and coding agents can discover and use Connect endpoints correctly without loading the entire API specification into their context.

Proposed experience

posit connect api search content
posit connect api describe getContent
posit connect api describe getContent --json
posit connect api call getContent -F guid=... --jq ".title"

The exact discovery command names are open to refinement. The important workflow is: search for an operation, retrieve concise machine-readable instructions, then execute it through the existing authenticated transport. Raw path calls must remain available as an escape hatch.

describe --json should return only the context needed to make a correct request:

• operation ID, method, and path
• short purpose and relevant deprecation/experimental status
• required and optional path/query parameters
• accepted request media types and request-body schema
• response schema and media types
• pagination style
• one concise example

api call compatibility

posit connect api call <operationId> must be another entry point into the existing posit connect api request pipeline, not a separate or reduced client. It should infer the documented method and path from the operation catalog, substitute documented path parameters, and then accept the existing command arguments and flags wherever they apply.

This includes:

• -X/--method
• -f/--raw-field and -F/--field
• -H/--header
• --input
• -q/--jq
• -i/--include
• --paginate and future --slurp
• -n/--name, -s/--server, and -k/--api-key
• --no-tls-verify and -c/--cacert
• future shared output/transport options such as --output, --silent, and --verbose

Avoid duplicating Click option declarations or request-building behavior. Extract and reuse shared option decorators, request models, or execution functions so raw-path and operation-ID calls remain behaviorally consistent. OpenAPI metadata may provide defaults and hints, but explicit user flags retain their normal meaning and precedence.

Examples:

posit connect api call getContent -F guid=CONTENT_GUID --jq ".title"
posit connect api call getContents -f limit=20 --paginate --jq ".results[] | .name"
posit connect api call updateContent -F guid=CONTENT_GUID -f title="New title" -H "X-Correlation-ID: 123"
posit connect api call getContent -F guid=CONTENT_GUID -s https://connect.example.com -k "$CONNECT_API_KEY"

The implementation must distinguish path parameters from query parameters and request-body fields using the operation metadata. If a field name is ambiguous, require an explicit syntax rather than silently routing it incorrectly.

OpenAPI strategy

• Generate a compact, data-only operation catalog from a pinned Connect OpenAPI specification at build time.
• Use the catalog for search, descriptions, shell completion, request hints, path-parameter substitution, and agent context.
• Keep request execution schema-independent so unknown, experimental, newer, and server-specific endpoints continue to work through posit connect api <path>.
• Do not generate or maintain a second HTTP client; reuse the existing RSConnectExecutor / RSConnectClient authentication and OAuth refresh behavior.
• Consider optional per-server runtime refresh later, with ETag/Last-Modified caching, atomic replacement, stale-cache fallback, size limits, and no credentials in the cache. Do not make help or raw requests depend on network access.
• Treat schemas as guidance and optional validation, not a mandatory gate.

Concise agent skill

Update the existing skills/posit-cli/SKILL.md as part of this work. The skill should remain concise and use progressive disclosure rather than embedding the endpoint catalog or full schemas.

It should teach this workflow:

Before calling an unfamiliar endpoint, run posit connect api search. Then run posit connect api describe <operationId> --json. Use posit connect api call <operationId> with the normal posit connect api flags. Fall back to posit connect api <path> when the operation is absent from the bundled catalog.

The skill should include:

• when to use raw-path calls versus operation-ID calls
• the search, describe, call, and raw fallback workflow
• a compact explanation that api call accepts the existing request, output, authentication, and TLS flags
• one read example, one write example, and one pagination example
• guidance to inspect describe --json instead of guessing parameter placement or payload shape
• guidance not to load or paste the complete OpenAPI document into context
• a reminder that explicit CLI help is the source of truth for flags

Do not duplicate all endpoint descriptions in AGENTS.md, the skill, or a global prompt. Keep durable instructions small and retrieve operation details only when needed.

Common endpoint guidance

The skill should also include a compact quick reference for the most frequently useful Connect API areas. Keep this curated rather than exhaustive: roughly 8-12 entries, each with the endpoint or operation name, its common purpose, and one important usage note.

At minimum, cover:

• v1/user for confirming authentication and inspecting the current user
• v1/content and v1/content/{guid} for finding, inspecting, creating, and updating content
• v1/content/{guid}/permissions for reviewing and managing content access
• v1/users and v1/groups for administrative identity lookup and pagination
• v1/audit_logs for operational and security investigation
• content jobs for status, logs, and troubleshooting
• schedules for listing and managing scheduled execution
• content environment variables, with explicit guidance about sensitive values
• server information/settings for version and capability checks

For each area, provide basic direction such as whether it is normally a read or write operation, whether administrator permissions are commonly required, whether pagination applies, and whether a higher-level posit connect command should be preferred. For example, routine deployment should point agents toward posit connect deploy rather than teaching them to manually reproduce the bundle/build/deploy sequence through raw API calls.

Use these entries as orientation and examples, not as a substitute for api describe --json. The skill must tell agents to inspect live command help and operation metadata before writes, deletes, permission changes, or requests involving secrets.

Raw command improvements

Harden the existing command where needed to cover the OpenAPI surface:

• Preserve binary request and response bodies; read --input as bytes and support byte-safe output/downloads.
• Avoid monkey-patching rsconnect _tweak_response; request raw responses and decode locally.
• Match gh api semantics when combining --input and fields: body from input, fields in the query string.
• Preserve repeated query parameters.
• Add nested/array field syntax or clearly direct complex requests to --input.
• Define pagination output explicitly and consider --slurp; avoid silently discarding paging metadata.
• Detect repeated cursors/URLs, preserve original query parameters, and validate next-page targets.
• Consider --output, --silent, and credential-redacted --verbose support.

Acceptance criteria

• Users and agents can search operations without reading the full OpenAPI document.
• describe --json provides sufficient context to construct a correct request for documented JSON endpoints.
• api call <operationId> reuses the existing request pipeline and supports the applicable existing posit connect api flags and arguments.
• Operation metadata correctly distinguishes and routes path, query, and body values.
• Discovery works offline from bundled metadata.
• Existing posit connect api <path> behavior remains supported for endpoints absent from the catalog.
• The bundled agent skill documents the concise search/describe/call/raw workflow and a curated high-value endpoint quick reference without embedding the full endpoint catalog.
• Generated metadata is deterministic and its source spec/version/hash are recorded.
• Tests cover metadata generation, lookup, concise JSON output, unknown operations, deprecated/experimental operations, representative path/query/body schemas, shared flag behavior on api call, and raw fallback behavior.

Non-goals

• Generating a full typed Python client.
• Dynamically registering all OpenAPI operations as permanent top-level Click commands.
• Rejecting raw requests because an endpoint or payload is absent from the bundled specification.
• Embedding the full OpenAPI specification or every endpoint description in agent instructions.