# Integration Templates (ADR-015 / federated OCI artifacts)

Three starting templates for integration. Pick the role you want to play; you
can be both a producer and a consumer.

## Pick the template that matches what you want to do

| Template | Role | Outcome |
|---|---|---|
| `domain-producer/` | Define a typed contract for structured data | Push `domains/<participant>/<id>:<version>` to ZOT |
| `mode-producer/` | Author an orchestration mode that consumes domains | Push `modes/<participant>/<id>:<version>` to ZOT |
| `mode-consumer/` | Adopt someone else's published mode | Cabling file in `infra/<ws>/integrations/` |

## Layout

```text
domain-producer/
  contract.ncl.template       ← schema (Nickel types) for the structured data
  example.json.template       ← reference instance matching the contract
  manifest.ncl.template       ← DomainArtifact descriptor

mode-producer/
  provisioning.ncl.template   ← IntegrationMode declaration
  domains.lock.ncl.template   ← pinned versions of consumed domains
  manifest.ncl.template       ← ModeArtifact descriptor

mode-consumer/
  cabling.ncl.template        ← binds mode params to workspace values
```

## Workflow

### Producer (one-time per artifact)

```bash
# 1. Copy template to your catalog dir
cp -r install/resources/templates/integration/domain-producer/  catalog/domains/my-domain/
mv catalog/domains/my-domain/contract.ncl.template  catalog/domains/my-domain/contract.ncl
mv catalog/domains/my-domain/example.json.template  catalog/domains/my-domain/example.json
mv catalog/domains/my-domain/manifest.ncl.template  catalog/domains/my-domain/manifest.ncl

# 2. Edit the files: replace <placeholders>, define your types

# 3. Publish
ore secrets bootstrap                                    # one-time, vault setup
prvng integration domain publish catalog/domains/my-domain <participant>
prvng integration domain verify <participant>/my-domain 0.1.0
```

### Consumer (one-time per mode you adopt)

```bash
# 1. Subscribe — pulls the mode + its domain dependencies, scaffolds cabling
prvng integration subscribe <mode-id> \
    --mode-file infra/modes/<mode-id>.ncl \
    --workspace-dir .

# 2. Edit the generated cabling file
$EDITOR infra/<ws>/integrations/<mode-id>.ncl

# 3. Validate that all bindings resolve
prvng integration validate <mode-id> --workspace-dir .

# 4. Invoke the mode
prvng integration invoke <mode-id> --binary <name>
```

## Without templates: minimal viable

The artifact format is documented in `provisioning/schemas/lib/integration/oci_artifact_format.ncl`.
You can write `contract.ncl`, `manifest.ncl`, `provisioning.ncl` from scratch following
the type definitions there. Templates only save copy-paste time.

## See also

- `reflection/qa.ncl::integration-*` — FAQ with diagrams
- `provisioning/schemas/lib/integration/oci_artifact_format.ncl` — types
- `prvng integration --help` — command surface