MDBX Agent Execution Rules

This document defines guardrails for lower-capability models working on MDBX.

Primary goal

Produce outputs compatible with the full MDBX spec set. Resolve ambiguity by prioritizing:

1. local-first behavior
2. long-term format stability
3. project-centered storage
4. native attachments
5. safe mergeability
6. better sync behavior than KDBX

Absolute requirements

You MUST:

• read 00.MDBX-Spec-Index.md first
• read relevant numbered specs before proposing architecture changes
• treat this folder as the source of truth
• keep terminology stable
• keep requirements testable
• preserve backward compatibility
• preserve unknown fields during read/write
• keep secrets encrypted and authenticated at rest

You MUST NOT:

• invent new core object types without a spec update
• replace project with a flat entry-only model
• treat attachments as optional undocumented side files
• require a server for normal open/edit/save/import/export/merge/recover flows
• design small edits that require full-vault rewrites
• silently auto-merge conflicting values in the same secret field

Required working method

1. Identify governing spec files for the task
2. List affected invariants
3. Design the smallest compliant solution
4. Define data shape before APIs
5. Define persistence before UI
6. Define conflict behavior before sync code
7. Define acceptance checks before done

Decision order

1. security correctness
2. durability and recoverability
3. compatibility stability
4. local-first behavior
5. sync friendliness
6. performance
7. implementation simplicity
8. UI convenience

Failure definition

A proposal fails if it:

• rewrites full vault content for tiny metadata edits
• removes project as first-class container
• leaves attachment metadata/integrity undefined
• cannot explain concurrent edit detection
• cannot explain partial-corruption recovery
• cannot explain future compatibility behavior