SKILL Guidelines | ONDE Docs

Core Promise

Journal = truth. Markdown = view. Terminal = UI. Time = first-class.
Agent writes content. onde handles bookkeeping.
No daemon. No hidden DB. No vector fog. Exact graph math. Deterministic merge.

The Agent Loop

1. Edit .md freely (any editor, any script, no onde running)
2. Run `onde lint` → parse → diff → journal → auto-fix → validate → materialize
3. Run `onde find` / `onde q` → load head.bin → query graph → pipe to reasoning
4. Run `onde git commit` → auto-message → stage .onde/ + changed MD → commit
5. Repeat. Idempotent. Atomic. Zero conflict.

Mental Model

Disk = workspace. .onde/journal/ops.md = append-only SSOT. MD = cache. Delete MD? onde materialize rebuilds.
Sync on demand. No watcher required. onde lint heals, journals, validates. --watch optional.
Time lives in data. Every fact carries created_at + invalidated_at. Query past: --as-of T. Rollback safe.
TOON density. ## Title:: type[N]{cols} + pipe rows. ~15 tokens/node. Pack 10x context per window.
Free-form preserved. Text before/after/between TOON = untouched. Schema validates structure only.
CRDT merge. Concurrent edits → deterministic line append. Git merges clean. onde lint resolves MD conflicts.

Syntax Contract

Element	Rule	Example
Property	`key:: value` (exact `::`, one space)	`status:: BLOCKED`
Link	`[[target]]` (ID/title/path/relative)	`depends:: [[task-881]]`
Edge props	`{key: val}` after link	`{critical: true, weight: 3}`
TOON header	`## Title:: type[N]{col1 col2}`	`## Backlog:: task[3]{id title status}`
TOON row	`- val \| val \| val`	`- task-01 \| Fix auth \| BLOCKED`
Group	`by prop:: value` (no `-` prefix)	`by status:: TODO`
Sort	`@sort: field asc, field desc`	`@sort: priority asc, deadline asc`
Free-form	Anywhere outside TOON/props	Preserved verbatim. Never validated.

Traps: Space before :: → syntax error. Comma inside [[ ]] → breaks parser. Column mismatch → error. Count mismatch → auto-fixed.

Schema Evolution

