---
id: TASK-18.3
title: Document interpolation limitations and supported fields
status: Done
assignee:
  - codex
created_date: '2026-02-19 17:45'
updated_date: '2026-02-19 17:51'
labels: []
dependencies: []
references:
  - README.md
  - lua/zync/api/configurator/sandbox.lua
parent_task_id: TASK-18
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Add documentation for limitations/edge cases and a reference list of known config keys available for interpolation.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Document limitations: missing keys remain unchanged, interpolation is string-only, and cycles are left unresolved.
- [x] #2 Provide a reference list of common keys available for interpolation in zconf (e.g., board, runner, build_dir, project_dir, profile, zephyr_ws, zephyr_base).
- [x] #3 Clarify that custom keys are not allowed at top-level due to schema; interpolation is intended inside existing supported fields (like args/profiles).
<!-- AC:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Added limitations/edge-case notes and top-level schema restriction to README interpolation section; referenced supported keys list already present.
<!-- SECTION:NOTES:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Summary:
- Added interpolation limitations/edge cases and schema restriction note to the README interpolation section.
- Confirmed supported keys list is present alongside the feature description.

Tests:
- Not run (documentation-only changes)

Notes:
- No Definition of Done items were defined for this task.
<!-- SECTION:FINAL_SUMMARY:END -->
