> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.questra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Programming

> survey.programming — convert a questionnaire into platform content.

Programming turns the tip (or chosen) questionnaire into the target platform deliverable. Progress lives on a `survey.programming` run (newest-wins per survey).

Greenfield runs expose lean status plus `workflow_id` / `stream_url`. Clients subscribe on the **generic** World stream; product resume for target/template uses domain `PUT` routes.

## Product steps

Ordered work (anatomy / World steps; UI should follow the live stream rather than inventing a second plan):

1. **Initial programming** — questionnaire → Questra HCL (streams compose previews)
2. **Conjoint design** — fan-out over cross elements (skipped when none)
3. **Target selection** — configure gate; resume via `PUT .../programming/target` (or generic hook token when present)
4. **Template selection** — configure gate; resume via `PUT .../programming/template`
5. **Transpile** — compile HCL once and persist platform source + sidecars
6. **Fine tuning** — skipped when effective instructions are empty
7. **Audit / diagnostics loops** — bounded repair; exhaustion → warnings
8. **Upload files / survey configuration** — API delivery only; skipped for offline targets

Workspace **`default_file_hosting`** (`questra_cdn` vs `platform_native`) controls whether movable media stay on the Questra CDN or are uploaded upstream. Platforms without a file-manager API always keep movable media on Questra CDN.

Offline targets still run through diagnostics and persist local artifacts at every completed stage. Only upstream upload steps skip.

## Start

```http theme={null}
POST /v1/surveys/{surveyId}/programming
Content-Type: application/json

{}
```

**202** includes `workflow_id`, `stream_url` (`/v1/workflows/{workflow_id}/stream`), and a lean `programming` detail (empty `phases` for greenfield).

You may start **without** a frozen platform target (`platform: null`). The run waits on configure gates; set target (and optionally template) with the product resume routes below.

## Subscribe to progress

Prefer the start response `stream_url`:

```http theme={null}
GET /v1/workflows/{workflowId}/stream?startIndex=
```

Legacy domain subscribe (resolves the current binding for the survey):

```http theme={null}
GET /v1/surveys/{surveyId}/programming/stream?startIndex=
```

NDJSON lines are raw World stream chunks (anatomy + progressive logs). Reconnect with `startIndex` while the World retains the stream. Authoritative status reconciles from `GET /v1/workflows/{workflowId}` or `GET .../programming`.

## Target and template resume

```http theme={null}
PUT /v1/surveys/{surveyId}/programming/target
Content-Type: application/json

{ "platform": "decipher", "instructions": null, "config": {} }
```

```http theme={null}
PUT /v1/surveys/{surveyId}/programming/template
Content-Type: application/json

{ "fine_tuning_template_id": null }
```

`fine_tuning_template_id: null` clears the template and uses the code-owned canonical platform template.

Frozen target output includes a secret-free `delivery` discriminant: `{ mode: "offline" }` or `{ mode: "api", integration_id, upstream_survey_id? }`. Connected resume sends `config` refs for the integration and optional upstream survey. Export-only freezes `mode: "offline"`.

Greenfield anatomy may also expose SDK hook tokens — resume those with `POST /v1/workflows/{workflowId}/hooks/{token}` when the UI is following `resumePath` from the stream.

## Accept / cancel

```http theme={null}
POST /v1/surveys/{surveyId}/programming/accept
POST /v1/surveys/{surveyId}/programming/cancel
```

## After success

* `GET .../content` — tip revision written by programming
* Webhooks: `workflow.*`, `content.updated`
* Manual `PUT .../content` is blocked while a programming (or content-edit) run is still pending/running — completed bindings may remain current and do not block saves

## Concurrency

Newest-wins per survey: a new `POST .../programming` cancels the prior run. Switch to the new `stream_url`.