# Quickstart
This quickstart exercises the four runtime helpers:
1. `zynk compose`
2. `zynk send herdr`
3. `zynk status`
4. `zynk audit`
5. `zynk dashboard`
Run commands from the package root unless noted otherwise.
The herdr pane and workspace IDs below are examples from the original trial session. Replace them with current IDs from `herdr pane list` when sending real messages.
## 1. Build
```bash
cargo build
```
This builds one command with subcommands:
```bash
./target/debug/zynk --help
```
## 2. Run Tests
Verify the environment before sending or writing runtime records:
```bash
cargo test
```
The test suite covers message composition, herdr transport wrapping, status updates, audit append behavior, and dashboard rendering.
## 3. Compose A Message
```bash
zynk compose \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid qk1234 \
--type request-review \
--ref zynk-status \
--mode review \
--body "Please review the status helper."
```
Expected shape:
```text
[from-codex via herdr] [herdr from=codex:w652dc9b3ded432-2 to=claude:w652dc9b3ded432-1 mid=qk1234 type=request-review ref=zynk-status mode=review] BODY: Please review the status helper.
```
## 4. Send Through Herdr
Dry-run first:
```bash
zynk send herdr \
--pane w652dc9b3ded432-1 \
--dry-run \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid qk1234 \
--type request-review \
--ref zynk-status \
--mode review \
--body "Please review the status helper."
```
Dry-run output is not delivery proof. Do not record `delivery_status=sent` for a dry-run or a copied draft.
When running inside herdr and ready to send, remove `--dry-run`:
```bash
zynk send herdr \
--pane w652dc9b3ded432-1 \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid qk1234 \
--type request-review \
--ref zynk-status \
--mode review \
--body "Please review the status helper."
```
## 5. Update Rolling Status
```bash
zynk status \
--session-id quickstart-demo \
--phase tooling \
--mode validate \
--artifact-ref zynk-status \
--lead-agent codex \
--status working \
--completed "message composed" \
--in-progress "status and audit quickstart" \
--next-action "append audit record" \
--event "Started quickstart workflow."
```
This writes:
```text
outputs/sessions/quickstart-demo/status.md
```
Runtime `outputs/sessions/` is ignored by git in this package.
When writing into another project, pass `--root <project>/outputs`. The `--root` value is the runtime outputs root itself, not the project root.
Status files are generated artifacts. Avoid hand-editing multiline values into `status.md`; `zynk dashboard` reads the generated `key: value` and `- key: value` lines.
## 6. Append Audit Record
```bash
zynk audit \
--session-id quickstart-demo \
--source-agent codex \
--source-address w652dc9b3ded432-2 \
--target-agent claude \
--target-address w652dc9b3ded432-1 \
--transport herdr \
--workspace-id w652dc9b3ded432 \
--mid qk1234 \
--type request-review \
--mode review \
--ref zynk-status \
--command-origin agent \
--payload "Please review the status helper." \
--delivery-status sent \
--observed-by codex \
--verified-by helper-tool
```
This writes or appends:
```text
outputs/sessions/quickstart-demo/audit.md
```
The same `--root <project>/outputs` rule applies when appending audit records for another project.
Use `--delivery-status drafted --verified-by agent` when auditing a protocol-shaped draft that was printed in a pane but not sent through a transport.
## 7. Render Dashboard
```bash
zynk dashboard
```
This reads `outputs/sessions/*/status.md` and writes:
```text
outputs/dashboard.md
```
To render a dashboard for another project, pass that project's runtime outputs root:
```bash
zynk dashboard --root /path/to/project/outputs
```
## Troubleshooting
- `zynk: command not found` means the binary is not installed; use `cargo run -- <subcommand>` from the package root or `cargo install --path .`.
- `herdr CLI not found` only affects live sends. Use `--dry-run` outside herdr, or install/run herdr before removing `--dry-run`.