> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt > Use this file to discover all available pages before exploring further. # Word and Sheet editing > Edit a native Word document or Sheet one person at a time: take over editing, ask for a handoff, follow an agent task, browse and restore versions, and recover a draft after a crash or a full history. This guide covers native Craft Word and Sheet files: Word opens in WordCraft, a Sheet in GridCraft. Word documents using the separate Docs backend follow [Document save state](https://docs.crewship.ai/guides/document-drafts.md) instead. Exactly one person or agent edits it at a time. That person or agent holds the **lease**, and everyone else sees the document read-only until the lease is released or handed over. Every confirmed save becomes a new **version**. > [!NOTE] > > **Availability.** Native Word and Sheet are off by default. > > * **Instance switch (required):** the operator starts the server with > `CREWSHIP_CRAFT_NATIVE_ENABLED=true` and a qualified Word or Sheet editor > profile. Without it, the native editor page shows *The native editor is not turned on*. The separate Docs backend may still > offer Word creation. > * **Agent tasks** also need `CREWSHIP_CRAFT_NATIVE_AGENTS_ENABLED=true` on the > server, and the workspace's agent artifact policy must be enabled and list the > agent's crew (a workspace admin can check it with > `crewship workspace artifact-policy show`). Whole-document consent works only > inside that policy: a task for an agent of an unlisted crew, or under a > disabled policy, is refused with `403`, and a running task stops at its next > step (any agent tool call, dispatch or confirmation) once the crew is removed > or the policy is turned off. > * **Build-time UI flags:** the Artifacts library needs > `NEXT_PUBLIC_ARTIFACTS_LIBRARY=true`. The lock bar in the library and in chat > needs `NEXT_PUBLIC_CHAT_CRAFT_LEASE=true`; the default production build sets it > to `false`. The editor page itself needs no build flag. > * **Version history** (list and restore) also needs the workspace feature > flag `craft_version_history`, which is off by default. See > [Version history and restore](#version-history-and-restore). > > The native editor's own controls are in Czech in this release. This guide > quotes each label as shown, with its English meaning. ## Create a Word document or a Sheet 1. Open **Artifacts** and choose **New artifact**. 2. Select **Word document** or **Sheet**, type a **Name**, pick a **Folder** (or leave **Unfiled**), and keep **Start with: Blank**. 3. Choose **Create and edit**. The new document or workbook opens in the Artifacts detail view. **Sheet** is offered only when the instance advertises the native GridCraft profile: `crewship doc status` must report `gridcraft_native: true`. Without it, **Sheet** is listed under **Coming** in this dialog. **Word document** is offered only when the instance's document service is available; otherwise it is listed under **Coming** too. Native Word requires `wordcraft_native: true`. If only the separate Docs service is available, this dialog creates a Docs document instead; follow [Document save state](https://docs.crewship.ai/guides/document-drafts.md). A native profile alone does not make the Word tile available in the current UI; use **New Doc** in the older view when that view is available. The older Pages view still has a **New Doc** button whose **Format** field offers **Word** and **Sheet**. It opens at `/pages` on your Crewship address (for example `https://crewship.example.com/pages`), but only when `/pages` does not redirect to Artifacts. It redirects when the build flag `NEXT_PUBLIC_ARTIFACTS_LIBRARY` is `true`; then there is no place in the app to create a Sheet. ## Open the editor Open the native Word document or Sheet in **Artifacts**. With the build flag `NEXT_PUBLIC_ARTIFACTS_LIBRARY` enabled, the Craft editor opens inside the detail when the server confirms editing is available. Follow [Take over editing](#take-over-editing) in that editor. In this mode there is no full-view link, and `/pages/` and `/pages/craft/editor?page_id=` lead to the artifact detail. Readers without edit access get the shared preview. ### In the Artifacts frame Inside the artifact detail the editor's controls sit where every artifact keeps them: * **The lock is in the status chip.** The chip next to the name says who can edit right now: **Free to edit**, ***name* is editing**, **You are editing**, **Proposal waiting**, **Recovered draft** or **Read-only**. Select it to see who holds the lock and since when, and the lock actions this page describes below: **Take over editing**, **Request edit**, **Hand back** and **Hand over to *name***. There is no separate lock bar above the editor. * **History** is a tab of the right panel. The pill at the top left shows the artifact's name and the version you see (for example **v5 · Latest**); select it to open the History tab. * **Agent → Edit** in the right panel starts the Craft agent task, when the server allows agents and you can edit. **Ask** opens the chat with the document as context and changes nothing. * A waiting proposal or a recovered draft appears as one banner above the editor with its actions (**Compare**, **Keep a copy**, and **Accept** or **Reject** for a proposal). * The editor's own ribbon, sheet tabs and export stay inside the editor. * **On a phone**, a Word document opens as read-only, reflowed text. To edit, select the status chip and choose **Take over editing**; the editor replaces the text while you hold the lock. A Sheet opens in its editor, which scrolls inside itself. The rest of this page names the controls as they read on the dedicated editor route; in the frame they are the same buttons in the places above. Outside that mode, Word detail shows the saved version read-only. With the lock bar enabled, a bar above it shows: * **Free** · *nobody is editing*, with **Edit**; * **Editing: you** · *in the editor*, with **Open in new tab**; * **Editing: *name*** · *you see a read-only preview*, with **Request edit**. When an agent holds the lease, its name is followed by **(agent)**. Choose **Edit** to open an editor in a new tab, or **Open full view** to open one in this tab. Without the lock bar, or for a Sheet outside the inline mode, use **Open full view**. A document result in chat has the same bar in its side panel. There, **Edit** also opens the editor in a new tab. Chat never takes the lease itself. People who can read the document but not edit it don't get the editor. They see the last shared version, labelled *Shared preview · version N* ("Shared preview · version N"), or *The shared preview is not published yet*. ## Take over editing The bar at the top of the editor shows who holds the lease: | Bar text | Meaning | | - | - | | **Free** | Nobody is editing. | | ***name* is editing** | *Name* is editing. An agent shows its name, or **Agent**. | | **Read-only** | You can't edit here right now, for example after the connection ended. | 1. When the bar says **Free**, choose **Take over editing**. 2. The bar changes to ***your name* is editing**, and the status line under it reads **Ready to edit**. 3. Type. Your edits are saved automatically a moment after you stop: **Unsaved draft**, then **Saving…**, then **Saved · version N**. Editing starts only once this browser can keep a private copy of your draft. If the browser's storage is slow, the editor tries to open it up to three times. If it still can't, editing doesn't start: the editor gives the lease back, the bar returns to **Free**, and an alert says *The draft storage in this browser could not be opened, so editing did not start. The document is free again*. Choose **Take over editing** to try again. If the lease could not be given back, the alert says so; choose **Hand back** or reload the page. While you hold the lease, the editor renews it in the background. If you close the tab or lose the connection, the lease runs out by itself after about 15 seconds. A server restart invalidates editor admissions; reopen the editor and recheck the lease. On Linux a process restart does not change the persisted lease’s host boot ID, so it can remain occupied until expiry; a host reboot makes the old lease read as free. ### Release editing Choose **Hand back**. The editor saves your last change first, then switches to read-only and the bar shows **Free**. If you changed nothing since you took over, no new version is written, even though the Word editor rewrites a document into its own form when it opens it. The same holds for a handoff and for accepting an agent's proposal, so a proposal made over the version you opened still applies. If that final save can't be confirmed, nothing is released, and you see *The result of the action was not confirmed. The draft is kept.* ## Ask for a handoff When someone else is editing: 1. Open the editor and keep that tab open. Choose **Request edit** there. The request is bound to this editor session. Once the server confirms it, **Request sent** and a waiting message appear; the request button stays disabled for that holder and lease generation. This confirms the request, not editing access. If the next status read fails, the confirmation remains and a separate message explains that the current editing status could not be read. 2. The editor of the person holding the lease shows a button **Hand over to *your name*** (Hand over to *your name*). 3. When they choose it, their last change is saved and their editor becomes read-only. The lease is now yours: in your editor the bar changes to ***your name* is editing**, with **Hand back**, and a **Take over editing** button appears under the bar. 4. Choose that **Take over editing** to start typing. You don't wait for the bar to show **Free**; the lease is already yours. The editor loads the latest saved version first. An agent holder does not perform this human handoff flow. Its confirmation says that the request was recorded and that the agent does not hand over on its own. **Stop agent** appears only when the server authorizes you to stop that agent; recording a handoff request does not grant this permission. The holder doesn't get a decline button: if they never hand over, your request lapses when the lease changes hands or ends. A request made for one lease doesn't carry over to the next holder. > [!WARNING] > > **Request edit** in the Artifacts detail view or chat requests handoff to that > preview’s admission session. Opening the editor afterwards creates another > session, which does not own that lease, even for the same person. The preview > may say **Editing: you**, but the new editor cannot take over that session’s > lease. Use the already-open editor to request handoff. If you requested from > a preview, stop using that preview and wait for its lease to expire before > acquiring a free lease in the editor; if another holder has acquired it, ask > from the editor again. Do not treat the person’s name as proof that this tab > owns the lease. ## Follow or stop an agent task An agent can edit a Word document or Sheet only after you give it a task with explicit whole-document consent. Agent tasks need `CREWSHIP_CRAFT_NATIVE_AGENTS_ENABLED=true`, a qualified private native agent runtime on the server, and your current edit rights on the document. The two startup switches alone do not supply that runtime. Before starting, finish your save and choose **Hand back** so the human editor no longer renews the lease; a task cannot take it away from a person. 1. Collect four IDs: * **Page ID.** For a native Word or Sheet open at `/artifacts/`, the immutable `` is the page ID. Alternatively, run `crewship page get --format json` and use its `id` field. A dedicated editor address carries the same ID as its `page_id` query parameter. * **Workspace ID.** Run `crewship workspace list` and use the **ID** column for the document's workspace. * **Chat ID.** In an agent chat, send your instruction for the document. `crewship chat list ` shows that chat's ID in the **ID** column. * **Message ID.** `crewship chat source messages agent_session --format json` lists the chat’s messages. Use `messages[].message_ref.source_message_id` from your own instruction (`role: "user"`, with your `author.user_id`). Do not use `source_id` (the chat ID) or the message’s position. The agent slug for `chat list` comes from `crewship agent list`. 2. Start the task from the CLI. Write the page ID with a leading `@`: ```bash theme={null} crewship craft task start @ --chat-id --message-id --whole-document ``` The response contains a work ID. Accepted means queued, not done. 3. To watch the task, open the dedicated Craft editor route with the collected page and workspace IDs plus `craft_task_id=`: `https://crewship.example.com/pages/craft/editor?page_id=&workspace_id=&craft_task_id=`. A panel under the lease bar shows the task state: | Panel text | Meaning | | - | - | | Agent task queued | The task is queued. | | Agent is starting | The agent is starting. | | Agent is working | The agent is working. | | Agent task finished | The task finished. | | Agent task failed | The task failed. | | Agent task cancelled | The task was cancelled. | | Checking the task result | The outcome is still being checked. | *The agent did not take over editing: a person was editing the document* means the agent couldn't take the lease because a person was editing. *Last confirmed version N* names the last version the agent saved. 4. While the agent holds the lease, the bar shows ***agent name* is editing** and, if you may stop it, **Stop agent**. Choose it to withdraw the agent's write access. The result is *Agent stopped*, or *Agent writing stopped · checking that the run ended*. The CLI equivalents are `crewship craft task status @ ` and `crewship craft task stop @`. Stopping an agent never takes the lease from a person and leaves saved versions in place. An admitted agent task saves confirmed versions directly. ## Publish a shared version People with Read or Comment access see only the version you publish, through every route: not the latest save, not older versions and not agent proposals. 1. While you hold the lease, choose **Publish preview**. 2. The editor saves your last change, then shows **Shared preview · version N**. Publishing selects an already saved version. If the save can't be confirmed first, nothing is published, and the editor says so. ## Version history and restore Every confirmed save of changed content is a version. The history lists them all, newest first, and restoring one never deletes anything: it saves the old content again as a new version on top. Ctrl+S without a change adds no version and uses no quota: the editor confirms the version it already has. If the last save's result is unknown, Ctrl+S first asks the server about that save and sends nothing until it knows. If the server can't tell yet, you keep seeing *Result not confirmed*. > [!NOTE] > > The history is off by default. An instance administrator defines the flag > once with `crewship feature-flag create --key craft_version_history`; a > workspace owner or admin then turns it on for that workspace with > `crewship feature-flag enable craft_version_history`. The native instance > switch above is still required. ### See the versions 1. Open the native Word document or Sheet in **Artifacts** (`/artifacts/`). 2. Choose **Version history (N)** above the editor. In the Artifacts frame, open the **History** tab of the right panel instead (or the version pill at the top left). A workspace owner or admin who reads the document without the editor finds it above the shared preview or the read-only detail. People with only Read or Comment access don't get the history: they see the shared version alone. 3. Each row shows **Version N**, when it was saved and who saved it: a person by name, an agent as *name* **(agent)**. The version the editor opens is marked **current**. A restored version adds *restored from version M*. In the Artifacts History tab each row reads as a sentence instead, for example *Saved by Jana* or *Pavel restored version 2*, with **vN** and **Latest** on the current one. Anyone who can read the document sees the list. People with comment-only access, and people outside the workspace, don't. The list shows the latest 200 versions; older ones stay stored, and the panel says so. ### Preview and compare a version Next to each version, **Preview** opens that version read-only in the same editor, below the list; nothing you do there is saved. Next to each older version, **Compare** shows it against the current version: how many lines were added and removed, each changed line, and both versions side by side. Both are available to everyone who can see the list, and both close with **Close** or Esc, which returns focus to the button you came from. A workspace owner or admin who reads another member's document, its history or one of its versions is recorded in the audit log, as for any other read. If your access is removed while a preview or comparison is open, it disappears together with the list. ### Restore an older version You need edit rights **and** the lease in this editor. 1. Choose **Take over editing** if you don't hold the lease yet. Until then, **Restore** is disabled and the panel says *Take over editing to restore a version.* It stays disabled for anyone who reads without edit rights. 2. In **Version history**, choose **Restore** next to the version you want. 3. Confirm with **Restore as a new version**, or **Cancel**. 4. The editor saves your last change first, then stores the old content as a new version, N+1, and reopens on it. The list now shows that version as **current**, with *restored from version M*. All earlier versions are still listed. The restore uses the same checks as a save: your lease, its generation and the version you last saw. If someone else changed the document or the lease moved on, nothing is restored and the editor shows *Restoring the version was not confirmed. The document and the local draft are kept.* From the CLI, `crewship craft versions ` lists the same history and `crewship craft version --output FILE` saves one version's bytes without touching the document; see [Craft commands](https://docs.crewship.ai/cli/craft.md#version-history). ## When the connection drops or the browser crashes Before every save, the editor keeps a copy of your draft in this browser. That copy is never uploaded or restored by itself, because the server version may have moved on. **While the editor is open.** If the connection drops, the server restarts, or your lease ends, editing stops. The bar or the status line shows one of: | Text | Meaning | | - | - | | Result not confirmed | The last save's result is unknown. Choose **Check the result** to ask the server. | | Read-only · local draft kept | This session cannot write; your draft is kept in this browser. The lease may still name you. | | The draft stays in this editor | The draft couldn't be captured safely; it stays in the open editor. Don't close the tab yet. | | Editor disconnected · draft kept | The editor disconnected; the draft is kept. | | Unsaved draft · browser storage did not respond | This browser's storage didn't answer in time. Editing continues; your next edit or Ctrl+S saves again (after a save the server already confirmed, the editor also retries once by itself). Nothing is sent until the browser copy is written. | **After a crash or a closed tab:** 1. Open the document's editor again and choose **Take over editing**. If someone else took over in the meantime, wait for them or ask for a handoff first. 2. Each kept draft appears as **Local draft · version N**, in one banner above the editor. 3. Choose **Compare** to see the server version and your draft side by side. The header says whether they hold *identical data* or *different data*. 4. Choose **Keep a copy** to download the draft as a `wordcraft-recovery.json` or `gridcraft-recovery.json` file, then carry over what you need by hand. The editor never loads an old draft over the current version. Drafts are private to you in this browser. They are deleted when you sign out, when someone else signs in in this browser, or when your read access ends; the editor then shows *Read access was removed*. The same browser-copy rules as for Docs apply; see [Document save state](https://docs.crewship.ai/guides/document-drafts.md). ## When the history is full Every saved version is kept. Each Word document or Sheet has its own history budget, 16 GiB. The status line warns as it fills: from 80 % it adds *Version history is nearing its limit*, from 95 % *Version history is almost full* and at the limit *Version history is full*. When a save would go over the budget of the document, the workspace or the instance, the server refuses it and keeps every existing version. The status line stays on **Unsaved draft**, and an alert appears under it: *Storage is full, so nothing more can be saved. Your changes are not saved on the server yet.* The editor keeps your changes, the draft stays in this browser and every earlier version is kept. Autosave doesn't retry on its own. To keep your work: 1. Leave the editor open and keep working if you like. 2. Once space is freed (for example an instance administrator raises the workspace limit with `crewship admin instance artifact-storage set`), choose **Save again** in the alert or press Ctrl+S. The editor sends the current content as a new version; if storage is still full, the alert stays and nothing is lost. 3. To be safe, choose **Download draft**. You get the current content of the editor as a `wordcraft-recovery.json` or `gridcraft-recovery.json` file. You can also export from the editor itself. Crewship doesn't delete old versions, and the per-document budget is fixed in this release. If the document's own history is full, a retry is refused again: download the draft and carry on in a new document (see [Create a Word document or a Sheet](#create-a-word-document-or-a-sheet)). The draft also stays in this browser. When you open the editor again, it is offered as a **Local draft** row, as after a crash. ## Related * [Document history](https://docs.crewship.ai/guides/document-history-review.md) * [Document save state](https://docs.crewship.ai/guides/document-drafts.md) * [Craft commands](https://docs.crewship.ai/cli/craft.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.