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

# Projects: screens, comments and agent work

> Move between the screens of a Project artifact, pin comments to exact elements, send them to the agent, and see what the agent may do.

A **Project** is an artifact made of linked HTML screens, for example an order
list, an order detail and a settings screen. An agent writes it from a chat. You
review it in **Artifacts**, click the part you want changed, and the agent
publishes a new version and answers your comment. Every save is a numbered
version; nothing in the history is deleted automatically.

> [!NOTE]
>
> Projects are off by default. Each surface on this page needs these switches:
>
> | Surface | Needs |
> | - | - |
> | Projects at all (create, view, comment, agent tools) | Workspace flag `artifact_projects`: `crewship feature-flag enable artifact_projects`. An operator can turn it on for every workspace with `CREWSHIP_ARTIFACT_PROJECTS_ENABLED=true`. |
> | **New artifact** › **Project** and the Project preview in **Artifacts** | Build-time `NEXT_PUBLIC_ARTIFACTS_LIBRARY=true` and `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=true`. The default production build sets `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=false`. |
> | Project cards and the side viewer in chat | Build-time `NEXT_PUBLIC_CHAT_ARTIFACT_PROJECTS=true` |
> | **Create artifact project** in a chat | Workspace flag `artifact_projects` only |
> | An agent creating or publishing | The workspace artifact policy must be on and list the agent's crew: `crewship workspace artifact-policy show` and `crewship workspace artifact-policy set` (workspace owner or admin) |
>
> Dashboards and Slides are Projects with extra files and have their own flags
> (`artifact_dashboard_data`, `artifact_slides`).

## Create a Project

In the app, a new Project is written by an agent, and only after you allow it
for one message.

### Before you start

* The workspace flag `artifact_projects` is on (see the note above).
* You have an agent that can run: it has a model set. Its chat shows "Model not
  set" otherwise, and nothing is created.
