Giraffe

Create a NEW persistent Giraffe project — a durable context the user will keep coming back to over weeks or months (a person, a company, an ongoing initiative), not a one-off write-up. If what the user wants is something WRITTEN UP from a context that already has a project (a brief, a plan, a summary), that's a Document, not a new project — call create_document against the existing project instead. Only call this after the user explicitly asks to save, remember or update, or says yes to your offer to — never automatically, and never because you read a project or a conversation happened. Before calling, check list_projects or search_projects: if a similar project already exists, call update_project on it instead of creating a near-duplicate; if the conversation could plausibly belong to more than one existing project, ask which one rather than guessing. Extract durable conclusions from the conversation (facts, decisions, open questions, notes) — not a transcript dump — and never invent a value the user didn't actually state. 'changes' uses the same structured change types as update_project (set_fact, add_decision, add_question, add_note, ...). After a successful call, tell the user which project was created.

create_project

Change PART of a Document without resending it: append blocks at the end, insert_after a block, replace a block, or delete one. Only call this when the user asks for it — never automatically. Operations apply in the order given and are all-or-nothing — if any one fails, none of them happen and the document is untouched. Prefer this over update_document whenever the user wants something added, corrected or removed rather than the document rewritten: it does not make you re-transcribe content you are not changing, which is both cheaper and the only way to be certain you did not alter it by accident. Block ids come from get_document — mode:"outline" is the cheap way to get them. Operations address TOP-LEVEL blocks; to change something inside a section, replace the whole section. expected_version works exactly as it does for update_document. The response returns the new version, the resulting block count and a content hash, so you can confirm the edit arrived intact. Use update_document instead when the user genuinely wants the document rewritten.

edit_document_blocks

Get the full change timeline for a Giraffe project (every fact/decision/question/note change, who made it, and when). Only call this when the user specifically asks about history or how something changed over time — get_project already covers current state plus a short recent-changes summary for everything else.

get_project_history

Get the full current state of one Giraffe project: overview, current facts, decisions, open questions, notes, which Documents exist for it, recent changes, and its version number. Call this without being asked when the user is clearly continuing or recalling work that likely lives in their projects — 'where did we leave off?', 'what did we decide?', 'continue the launch plan' — even if they never name Giraffe. Not on every turn, and not for a passing mention, casual brainstorming or a one-off question. Reading never authorizes a write. If you do not know which project, call search_projects first. Always call this (or already have its output, just as fresh) before update_project — not just to get the version number, but to understand what the project currently believes before you change it: read the current facts before claiming one changed, check open questions before adding a near-duplicate, and check existing Documents before composing one that already exists. Accepts a project name, slug, or project_id; if nothing matches, returns close suggestions instead of failing silently.

get_project

List the user's projects in Giraffe: name, id, space, a one-line overview snippet, and version, most recently updated first. Call this when you don't already know which project a save belongs to, or before create_project to check whether a similar one already exists — never make the user navigate Giraffe manually to find something you can look up. If the conversation already makes the project obvious (the user named it, or you've been discussing it the whole conversation), route to it directly instead of listing defensively. A large library is capped and the response says so — use search_projects to find a specific one rather than paging. Pass include_archived:true only if the user explicitly asks for archived projects.

list_projects

The revision history of one document — version number, who wrote it, and the note left with it. Use it when the user asks what changed or wants an earlier version read back; get_document takes a version number.

get_document_versions

List the documents that already exist for a project, with their ids, versions, who wrote each, and whether the project has moved on since. Check this before create_document: if a suitable document already exists, revise it with update_document instead of creating a near-duplicate.

list_documents

Compose a document from an existing Giraffe project and save it there — a meeting brief, a study sheet, a handover, a board update, a plan, a summary. Use this when the user asks you to PREPARE, WRITE UP or GET READY with something from a project, rather than to change what the project knows. Only call this when the user asks for it — never automatically. It does not alter the project's facts, decisions, questions or notes: a document is a way of presenting them, and can be deleted without losing anything. Read the project first (get_project) so you compose from what is actually there and invent nothing. Infer the right shape yourself from what the user said — who it is for, how long it should be, whether it wants prose or points — and only ask if that is genuinely ambiguous; do not offer the user a list of formats to choose from. You choose the blocks, their order and their words; Giraffe chooses every visual detail, so send no HTML, CSS or styling. After it succeeds, tell the user what you prepared and that it is in Giraffe. IF A CALL'S OUTCOME IS UNCLEAR, DO NOT SIMPLY SEND IT AGAIN. Unlike create_project, this is not durably idempotent: past a short window a second call makes a second document. Call list_documents first, decide whether the document you meant to create is already there, and only create again once you have established it is not. If you still cannot tell, say so to the user rather than risking a duplicate.

create_document

Read one document's block structure, its version number, who wrote it, and whether the project has changed since it was prepared. Call this before update_document so you revise the real current document rather than rewriting it from memory, and so you have the version number the update needs. For a long document, read it in two steps instead of one: mode:"outline" returns one line per block — id, type, size and a short label — and block_ids:[...] then returns just the blocks you name. Blocks inside a section are addressable the same way. Note that update_document still replaces the WHOLE document, so a partial read is for finding and quoting, not for revising: read in full before you revise.

get_document

Return Giraffe's machine-readable contract, versioned: the Project vs Document model, the write rules, how to reconcile new information against existing state, every error code and how to recover from it, the document block grammar with its limits, and four worked examples of a request becoming a document. Call it once before composing your first Document, or when a call fails in a way you don't recognise. It is orientation, not enforcement — reading it changes nothing about what Giraffe will accept.

get_contract