Appendices | ONDE Docs

A. Migration Guides

Safe transitions. Dry-run first. Lock after clean.

Schemaless → Schemaful

onde schema extract > .onde/schema.md   # infer from existing files
# Edit. Remove junk types. Fix typos. Add @required/@default.
onde lint --soft                        # test law. warnings only.
# Fix data OR fix schema. Repeat until warnings drop.
onde lint                               # lock. errors block writes.
git add .onde/schema.md && git commit -m "Enforce schema"

v5 → v6 Directives

Old @id-prefix, @id-style, @id-pad deprecated. Replaced by id field + @default(...).

onde migrate --from 5 --to 6 --dry-run  # preview conversion
onde migrate --from 5 --to 6            # apply. rewrites schema.md
onde lint                               # verify. zero data loss.

Manual mapping if needed:

Old (v5)	New (v6)
`@id-prefix: task`	`id: string @id @default(counter(prefix: "task", pad: 3))`
`@id-style: kebab`	`id: string @id @default(kebab)`
`@id-pad: 4`	`id: string @id @default(counter(pad: 4))`

Bulk Enum Shift

Schema changed A B C → P0 P1 P2. Existing files now invalid.

# Option 1: Extend schema (backward compat)
# priority: enum(A B C P0 P1 P2) @default(P3)
# Option 2: Bulk replace in files
sed -i 's/priority:: A/priority:: P0/' tasks/*.md
sed -i 's/priority:: B/priority:: P1/' tasks/*.md
onde lint                               # validate. clean exit.
# Option 3: Soft transition
onde lint --soft                        # warnings only. fix gradually.

Link Mode Conversion

Workspace mixed ID/title/path links. Standardize to ID.

onde relink --audit                     # see distribution
onde relink --to id --dry-run           # preview changes
onde relink --to id                     # convert all. safe.
onde lint                               # verify resolution.

Rule: Convert before moving/renaming files. Path links break on move. ID links survive.

B. Performance & Scaling Tips

Workspace grows. Keep lint fast. Context clean.

Scenario	Fix
Lint slows on 10k+ files	Scope commands: `onde lint tasks/`. Use `--continue-on-error`.
Watch mode triggers too often	Add debounce. Scope to active dir. Don’t watch whole repo.
Token counting burns CPU	Budgets trigger counting. Set only when needed. Use `@soft` during drafts.
`ops.md` grows large	Auto-compacts at threshold. Let it run. History archived. Zero data loss.
Edits fan out to many files	Group changes. Lint once at end. Not after every save. Saves I/O.
`head.bin` feels stale	Delete it. `onde lint` rebuilds from journal. Fast. Safe.
Query returns too much	Use `--limit N`, `--format md-dense`, `--no-body`. Trim context.
Schema validation noisy day one	Start `--soft`. Promote rules to hard gradually. Team adapts without friction.
Git merge slows down	`ops.md` merges by line append. Fast. MD conflicts cosmetic → `onde lint` heals.
Dashboard queries lag	Embedded queries cache results. Only re-run when deps change. Stack wisely.

Rule: Lint scales with dirty files, not total files. Keep commits small. Compact runs automatic. Cache rebuilds on demand.

C. Glossary

User-facing terms. One line each. Zero theory.

Term	Meaning
TOON	Typed Object Outline Notation. Dense pipe rows. ~15 tokens/node.
CRDT	Conflict-free merge. Concurrent edits combine deterministic. Zero conflicts.
HLC	Hybrid Logical Clock. Timestamps every fact. Orders events across agents.
Journal	Append-only log. Single source of truth. Never deleted.
Materialize	Rebuild markdown from journal. Recover deleted files. Sync cache.
Mirror	Plain text reference to node. Auto-syncs when source changes. Editable.
Head.bin	Current graph cache. Fast load. Derivable from journal.
Ops.md	Active journal file. Records every change. Git-mergeable.
Schemaful	Strict mode. `schema.md` present. Types, edges, dirs, budgets enforced.
Schemaless	Free mode. No `schema.md`. Syntax-only validation. Fast capture.
Temporal Index	Fast history lookup. Query past states. Point-in-time traversal.
Lint	Sync + validate + auto-fix + materialize. One command. Heartbeat.
Cascade	One edit triggers inverses, mirrors, queries. Batched. Written once.
Round-Trip	Query output = valid input. `md`/`md-dense` re-ingest cleanly.
Distro	Pre-built template. Schema + dirs + SOUL.md. `onde init -t <name>`.
SOUL.md	Agent behavioral rules. Distro-specific workflow prompts. Lint reads, never enforces.
Marketplace	Registry of distros. Browse, search, install. `onde init --list`.

D. Marketplace & Template Distros

Pre-built graph topologies. Download physics. Drop schema + dirs + rules. Start writing.

onde init -t <distro>              # create workspace from distro
onde init --list                   # browse all distros
onde init --search <query>         # search by name, category
onde init --local <path>           # load custom local distro
onde init -t <name> --dry-run      # preview. no writes.

All Distros

#	Name	Category	Command	Topology
01	BountyHunter	Security	`onde init -t bountyhunter`	`target > exploit > poc > bounty`
02	DevOps	Workflow	`onde init -t devops`	`bug > blocks > PR > fixes > file`
03	DungeonMaster	Creative	`onde init -t dm`	`pc > npc > quest > location > item`
04	Hermes	Coding	`onde init -t hermes`	`attempt > fails > reason > tweaks > skill`
05	Lex	Legal	`onde init -t legal`	`claim > cites > precedent`
06	Palace	Memory	`onde init -t mempalace`	`wing > room > drawer`
07	StoryWeaver	Creative	`onde init -t storyweaver`	`character > arc > location > chapter`
08	SysAdmin	Workflow	`onde init -t sysadmin`	`server > alert > metric > resolution`
09	Karpathy Wiki	Memory	`onde init -t karpathy-wiki`	`concept > source > summary > comparison`

Short aliases: dm = DungeonMaster, mempalace = Palace, legal = Lex.

What You Get

.onde/schema.md — node types, edges, dirs, budgets
SOUL.md — agent behavioral rules. Distro-specific workflow prompts.
Directory structure matching distro topology
2-5 starter nodes per type
journal/ initialized. Empty. Ready.

After Init

Read SOUL.md. Understand distro workflow.
Write nodes. Lint enforces schema.
Graph grows. Time-travel via journal.
Zero lock-in. Delete schema.md → schemaless.

Custom Distros

# Build your own
mkdir my-distro && cd my-distro
# Write: distro.toml, schema.md, soul.md, nodes/

# Validate
onde init --local . --dry-run

# Use
onde init --local /path/to/my-distro/

Distro Upgrade

Distro evolves. Workspace independent. Schema not auto-updated.

onde distro check                 # compare workspace vs latest
onde distro diff                  # show what changed
onde distro upgrade --dry-run     # preview merge
onde distro upgrade               # merge new fields. preserve data.

Rule: Pick distro. Run onde init -t <name>. Read SOUL.md. Start writing. Lint syncs. Graph enforces.

End of Guide.
onde ready. Workspace yours. Journal eternal. Markdown disposable. Time queryable. Graph exact.
Edit → Lint → Query → Commit. Repeat.