Day 1: Schemaless. Write freely. Syntax-only validation.
Grow: onde schema extract > .onde/schema.md. Review. Commit.
Schemaful: Enforces types, enums, edges, dirs, naming, budgets.
Dirs: tasks/**: type(task) @naming("{id}.md") @max-file-tokens(500)
Extensions: tasks/**: @ext(task.md) — scan .task.md files. @reject-ext(txt csv) — block junk.
Switch: mv schema.md schema.md.bak → schemaless. Zero data loss.
Soft: Add @soft to dir rule → warnings, not errors. Exit 0.

Temporal & Memory

HLC clock: (physical, logical, agent_id). Deterministic. No coordinator.
Point-in-time: onde find task --as-of 2026-04-05T12:00
Drift tracking: onde history task-882, onde diff HEAD~3 HEAD
Views: onde view --at T --name N (read-only, zero side effects)
Restore: onde restore --at T --reason "R" (forward ops, full provenance)
Journal eternal. Compact archives segments. History never deleted. Body versioned. Edges timestamped.

CLI Cheatsheet (Agent-Optimized)

Sync & Heal

onde lint                     # full pipeline
onde lint --dry-run           # preview, zero writes
onde lint --watch             # auto-sync on save
onde lint --soft              # errors → warnings
onde lint --continue-on-error # write valid, skip broken

Init & Distros

onde init -t devops           # create workspace from distro
onde init --list              # browse all distros
onde init --search memory     # search by category/name
onde init --local ./custom/   # load local distro
onde distro check             # compare schema vs latest
onde distro upgrade           # merge new fields

Query & Traverse

onde find task --status BLOCKED --format json
onde find task --group-by status --sort priority
onde q 'task[status=BLOCKED] >depends> task[status=TODO]'
onde q 'task | group by status | count | sort count desc'
onde deps task-882 --depth 3 --format mermaid
onde impact task-882 --format tree
onde path task-882 task-895

Temporal

onde find task --as-of 2026-04-05
onde find task --changed-between 2026-04-01 2026-04-07
onde history task-882 --format timeline
onde view --at 2026-04-05 --name apr5
onde restore --at 2026-04-05 --reason "rollback"

Organize & Recover

onde organize                 # format + sort + group
onde organize --split         # one file → many
onde organize --split --batch-size 30  # paginate: 30 nodes per file
onde organize --type task --merge --output overview.md
onde organize --dirs --rename # match schema rules
onde relink --to id           # stabilize links
onde materialize              # rebuild MD from journal
onde materialize --type task  # scope rebuild

Git

onde git commit               # auto-message, stage .onde/ + changed MD
onde git status               # uncommitted ops + staged files
onde git log --count 50       # scannable history

Embedded Queries (`onde::`)

Syntax: onde:: find task --status BLOCKED --fields id,title,status
Refresh: Auto-updates on every onde lint.
Formats: list, dense, table, cards, timeline, tree, mermaid, csv, json.
Bidirectional: --fields present → edit result → source updates → cascade.
Read-only: No --fields → manual edits overwritten next lint.
Eager: --with assigned.depends → multi-hop inline. Dot notation.
Dashboard: Stack multiple onde:: blocks. One lint refreshes all.

Agent Guardrails

Write MD freely. Never run background service. Never touch .onde/journal/ manually.
After every edit: onde lint. Before work: onde find task --status TODO --sort priority.
Never guess IDs or links. Query first. Use exact ID or full title.
If lint fails: read ERR file:line, fix, re-run. Do not skip. Atomic guarantee: error = zero writes.
Do not edit query results without --fields. Changes vanish.
Commit with onde git commit. Let it scope correctly. Non-onde files untouched.
Context tight? Use --format md-dense, --limit N, or --no-body.
Replace vector memory with exact queries. status=BLOCKED returns only blocked. Zero noise.
Schema too strict? onde lint --soft or mv schema.md schema.md.bak. Tighten later.
Broken workspace? onde materialize. Journal owns truth. MD disposable.

Quick Reference

Lint Exit States

State	Exit	Files Changed?	Action
`CLEAN`	0	No	Continue
`FIXED`	0	Yes	`onde git commit`
`ERROR`	1	No	Fix `ERR file:line`. Re-run.
`WARNINGS`	3	No	Commit safe. Fix later.
`FATAL`	2	No	Fix environment/journal.

Link Modes

Mode	Syntax	Lookup	Stability
ID	`[[task-882]]`	O(1) exact	Agent default. Stable.
Title	`[[Fix auth]]`	Fuzzy	Human-friendly. Ambiguous.
Path	`[[/tasks/fix.md]]`	File path	Breaks on move.
Relative	`[[./fix.md]]`	Relative	Compact clusters.

Output Formats

Flag	Use	Round-Trip?
`--format md`	Full nodes, reports	Yes
`--format md-dense`	TOON rows, agent context	Yes
`--format json`	Scripts, APIs, LLM input	No
`--format table`	Terminal scan	No
`--format mermaid`	Diagrams, GitHub/VS Code	No
`--format lines`	Grep/awk pipes	No

Common Traps & Fixes

Trap	Symptom	Fix
Edits vanish	Edited query result, overwritten	Add `--fields`. Enables bidirectional sync.
Lint blocks write	`ERROR` exit, zero files changed	Fix listed lines. Atomic by design.
Broken links after move	`[[/old/path.md]]` fails	`onde relink --to id` before moving.
Schema too noisy day one	Many `unknown property` errors	Start schemaless. `onde schema extract` later.
Context overflow	LLM chokes on large output	`--limit N`, `--format md-dense`, `--no-body`.
Git merge messy MD	Conflict markers in `.md`	`git pull` → `onde lint`. Journal heals MD.

Rule: Human first. Terminal second. Agent last.
Flow: Edit → Lint → Query → Commit.
Truth: Journal eternal. Markdown disposable. Time queryable. Graph exact.

onde ready. Agent proceed.