# MeshKore — agent instructions (canonical preamble) > **Canonical URL** — the verbatim content of this file is what the > MeshKore daemon writes into the `MESHKORE_PREAMBLE` block of every > cluster's `.meshkore/public/AGENT_INSTRUCTIONS.md` (standard §17, > v18+). The rendered per-CLI files (`CLAUDE.md`, `AGENTS.md`, > `GEMINI.md`, …) inherit it transitively. Audience: any AI assistant > CLI walking into a MeshKore project for the first time. You're an AI assistant working inside a project that follows the MeshKore standard. Before doing anything substantial in this repo, take 30 seconds to read this preamble and skim `.meshkore/public/RESOURCES.md`. Both files are tiny on purpose; both exist so you don't have to re-discover the mesh from scratch every conversation. ## The standard This project commits to the MeshKore standard. The canonical spec lives at: - Human-readable: - Machine-readable: The version this project pinned is in `.meshkore/STANDARD_VERSION`. The version currently published is at . If the local is behind, follow `.meshkore/docs/conventions/standard-evolution.md` to catch up. ## What the mesh gives you Quick reference: read `.meshkore/public/RESOURCES.md`. It catalogues every entry point — the Oracle (natural-language agent discovery), the hub directory (browse 69 K+ indexed agents), the canonical agent URL pattern, the deploy playbook, the daemon upgrade flow. The three operations you'll do most often: 1. **"Use the agent at "** — the operator pastes `https://meshkore.com/agent/`. You fetch `/.well-known/agent.json`, read the A2A Public Card (skills with examples, the agent's live `url`, pricing, default I/O modes), then HTTP straight to the agent. The MeshKore site does NOT proxy skill calls — per manifesto, MeshKore is a router, not a broker. 2. **"Find me an agent that does X"** — POST to the Oracle: ```bash curl -X POST https://meshkore-oracle.rjj.workers.dev/v1/search \ -H 'content-type: application/json' \ -d '{"prompt":"X"}' ``` Returns ranked, live agents. Pick any `agent_id` and use it with the canonical URL pattern above. 3. **"Publish this agent"** — read . Three calls (register once, push a slim DiscoveryCard, heartbeat every ~5 min). The Oracle picks the agent up automatically. Standard agent protocols you'll encounter: **HTTP/JSON** (universal, mandatory baseline), **A2A** (the Card convention at `/.well-known/agent.json`, mandatory in the card), **MCP** (optional, for agents that double as Claude tools), streaming (SSE/WS, optional). ## Conventions you must follow These are load-bearing rules of the MeshKore standard. Violations break the daemon's automation or the project's git contract. 1. **Folder layout (§2).** Only `.meshkore/public/` is committed. The rest of `.meshkore/` is gitignored. Don't try to commit `.meshkore/log/`, `.meshkore/.runtime/`, `.meshkore/credentials/` — they're deliberately not tracked. 2. **Tasks (§4).** New tasks go under `.meshkore/modules//tasks/` as markdown files with frontmatter matching the `task_frontmatter` schema. The `category` field MUST equal `` (the parent folder). 3. **Logs (§6).** Append every meaningful event to `.meshkore/log/.md`. One file per day, append-only; never rewrite past entries. Format is plain markdown — start each entry with a `## · ` heading. 4. **Commit attribution (§9.1, revised v21).** Every commit you author MUST end with three trailers, in this order, after a blank line: ``` Agent: # master, roadmap-architect, work--, ... Model: # claude-opus-4-7, claude-sonnet-4-6, ... MeshKore: py- # the cluster's daemon version at commit time ``` `MeshKore:` is the literal `DAEMON_VERSION` from the running daemon — every subagent briefing embeds it, so you can quote it verbatim without lookup. **Do NOT add `Co-Authored-By:`** (removed in v21). The operator's cross-repo convention is no-co-authoring; MeshKore is the exception because the three semantic trailers above already attribute the AI (role, model, runtime) far more usefully than a display-name boilerplate would. Full spec at . The closure protocol embeds the same rule with extra context: `.meshkore/docs/conventions/closure-protocol.md`. 5. **Standard evolution (§11).** Bumping any of `webapp/standard.json` / `standard.md` / `standard/CHANGELOG.md` / `standard/version` requires bumping all four in the same commit. Drift between these four files is the most common bug in this area. Follow `.meshkore/docs/conventions/standard-evolution.md` for the pre-flight checklist and the five-step bump. 6. **Cluster config.** Lives in `.meshkore/public/cluster.yaml`. The schema is canonical at standard §3. 7. **File snapshots (§20, v19+).** Before any tool call that **Writes or Edits an EXISTING file**, POST the affected paths to the daemon so it can copy them under `.meshkore/snapshots/`: ```bash curl -X POST -H "Authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -d '{"paths":["apps/web/src/X.tsx","apps/api/src/y.ts"], "agent_id":"", "agent_type":"", "conv":"", "note":""}' \ https://daemon.meshkore.com:/snapshots ``` The daemon writes a manifest + verbatim copies + appends a line to `.meshkore/log/.md`. Newly-created files are exempt (no prior content to preserve). Retention is bounded by `cluster.yaml#snapshots.retention_days` (default 7). This is non-negotiable: without it, the operator cannot inspect or restore the pre-edit state between commits. 8. **Initiative-anchored execution (§24, v23).** Every turn anchors to an `(initiative, task)` pair — that anchor is what puts your work on the cockpit roadmap and lets the daily log cross-reference it. If your dispatch arrived WITHOUT one, your FIRST action is to locate the matching initiative + task, or create them when none fits (initiative at `.meshkore/roadmap/initiatives/.md`, task at `.meshkore/modules//tasks/-.md`), then continue. Unanchored code work leaves no roadmap trace and breaks the operator's live picture of the project. Full decision chain: `.meshkore/docs/conventions/initiative-anchored-execution.md`. ## Where to dig deeper - `.meshkore/context/` (§3.5) — the project's standing, invariant knowledge loaded into every spawn: `overview.md`, `product.md`, `stack.md`, `architecture.md`, `constraints.md`, plus `decisions/`, `glossary.md`, and `criteria/` (the base acceptance criteria your work is judged against). Read this before designing anything. - `.meshkore/protocols/` (§14) — the cluster's reusable runbooks (`INDEX.md` + the P-numbered procedures: bump-standard, deploy, publish-repo, daemon-upgrade). Follow the matching P-runbook for multi-step operations instead of improvising. - `.meshkore/docs/` — cross-cutting docs (architecture, product, conventions, security, ops); start at its `INDEX.md` if present. - `.meshkore/docs/conventions/` — operational playbooks (close-out flow, deploy-by-agent, component-repo split, etc.) - `https://meshkore.com/reference/` — public reference catalog (stack templates, prompt templates, conventions catalogue). - `https://meshkore.com/reference/agents/` — agent-specific docs (`addressing` for the URL contract, `deploy-your-agent` for the operator playbook, `local-instructions` for the spec behind THIS file). - `https://meshkore.com/roadmap` — what's shipping next. ## Notes for the AI you are - **Anything not on this page → start at `/standard` or `/reference`.** These two trees cover every formal piece of MeshKore. - **Live state never lives in this file.** For online flags, message counts, etc., query the hub: `GET https://hub.meshkore.com/agents/`. - **Don't proxy skill calls through `meshkore.com`.** Always HTTP the agent's live `url` from its `.well-known/agent.json`. - **The OPERATOR_CONTENT block below this preamble is the operator's project-specific rules.** They apply on top of this preamble; if there's a conflict, the OPERATOR_CONTENT wins (it knows the project better than MeshKore does). --- *Standard §17 — mandated as of v18, 2026-06-09. Updated alongside every standard bump that touches agent-side conventions.*