First-Run Object Tutorial (Mint ➔ Promote ➔ Reference Linking ➔ Lifecycle Transitions)

Audience: Developers and autonomous AI agents getting started with ZQK Knowledge Kernel mutations.
CLI: Canonical binary zqk (or ./bin/zqk).
Core Principle: Always prefer typed, schema-aware kernel commands (zqk object ref add, zqk object promote, zqk new <kind>) over unstructured legacy field mutations (--field status=... or --field *_ref=...).

---

0. Orient: Discover Active Priorities

Before creating or modifying objects in the kernel, query the lead priority plan and shovel-ready backlog:

zqk workflow whats-next --format json

This returns active priority plan details, runway depth, and pending backlog items (BLI-*).

---

1. Step 1: Mint onto the Draft Plane (zqk new <kind>)

The standard, fail-safe way to create an object is by minting it with zqk new <kind> onto the Draft Plane:

zqk new question --title "First-run sanity question"

This creates a new object in .zqk/object_drafts/ with a deterministic ID (e.g. QUE-178...). Draft-plane objects remain safely isolated in working memory without polluting Content-Addressed Storage (CAS) or affecting audit metrics until they pass schema validation and Definition of Done (DoD).

---

2. Step 2: Enrich Schema Attributes

Enrich scalar attributes (such as body text, questions, or descriptions) on the draft object:

zqk object update <QUESTION_ID> --field question_text="What is the canonical object creation flow?"

---

3. Step 3: Promote to Authoritative CAS (object promote)

Once the object satisfies schema requirements and definition of done, promote it from the draft plane into authoritative CAS:

zqk object promote <QUESTION_ID>

object promote checks preconditions, computes the cryptographic CAS content address, logs a state journal mutation, and promotes the object into the master knowledge graph.

---

4. Step 4: Link Relationships Semantically (object ref add / object ref remove)

Connecting objects across the ontology graph is a first-class operation.

Preferred Modern Mechanism: zqk object ref

Do not use object update --field <kind>_ref=<ID> or edit slice arrays manually. Use schema-aware reference commands:

# Link a requirement to a backlog item (automatically resolves to requirement_refs):
zqk object ref add BLI-001 REQ-001

# Link multiple acceptance criteria to a requirement in a single atomic command:
zqk object ref add REQ-001 CRIT-001 CRIT-002

# Explicitly target a specific reference field when disambiguation is needed:
zqk object ref add BLI-001 PRI-001 --field priority_plan_ref

# Remove references cleanly:
zqk object ref remove BLI-001 REQ-001

Why object ref add is preferred:

• Schema-Aware Resolution: Automatically maps target IDs to scalar fields (*_ref) or slice arrays (*_refs).
• Target Existence Verification: Fails closed if the referenced object does not exist in CAS.
• Cycle Detection: Automatically prevents cycles in related_object_refs.
• Scope-Lock Enforcement: Enforces sealed priority plan boundaries.

(Legacy Fallback: Manual edits via zqk object update <ID> --field "requirement_refs=..." exist for raw migration scripts, but bypass kernel graph consistency validation).

---

5. Step 5: Advance Lifecycle States (object promote / demote / park)

Every object kind in ZQK follows an authoritative finite state machine (e.g. originated ➔ planned ➔ in_progress ➔ validated ➔ complete).

Preferred Modern Mechanism: Typed Lifecycle Transitions

Do not use object update --field status=<status>. Mutating status directly bypasses state machine check-valves and preconditions. Instead, use the dedicated lifecycle verbs:

# Advance object to the next valid lifecycle state (evaluates all entry gates & criteria):
zqk object promote BLI-001

# Promote multiple objects concurrently:
zqk object promote BLI-001,BLI-002,BLI-003

# Demote an object if verification fails or work needs rework:
zqk object demote BLI-001

# Intentionally park an object along a valid lifecycle exit:
zqk object park BLI-001

Why object promote is preferred:

• Validates all prerequisite acceptance criteria (CRIT-*) and tests (TST-*).
• Enforces strict unidirectional transition rules defined in .zqk/specs/lifecycles/.
• Emits real-time WAL lifecycle shockwave events for listeners and dashboards.

(Legacy Fallback: Direct field modification zqk object update <ID> --field status=<status> should only be used by administrative operators recovering from manual corruption).

---

6. Step 6: Read & Inspect the Object

Inspect objects using machine-readable JSON or human-centric TUI inspection:

# Retrieve full YAML representation
zqk object get <QUESTION_ID> --format yaml

# Autonomous agent semantic projection (token-efficient JSON)
zqk object get <QUESTION_ID> --format json

# Interactive visual inspector with lineage radar and CAS profile
zqk object inspect question <QUESTION_ID>

---

7. Step 7: Graph Traversal (neighbors & path)

Once relationships are linked, traverse the Knowledge Kernel graph:

# Discover immediate 1-hop dependencies and parent objects:
zqk object neighbors BLI-001

# Trace the ontological path between a Goal and an Acceptance Criterion:
zqk object path GOAL-001 CRIT-001

# Query related objects via reference edges:
zqk object related BLI-001

---

8. Clean Up (Optional)

When an experimental object is no longer needed, remove it cleanly:

zqk object delete <QUESTION_ID>

---

Summary of Modern vs. Legacy Mutation Patterns

---

Related Guides & References

• AI Agent Onboarding Guide — Agent directives and continuous loop discipline.
• Visual Lifecycle State Machines — State machine check-valves and transitions.
• Object Inspector & Policy Studio Manual — TUI inspector and live policy dry-runs.
• Community First-Run Guide — Complete onboarding and verification.