Write a document in your member home

The job

Create a document in the member's own home, then change it safely, so that no change overwrites text that someone else changed after you read it.

Prerequisites

The person who connected is a member. An admin or staff connection never gets writeDoc or editDoc.
The connection holds knowledge:read and knowledge:write.
The instance has home writing turned on. It is off by default, and the instance's operator turns it on.
writeDoc and editDoc are in your tool list. If they are not, one of the conditions above is not true. See the document write tools.

There is no confirmation step, no history and no undo. A replacement discards the old text. Make each change only when the person asked for it.

Steps

If writeDoc and editDoc are not in your tool list, read the writing section of the guide before you tell the person anything:
```
{ "section": "writing" }
```
Find the member home. Call listProjects:
```
{}
```
The member home is the project whose kind is member-home, in this example member-14.
Create the document. Call writeDoc without expectedVersion. Make a new operationId for this change, for example a UUID.
```
{
  "operationId": "7c1e4b2a-9f3d-4e6a-8b10-5d2c7f9e0a41",
  "project": "member-14",
  "path": "notes/2026-10-02-client-call.md",
  "content": "# Client call, 2 October 2026\n\nThe client asked for the diagnostic at the standard price.\n",
  "reason": "Notes from the client call"
}
```
The result has created: true and the new version. If the request times out, send it again with the same operationId and the same arguments. The retry returns the first result and does not write twice.

Before you change the document, read it. Keep the version from the result.

{ "project": "member-14", "path": "notes/2026-10-02-client-call.md" }

{
  "path": "member-14/notes/2026-10-02-client-call.md",
  "content": "# Client call, 2 October 2026\n\nThe client asked for the diagnostic at the standard price.\n",
  "totalBytes": 90,
  "offset": 0,
  "bytesReturned": 90,
  "truncated": false,
  "version": "AQ-example-opaque-version"
}

Change one passage with editDoc. Pass the version from step 4 as expectedVersion, and make a new operationId. oldString must occur exactly once in the document.

{
  "operationId": "c4d8e2f1-6a3b-4c9d-9e07-1b5a8f2d6c30",
  "project": "member-14",
  "path": "notes/2026-10-02-client-call.md",
  "oldString": "at the standard price.",
  "newString": "at the standard price. A partner will confirm the start date by 9 October.",
  "expectedVersion": "AQ-example-opaque-version",
  "reason": "Add the agreed next step"
}

The result has created: false and a new version. Use readDoc again before the next change.

To replace a whole document, call writeDoc with the version from readDoc as expectedVersion. Use editDoc when you can: it changes the least.

What can go wrong

The full list of refusals is in the document write tools. The ones that this job meets most often:

version_conflict:stale_version: the document changed after your read. Read it again, decide whether your change still applies to the new text, and retry with the new version and a new operationId.
version_conflict:target_exists: in step 3, a document already exists at that path. Read it, and replace it only if that is what the person wants.
invalid_input:edit_no_match or invalid_input:edit_not_unique: oldString does not occur in the document, or occurs more than once. Include more surrounding text.
forbidden:home_writes_disabled: this instance has home writing turned off. Ask the operator, or write to a shared project where the person has a write grant.
idempotency_conflict:operation_id_reused: you used an operationId again for a different change. Make a new one.
MCP error -32602: Tool writeDoc not found: a condition in the prerequisites is not true. Read the writing and permissions sections of getDocs. Do not tell the person that Sasha cannot write.

Write a document in your member home

The job

Prerequisites

Steps

What can go wrong

Related notes