docs: describe the current agent contract and trim repeated guidance (#88)

* docs: describe the current agent contract and trim repeated guidance

* docs: scope the structured-output claim to leaf commands

Author: altaywtf

AGENTS.md

@@ -10,20 +10,10 @@
 
 ## Commands
 
-Primary:
-
-- `pnpm exec vp run verify`
-
-Focused:
-
-- `pnpm exec vp run check`
-- `pnpm exec vp run build`
-- `pnpm exec vp run test`
-- `pnpm exec vp run coverage`
-- `pnpm exec vp run check:dead-code`
-- `pnpm exec vp run skills:lint`
-- `pnpm exec vp run smoke:pack`: writes the report to `.artifacts/smoke-packed-install.json`
-- `pnpm exec vp run build:sea` then `pnpm exec vp run verify:sea`
+- `pnpm exec vp run verify`: the gate; pre-push and CI run it
+- Focused checks are the `scripts` in [package.json](package.json); run them as `pnpm exec vp run <script>`
+- `smoke:pack` writes its report to `.artifacts/smoke-packed-install.json`
+- `verify:sea` needs `build:sea` first
 
 Runtime proofs:
 
@@ -54,7 +44,7 @@ touches, and search `node_modules/effect/src` for anything it does not cover.
 ## Testing
 
 - Prefer in-process tests unless the process boundary is the behavior under test.
-- Add command-path coverage when the `@effect/cli` boundary changes.
+- Add command-path coverage when the `effect/unstable/cli` command boundary changes.
 - Prove command-surface changes with the built binary.
 - Finish in-scope edits, guardrails, and fixes without pausing; ask before publishing, credential-bearing release or SEA builds, and live writes against shared accounts.
 

README.md

@@ -212,29 +212,25 @@ for status interpretation and missing-file checks.
 
 ## Crash Reporting and Diagnostics
 
-Official releases enable privacy-safe crash reporting by default for unexpected CLI failures. It
-does not collect usage analytics, command results, or original error data. Manage the persisted
-preference with:
+Official releases send privacy-safe crash reports for unexpected CLI failures by default. There is
+no usage analytics. Manage the persisted preference with:
 
 ```bash
 putio telemetry disable
 putio telemetry status
 putio telemetry enable
 ```
 
-The preference lives in the normal private CLI config and applies to interactive, CI, agent, and
-other non-interactive runs. `DO_NOT_TRACK` does not override it. Missing config keeps reporting
-enabled; unreadable or invalid config fails closed for that process.
+The preference lives in the private CLI config and applies to interactive, CI, and agent runs alike;
+`DO_NOT_TRACK` does not override it. Missing config keeps reporting enabled; unreadable or invalid
+config disables it for that process. The `crashReporting` object in `describe` shows the effective
+state, flush deadline, and captured-field allowlist.
 
-The `crashReporting` object in `describe` shows the effective enabled state or disabled reason,
-flush deadline, preference commands, and captured-field allowlist.
-
-At most one synthetic event is sent per process: a random event ID and timestamp, one of three
-fixed failure categories, fixed runtime labels, and the package release. It never contains the
-original error, credentials, config, command arguments, request data, paths, or identifiers.
-[Architecture](./docs/ARCHITECTURE.md#crash-reporting-policy) lists the exact payload, process
-boundary, provider ownership, retention, and removal policy. Use the private contact in
-[Security](./SECURITY.md) for sensitive reports or deletion requests.
+A process sends at most one synthetic event: a random ID, timestamp, one of three fixed failure
+categories, fixed runtime labels, and the package release. It never contains the original error,
+credentials, config, command arguments, request data, paths, or identifiers.
+[Architecture](./docs/ARCHITECTURE.md#crash-reporting-policy) has the full policy. Use the private
+contact in [Security](./SECURITY.md) for sensitive reports or deletion requests.
 
 ## Docs
 

docs/ARCHITECTURE.md

@@ -1,8 +1,8 @@
 # CLI Architecture
 
-This repository is being refactored toward an agent-first, deeply Effect-native CLI.
+The CLI is agent-first and Effect-native.
 
-## North Star
+## Principles
 
 - Thin Effect CLI command adapters from `effect/unstable/cli`
 - Explicit services and layers for runtime, output, config, state, SDK access, and workflows
@@ -119,25 +119,11 @@ Sensitive reports and deletion requests go to the private security contact.
 
 ## Agent-First Contract
 
-- Every command should have structured output.
-- Mutating commands should grow raw JSON payload input and dry-run support.
-- Read commands should grow field-selection and pagination controls.
-- Machine-readable introspection should describe command purpose and capabilities without relying on prose docs.
-- Structured renderers should redact sensitive values and mark prompt-injection-like API text as untrusted data.
-- Repo docs should explain the architecture and guardrails in formats agents can consume quickly.
-
-## Current Phase
-
-The current CLI contract already includes:
-
-- schema-backed `describe` metadata for command purpose, capabilities, flags, and raw JSON payload shapes
-- neutral automation metadata in `describe` for supported output, dry-run, raw JSON input, field-selection, streaming, and safety features
-- raw `--json` input and `--dry-run` on mutating commands
-- named auth profiles with env/default-profile selection and legacy single-token fallback
-- `--fields` on agent-relevant read commands
-- cursor-backed `--page-all` on `files list`, `files search`, `search`, and `transfers list`
-- shared hardening for field selectors and identifier-like inputs before API calls
-- structured output redaction plus `_meta.agentSafety.untrustedTextPaths` annotations for prompt-injection-like API text
-- a versioned consumer skill library in `skills/putio-cli` with surface guides for discovery, auth/device approval, reads, writes, guardrails, and OpenAI/Codex picker metadata
-
-Next architectural work can keep extracting deeper services and workflows without losing the agent-first CLI surface.
+- Schema-backed `describe` metadata covers command purpose, capabilities, flags, raw JSON payload shapes, and neutral `automation` metadata for output, dry-run, raw JSON input, field selection, streaming, and safety features, so agents do not depend on prose docs.
+- Every leaf command catalogued by `describe` has structured output; the root and group commands such as `putio auth` print plain help text.
+- Mutating commands accept raw `--json` input and `--dry-run`.
+- Agent-relevant read commands accept `--fields`; `files list`, `files search`, `search`, and `transfers list` also accept cursor-backed `--page-all`.
+- Field selectors and identifier-like inputs are hardened before API calls.
+- Named auth profiles support env and default-profile selection, with the legacy single-token config as fallback.
+- Structured renderers redact sensitive values and mark prompt-injection-like API text in `_meta.agentSafety.untrustedTextPaths`.
+- [`skills/putio-cli`](../skills/putio-cli/SKILL.md) is the versioned consumer skill, with references for discovery, auth and device approval, reads, writes, and guardrails, plus OpenAI/Codex picker metadata.