Project-configuration reference

This is the complete local path, artifact, override, and Viewer-preference contract.

Use one explicitly named ptc-project.json to remember stable local paths and development preferences:

ptc run ptc-project.json
ptc doctor ptc-project.json
ptc doctor ptc-project.json --connect
ptc repl --project ptc-project.json
ptc repl --project ptc-project.json --mission review
ptc viewer ptc-project.json

ptc init DIRECTORY generates this file alongside ptc.json, main.clj, and an AGENTS.md routing card for coding agents. PtcRunner never searches parent directories or guesses a project from its filename; the "kind": "ptc-project" discriminator identifies the document.

The kernel tutorial ships one project document per runnable example. A credential-free run and its Viewer need only the same JSON path:

ptc init kernel-tutorial --example kernel-tutorial
ptc run kernel-tutorial/01-orders.ptc-project.json
ptc viewer kernel-tutorial/01-orders.ptc-project.json

The provider-backed examples additionally reference the shared host document and kernel-tutorial/.env from their project files. After creating that explicitly named environment file, their run commands have the same single-argument shape:

ptc run kernel-tutorial/04-multi-turn-agent.ptc-project.json

Keep the three files separate

Credential values and provider declarations do not belong in the project file. Project choices do not become part of application content identity.

Document shape

{
  "$schema": "https://ptc-runner.dev/schemas/ptc-project-config.schema.json",
  "kind": "ptc-project",
  "version": 1,
  "application": {"path": "ptc.json"},
  "host": {
    "path": "ptc-host.json",
    "env_file": {"path": ".env"}
  },
  "artifacts": {
    "root": ".ptc",
    "trace": true,
    "inspection": false,
    "result": false,
    "envelope": true
  },
  "viewer": {
    "port": 0,
    "open": true,
    "repl": true,
    "private": false
  }
}

kind, version, and application are required. host, artifacts, and viewer are optional. A document that declares "kind": "ptc-project" and then fails this schema reports project/project_schema_invalid. The diagnostic names a bounded schema rule and the deepest project-schema-authorized JSON Pointer; it does not retain the rejected value, an unknown property name, or the filesystem path. If bounded schema validation times out or exceeds its resource bound, the retryable project/schema_validation_unavailable diagnostic reports the unavailable validation instead of claiming that the document is invalid. A syntactically valid run, validate, doctor, or models invocation still publishes a requested --envelope before any project reference or provider is opened. Malformed command syntax remains an argument rejection and publishes no envelope.

Every object rejects unknown and duplicate keys. Paths are portable relative paths resolved beneath the project document's directory; absolute paths and .. traversal are rejected. The generated schema is served as ptc docs schema-project (priv/schemas/ptc-project-config.schema.json in the repository).

Inspection requires traces because private records must correlate with a matching run. viewer.private is a separate explicit local grant: creating a private artifact does not automatically expose it to Viewer. viewer.repl independently enables the browser REPL, including when viewer.private is true. REPL evaluations remain fixed to the public run-analysis-v1 profile and its immutable normal-trace snapshot; they cannot query the private evidence displayed elsewhere in the Viewer.

Artifact layout

For run, enabled project artifacts derive from the command run reference:

.ptc/traces/<run-ref>.jsonl
.ptc/traces/<run-ref>.private.jsonl
.ptc/inspection/<run-ref>.inspection.jsonl
.ptc/results/<run-ref>.json
.ptc/results/<run-ref>.private.json
.ptc/envelopes/<run-ref>.json

The root and its fixed child directories are owner-only. The first project run creates the complete layout atomically; an existing incomplete, permissive, or symlinked layout is refused. When a pre-existing directory fails the owner-only (0700) check, the command names the path and the chmod 700 remedy rather than a bare publication failure. Artifact files retain the normal no-replace and privacy rules.

Overrides and lazy environment loading

An explicit command value wins over the corresponding project default for host, environment, and trace/inspection/result destinations:

ptc run ptc-project.json --host-config deployment/staging-host.json
ptc run ptc-project.json --trace-dir tmp/one-off-traces
ptc repl --project ptc-project.json --env-file deployment/staging.env
ptc repl --project ptc-project.json --mission review
ptc viewer ptc-project.json --env-file deployment/staging.env

--envelope FILE is different: it adds a convenience copy for the invocation and does not suppress the project ledger under .ptc/envelopes/ when artifacts.envelope is enabled. Trace, inspection, and result overrides still replace their project defaults.

Mission selection, input, and component-override switches remain invocation-only. Mission names stay in the application manifest rather than being duplicated as project defaults. A project environment file is loaded only when inert preparation proves that a selected mission provider or its dependency uses an environment-backed credential. Unrelated providers do not cause environment-backed credentials to be read. Runs without providers, passive doctor, Viewer startup, and file- or literal-backed credentials do not read it. Viewer-started workflows and missions read the selected file lazily through their ordinary command preparation.

Direct manifest invocation remains the low-level form for automation:

ptc run ptc.json \
  --host-config ptc-host.json \
  --trace-dir build/traces \
  --envelope build/command.json

Viewer

ptc viewer ptc-project.json uses the project's trace root, port, browser-opening preference, REPL setting, and private-data authorization. Trace and correlated inspection directories are captured before the listener starts; HTTP requests select only a run ID and never a filesystem path. Browser opening is a bounded convenience, and additionally requires an attached terminal: missing or failing platform openers do not stop Viewer.

The Viewer port defaults to 0, which asks the operating system for a free port; startup prints the selected address before opening a browser. Set a fixed port only when another process needs a stable address. If that port is occupied, the command probes loopback and names the project when another PTC Viewer owns it. The Live project header and /api/live/project expose the exact project document path, so a working page cannot silently look like the project whose startup just failed.

The REPL and private-data settings are orthogonal. Enabling both presents the public-trace REPL alongside the private evidence panels without adding private inspection authority to the evaluation session.

Because artifacts.inspection and viewer.private must both hold, the private routes distinguish which one is missing: inspection_not_configured for a project that records no inspection artifact, inspection_not_private for one that records it and withheld the grant. The second needs no re-run — the artifact on disk is already usable once the Viewer restarts with the grant.

A run can also fall outside evidence the Viewer does hold, which the routes name separately from the project settings: inspection_run_not_recorded for a run made before artifacts.inspection was set, and inspection_run_mismatch for a Viewer pinned to one other run's artifact. The debug-navigation reference carries the complete table.

Viewer-started workflows and missions use the project's host.env_file when one is declared. ptc viewer ptc-project.json --env-file FILE supplies an invocation-time override instead. PtcRunner never searches implicitly for .env; without either form, credentials must already be present in the Viewer process environment or use another trusted host binding.

The listener binds 127.0.0.1. The project document deliberately cannot change that: exposure is an invocation-time decision made with --listen 0.0.0.0, where it stays visible in the command line rather than stored in a file. See Running and debugging.

The Viewer ships in the standalone release and container image and is absent from the published package.