AGENTS.md for a folder synced with a space

When a space is synced with a SharePoint, OneDrive, Google Drive, Dropbox or Proton Drive folder, Cloud Sync writes the file below to the top of that folder, once, if no AGENTS.md is there yet. Coding agents such as Claude Code, GitHub Copilot, Codex and Cursor read AGENTS.md before they work in a folder, so they learn how the folder maps to the space and what not to touch.

It suits a repository synced with GitHub sync just as well: copy it to the top of the repository. The file ends with an empty This project section. Add what an editor of your space must know there; Cloud Sync never overwrites the file once it exists.

The file

# AGENTS.md — a folder synced with a MeshWeaver space

This folder is kept in sync with a **MeshWeaver space** — by the MeshWeaver cloud sync (SharePoint,
OneDrive, Google Drive, Dropbox, Proton Drive) or by GitHub sync. It reads like an ordinary folder
of files, but every file here is one **node** in that space, and the sync carries your edits in
both directions. These instructions are for any agent (Claude Code, Copilot, Codex, Cursor, …) or
person editing the files directly.

The space this folder mirrors is named in `index.md` at the top of the folder.

## How files map to nodes

Every page of the space is a **`.md` file** you can open and read anywhere.

| File | Becomes |
|---|---|
| `index.md` (top level) | The space itself: its name, description and type. |
| `X.md` with only front matter and text | A Markdown page. The optional YAML front matter (`name`, `description`, `icon`, `nodeType`) is the page's metadata; the body is its text. |
| `X.md` ending in a ` ```json meshweaver-content ` block | A typed page (a record, a setting, a source…). The front matter (`nodeType`, `name`, `description`, `icon`, `category`, `order`) is its metadata, the closing block is its **data**, and the text between them is a read-only summary: edit values in the block or the front matter, never in the summary. |
| `X.cs` | C# source, with a `// <meshweaver>` header that names the node. Code stays code. |
| `X.json` | An older form of a typed page. It is still read, and the sync keeps writing it as `.json` while it is here. |
| `X/` beside `X.md`, or `X/index.md` | The children of page `X`. |
| anything else (`.pdf`, `.docx`, `.xlsx`, images, …) | A file in the space's content, stored as it is, never parsed. |

**A folder needs a node file beside it.** Add `Reports.md` next to `Reports/`, or the folder's
pages have no parent in the space. The file's name, without its extension, is the node's id, and
that id becomes part of the node's address. Use plain names without spaces or slashes.

## Rules for editing here

1. **Edit, don't regenerate.** Change the lines you mean to change. Rewriting a whole file
   re-orders its members, and every other editor of the space then sees a change nobody made.
2. **Never write the mesh's own bookkeeping.** Leave out `version`, `lastModified`,
   `lastModifiedBy`, `createdBy`, `createdDate` and, on a NodeType, `compilationStatus`,
   `latestAssemblyPath` and the other compile records. The mesh writes those. A copied value is
   stale on arrival and can make the next sync refuse the file.
3. **Keep it parseable.** A file that no longer parses (a broken data block, invalid JSON) is not
   taken: the sync page names it, the other files keep syncing, and the next sync takes it once
   it is fixed.
4. **Never rename or move a file only to tidy up.** A rename is a delete and a create. Links to
   the old address break, and comments and history stay with the old node.
5. **Deleting a file deletes the node** at the next sync. The one exception: a node someone edited
   in the space since the last sync is kept and reported, never deleted unseen.
6. **No secrets.** Every file here is readable by everyone who can read the space, and by the
   people the folder is shared with in the drive. Credentials live in the mesh's Connections.
7. **Leave the files that start with `_` alone, and leave this file in place.** The sync never
   writes over an `AGENTS.md` that is already here, so you can extend it for this project. Add
   your own section below.

## When both sides changed

If a file changed here **and** in the space since the last sync, the sync takes **neither**
version. It records a conflict and names it on the space's **Sync** page, where someone chooses
*Keep the space's version* or *Keep the drive's version*. Until then, the sync leaves that file
alone and syncs all the others. So a conflict means waiting for a choice, and nothing is lost
while you wait.

## Working with the space rather than the files

When you have the MeshWeaver MCP server connected, you can work with the space directly: `get`
reads a node, `search` finds nodes, and `create`/`update` write them. Those writes reach this
folder at the next sync. Don't use both routes on the same file in one session: you then create
the conflict described above.

## This project

<!-- Describe what this space is for, who owns it, and any conventions an editor must follow. -->