# Put your agent to work

## Copy a file, folder or space

Choose **Use with agent** on a space card, folder header, file header or item menu. **Copy reference** gives a stable `stuff:item:ID` or `stuff:space:ID`. **Copy for agent** includes the reference, canonical URL, name, current file version and a task placeholder. Add your instruction and paste into a connected assistant. Names are explicitly marked as data.

No credentials, public-share tokens, file body or private descriptions are embedded. References do not grant permissions. Your assistant must have a connection covering that item; moving or renaming keeps the item ID but may change access. Public-link visitors use normal sharing; agent-copy controls require sign-in.

REST: `POST /api/v1/agent-context` with `{"reference":"stuff:item:ID"}`. MCP: `agent_context`. CLI: `stuff context REFERENCE`. Each resolves current access before returning context.

## Compare versions

Open a file's **History → Compare versions** and choose From/To. Added and removed lines are shown with old/new line numbers, each version's user and saved client/model attribution, and original downloads. Restoring still creates a new immutable version; comparison changes nothing.

REST: `GET /api/v1/items/ID/diff?from=1&to=2&context=3`. MCP: `compare_versions` with `reference`, `from`, `to` and optional `context` (0–10). CLI: `stuff diff REFERENCE 1 2`.

Responses include `kind`, `changed`, `from`, `to`, `added`, `removed`, `truncated`, and `hunks` with numbered `lines`. Text, `binary`, `too_large`, and `too_complex` outcomes are explicit; non-text outcomes include a `reason`. Text comparison supports recognized UTF-8 text originals up to 1 MiB and 20,000 lines each, with a bounded computation and output. CRLF/CR and missing final newlines are marked. Long lines or output are visibly shortened. Binary files keep original downloads; Office/media/3D visual comparisons are not included. Historical editor access and scan checks apply even when the connection itself is read-only.

## Know your connections

**Connections → Edit details** saves a connection name, optional assistant/app name and optional AI-agent/automation default. These are user/client-reported labels; they do not verify which model executed code. New writes use these defaults only when the caller supplies no replacement. Existing history remains immutable. A model is always supplied per edit or left unknown.

`GET /api/v1/agents` includes `client_name`, `client_kind`, `profile_revision`, `last_used` (last authenticated contact, not proof a task succeeded), and `last_activity` (last recorded mutation through that connection). Existing scope, write/management permissions, expiry and revoked state remain visible. OAuth's registered client name remains the fallback when no profile name is set.

REST profile update: `PATCH /api/v1/agents/ID/profile` with `name`, `client` (empty string clears), `kind` (`agent`, `automation`, or null) and the current `revision`. MCP: `update_connection_profile` with those fields plus `id`. Stale revisions return 409. Renaming does not rotate a secret or change scope; scope changes require reconnecting. Account-wide management permission is required to inspect/update owned connections; there is no admin-only shortcut.

**Check access** tests the saved grant, expiry/revocation (including delegated ancestors), scope and current user roles without editing files. It returns `ready`, `partial` or `unavailable` with root-level read/write results, bounded to 20 destinations. It does not impersonate the external assistant or prove the vendor has a valid saved credential.

For a real client test, ask that assistant to run MCP `connection_check` (no arguments). From a key-authenticated client, use `GET /api/v1/connection/check` or `stuff check`. An account manager can check another owned grant with `POST /api/v1/agents/ID/check` or MCP `connection_check` with `id`. Read an actual authorized file next to test the complete retrieval path. Files, scopes and history are never changed by the check.

## Installation

See [CLI installation](https://stuff.ac/connect/cli.md). The package is built from an explicit allowlist of CLI code and compiled shared schemas, without repository files, user content or credentials. It uses the same normal API as remote MCP and the signed-in app.