---
id: TASK-18
title: >-
  Document zconf variable/config value referencing in code annotations and user
  docs
status: Done
assignee:
  - codex
created_date: '2026-02-19 17:40'
updated_date: '2026-02-20 08:48'
labels: []
dependencies: []
references:
  - lua/zync/lib/utils.lua
  - lua/zync/api/configurator.lua
  - lua/zync/api/configurator/sandbox.lua
  - README.md
  - docs/
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Add documentation for ${key} placeholder interpolation in zconf.lua, including code annotations and user-facing docs that explain recursive/config-scoped interpolation and profile-aware resolution.

This task will be completed via subtasks covering code annotations and user documentation updates.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Document interpolation behavior in code annotations/comments near implementation and schema references.
- [x] #2 Update user-facing docs (README or docs) with examples of ${key} placeholders, profile-aware resolution, and supported fields.
- [x] #3 Docs mention limitations/edge cases (e.g., missing keys left unchanged, interpolation scope).
<!-- AC:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
User requested explicit tasks for documenting ${key} interpolation; converting this parent task to a subtask-driven breakdown.
<!-- SECTION:NOTES:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Summary:
- Documented ${key} interpolation behavior in code annotations and user docs, including supported keys, examples, and profile/CLI scope.
- Added limitations/edge-case notes and clarified schema constraints for top-level keys.

Tests:
- Not run (documentation-only changes)

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