Edge & Headless First-Run Guide
Audience: Operators on remote servers, appliances, DGX/GPU clusters, SSH-only hosts, or local SLM runtimes without desktop IDE agents.
Related Guides: COMMUNITY_FIRST_RUN.md, AI_AGENT_ONBOARDING.md.
Goal
Treat ZQK as the control plane: init → seat → thin AGENTS.md → sync report. Do not write IDE rule forests (.cursorrules, …) unless you pass --all-vendors. Do not invent organ binaries (zqk-neuron, …) into the community default seed until market probes close.
Sequence
# After system init on the appliance / host
zqk system agent-onboard --headless --format json
# Or auto Vector B when no IDE markers are present:
zqk system agent-onboard --format json
| Stage | Vector B behavior |
|---|---|
| detect | Reports IDE markers (usually empty) + edge_signals (SPECIALIZATION_TIER, NVIDIA/DGX/SSH hints, optional .zqk/agent-runtime/headless_edge.json) + open market_probe questions |
| seat | Same default seating pack as community |
| prime_workspace | Only .agents/AGENTS.md (unless --all-vendors) |
| prime_kernel | .zqk/agent-runtime/agent_workspace_sync.json |
| smoke | AGENTS.md + sync report |
Optional marker (operator-declared, not required):
mkdir -p .zqk/agent-runtime
echo '{"schema":"zqk_headless_edge_v1","note":"appliance control plane"}' > .zqk/agent-runtime/headless_edge.json
Specialization (when meaningful on the node):
export ZQK_SPECIALIZATION_TIER=neuron # or muscle|heart|lung — see pkg/specialization
Market probes (open until evidence)
Returned under market_probe_open in agent-onboard JSON. Canonical list also in the strategy doc. Do not ship organ-named community binaries until human ACK on these signals.
Wake / interrupt
Prefer scheduler ticks and feed/delivery_mode=notify — not Terminal paste. See mesh wake policies when multi-agent seats exist.
After Setup
zqk workflow whats-next --format jsonCOMMUNITY_FIRST_RUN.md— First-run setup, CLI tools, and kernel verification.AI_AGENT_ONBOARDING.md— Agent operating directives and seating configuration.