---
id: TASK-9.3
title: Document pre-run rebuild and --norebuild flag for `zync run`
status: Done
assignee:
  - '@codex'
created_date: '2026-02-04 09:46'
updated_date: '2026-02-04 10:39'
labels: []
dependencies: []
references:
  - README.md
parent_task_id: TASK-9
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Update user-facing documentation to describe the new pre-run rebuild behavior when running the simulator binary directly, and the `--norebuild/-n` option to skip it. Clarify that fallback to `ninja run` remains unchanged.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Docs describe that `zync run` performs a build before executing the simulator binary directly by default.
- [x] #2 Docs describe the `--norebuild/-n` option and when it applies.
- [x] #3 Docs note that fallback to `ninja run` behavior is unchanged.
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1. Update the `zync run` behavior section in `README.md` to mention the new pre-run rebuild when executing the simulator binary directly.
2. Add the `--norebuild/-n` option description near the run-args explanation and clarify it only applies to direct simulator-binary execution.
3. Explicitly state that `ninja run` fallback behavior remains unchanged.
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Updated README run behavior to document pre-run rebuild for simulator binary execution, `--norebuild/-n`, and unchanged ninja-run fallback.
<!-- SECTION:NOTES:END -->
