Skip to main content
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.
Projects are off by default. Each surface on this page needs these switches: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.

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

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