delete
ChatGPTRemove a file — or a whole folder — from the live yarnnn workspace. The file goes to Trash: it is a PLACE, not an erasure — the revision chain is retained and the user can put it back. ONE VERB, TWO GRAINS. reference may name a file or a FOLDER, and the workspace resolves which — you don't have to know. Naming a folder deletes its whole subtree, every file under it, as one restorable unit. That is a much larger act than deleting a file: say what you are about to sweep, and for anything beyond obvious scratch, confirm with the user first. If only some of it should go, list the folder and delete the files by name. Call this when something would mislead the next reader: superseded scratch, a dead duplicate after a move, a stale artifact. Nothing is lost — an attributed tombstone records who removed it and why, the revision chain keeps the content, and history still walks it; the user can restore from the workspace. Governance-protected paths refuse, same as save — on a folder they are reported in locked rather than silently skipped, so say "19 moved to Trash · 2 are managed by the system and stayed" rather than claiming a clean sweep. A folder larger than one gesture should move (500 items) is refused outright rather than half-performed. Say why in message — the tombstone is the next reader's explanation. Args: reference: The file OR folder — same grammar as open. Required. message: Why this is being removed (recorded on the tombstone).
edit
ChatGPTChange PART of a file in the user's yarnnn workspace — an anchored edit. Call this for any targeted change to an existing file: fixing a line, updating a section, appending an entry. Pass the exact current text as old (verbatim, including whitespace — include surrounding context to make it unique) and the replacement as new. Only the change travels: content you never read is never at risk, which makes this the REQUIRED verb for files open returned truncated, and the right one when several principals work the same file (edits to different regions don't conflict). Fails loudly, never guesses: old_string_not_found means your view is stale or the anchor isn't verbatim — re-open and re-anchor; old_string_not_unique means add more context or pass replace_all=true. The edit lands as one attributed revision signed as you; use save only to create a file or rewrite one wholesale. A Word, Excel or PowerPoint file is edited IN PLACE — its formatting, formulas and layout stay as they are. open labels each element with its address; pass it as at ('p12' a paragraph, 'Budget!B7' a cell, 's3/5' a slide shape). With old the phrase is replaced inside that element; without it the whole element is. In Word the change shows as a tracked change signed with your name. Args: reference: The file — same grammar as open. Required. new: Replacement text. old: Exact text to replace (verbatim; unique unless replace_all). Required for a text file; optional with at. replace_all: Replace every occurrence (default false). message: Optional one-line description of the change. at: An office file's element address, as open labels it.
history
ChatGPTShow how one EXACT file in the user's yarnnn workspace changed over time. Applies to questions about how a file came to be as it is — when something was decided, who added a passage, what it used to say. Returns the file's authored revision chain: who changed it, when, the change message, a per-revision diff, and the chains of any cited sources it was built from. Pass the same reference open takes (yarnnn://workspace/… handle, /workspace/… absolute, or a workspace-relative path). history is exact: an unknown path returns found: false. search resolves a path when only the topic is known. On a host that renders MCP widgets the chain is additionally returned as an interactive timeline (ADR-372); on a text-only host the full chain is in the text channel. Both carry the same revision data. Args: reference: The file — yarnnn://workspace/{path}, /workspace/{path}, or a bare workspace-relative path. Required. limit: Max revisions (default 10, max 30).
list
ChatGPTList the files under a folder in the user's yarnnn workspace. Call this to see what exists — before guessing a path, when the user asks "what's in my workspace / in that folder", or to orient yourself at the start of real work. Pass a folder reference (a workspace-relative path like Documents/reports, or a yarnnn://workspace/… handle); omit it to list the entire workspace tree. THE CHANGE FEED: pass since (ISO timestamp) to get only the files whose last change landed after that moment — "what moved since I was last here" in one call. Returning to a workspace after time away? list(since=…) first. Returns every matching file — path, size, who last changed it, and when. The listing is real enumeration, not inference: what it returns is what exists. When truncated is true, continue from next_offset. Use open on any returned path for exact content, and search when you're after meaning rather than structure. Args: reference: Optional folder — workspace-relative path or yarnnn://workspace/{path}. Omit to list the whole workspace. since: Optional ISO timestamp — only files changed after this moment. limit: Max files per page (default and cap 500). offset: Page start in path order (use next_offset from a truncated call).
move
ChatGPTMove or rename a file — or a whole folder — in the user's yarnnn workspace. Call this to put work where it belongs — a better home, a clearer name. One attributed operation: the content lands at the new path, the old path keeps a tombstone pointing there, and both revision chains are retained. Refuses to overwrite an existing destination — if the destination must be replaced, delete it first (explicit intent). ONE VERB, TWO GRAINS. reference may name a file or a FOLDER, and the workspace resolves which — you don't have to know. Naming a folder moves every file under it, keeping their relative layout; a rename is the same act with a new leaf. Locked children are reported in locked and a partially-landed fan in failed, never hidden — report what actually moved rather than assuming the whole tree did. Args: reference: The current path of the file OR folder — same grammar as open. Required. new_reference: The destination path (must not already exist). Required. message: Why this is moving (recorded on both revisions).
open
ChatGPTOpen an EXACT file from the user's yarnnn workspace by its reference. Call this when you hold a reference to a specific file — a yarnnn://workspace/… handle (the user may paste one, e.g. from Studio's "Copy AI reference"), a workspace-relative path like Documents/reports/q3.md, or a /workspace/… absolute path. This is the exact-version read: you get THIS file's current content, who last changed it, and its recent attributed revisions — so you and the user are looking at the same version, not a copy. open never searches or guesses: an unknown path returns found: false. When you only know the topic (not the path), use search; to see what exists, use list; for the full revision chain with diffs, use history. A large file is PAGED, not lost: truncated: true comes with next_offset — call again with offset=next_offset to read on. content_chars is the length of the READABLE VIEW, so you always know how much remains to read. Read to the end before summarizing a long file. ⚠️ Reading to the end is NOT the same as holding the file. A Studio artifact's machine-composed stylesheets are elided from the view, so stored_chars exceeds content_chars and no amount of paging closes the gap. `complete_for_write` is the only field that answers "may I `save` this back". When it is false, use edit — its anchors match the stored bytes and are unaffected by elision. citations lists the workspace files an artifact CITES. Their content is projected from the source when the document renders, so a cited element is usually EMPTY in what you read here — that is a working citation, not missing content. Open a cited file to learn what it shows, and never write content inside a citation: it is overwritten on the next render. Args: reference: The file reference — yarnnn://workspace/{path}, /workspace/{path}, or a bare workspace-relative path. Required. revisions: How many recent revisions to summarize (default 5, max 10). offset: Character offset to read from (default 0). Pass next_offset from a truncated call to continue.
request_upload
ChatGPTGet a link for putting a NON-TEXT file into the user's yarnnn workspace. Use this for anything whose content is bytes rather than characters — an image, PDF, video, audio file, spreadsheet, font, archive. save writes text and will refuse a binary file; this is the door for the other case. HOW IT WORKS. You get back a short-lived, single-use upload_url and a ready-to-run curl command. The bytes go straight to that URL over plain HTTPS — they never pass through this conversation, because binary sent through a model's context gets corrupted (it is not a size limit; the characters themselves change). No credentials are needed to redeem it: the ticket IS the authorization, and it can only write the one file you named, to the one place you named. ⚠️ WHO RUNS THE COMMAND. If you can execute shell commands, run the curl yourself. If you cannot, say so plainly and give the command to the user — do not claim the file was uploaded, and do not attempt to send the bytes in a message. The ticket expires in an hour. WHERE IT LANDS. Pass destination as the workspace folder it belongs in, chosen by MEANING like any other path (e.g. marketing/assets). Omit it and the file arrives in Downloads, the arrivals folder. Once it lands it is an ordinary workspace file: attributed to the user, versioned, searchable, and readable by every member. Args: filename: The bare filename WITH its extension (e.g. promo-cut.mp4). Not a path — the folder is destination. destination: Optional workspace-relative folder (no leading slash). size_bytes: Optional size, so an over-limit file is refused now rather than after the transfer.
runs
ChatGPTWhat the workspace's agents DID — the run ledger, newest first. A run is one occurrence of work: a standing declaration's run, or the acts an agent performed in a member's own browser (opened, read, filled, pressed…), each step with where the tab was when it ended. Use it when the user asks what an agent did, whether a piece of standing work ran, or what happened on a site on their behalf. What a run wrote is a revision of its kept file — open reads the file, history its chain; a declared browser run's record file is at its record path. Args: limit: Max runs (default 10, max 30). topic: Only the runs of one piece of standing work (its folder). Omit for every run. live: True for runs still going (queued · running · waiting), False for ended ones (done · failed · stopped); omit for both.
save
ChatGPTSave content to an EXACT file in the user's yarnnn workspace, as an attributed revision. Call this to CREATE a file or REWRITE one wholesale. Pass the same reference open takes (yarnnn://workspace/… or a workspace-relative path) and the FULL new content (this is an overwrite, not a patch). For a targeted change to an existing file — especially one open returned truncated — use edit instead: it sends only the change, so content you never read is never at risk. A save over a file larger than open's cap is refused unless you pass confirm_full_replace=true (stated intent). THE CONTRACT — read before write: for an existing file you MUST pass base_revision = the head revision id you got from open (history[0]. revision_id). If someone changed the file since, you get stale_write with WHO changed it — re-open, merge their change with yours in your own reasoning, and save again with the new base. Never retry a stale save with the same content unexamined. Omit base_revision only to CREATE a new file. CITE WHAT YOU BUILT ON: if this content was made FROM other workspace files — a document you opened and rewrote, sources you synthesized, a reference you worked from — pass their references as derived_from. The workspace uses that edge to show what was made from what, and to warn someone before they delete a file yours depends on. An uncited derivation arrives as an orphan; cite it and it joins the record. OFFICE FILES: save to a .docx, .pptx or .xlsx reference and yarnnn writes that format — content is the source (Markdown or HTML for .docx, CSV for .xlsx, a Markdown outline for .pptx: # the title, then one ## per slide, with its text, one table or one picture ). To convert an existing file, pass content='' and derived_from=[that file]; it never passes through you. The file is written in the workspace's look (design/, else yarnnn's house look) and the result names it: the words and structure survive, a source's own styling does not. Your write lands signed as you in the workspace ledger — the user and their team see exactly what you changed, beside every human change. save also captures conversational conclusions worth keeping: write them by meaning like any participant — an observation with no better home goes under Downloads. Args: reference: The file — yarnnn://workspace/{path} or workspace-relative path. content: The full new content. Required; empty only to convert a derived_from source into an office file. base_revision: The head revision id from open (required for existing files). message: Optional one-line description of the change. derived_from: Optional references of the source file(s) this was made from (same grammar as reference). Pass whenever you author from sources you read. confirm_full_replace: Required true to wholesale-overwrite a file larger than open's content cap (stated intent; prefer edit).
search
ChatGPTSearch the user's yarnnn workspace by meaning. Applies when the user refers to a topic, project, person or decision that may be written down in their workspace and no exact path is known. Returns ranked results — path, excerpt, timestamp and a confidence grade. It returns source material rather than a composed answer, and it does not resolve ambiguity on its own. Every result's path can be passed to open for that file's exact current content; search matches by meaning, open returns the stored file. confidence is always present, including on a miss, and grades the result set: • "high" — one clear, dominant match. • "ambiguous" — several files match and none dominates; the candidates are in results with their similarity. • "weak" — only partial or substring matches, below the dominant bar. • "none" — nothing matched; results is empty. For "ambiguous", "weak" and "none" the response's explanation states what the grade means for the result set in hand. Args: query: What to find (topic, entity, keywords). Required. limit: Max results (default 10, max 30).
share
ChatGPTCreate a share link for the user's yarnnn workspace (or one exact file in it). Applies when the user asks to share their work — "share this with my team", "send this doc to Alex", "make a link for this". Pass the file's reference (a yarnnn://workspace/… handle or workspace-relative path) to share that artifact; omit it to share the workspace itself. Returns the share link in the response. yarnnn sends nothing outbound: the link is returned as text. Whoever opens it sees the artifact and who changed it without an account; joining the workspace requires signing in. access sets what accepting the link grants. "member" (the default) grants full access to work in the workspace, including writing to it — every holder of a member link can change the workspace's files. "viewer" is read-only: the document and its history, with no ability to change anything. Args: reference: Optional file to share — yarnnn://workspace/{path}, /workspace/{path}, or a bare workspace-relative path. access: "member" (full access, default) | "viewer" (read-only).
whoami
ChatGPTIdentify which yarnnn workspace this connection is bound to. Applies when the workspace behind a reference is not already established: a person can reach more than one workspace, and the yarnnn://workspace/… grammar is identical in all of them, so a path or handle alone does not identify which workspace it belongs to. Returns the workspace's name (set by its operator at consent), how this connection resolved to it, the attribution this connection's writes carry, and which verbs its token authorizes. binding reports how the workspace was resolved: • "chosen" — the workspace the operator selected for this connection. • "default" — no explicit choice on this connection; their default workspace. • "fallback" — the bound workspace is unreachable and this is not the one the operator chose. Writes still succeed and are attributed. The response's explanation says so. • "unresolved" — resolution failed and workspace_id is null. A workspace with no name returns workspace: null with workspace_named: false; it is identified by its address instead.
