# Tools
Config and helper-tool entry points for the protocol.
The canonical installed entrypoint is:
```bash
zynk --help
```
The Rust implementation embeds `tools/message-profile.yaml` as its default profile. The previous Python scripts are preserved at git tag `python-v0.1-final`.
## Current Files
- `message-profile.yaml` - project-level profile for identity, headers, body style, mode switching, operator status, audit defaults, and common shorthand templates.
## zynk compose
Example:
```bash
zynk compose \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid abc123 \
--type request-review \
--ref outputs/decisions/010-brainstorm.md \
--mode review \
--body "Please review the brainstorm ADR."
```
Output:
```text
[from-codex via herdr] [herdr from=codex:w652dc9b3ded432-2 to=claude:w652dc9b3ded432-1 mid=abc123 type=request-review ref=outputs/decisions/010-brainstorm.md mode=review] BODY: Please review the brainstorm ADR.
```
By default the helper uses the embedded profile, so it can be run from outside the package root.
## zynk send herdr
Dry-run example:
```bash
zynk send herdr \
--pane w652dc9b3ded432-1 \
--dry-run \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid abc123 \
--type ack \
--re q4j8k1 \
--body "Received."
```
Send example:
```bash
zynk send herdr \
--pane w652dc9b3ded432-1 \
--from codex:w652dc9b3ded432-2 \
--to claude:w652dc9b3ded432-1 \
--mid abc123 \
--type ack \
--re q4j8k1 \
--body "Received."
```
The wrapper exits with a compose validation status if composition or validation fails. Otherwise it exits with the `herdr pane run` status.
Dry-run output is not delivery proof. It prints the message that would be sent and writes a warning to stderr. Audit dry-runs as `delivery_status=drafted`, not `sent`.
Dependency: the `herdr` CLI for non-dry-run sends.
## zynk status
Example:
```bash
zynk status \
--session-id portable-collab-design-20260528 \
--phase tooling \
--mode validate \
--artifact-ref zynk-status \
--lead-agent codex \
--status working \
--completed "compose and send-herdr behavior verified" \
--in-progress "status helper" \
--next-action "request review" \
--event "Updated rolling status"
```
By default the helper writes to `outputs/sessions/<session_id>/status.md`. `--root` is the runtime outputs root itself, not the project root. To write into another project's `outputs/sessions/...`, pass `--root <project>/outputs`. Rolling events are stored newest-first and capped by `--max-events` (default 10).
The workflow status enum is loaded from `message-profile.yaml` (`operator_interface.workflow_status_enum`) so the profile remains the source of truth.
Status files are generated artifacts. Avoid hand-editing multiline values into `status.md`; `zynk dashboard` reads the generated `key: value` and `- key: value` lines.
## zynk audit
Example:
```bash
zynk audit \
--session-id helper-build-20260528 \
--source-agent codex \
--source-address w652dc9b3ded432-2 \
--target-agent claude \
--target-address w652dc9b3ded432-1 \
--transport herdr \
--workspace-id w652dc9b3ded432 \
--mid abc123 \
--type request-review \
--mode review \
--ref zynk-audit \
--command-origin agent \
--payload "Please review audit behavior." \
--delivery-status sent \
--observed-by codex \
--verified-by helper-tool
```
By default the helper writes to `outputs/sessions/<session_id>/audit.md`. `--root` is the runtime outputs root itself, not the project root. To write into another project's `outputs/sessions/...`, pass `--root <project>/outputs`. It computes `payload_hash=sha256:<hex>`, `content_size`, and `previous_audit_id` from the existing audit file. Use `--payload-redaction-policy excerpt` for inline first/last excerpts, or `full` only for explicitly non-sensitive content. Sensitive categories configured in `message-profile.yaml` force `hash-only`.
Delivery status distinguishes `drafted` (message-shaped text produced locally), `sent` (transport/helper/operator confirms send), and `observed` (receiver or operator confirms receipt). `delivery_status=sent` rejects `verified_by=agent` because self-attested sender text is not transport delivery proof.
Use exactly one of `--payload` or `--payload-file`. The helper rejects duplicate explicit `audit_id` values and generates random 6-character ids when `--audit-id` is omitted. Appends use an advisory file lock where supported by the platform so `previous_audit_id` is read and the new record is written within one critical section.
The helper uses advisory file locking where supported by the platform.
## zynk dashboard
Example:
```bash
zynk dashboard \
--root outputs
```
By default the helper reads `outputs/sessions/*/status.md` and writes `outputs/dashboard.md`. To render another project's dashboard, pass `--root <project>/outputs`. The dashboard is static Markdown: active sessions, operator-attention rows, and links to each session's status, summary, and audit files.
## Tool Format
Prefer small, inspectable helpers with minimal dependencies. New runtime helpers should be added as `zynk` subcommands unless there is a concrete reason to split the binary.
## Candidate Helpers
- `zynk compose` - implemented; future work can add automatic `mid` generation and audit/status writes.
- `zynk send herdr` - implemented first herdr transport wrapper.
- `zynk status` - implemented ADR 022 rolling status writer.
- `zynk audit` - implemented ADR 023 audit writer.
- `zynk dashboard` - implemented ADR 022 static aggregate dashboard renderer.
Build only the helpers that a real workflow exercises.