Skip to main content
A Slides artifact is a slide deck that an agent writes and you read, present, comment on and export. Every save is an immutable version: the deck you see, the presentation you give and the PDF you download all come from one exact version, so what you send is what you reviewed. You change a deck by asking the agent, or, as the owner or an editor, by editing its source files with Edit source. Each change becomes a new version; earlier versions stay as they were.

Before you start

Slides is off by default. It needs both switches below. Server, per workspace. Slides builds on the workspace flag artifact_projects, the base for every versioned artifact, which is on unless someone turned it off. A workspace owner or admin enables artifact_slides, which adds the deck view and PDF export:
An operator can instead switch Slides on for every workspace on the instance with CREWSHIP_ARTIFACT_SLIDES_ENABLED=true in the server environment. See crewship feature-flag for overrides and how to revert them. Web app, at build time. The browser screens are compiled in only when the web app is built with these variables set to true: A default build sets none of them. With the server flags on and the build variables off, the CLI still reads decks and exports PDFs.

Create a slide deck

An agent writes the first version of a deck from your description. You need a direct chat with an agent in this workspace.
  1. Open Artifacts in the sidebar.
  2. Click New artifact in the top bar and pick Slides. The New artifact dialog opens.
  3. Under Start with, choose Describe it and write what the deck should contain in What should it contain?, for example “A six-slide quarterly review: results, risks, next steps”. Or choose From template and pick Quarterly review, Project update or Pitch.
  4. Optionally type a Name. The Folder stays Unfiled: the agent creates the deck unfiled, and you can file it afterwards.
  5. Click Continue in chat. A new direct chat with an agent opens with your request as an unsent draft in the message box.
  6. Turn on Create artifact project under the message box and send. The status line reads “Private project · Sharing requires your approval”.
The draft stays only in the chat that opened. If that chat is with the wrong agent, open a direct chat with the right one, paste the request again and continue with step 6 there. When the agent has saved version 1, the deck appears in the library with the Slides kind and Not shared. Only you can open it until you share it.

Open and read a deck

  1. Open Artifacts and click the deck in the list.
  2. The detail view shows the deck name, a Slides badge and its state (Draft unless the latest version is shared). On the right, Latest and Shared show which version each one points at.
  3. The Preview tab shows the current slide with Slide 1 / N above it and a row of thumbnails below it.
  4. Click a thumbnail to show that slide. The counter follows the slide you are on.
The keyboard moves the same slide when you are not typing: → or Page Down for the next slide, ← or Page Up for the previous one, Home and End for the first and last. The thumbnails, All slides, the slide picker above the deck and Speaker notes all show the same slide. The address names the slide you are on, for example /artifacts/<id>?workspace_id=<workspace>#slide-results. Copy it to send a link to that slide; reloading the page or going back to it opens the same slide. A link to a slide the deck no longer has opens the first slide. Use History to pick an earlier version; the deck view, Present and Download PDF then use that version. Edit source, shown to the owner and editors, opens the deck’s files on a separate screen. There, Edit source shows a file in a text box and Save project saves your edit as a new version. The new version must still follow the deck format, or it is not shown as Slides.
Who sees which version: the owner can read any retained version. People with edit access read the latest version. Everyone else who can open the deck reads only the version that is currently shared. If nothing is shared yet, they see no deck.

Present a deck

  1. Open the deck and go to the slide you want to start from.
  2. Click Present. The slide fills the screen on a black background with Previous slide, the position (for example 2 / 6), Next slide and Close presentation below it.
  3. Move with Next slide and Previous slide, or with the keyboard: → or Page Down for the next slide, ← or Page Up for the previous one, Home and End for the first and last slide.
  4. Press Esc or click Close presentation to return to the deck. The deck stays on the last slide you presented. Leaving the browser’s full screen ends the presentation the same way.
Speaker notes are kept with each slide but are not shown in Present mode or in the PDF.

Present with speaker notes

Presenter view keeps your notes on your own screen while the audience sees only the slides.
  1. Open the deck on a computer and go to the slide you want to start from.
  2. Click Presenter view next to Present. A new browser window opens with the current slide, the next slide, that slide’s speaker notes and the elapsed time. The original window starts Present with the speaker notes panel closed: move it to the projector or shared screen and click Full screen there.
  3. Move with Next slide and Previous slide or the same keys as in Present, in either window. Both windows always show the same slide.
  4. Click End presentation in the presenter window, press Esc in the audience window, or close either window. Both stop; the deck stays on the last slide shown.
The two windows talk to each other only inside your browser; nothing about the presentation is saved or sent to other people. If your browser blocks the new window, the deck says “Your browser blocked the presenter window. Allow pop-ups for this site and try again.” and does not start presenting. Presenter view is not offered on a phone.

Comment on slide text

