# Quickstart
This quickstart exercises the core runtime helpers:
1. `zynk compose`
2. `zynk send herdr`
3. `zynk status`
4. `zynk audit`
5. `zynk dashboard`
6. `zynk report`
7. `zynk decide`
8. `zynk reveal`
9. `zynk assign`
10. `zynk db serve`
11. Workflow profiles (ADR 037)
Run commands from the package root unless noted otherwise.
The steps below show `send` and `audit` separately to exercise each helper. As of
v0.5 (ADR 029), `zynk send herdr --session-id <id>` collapses steps 2 and 4: it
sends and writes the sender audit + corpus content in one command, so you would
not also run the standalone `zynk audit` for that same message.
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, work telemetry, operator decisions, custody /
reveal, 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 writes a point-in-time snapshot:
```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
```
When `.zynk/zynk.db` exists, `zynk dashboard` uses the DB-backed sessions and
latest status; otherwise it falls back to `outputs/sessions/*/status.md`.
## 8. Record Work Telemetry
```bash
zynk report think \
--session-id quickstart-demo \
--actor codex \
--text "Need review on the status helper."
```
Other work-event kinds include `system`, `tool`, `plan`, `usage`, `diff`,
`artifact`, `gate`, and `conflict`. Inspect each shape with
`zynk report <kind> --help`.
## 9. Serve The Live Dashboard
```bash
zynk db serve --port 8787
```
This serves the DB-backed live console on loopback. Browser writes are disabled
by default. To enable audited browser controls for send/decision/reveal in a
trusted local session:
```bash
zynk db serve --allow-writes --port 8787
```
## 10. Reveal Retained Payloads
Redacted payloads are revealable only if the original audited write used
`--retain-custody`. Reveal writes an operator-verified proof before printing
plaintext:
```bash
zynk reveal <audit_id>
```
## 11. Assign Participant Overlays
In a 3+-agent workflow, make the roster actor/role/trait aware (ADR 036). Each
assign is one audited write (`record_type=participant-overlay`, a non-transport
operator proof — never `delivery_status=sent`):
```bash
# the human operator is a `human`, NOT an agent (rendered distinctly)
zynk assign actor-kind --session-id session-001 --subject operator --kind human
# free-form, profile-defined role (machine never reasons over the role name)
zynk assign role --session-id session-001 --subject codex \
--role-id reviewer --role-label "Independent reviewer"
# a small KNOWN integrity-trait vocabulary the machine DOES reason over:
# independent, can_edit_source, non_iterating, can_verify_gate, can_merge_approve
zynk assign trait --session-id session-001 --subject codex --trait independent
```
The roster shows kind + role + trait badges with their asserter/asserted-at
provenance. The honesty bound is STRUCTURAL: a trait is only honored when the
proof-bound asserter is not the subject (no self-grant) and the proof is
operator-grade (`verified_by=operator`, `command_origin=operator`,
`transport=none`). zynk has no identity authentication, so the badge cites
provenance and never implies an authenticated identity. See
`zynk assign <actor-kind|role|trait> --help`.
## 12. Workflow Profiles (reusable gated-verification workflows)
A *workflow profile* (ADR 037) packages a reusable multi-agent
gated-verification workflow — its roles, the role→integrity-trait mapping, and
its gate sequence — by composing the existing verbs (no core change; separate
from the message/audit `--profile`). The repo ships:
- `examples/workflow-profiles/gated-verification-template.md` — the generic
template for any N-role workflow.
- `examples/workflow-profiles/smscode-gated-verification.md` — a sanitized
4-role reference instance.
- `scripts/workflow-profile-smscode.sh` — a deterministic reference script that
enacts the reference with real `zynk assign` overlay commands.
Run the reference into a session/DB:
```bash
ZYNK_BIN=$(command -v zynk) DB=.zynk/zynk.db ROOT=outputs SESSION_ID=session-001 \
bash scripts/workflow-profile-smscode.sh
```
Every overlay it writes is operator-asserted and roster-only; a profile declares
roles freely but never invents a machine-reasoned trait. See the
`zynk-workflow-profiles` skill for the full guidance.
## 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`.