Provision your first vertical in 5 minutes

This walks you from "I have a Frank tenant" to "data lands in the ontology" using the frankctl pipelines apply -f path the v4 spec introduced. It assumes:

• frankctl is installed (cd frank-cli && npm install && npm run build && npm link).
• You have an OWM API key (or you'll swap in another REST endpoint).
• You have credentials for a Frank tenant.

By the end you'll have a Source, Pipeline, and BackingDataset all provisioned from a single YAML file, with bronze rows landing on the next scheduled sync.

1. Authenticate

frankctl auth login

Follow the device-code prompt. Token caches under ~/.frankctl/. Sanity check:

frankctl sources list --limit 5

If that returns rows, you're authed.

2. Copy the example

Pick the closest shape from dev_docs/examples/pipelines/. For a first try, copy air-quality-observed/ — it exercises every piece (Source + Pipeline + BackingDataset + ensure_schema:):

cp -r dev_docs/examples/pipelines/air-quality-observed \
      verticals/my-first-vertical
cd verticals/my-first-vertical

3. Edit the YAML

Open air_quality_observed.yaml and change:

• Every metadata.name to something unique for your tenant (e.g. cm_felgueiras_air_quality_observed).
• Source.spec.source_config.query_params.lat / lon to your monitoring location.
• BackingDataset.spec.ontology_tenant_id if your tenant fans out into multiple ontology tenants (otherwise leave it as ts_demo or remove the line entirely).

Don't touch:

• apiVersion, kind, or the document structure.
• pattern_id: rest_api (changing it triggers a 409 on re-apply).
• iceberg_namespace / iceberg_table (immutable per BD; pick names you're comfortable with for the lifetime of this BD).

4. Dry-run

export OWM_API_KEY=<your key>
frankctl pipelines apply -f air_quality_observed.yaml --dry-run

The dry-run validates YAML shape client-side and prints the apply plan (which docs would POST, in dependency order). It doesn't talk to the server. If the plan looks right, drop --dry-run and re-run.

5. Apply

frankctl pipelines apply -f air_quality_observed.yaml

Expected output (~2-5 seconds):

applying Source/cm_felgueiras_air_quality_observed...
applying Pipeline/cm_felgueiras_air_quality_observed...
applying BackingDataset/cm_felgueiras_air_quality_observed...
applied 3 doc(s)
KIND            NAME                                ID
Source          cm_felgueiras_air_quality_observed  bd4b...
Pipeline        cm_felgueiras_air_quality_observed  c38b...
BackingDataset  cm_felgueiras_air_quality_observed  4575...

If you see a 409, jump to docs/troubleshooting/apply-errors.md. The most common cause for a brand-new vertical is Pattern 'rest_api' not found — meaning the Frank deployment hasn't seeded the pattern catalog. Check with frankctl patterns list.

6. Trigger the first sync

The Source will sync on the next cron tick (top of the hour in the example). To fire one immediately:

frankctl sources sync <source-id-from-apply-output>

Wait ~30 seconds, then:

frankctl sources history <source-id> --limit 3

A row with status=completed and records_extracted > 0 means bronze got data.

7. Confirm the ontology binding

# The schema Frank ensured on apply:
curl https://ts.ubp.pt/ontology/api/v1/schema/types/air_quality_observed

# Once the BD has fired its first sync, the data:
curl "https://ts.ubp.pt/ontology/api/v1/air_quality_observed?ontology_tenant_id=ts_demo&limit=5"

8. Commit the YAML to git

The YAML is now the source of truth for this vertical. Commit it. Re-running apply -f against the same file is a no-op — runtime state (cursor, last_sync_at) is preserved. Edit and re-apply to change mutable fields.

git add verticals/my-first-vertical
git commit -m "provision cm_felgueiras air quality vertical"

What's next

• Read docs/guides/cli.md for the full apply semantics + --allow-recreate.
• Read docs/reference/patterns.md to see what other connectors are available.
• Try frankctl ai compose-pipeline --output yaml to scaffold a new vertical from an intent description.
• If you have a wizard-built pipeline you want to move into git, frankctl pipelines export <id> -o yaml > existing.yaml round-trips it. See the "Adoption workflow" section of cli.md.

Got stuck?

• frankctl pipelines apply --dry-run -f ... shows the apply plan without POSTing — useful for debugging multi-doc YAML structure.
• frankctl sources history <id> shows the last N sync runs with errors inline.
• frankctl sources streams diff-types <source-id> <stream-id> shows bronze column types vs the stream's declared JSON-Schema — useful when syncs are failing on type drift (#469).
• docs/troubleshooting/apply-errors.md has copy-paste recovery flows for the common 409s.