Drive ptc as an agent

Use the executable's help and embedded documentation when a coding agent drives ptc. They work offline and describe the version you invoke.

You do not need network access or a remembered API.

Ask the binary instead of guessing

Help and embedded pages come from the running executable, so they match its parser and version. Prefer them over remembered syntax or web pages for another version.

Use ptc docs manifest for the application document, ptc docs functions for built-in functions, and ptc docs preludes plus ptc docs agent-library for the shipped libraries.

Follow the loop

Choose one ptc init form, then run the remaining steps in order so each fails early and cheaply.

ptc init hello-ptc                       # a plain application
ptc init hello-ptc --example llm-replay  # or a model with no credential
ptc validate hello-ptc/ptc-project.json  # compile without executing
ptc repl --project hello-ptc/ptc-project.json -e '(dir)'
ptc doctor hello-ptc/ptc-project.json    # check provider readiness locally
ptc run hello-ptc/ptc-project.json --envelope out.json

ptc init writes a complete project, including an AGENTS.md that points a later agent back at these commands. Edit the component selected by ptc.json for behavior, and edit ptc.json for input and limits.

Experiment before committing to a file

ptc repl is the cheapest place to check a language question, and its discovery functions work in every input context — not only at a terminal, so a detached agent gets the same answers:

ptc repl --project PROJECT.json -e '(apropos "json")'   # search attached exports
ptc repl --project PROJECT.json -e '(doc "reduce")'     # print one function's documentation
ptc repl --project PROJECT.json -e '(dir)'              # list the attached prelude API

Repeat -e to build up a session in order. --project PROJECT.json evaluates against the real workflow environment, capabilities, and model routes instead of a bare scratchpad. This answers "does this expression work" without editing a component, revalidating, or spending a provider call.

Read outcomes as data

Pass --envelope FILE and parse that JSON document. Do not scrape stdout — it is a human channel and may carry application output too. The CLI reference lists which commands accept the flag and what the document contains.

Exit status is part of the contract: 0 on success, the diagnostic catalog's status for a classified failure, 70 for a caught internal failure, and 74 when envelope publication itself fails. ptc docs cli has the complete process contract.

Expect a bounded failure report

A failed run reports a closed phase and code pair. Deliberate fail values are deliberately not copied into the command diagnostic, and private detail never reaches public evidence, so do not expect a stack trace or a model transcript in normal output.

To debug, read the trace the run recorded, then ptc docs debug for the query surface and ptc docs traces for the record contract. ptc viewer PROJECT.json browses the same evidence when a human is present.

When you need the exact private records — model exchanges, generated source, capability payloads — they require explicit private authorization; see ptc docs repl and ptc docs cli.

Respect what each file can configure

An application document selects only what ptc-host.json already installed. It cannot add credentials, endpoints, commands, or wider limits, and no prompt or generated program can escalate that.

If a provider or tool is missing, the fix belongs in the host configuration a person controls (ptc docs host), not in the manifest or in a retry. Report the gap instead of working around it.

Keep credentials in the exact environment file passed with --env-file; never inline a secret into a manifest, a component, or a prompt.