You can attach a comment to a text block or a table on a slide. The comment keeps the exact version and the quoted text, so the agent knows what you mean.
  1. Open the deck and go to the slide.
  2. Click Select above the deck. Select appears only when you have write access to the deck and are on the latest version, not an earlier one.
  3. Click a text block or a table. A box opens headed with the element, its quoted text and the version, for example On #results-title · “Results” · v1.
  4. Type in What should change here?. Which buttons you see depends on who you are:
    • The owner of a deck an agent made sees Add to queue and Send to agent. Send to agent saves the comment and starts the agent on it. Add to queue saves it as a waiting task; Send N to agent under the comment list later starts every waiting one.
    • Everyone else with write access sees Save comment. The comment is saved with the deck and does not start the agent.
    Cancel discards the comment.
The agent works on a comment only after it is sent: “A comment starts the agent only when you send it.” Shapes cannot carry comments. Clicking one shows “Choose authored text or a table to comment on.” Read comments and the agent’s replies in the Comments tab. It has no reply form; to ask for another change, select the relevant slide element and add a new comment.

Download a PDF

  1. Open the deck at the version you want.
  2. Click Download PDF. The button reads Preparing PDF… while the server renders the deck.
  3. Your browser saves slides-v<version>.pdf, for example slides-v3.pdf.
The PDF is a vector rendering of the same version you were viewing, one page per slide in deck order. If a text block does not fit its frame, the deck view shows “Some slide content overflows its frame. PDF export may be unavailable.” The export then fails with “PDF download is unavailable. Reload to check access or slide overflow.” Ask the agent to shorten the text or enlarge the frame, then export the new version.

Read and export from the CLI

The same deck view and PDF are available to the crewship CLI. Pass the artifact slug or @<artifact-id> and an exact version:
--version is required for both commands. export-pdf also requires --out, a local file path that is never sent to the server. It prints a receipt with the path, media_type, code_version, byte_length and sha256 of the file it wrote. Agents use the equivalent artifact_slides_read and artifact_export_pdf tools. The HTTP endpoints are GET /api/v1/pages/{slug}/artifact/slides?version=<n> and GET /api/v1/pages/{slug}/artifact/export.pdf?version=<n>. The PDF response is application/pdf with the file name artifact-<artifact-id>-v<n>.pdf.

When a deck cannot be shown or exported

In the browser, a version whose files do not follow the deck format is not recognised as Slides: it carries an Artifact badge instead of Slides, and the preview reads “This Slides format is unsupported.” Other failures show “Slides preview is unavailable. Reload to check access.” or, for the PDF, “PDF download is unavailable. Reload to check access or slide overflow.” The HTTP endpoints return a specific status and code; the CLI prints the status and the message:

Deck format

Agents write a deck as a fixed, closed format. You do not need it to read a deck, but it explains why a version is refused. A deck version contains:
  • deck.json: {"schema_version":1,"order":["intro","results"]}, the slide IDs in order, at most 100 slides. schema_version stays 1 for decks that use the rich profile.
  • One slides/<id>.html file per listed slide and no other files.
Each slide file is a single <section id="<id>"> holding, in order, any number of these elements and at most one closing <aside id="..."> (the id is required) with plain-text speaker notes:
  • <p>: a text block with plain text only.
  • <div data-shape="rectangle"> or <div data-shape="ellipse">: an empty shape.
  • <table> with one <tbody>, plain <tr> rows and plain-text <td> cells.
Every element has an id and an inline style that sets left, top, width and height in whole pixels on a 1920 × 1080 slide. Text blocks also set font-size, color and text-align; shapes set background-color, border-color and border-width; tables set font-size, color, background-color and border-color. Colors are six-digit hex values such as #F97316. Scripts, images, links, comments, nested markup and other elements or styles are refused. A deck can also use the rich profile, which the deck view, Present and the PDF all draw the same way:
  • Typefaces: Go Regular (the default), IBM Plex Sans (regular, semibold, bold) and JetBrains Mono (regular, semibold). The faces ship with Crewship; a deck cannot load a font from anywhere else.
  • Text: bold and semibold weights, letter spacing, line height and font sizes up to 320 pixels.
  • Shapes: rounded rectangle corners, linear gradients between hex colors, and straight lines with optional triangle arrowheads.
  • Icons: about fifty outline icons picked by name, such as users, message-circle or rocket, in any hex color. A deck names an icon; it cannot supply its own SVG.
  • Transitions: a slide can fade or push in when you reach it in Present. With reduced motion turned on in your system, slides change without animation. The PDF has no transitions.
The exact syntax and the full icon list are in the crewship page artifact reference. The bundled faces are set without kerning or ligatures in both the deck view and the PDF, so text wraps the same way in both. In the PDF, a gradient is drawn as 128 narrow bands of the exact colors. What the profile still cannot express: images and photos, CSS layout (flex or grid), text-transform, mixed styles inside one text block, element animations (build-ins), shadows, opacity and radial gradients. Limits: at most 2 MiB of source in total, 256 KiB per slide file, 200 elements per slide, 1,000 elements per deck and 4,000 characters of notes per slide. A version beyond these limits is refused as unsupported (422). A PDF can be at most 8 MiB; a larger one is refused with 413.