mdevolved: Instructions file for Codex

MDevolved Agent Instructions

These instructions apply to the entire repository. They are the operational contract for humans and coding agents working on MDevolved.

Mission

Build a self-hostable Cloudflare application that lets one owner pair, browse, search, lightly edit, snapshot, back up, and recover explicitly paired Markdown Sources, including folders and Obsidian workspaces, then use that durable context to coordinate independent AI harnesses through versioned Projects, Work Packets, Handoffs, Reviews, Decisions, Knowledge, and Skills. A new user should be able to deploy the service and pair a first Source without operating a server. MDevolved complements the subscriptions and native harnesses the owner already uses; it does not become their model runtime.

Instruction precedence

1. User instructions for the current task.
2. This file and any narrower AGENTS.md in the edited subtree.
3. Architecture, security, compatibility, and collaboration contracts in docs/.
4. Product, onboarding, quality-gate, and development documents in docs/.

If two rules conflict, stop and surface the conflict before making a durable or security-sensitive change.

Non-negotiable product boundaries

• This is a public Apache-2.0 Community project. Never commit Source content, private production receipts, credentials, pairing tokens, WebAuthn data, account identifiers, or production binding IDs.
• The default deployment is one integrated Cloudflare Worker serving the web app, API, and pinned YAOS-compatible sync routes.
• The initial product is single-owner and multi-Source. Do not imply multi-user authorization exists.
• Distribution has two modes: the current free Community deployment and a future optional managed service. Community must remain complete, independently deployable, and free of any control-plane or billing runtime dependency.
• A managed deployment preserves the single-owner model by provisioning one isolated data-plane cell per owner. Do not add a shared tenant column to the current D1 schema or share D1, R2, Durable Object namespaces, OAuth KV, or runtime secrets between owners.
• YAOS-compatible Yjs state is the live synchronization source of truth. D1 search rows and R2 Markdown mirrors are derived projections.
• V1 editing is Markdown text editing and note creation only. Deletion, rename, attachment mutation, conflict UI, and .obsidian writes are out of scope unless an accepted decision changes this.
• Default authentication is built-in passkeys. Cloudflare Access may be an advanced option, but must not block sync endpoints.
• A normal installation must not require a local terminal. Development may.
• Agent integrations use MDevolved's remote MCP boundary. Hermes and Hoplon are optional external clients, never required runtime dependencies.
• MDevolved Sync synchronizes only the explicitly paired Markdown folder. MDevolved Sync for Obsidian synchronizes only the explicitly paired vault. Neither connect agents, create Projects, transport collaboration records, or manage Project permissions.
• The normal Project path begins in the owner's existing agent with Connect this project to MDevolved. The website is the owner surface for setup, exact consent, activity/provenance, Decisions, revocation, recovery, and advanced inspection; manual Project construction is a fallback.
• Orca ADE and similar external agent workbenches are optional execution environments, never required MDevolved runtimes. MDevolved does not launch or stop their agents, send terminal input, manage worktrees or branches, import raw transcripts, or change client permission and sandbox settings. Compatibility uses the same OAuth/MCP, portable-file, and inert-skill boundaries as every other client.
• Agent collaboration never prescribes a model brand or fixed planner, builder, reviewer sequence. Roles belong to individual Attempts, and the owner chooses which compatible harness participates next.
• Domain contracts and application services remain transport-neutral. MCP is the primary live adapter and portable Markdown/JSON is the universal fallback; experimental MCP Tasks, A2A, or vendor-specific packs cannot become required durable state.