Skip to main content
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 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.
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.
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. 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 in that editor. In this mode there is no full-view link, and /pages/<slug> and /pages/craft/editor?page_id=<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:
  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.
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/<id>, the immutable <id> is the page ID. Alternatively, run crewship page get <slug> --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 <agent> shows that chat’s ID in the ID column.
    • Message ID. crewship chat source messages agent_session <chat-id> --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 @:
    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=<work-id>: https://crewship.example.com/pages/craft/editor?page_id=<page-id>&workspace_id=<workspace-id>&craft_task_id=<work-id>. A panel under the lease bar shows the task state: 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 @<page-id> <work-id> and crewship craft task stop @<page-id>. 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.
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/<id>).
  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 <page> lists the same history and crewship craft version <page> <version> --output FILE saves one version’s bytes without touching the document; see Craft commands.

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: 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.

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). 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.