---
id: TASK-1.1
title: Parse profiles from zconf.lua and select default profile
status: Done
assignee:
  - codex
created_date: '2026-01-29 15:37'
updated_date: '2026-01-29 16:00'
labels: []
dependencies: []
references:
  - lua/zync
  - zconf.lua
  - spec
parent_task_id: TASK-1
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Extend zync config loading to support `profiles` and `default_profile` fields. Provide deterministic default selection (preserving profile definition order in `zconf.lua`) when no profile is explicitly chosen, and surface clear errors for missing/invalid profiles while keeping non-profile projects working as before.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 zync config loader reads `profiles` and `default_profile` keys without breaking existing configs
- [x] #2 When no profile is specified on the CLI, zync selects `default_profile` if set; otherwise selects the first profile defined in the config in a deterministic way
- [x] #3 When a requested profile is missing or invalid, zync fails with a clear error message that lists available profile names
- [x] #4 If `profiles` is absent, zync behavior matches current non-profile projects
- [x] #5 Docs updated to describe config schema for `profiles` and `default_profile`
- [x] #6 Tests cover default selection, missing profile errors, and legacy config behavior
- [x] #7 Deterministic default uses profile order as defined in `zconf.lua` (no sorting)
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1) Inspect config loading and schema: find where `zconf.lua` is read/validated and how board/runner are currently resolved.
2) Add `profiles` and `default_profile` parsing in the config layer, keeping legacy configs unchanged.
3) Implement deterministic default selection (use `default_profile` if set; otherwise the first profile in `zconf.lua` insertion order).
4) Add validation + error messaging for unknown profile (include list of available profiles).
5) Update docs for config schema.
6) Add/adjust Busted tests for default selection, missing profile errors, and legacy behavior.
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Implemented profile parsing/selection in `lua/zync/api/configurator.lua` (default_profile + first profile order, error for unknown profile with list).

Extended zconf schema in `lua/zync/api/configurator/sandbox.lua` to allow `profiles` and `default_profile` with conditional board requirement.

Updated docs in `README.md` and config type hints in `lua/zync/api.lua` for profiles.

Added tests for profiles in `spec/api_spec/configurator_spec.lua` and `spec/api_spec/sandbox_spec.lua` (not yet run).

Ran `busted` (all 40 specs passing).

Updated test harness to load local repo modules via absolute package.path and clear cached zync modules (spec/zync_test.lua).
<!-- SECTION:NOTES:END -->
