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

# Artifacts

> Versioned multi-file artifact projects: the library, versions, sharing, comments and storage limits.

An artifact project is a private Page that holds a complete set of files (an
`entrypoint` such as `index.html` plus its other files) as numbered,
immutable versions. Every save is a whole new version; nothing is edited in
place, and restoring an old version creates a new one. People read one
version that the owner chose to share, while the owner keeps working on the
latest one.

> [!NOTE]
>
> Artifact projects are **on by default** through the `artifact_projects`
> feature flag. A workspace manager can turn them off for one workspace
> (`crewship feature-flag disable artifact_projects`), and an instance admin for
> every workspace without an override (see
> [Turning Projects off](https://docs.crewship.ai/configuration/artifacts.md#turning-projects-off)). While
> they are off, the create, version and comment routes answer `404`.
> `crewship page artifact availability` reports `{"enabled": true}` or
> `{"enabled": false}` for the current workspace.

## The Artifacts library

The `/artifacts` library is a browser view over the Pages the caller can
read. `NEXT_PUBLIC_ARTIFACTS_LIBRARY=true` at build time opens this library
and makes the **Artifacts** sidebar entry lead there. The Design build flag
`NEXT_PUBLIC_ARTIFACTS_DESIGN=true` also opens `/artifacts`, but without the
library flag the sidebar still leads to `/pages`; open `/artifacts` directly.
When both flags are off, `/artifacts` sends the browser to `/pages`. With the
library flag on, old Pages addresses lead to the library as well; see
[One address per artifact](#one-address-per-artifact).

The library lists each Page with its kind: Project, Dashboard, Page, Word,
Sheet, Slides or Design. The kind comes from the server's `artifact_kind` and
`artifact_profile` or from the Page's stored content, never from its name. For a versioned item it
shows the shared version, or marks the item as not shared yet. The list,
counts, filters, preview, header and New artifact all show the same library
label for it: a design system is **Design · Library**, and an interactive
project is an **App**, never a Dashboard.

| View | What it holds |
| - | - |
| Home, All artifacts | Every item except empty, test and archived ones |
| Needs attention | Versioned items that were made but never shared |
| Recently opened, Favorites | Your own history and stars, kept as your user preference for this workspace |
| Mine | Items you own |
| Clean up, Test items, Empty, Archive | Repeated series, items created as tests, items with nothing in them, and archived items |

Archived, test and empty items appear only in their own views; nothing is
deleted by hiding it. The search box accepts free text plus `kind:`, `is:`
and `owner:` operators, for example `kind:word is:private owner:you budget`.
`is:` takes `private`, `shared`, `unshared` (or `draft`) and `empty`.

## One address per artifact

Every artifact opens at `/artifacts/<id>?workspace_id=<workspace-id>`, where
`<id>` is its immutable page ID, never its slug. A pinned version adds
`&version=N`. Links the server generates use this address: the `url` from
`crewship doc create` and the project commands, and the `page_path` the agent
project tool reports.

With `NEXT_PUBLIC_ARTIFACTS_LIBRARY` in the build, older addresses keep working
and replace themselves with that address, so Back does not return to them:

| Old address | Opens |
| - | - |
| `/pages` | `/artifacts`, with the same query |
| `/pages/<slug>`, `/pages/@<id>`, `/pages?ref=<id>&workspace_id=…` | `/artifacts/<id>?workspace_id=…` |
| `/pages/<slug>?artifact=1[&version=N]`, `/pages/<slug>?version=N` | `/artifacts/<id>?workspace_id=…[&version=N]` for a project the detail shows in its project viewer |
| `/pages/craft/editor?page_id=<id>&workspace_id=…` | `/artifacts/<id>?workspace_id=…`, where the same Craft editor opens |
| `/pages/<slug>/editor`, `/pages/@<id>/editor` | `/pages/<slug>?mode=edit`, which then moves on like any Pages editor address |
| `/artifacts/@<id>` (the CLI's `@<id>` form) | `/artifacts/<id>`, with the same query |
| `/artifacts/<slug>` | `/artifacts/<id>`, keeping `workspace_id`, a version pin `?version=N` and `?ref=`. An artifact whose ID is that text always wins over a slug |

An address stays on Pages when Pages is the only place that shows it: the panel
editor (`?mode=edit`), the project source editor (`?artifact=1&edit=1`), and
a page the Artifacts detail cannot open, such as an older Craft workbook. A
refused or failed read also stays on Pages, which answers it the way it always
did. The public share address `/p/<token>` is unchanged.

None of these moves reveals whether an artifact exists. `/artifacts/@<id>` and
`/pages/<slug>/editor` move by address alone, before any read. `/artifacts/<slug>`
matches only the artifacts the person's own catalog lists; anything else gets
the server's single answer for a page that is missing or not theirs, so the
screen reads "This artifact doesn’t exist" in both cases.

A restricted member is never redirected, and sees exactly what they saw
before: every `/pages` address shows their catalog of declared Page actions,
and `/artifacts` stays outside their access. The library reads
(`GET /api/v1/pages` and `GET /api/v1/pages/{slug}`) are not on the restricted
allowlist.

Without the library flag, `/artifacts/<id>` opens on Pages: a project in the
Pages project viewer, every other kind in its Pages detail.

## Versions

Save this complete example as `manifest.json`:

```json theme={null}
{"entrypoint":"index.html","files":[{"path":"index.html","content":"<h1 id=\"artifact-heading\">Current title</h1>","media_type":"text/html"}],"message":"First version"}
```

Create version 1, publish version 2 against the exact latest version you read,
then restore version 1 as a new version 3:

```bash theme={null}
crewship page artifact create demo --name "Demo" --file manifest.json
crewship page artifact get demo
crewship page artifact publish demo --base-version 1 --file manifest.json
crewship page artifact versions demo
crewship page artifact restore demo --base-version 2 --version 1
```

Every file is listed every time: a file
left out of the manifest is absent from the new version. If someone else
saved first, the server answers `409` with code `artifact_version_conflict`
and stores nothing; the CLI does not retry. Read the latest version, compare,
and publish again.

## Sharing

A new project is private to its owner. `share` pins one retained version as
the version everyone else reads:

```bash theme={null}
crewship page artifact share demo --base-version 3 --version 2
```

Only the human owner can share. Sharing also ends the Page's private
audience, so from then on the ordinary [Page permission
model](https://docs.crewship.ai/guides/pages.md#permission-model) decides who opens it: the owner, a
workspace ADMIN or OWNER, grantees and folder access. Grant levels decide what
each of them may do with the project:

| Who | Reads | May also |
| - | - | - |
| Owner | Every retained version, history and storage usage | Publish, restore, share, reply to comments, send comments to the agent |
| `write` grant or folder write | Only the latest version, once the Page is no longer private | Publish a new version under their own name, comment on the latest version |
| `comment` grant, workspace ADMIN or OWNER | Only the shared version | Comment on the shared version |
| `read` or `produce` grant | Only the shared version | Nothing else |

The project response tells a client which of these apply through
`can_write`, `can_comment`, `can_share`, `can_restore` and
`can_send_to_agent`. Issue grants with `crewship page grant` (also available
as `crewship page share`), for example
`crewship page grant demo --user ada@example.com --level comment`; see
[Page commands](https://docs.crewship.ai/cli/page.md).

## Comments

A comment is bound to one version, one file and one element:

```bash theme={null}
crewship page artifact comment demo --version 3 --path index.html \
  --selector '#artifact-heading' --quote 'Current title' \
  --text 'Make this title shorter'
crewship page artifact comments demo
```

Replace `COMMENT_ID` below with the comment response’s `id`. Change the
heading text in `manifest.json` while keeping its `artifact-heading` ID, then
publish that complete manifest as version 4 before replying:

```bash theme={null}
crewship page artifact publish demo --base-version 3 --file manifest.json
crewship page artifact reply demo COMMENT_ID --version 4 --text "Shortened the title"
```

The selector is a single `#id` that matches exactly one element in that file,
and `--quote` must still match the element's text. Give elements stable
`artifact-` prefixed IDs so they stay selectable across versions. A comment on
an outdated version returns `409` (`artifact_version_conflict`); a selection
that no longer matches returns `409` (`artifact_anchor_mismatch`). Neither
stores anything.

For an agent-created project with a source chat, add `--send-to-agent` to
queue a task bound to that version. The CLI-created project above has no
source chat; this flag does not connect one. A queued task is not
proof that an agent received it. A comment from a Comment grantee is stored
with a task, but it never starts the owner's agent. A reply normally names a
newer version that made the change; `--needs-clarification` replies on the
original version and asks for a new selection.

## Storage limits

| Limit | Value |
| - | - |
| Files per version | 1 to 256 |
| File content per version | 32 MiB |
| History per project | 256 MiB, every version kept |
| File path | 512 bytes |
| Version message | 4096 bytes |
| Project name | 200 bytes |
| Request body | 36 MiB; the CLI reads a manifest of at most 9 MiB |
| Comment text | 10000 bytes; selector and quote 2000 each |
| Pages per workspace | 100, including artifact projects |

Identical file contents are stored once per project. The owner's project
response carries `quota` with `used_bytes`, `limit_bytes` and `warning`, which
turns true at 80 % of the limit. A save that would exceed the history limit
returns `413` with code `artifact_history_quota` and keeps every existing
version; keep your local draft. A creation at the workspace page limit (100
by default) returns `422` with code `pages_limit` instead; it says nothing about an
existing project’s history. Other readers see a `quota` that names only
their retention (`latest-version-only` or `shared-version-only`).

Unsaved project source and comment drafts are kept encrypted in this browser
under the Page ID. A draft that an older Crewship version kept under the Page
address (slug) carries no Page identity, and that address may have belonged to
another Page. Opening the project shows it as an **older draft**: it is never
applied or deleted automatically. **Use old source draft here** (or **Use old
comment here**) stores it encrypted under this Page and only then removes the
old copy; **Discard** removes it. Only the account that typed it sees it.

A draft follows the read right. If the Page read right goes, the server stops
unwrapping the draft key and the browser deletes the draft, and the page says
so. It does not come back with a later grant. If you lose only the write right the
draft stays sealed in this browser and is offered to nobody, also in the tab where
you typed it; it comes back if the write right does.

## Give the agent its playbook

The server installs Crewship's artifact playbooks into the skill catalog when
it starts. It does not attach them to agents. Assign the one that matches the
work to each agent that should do it; the skill is written into the agent's
workspace when its next run starts.

| Skill | Use it for |
| - | - |
| `crewship-artifacts` | Project, Dashboard and Slides artifacts, plus edits to an existing Design canvas |
| `crewship-design` | Design canvases edited from node comments the owner sends to a connected chat |
| `crewship-craft` | Native Word and Sheet documents changed in a whole-document task |

```bash theme={null}
crewship skill assign crewship-artifacts <agent-slug>
crewship skill assign crewship-design --to-crew <crew-slug>
```

The tools still need their workspace flags. For Project, Dashboard, Slides
and Design the agent's crew must also be on the
[workspace artifact policy](https://docs.crewship.ai/cli/artifacts.md#agent-publishing-policy) allowlist;
native Word and Sheet tasks do not check that policy yet
([#4681](https://github.com/crewship-ai/crewship/issues/4681)). Design needs
the owner's connected chat and Craft the owner's task. The playbook only tells
the agent how to use them.
See [`crewship skill assign`](https://docs.crewship.ai/cli/skill#crewship-skill-assign).

## Choose a workflow

| Task | Guide |
| - | - |
| Browse and manage artifacts, including Design System tokens | [Library](https://docs.crewship.ai/guides/artifacts/library.md) |
| Grant access and share versions | [Sharing and access](https://docs.crewship.ai/guides/artifacts/sharing-and-access.md) |
| Build and review linked screens | [Project](https://docs.crewship.ai/guides/artifacts/project.md) |
| Edit a collaborative canvas | [Design](https://docs.crewship.ai/guides/artifacts/design.md) |
| Trace live dataset values | [Dashboard](https://docs.crewship.ai/guides/artifacts/dashboard.md) |
| Run a Project's own scripts with shared data | [Interactive artifacts](https://docs.crewship.ai/guides/artifacts/interactive.md) |
| Present or export a deck | [Slides](https://docs.crewship.ai/guides/artifacts/slides.md) |
| Edit native documents and hand over custody | [Word and Sheet](https://docs.crewship.ai/guides/artifacts/word-and-sheet.md) |
| Follow artifacts in a conversation | [Chat](https://docs.crewship.ai/guides/artifacts/chat.md) |
| Configure, back up and operate the feature | [Configuration](https://docs.crewship.ai/configuration/artifacts.md), [operations](https://docs.crewship.ai/guides/artifacts/operations.md) |

## Related

* [Pages API: artifact projects](https://docs.crewship.ai/api-reference/pages.md#artifact-project-creation)
* [Artifact commands](https://docs.crewship.ai/cli/artifacts.md)
* [Design, Craft and Mooring workflows](https://docs.crewship.ai/cli/artifacts-design-craft.md)
* [Artifacts API overview](https://docs.crewship.ai/api-reference/artifacts.md)
* [Page commands](https://docs.crewship.ai/cli/page.md)
* [Pages guide](https://docs.crewship.ai/guides/pages.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.