* The workspace artifact policy is on and lists that agent's crew. A workspace
  owner or admin checks it with `crewship workspace artifact-policy show` and
  changes it with `crewship workspace artifact-policy set`. Without it the
  agent’s create call is refused. To identify the crew, use `crewship agent
  list` (the **CREW** column), then `crewship crew get <crew-slug>`. Read the
  policy’s current `version` and use `artifact-policy set --base-version <version> --enabled --crew-id <crew-id>` with the complete crew allowlist;
  `set` replaces it. Use the workspace ID when selecting the workspace.
  See [workspace artifact policy](https://docs.crewship.ai/cli/workspace.md#crewship-workspace-artifact-policy-set).

### Steps

1. Open **Artifacts** and click **New artifact**.
2. **Project** ("Screens that link together") is selected. Under **Start with**
   choose **Describe it** and write what the screens should contain, or choose
   **From template** (Pricing site, Sign-up flow, Landing page, Status page).
3. Click **Continue in chat**. Chat opens on the conversation you were last in,
   with your description already in the composer as an unsent draft, for
   example "Create a project: …". Nothing is sent yet.
4. Check the agent name at the top of the chat. If it is the agent who should
   build the Project, go on. If you have several agents or want a different
   one, copy the draft text, open that agent under **Agents** in the sidebar,
   start a chat with it and paste the text into its composer. The draft does
   not move with you to another conversation.
5. Turn on **Create artifact project** under the composer. It reads
   "Private project · Sharing requires your approval".
6. Send the message.

You can also skip the dialog: in any private chat with an agent, turn on
**Create artifact project** and describe the screens yourself.

People with permission to create pages can also create a Project from the
command line, without an agent, by supplying all files in one manifest:
`crewship page artifact create <slug> --name "<name>" --file manifest.json`.
See [Artifact projects in the CLI reference](https://docs.crewship.ai/cli/page.md#artifact-projects-disabled-by-default).
A Project created this way has no source chat, so its comments are saved but
cannot be sent to an agent.

The agent saves all files in one step as version 1. The new Project is private
to you until you share a version. The agent cannot share it, choose an owner or
pick an audience.

## Share a version

After reviewing the latest version, the owner opens **Share** above the preview,
chooses the version and confirms **Share vN**. This selects the version readers
can see; publishing another version later does not move it. Grant people
access separately in the artifact’s **Access** or **Share** dialog. Agents
cannot share a version.

## Switch between screens

Open the Project from **Artifacts**. The detail has three tabs: **Preview**,
**History** and **Comments**.

On **Preview**, the bar above the canvas lists every HTML file of the Project as
a screen. The entry file comes first, then the others in file-name order.

* A screen is named after its `<title>` when every screen has a different title
  of at most 24 characters. Otherwise it is named after the file, so
  `detail.html` shows as **Detail** and `faq.html` as **FAQ**.
* Up to four screens show as buttons. With more, a narrow window shows a
  **Screen** drop-down instead.
* Links between screens work inside the preview. Clicking
  `<a href="settings.html">` on one screen opens the **Settings** screen.
  Links to anything outside the Project do nothing.

The preview runs in an isolated frame. Its scripts cannot read your session or
leave the frame, so a screen that loads data from the internet shows without it.

### Example: three screens

A Project with these files shows **Orders**, **Order detail** and
**Settings** as screens:

```html theme={null}
<!-- index.html -->
<title>Orders</title>
<link rel="stylesheet" href="style.css">
<nav id="artifact-nav"><a href="index.html">Orders</a> <a href="detail.html">Order detail</a> <a href="settings.html">Settings</a></nav>
<h1 id="artifact-orders-heading">Orders</h1>
<ul id="artifact-orders-list"><li><a href="detail.html">Order 1042</a></li></ul>

<!-- detail.html -->
<title>Order detail</title>
<h1 id="artifact-detail-heading">Order 1042</h1>
<div id="artifact-detail-summary">Total: 120 EUR. Status: shipped.</div>

<!-- settings.html -->
<title>Settings</title>
<h1 id="artifact-settings-heading">Settings</h1>
<p id="artifact-settings-email">Email me when an order ships.</p>
```

`style.css` is a fourth file. It is applied to every screen that links it and
is not a screen itself.

## Pin a comment to an element

You comment on an exact element of an exact version, so the agent knows what to
change.

1. On **Preview**, open the screen and make sure **Latest** is selected in the
   version switch. Older versions take no comments.
2. Click **Select**. Elements that can take a comment get a dashed outline;
   everything else shows a not-allowed cursor.
3. Click the element. A numbered card opens on the canvas, titled with the
   element and version, for example
   "On #artifact-settings-email · "Email me when an order ships." · v1".
4. Type the change in the box (its placeholder reads "What should change here?").
5. Save it (see the next section for which buttons you get).

Only elements with an `id` can be selected; clicking inside one selects the
nearest element with an `id`. Very long blocks of text cannot be selected;
pick a smaller part. If the
screen has none, you see "Nothing on this screen can take a comment yet:
comments anchor to parts with an id, and this screen has none. Ask the agent in
chat to add them." Agents are asked to give headings, cards, sections and
buttons stable IDs that start with `artifact-`.

Clicking a comment in the list switches to its screen and briefly outlines the
element.

### Your unsent comment is kept

While you type, the comment is saved in this browser for you, this workspace
and this Project. If the tab closes or the browser crashes, open the Project
again: the text is back in the comment card. Click **Select** and pick the
element again, because the selection is not kept.

The draft is cleared when the comment is saved. If the browser blocks storage,
nothing is kept; copy long comments before you leave.

## Send a comment to the agent

What the comment card offers depends on who you are and where the Project came
from:

| You | Buttons |
| - | - |
| Owner, Project created by an agent in your chat | **Cancel**, **Add to queue**, **Send to agent** |
| Owner, Project without a source chat | **Cancel**, **Save comment** |
| Someone else who can edit it | **Cancel**, **Save comment** |

* **Send to agent** saves the comment as a task and immediately posts a request
  in the chat where the Project was created. Successful delivery submits the
  task; it does not confirm that the agent run has started.
* **Add to queue** saves the task without starting the agent ("Added to the
  queue. The agent starts when you send it."). When you are ready, open
  **Comments** and click **Send N to agent**. Waiting tasks go out one by one;
  the first delivery failure stops the rest.
* **Save comment** only records the comment. It never starts an agent.

A comment starts the agent only when you send it. The request needs the source
chat to be connected and the agent to be idle. If it does not go out, the
comment stays saved and the viewer shows "The agent did not start" with
**Retry**. Sending the same comment again never creates a second task.

### Follow the agent's answer

Each comment in **Comments** shows its state:

| Label | Meaning |
| - | - |
| No label | Saved with **Save comment**; it is not for the agent |
| **Waiting** | Saved for the agent; its run has not started yet, including after delivery |
| **Agent working** | The agent's run has picked it up |
| **Done · v2** | The agent published version 2 and replied |
| **Needs a new selection** | The agent could not find the element and asked you to select it again |

The agent's replies appear under the comment with the version they refer to,
for example "v2: Added the shipping date". When you see **Needs a new
selection**, read the reply, select the element on the latest version and send
a new comment.

The number on the **Comments** tab counts tasks whose status is `pending`
(**Waiting**), including requests already delivered but whose runs have not
started. Ordinary saved comments and tasks with other statuses are not counted,
so the tab can show no number while it holds comments. On a wide window the same list also sits beside the preview.

### When something changed meanwhile

* **Changed meanwhile**: someone saved a newer version while you were
  commenting. Nothing was overwritten. Click **Reload and reapply** to put your
  comment and selection on the newest version.
* **This element changed. Select it again.**: the element is gone or no longer
  matches its text. Your text stays; select the element again.
* **Saving is paused**: the Project's history storage is full. Your comment
  stays in the card; use **Copy my comment** and **Manage versions**.

## Edit the source yourself

People who can edit a Project see an **Edit source** link above the preview.
Editing takes two clicks:

1. Click **Edit source** in **Artifacts**. This opens the full project view, a
   separate page.
2. Click **Edit source** again in that view. Choose a file under **Source file
   path** and edit it.
3. Click **Save project**. The save becomes a new version.
4. **Discard source draft** throws your changes away.

The full project view is meant for editing source. It differs from **Preview**:

* Its screens are buttons named after their files (for example `detail.html`,
  `index.html`, `settings.html`), not after their titles.
* It has its own **Version** select with **Restore version N** and **Share
  version N** buttons for the version you pick (owner only).
* It has its own simpler comment pane (**Select an element**, "What should
  change?", **Post comment** or **Send to agent**). Use the comment card in
  **Preview** instead: it shows the comment states described above and offers
  **Add to queue**.
* **Back to Page** leaves the view. To return to the Project in Artifacts, open
  **Artifacts** again.

Your unsaved source draft is kept in this browser. When you come back you see
"Unsaved source draft from version N was kept in this browser" with **Restore
source draft** and **Discard it**. If the Project moved on in the meantime,
saving the old draft reports a conflict and keeps your draft.

## What the agent can do

Agents work on Projects through these tools:

| Tool | What it does |
| - | - |
| `artifact_create` | Creates one private Project with all its files in one step |
| `artifact_publish` | Saves a complete new set of files as the next version |
| `artifact_versions` | Reads the current files, retained versions and storage use |
| `artifact_restore` | Restores an older version as a new version |
| `artifact_comments` | Reads the comments, each anchored to a version, file, element and quote |
| `artifact_reply` | Replies to a comment with the version that changed, or asks for a new selection |

Rules the server enforces:

* **One run, one permission.** An agent may create a Project only in the run
  started by your message with **Create artifact project** on. It may change a
  Project only in the run that created it, or in a run started by **Send to
  agent** on that Project, and only in a private chat that you started. The
  permission ends with the run.
* **Crew policy.** The workspace artifact policy must be on and include the
  agent's crew. The policy is a ceiling and never replaces your permission for
  the run.
* **Exact base version.** Every publish names the version the agent read. If
  the Project moved on, the server refuses with a conflict and keeps the
  current version.
* **No sharing.** Agents cannot share a version or grant access. Sharing is
  always your step.

What agents are instructed to do (the tool descriptions ask for it; the server
does not check it):

* **Reconcile conflicts.** After a conflict, keep the changes, explain the
  conflict and reconcile on purpose instead of retrying blindly against a
  newer version.
* **Stable IDs.** Write `artifact-` IDs on meaningful elements and keep IDs of
  unchanged elements, so existing comments stay anchored. The server never
  adds IDs itself.
* **Answer the comment.** After publishing, reply with the new version and what
  changed. If the anchor no longer identifies the element, ask for a fresh
  selection instead of guessing.

Limits per Project: up to 256 files and 32 MiB per version, and 256 MiB of
history in total. The viewer warns before the history is full.

## Who sees what

| Role | Sees | Can |
| - | - | - |
| Owner | Every version, all comments | Comment, send to the agent, edit source, restore, share |
| Editor (write access) | The latest version | Comment (saved only), edit source |
| Reader of a shared version | Only the shared version | View |

A Project is private until the owner shares a version. Later versions stay
private until they are shared too.


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