# Pixir Open Beta Quickstart

Pixir's first open beta is a developer preview. The supported public surface is the
Pixir runtime, terminal CLI, and ACP over stdio. Hex distribution, when used, installs
the same CLI/ACP runtime and does not imply a stable public Elixir library API. T3Code
pairing is useful for dogfooding through a local adapter, but that adapter is not
upstreamed or packaged.

## What You Need

- Elixir compatible with `mix.exs`.
- A local checkout of this repository for source installs, or Hex package access for
  escript installs.
- Either ChatGPT subscription login through `./pixir login` or an `OPENAI_API_KEY`.

See `docs/adr/0016-open-beta-scope.md` for the open beta scope and
`docs/adr/0025-hex-package-scope.md` for the CLI/ACP-only Hex package contract.

## Install From Hex

```bash
mix escript.install hex pixir
pixir help
pixir doctor
```

## Install From Source

```bash
mix deps.get
mix escript.build
./pixir help
./pixir doctor
```

Use JSON output when another agent or script needs to consume diagnostics:

```bash
./pixir doctor --json
```

`doctor` is local-only and no-network. It checks the runtime version, source-install
binary, workspace/session-log writability, local credential presence, `config.json`
shape, and ACP command availability. It may create `.pixir/sessions` and remove a
temporary probe file. It does not prove that the Provider accepts your selected model;
use a smoke task for that.

## Sign In

```bash
./pixir login
```

Follow the printed device-code instructions. The subscription credential is stored under
`~/.pixir/auth.json` with local file permissions. As a fallback, set `OPENAI_API_KEY`.

## Run A First Turn

From a project directory:

```bash
./pixir "inspect this repo and summarize the architecture"
```

Pixir writes the model answer to stdout and activity/session details to stderr. Session
Logs are stored under `.pixir/sessions/` in the workspace and can be resumed:

```bash
./pixir resume <session-id> "continue from there"
```

## Permission Modes

```bash
./pixir --read-only "inspect this repo"
./pixir --ask "make a small change and test it"
```

`--read-only` denies mutations. `--ask` prompts before writes and unsafe shell commands.

## ACP Clients

Build the escript first, then point an ACP client at:

```bash
./pixir acp
```

ACP is the beta UI transport contract. Pixir still executes tools internally and reports
tool lifecycle through ACP updates.

## T3Code Status

T3Code integration is not a packaged public beta path yet. In this repo, T3Code remains
dogfood through a local adapter for validating ACP behavior, projection issues, and UX.
Do not assume there is an upstream T3 PR or an installable T3 provider package.

If you are using Pixir daily through an ACP client, use the operator checklist in
`docs/open-beta-daily-driver-ritual.md` to keep the local binary, client wiring, and
dogfood evidence aligned.

## Subagents And Workflows

Pixir supports supervised Subagents and structural Workflows. For beta users, the honest
contract is:

- completed Subagents and Workflow steps may produce useful checkpoint bundles;
- partial Workflow outcomes are not success;
- timed-out, failed, cancelled, or detached children must be reported honestly;
- long-running non-blocking Subagent status/result retrieval is still an experimental UX
  surface.

## Local Verification

The default gate mirrors CI:

```bash
mix check
```

For targeted local checks:

```bash
mix pixir.smoke.skills
mix pixir.smoke.subagents
mix pixir.smoke.workflows --dry-run --json
mix pixir.smoke.prompt_cache --dry-run --json
mix pixir.smoke.websocket --dry-run --json
mix pixir.smoke.web_search --dry-run --json
```

Networked smoke tasks are manual/opt-in. The prompt-cache smoke checks durable
`cached_tokens` observability. The WebSocket smoke checks the Responses continuation
shape that Pixir intends to use as the WebSocket-first default Provider path, with
HTTP/SSE fallback when WebSocket is unavailable. The Web Search smoke checks hosted
Responses Web Search request shape and bounded evidence capture.

## Images And Hosted Search

Pixir treats image attachments as durable local Session Resources. The original resource
is local Pixir evidence; OpenAI `input_image` is only the Provider projection used when
the Turn needs the image. Later Turns should replay descriptors or digests by default
unless `resource_view` explicitly rehydrates the original image.

ACP `resource_link` blocks are also accepted as Session Resource descriptors. Readable
local `file://` links are copied into Pixir's local resource store; remote links are
recorded as references but are not fetched automatically.

Provider-hosted Web Search is opt-in. It is not MCP and not a local browser tool:
OpenAI runs the hosted search and Pixir records bounded source evidence in
`provider_usage`.