# Building a journey > Create a journey, lay out chapters, pages and blocks, set its checkpoints, paths, scorecard, theme and coach dock, and restore earlier versions. - Plans: All plans - Canonical: https://docs.devlin.ai/journeys/build-a-journey A journey is a hosted, multi-page learning experience that you compose from simulations, coaches, knowledge checks and your own content. It is organized as chapters, each chapter holds pages, and each page holds blocks. Learners move through it one screen at a time, and a page is one or more screens. Journeys are available on every plan. What a plan changes is how many journeys a workspace can hold and whether learners see the journey's own theme (see Theme below). ## Before you start - Journeys are on the **Journeys** tab of **Studio**. See [Finding your way around the app](https://docs.devlin.ai/get-started/find-your-way-around). - Any member of the workspace can create, edit and delete its journeys. The plan does not change who can build one. - A workspace can hold a limited number of journeys, counting drafts and published journeys together: 5 on Free, 10 on Starter, 50 on Core, 250 on Team and 1,000 on Enterprise. At the limit, creating another is refused with "Journey limit reached" and the advice to upgrade or delete a journey. - Create the simulations and coaches you want to include first. A journey block connects to a simulation or coach that already exists in the workspace. See [Creating a simulation](https://docs.devlin.ai/simulations/create-a-simulation) and [Building and publishing a coach](https://docs.devlin.ai/coaches/build-a-coach). - Building and saving a journey does not use credits, except a generated scene (see Theme below). The simulations and coaches inside it use credits when learners talk to them, as they do anywhere else. See [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage). ## Steps 1. In **Studio**, select **Create**. In the **Create new** dialog, choose **Journey**. On the **Journeys** tab you can also select **New journey**, or **Create journey** when the tab is empty. 2. In the **New journey** dialog, type a **Journey name**. 3. Under **Starting point**, pick a blueprint (see Blueprints below), then select **Create journey**. The editor opens on the new draft. 4. In the outline on the left of the **Content** section, select **Add chapter** and **Add page** to lay out the structure, and select a page to show it on the canvas. **Add page** asks for a layout to start the page from (see Page layouts below). 5. On the canvas, select **Add block** under the page's last screen (on an empty page, under the empty card), or the plus button (**Add block here**) in the gap above a screen or between two blocks, then choose a block type in the **Add block** dialog. 6. Fill in each block. Text and callout blocks are edited in place. Every other block opens a settings panel on the right of the canvas (see Canvas and Block types below). 7. Open the other **Design** sections to set the journey-wide behavior: **Checkpoints**, **Paths**, **Scorecard**, **Theme**, **Title & completion** and **Coach dock**. 8. Watch the save indicator beside the journey name. Your edits are saved automatically, and the indicator reads "Saved" when the draft is stored. 9. Select **Preview** to open the draft as a learner would see it, in a new browser tab. 10. When the draft is ready, publish it. See [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey). ## Result You have a draft journey that appears on the **Journeys** tab of Studio with its chapter count, its simulation count and its status. Learners cannot open a draft. Publishing, the learner link, LMS export, tracking and review links are covered in [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey). ## Blueprints A blueprint is the structure a new journey starts with. Every blueprint leaves its simulation and coach blocks unconnected, so you choose which simulation or coach each one uses. The checkpoints, paths and scorecard entries a blueprint creates start with no simulation chosen, and they block publishing until one is. When a journey has a single simulation block, connecting it fills them in for you. When it has more than one, as **Certification path** does, choose the simulation yourself in each checkpoint, path and scorecard entry. - **Blank journey**: one chapter with one empty page. - **Practice sprint**: one chapter with three pages. The first sets the scene, the second holds a simulation with a character beside it, and the third holds a debrief text and a coach. A checkpoint locks the debrief page until the simulation is completed. - **Certification path**: three chapters for learning, practicing and proving. It includes two simulations, a knowledge check with two sample questions, checkpoints that lock the practice chapter until both learning pages are viewed and the final chapter until both simulations are completed, and a weighted scorecard. - **Scenario branch**: a chapter with one simulation and a remediation chapter, with a path that sends a learner who fails the simulation to the remediation chapter. ## The journey editor The editor is the screen at the journey's own address under Studio. Any member of the workspace that owns the journey can open it. A journey from another workspace is not found. ### Top bar - The journey name is an editable field. See Name below. - A status badge shows whether the journey is a draft or published. - The save indicator reads "Saved", "Saving…" or "Unsaved changes". While the draft has anything to fix before publishing, a count beside it, such as "3 to fix before publishing", opens the list. Each line names the chapter, page and block, or the settings section, and says what is wrong. Selecting a line opens that page or section. See Saving below for "Changes are not being saved". - **Version history** opens the list of saved versions (see Version history below). - **Export**, **Preview**, **Publish Changes** and, for a published journey, **Unpublish** are described in [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey). **Publish Changes** is unavailable while the draft has publishing issues, and pointing at it tells you how many to resolve. Below the top bar, one row of tabs holds the editor's two stages, **Design** and **Publish**, followed by the sections of the stage you are in. **Design** has seven sections: **Content**, **Checkpoints**, **Paths**, **Scorecard**, **Theme**, **Title & completion** and **Coach dock**. The **Publish** stage shows a count of publishing issues while there are any. ### Outline The **Content** section uses the full width of the window: the outline on the left and the canvas beside it. - **Add chapter** appends a chapter that already holds one page named "New page". **Add page** opens the **Add page** dialog and appends a page built from the layout you pick to that chapter. - Selecting a page shows it on the canvas. - A page's name in the outline is also its name in the learner's menu. The heading on the page's screens starts as the same text and can be changed on its own on the canvas. - Pointing at a chapter or page reveals its controls: **Rename chapter** or **Rename page**, **Move chapter up** and **Move chapter down** (or the page equivalents), and **Delete chapter** or **Delete page**. Double-clicking a title also renames it. An empty title is not kept. - A page moves only within its own chapter. - The last chapter of a journey and the last page of a chapter cannot be deleted. - Deleting a chapter or page asks you to confirm. If checkpoints, paths, scorecard entries or buttons refer to what you are deleting, the confirmation lists what will also be removed or reset. - **Collapse outline** shrinks the outline to a narrow strip of chapter numbers and page dots. The rename, move and delete controls are available only when it is expanded. ### Canvas The canvas shows the selected page the way a learner sees it: as screens. A learner sees one full screen at a time, and the canvas lists the page's screens from top to bottom, each in a wide frame with the journey's theme and the scene that page uses. A frame is as wide as the canvas allows, but no taller than the window below the editor's header. The page's name is shown above its frames. The kind of block decides how much of the screen it takes: - Text, callout, image, download, knowledge check, divider and button blocks that follow one another share one screen, stacked inside a card over the scene. The card grows with the screen, up to a width that keeps lines of text easy to read, and a card of only images and dividers can grow wider. - A simulation, a simulation bank or a coach is always a screen of its own. A simulation has its character or its notes beside it when it shows them. On the canvas a bank is one frame, a placeholder that reads "Simulation bank", says how many of its simulations each learner gets ("Learners get N of M, chosen at random.", with the numbers filled in), and lists them. When it shows characters, the frame shows its first simulation's character. A learner sees one screen per call. - A video or a custom code block is always a screen of its own and fills it, with no scene behind it. Simulation, simulation bank, coach and knowledge check blocks appear as placeholders, not as live content. An image, video or download block with no address yet also appears as a placeholder that you can select to add one. A simulation or simulation bank with **Beside the simulation** set to **Character** always has a character frame on the canvas: where no character is chosen yet, or a custom character is not ready, the frame holds a plain silhouette, and a learner sees no character there. - The heading at the top of each frame is the heading learners see on that page's screens. Select it to type a different one: it can say something other than the page's name in the outline and the menu. Emptying it hides the heading on the page's screens (a card shows no heading); the learner's top bar shows the page's name instead. Typing the page's name again links the two again, so renaming the page changes the heading too. - **Add page** sits under **Add block** at the foot of every page. It opens the **Add page** dialog, and the new page is placed right after the page you are on, in the same chapter, and opened on the canvas. - **Add block** sits under the last frame of every page, and a plus button, **Add block here**, sits in the gap above each frame and between two blocks inside a card. Both are always shown and open the **Add block** dialog. Adding a simulation, a simulation bank, a coach, a video or a custom code block between two blocks of a card splits the card into two screens around it. - A new text or callout block opens for typing straight away. An empty one reads "Empty text block. Click to write." (or "Empty callout. Click to write.") on the canvas, and a learner sees nothing there. - Selecting a text or callout block lets you type its content in place. Clicking away or pressing Ctrl+Enter (Command+Enter on a Mac) keeps the change, and Escape discards it. - Selecting any other block opens its settings panel. **Block settings** on a block's hover controls opens the same panel. - **Drag to reorder** moves a block to another position on the same page. A block cannot be dragged to a different page. - **Delete block** asks you to confirm, and lists any checkpoint, path or scorecard entry that will be removed with it. - Pressing Ctrl+Z (Command+Z on a Mac) outside a text field undoes the most recent content edit. Undo covers content edits only, not renaming the journey, and the undo history is cleared when you leave the editor or restore a version. On a phone-width or small tablet screen the block settings panel opens as a sheet along the bottom of the screen, with its own scrolling. **Close inspector** or Escape closes it. On a wider screen the block settings panel opens on the right of the canvas, and stays in view as you scroll. It never covers the frame you are editing. On a very wide screen the outline stays beside the canvas while the panel is open. Below that, the outline steps aside to keep the canvas wide: to open another page, close the panel first. **Close inspector** or Escape closes it and brings the outline back, expanded or collapsed as you left it. Opening another block's settings on the same page switches the panel to that block. ## Page layouts The **Add page** dialog offers layouts, each drawn as a small picture of the learner's screen, under **Learn**, **Practice**, **Check** and **Build your own**: - **Lesson**: a heading and a text block in a card. **Lesson with a picture**: an image above the text. **Video**: a video that fills the screen. - **Simulation with a character** (the character on the right), **Character on the left**, **Simulation with notes**, **Simulation only**, **Simulation bank** and **Coach**. - **Knowledge check**: a knowledge check in a card. - **Custom code**: a custom code block that fills the screen. **Blank page**: a page with no blocks. A layout is only where the page starts. Its blocks are ordinary blocks: you can change their settings, swap what sits beside a simulation, add blocks or remove them. A page does not remember which layout it came from. An AI tool builds the same pages by writing their blocks. ## Block types The **Add block** dialog lists the block types under **Practice**, **Content**, **Media** and **Build your own**. Each one has an icon, a sentence about what it is, and where it sits on the learner's screen: **In a card**, **Its own screen** or **Fills the screen**. - **Text**: formatted text. The **Markdown** field supports headings, bold and italic, links and lists, and holds up to 20,000 characters. - **Callout**: a highlighted note. **Variant** is **Info**, **Tip** or **Warning**, and **Markdown** holds the text, with the same length limit as a text block. Info and tip callouts take the journey's accent color, told apart by their icons; a warning callout is always amber. - **Image**: **Image URL**, **Alt text** and **Caption (optional)**. - **Video**: **Video URL**, **Title**, **Captions URL (optional)** and **Poster image URL (optional)**. While no captions address is set, the panel shows a reminder to add captions. - **Download**: **File URL**, **Label** and **Description (optional)**. - **Divider**: a visual break. It has no settings. - **Button**: **Label** and **When clicked**, which is **Go to the next page** or a jump to a chapter or page you choose. A jump does not open a page that a checkpoint locks: the learner stays where they are, and **Complete these to continue:** with what is left appears under the button. A new button is labeled "Continue". **Go to the next page** moves the learner forward, like **Next**: to the page's next screen when there is one, otherwise to the next page. It never finishes the journey; on the last screen the learner selects **Finish**. While a checkpoint or scorecard holds the learner, it does nothing. A card with its own button gets no **Continue**. - **Simulation**: an embedded simulation. See Simulation blocks below. - **Simulation bank**: several simulations, of which each learner is given a few, chosen at random the first time they reach the bank and kept for that attempt. See Simulation banks below. - **Custom code**: your own HTML page, with its CSS and script written inline, shown on a screen of its own that it fills. **Title** is what screen readers say when the learner reaches it, and **HTML** holds the page, up to 100,000 characters. It runs in a sandboxed frame: its scripts run, but it cannot read the journey, the learner's session or their answers, and it cannot load scripts or call services on other sites. Images from a web address that starts with https still load. A learner moves on with **Continue** in a bar under it. On the canvas it is shown as a learner sees it, and an empty one reads "Add your code, or ask devlin to write it". A draft is saved with an empty title or no code, but the journey cannot be published until both are filled in. An AI tool can write the code for you. - **Coach**: an embedded coach. **Coach** lists the workspace's coaches with each one's status. A new block is **Not connected**. A coach is shown on a screen of its own and takes the size of the stage. A height stored on an older journey is ignored. - **Knowledge Check**: a scored set of questions. See Knowledge checks below. Image, video, file, captions and poster addresses must be a web address that starts with http or https, or a path on the same site that starts with a single slash. The panel shows "Enter a valid http(s) URL, or a root-relative path starting with a single /." for anything else. You paste an address; the editor has no file upload. A draft is saved while these fields are still empty, but the journey cannot be published until they are filled in: the address of an image, video or download block, the title of a video block, and the label of a download or button block. A new image, video or download block starts with these fields empty. An address that is filled in but not valid is different: the draft is not saved while an image, video, file, captions, poster, custom portrait or title page image address is invalid. Custom portrait addresses and the title page image show no message beside the field; the save indicator reads "Changes are not being saved" and lists what is wrong (see Saving below). ### Simulation blocks - **Simulation** lists the workspace's simulations with each one's status. A new block is **Not connected**. A draft can be saved with unconnected blocks, but it cannot be published until each one is connected. - **Beside the simulation** is **Character**, **Notes** or **Nothing**, and a new block starts as **Nothing** (a page layout may start it otherwise). With **Character**, a character stands beside the simulation as a cut-out, with no frame behind it, filling that side of the screen down to its bottom edge, and its mood changes as the conversation goes. The simulation's own character portrait, when it has one, is hidden, so the character is not shown twice. With **Notes**, a panel beside the simulation shows the **Notes** you write (formatted like a text block: the goal, a checklist, the facts of the case), which the learner can read and scroll during the conversation; the simulation keeps its own portrait. A draft is saved with empty notes, but the journey cannot be published until they are written. With **Nothing**, the simulation is centered and wider, and keeps its own portrait. Switching away from **Character** keeps the character you chose, so **Character** brings it back, but while it is not shown it is not shown anywhere, including the opening, and is not checked when you publish. Switching away from **Notes** removes the notes you wrote: choosing **Notes** again starts with an empty panel. - **Side** is **Left** or **Right**: where the character or the notes stand. Until you choose, it follows the theme's **Character side**. - **Choose a character** offers the 6 built-in characters. **Custom portrait URLs** switches to one address field for each mood (neutral, happy, sad, angry, afraid, surprised, disgusted), and **Use a library character** switches back. - **Your characters** lists the ready custom characters. With none ready, it says "No custom character is ready yet." **Create a character** opens the same dialog as the Brain's **Create character**, over the editor. A character finished there is picked for the block when you close the dialog. A workspace on a plan without custom characters sees **Your characters** faded, with **Not on this plan**, a message that starts "Custom characters are not included on this workspace's plan." and names the plans, and a **See plans** link. See "Use a character in a journey" in [Custom characters](https://docs.devlin.ai/knowledge/custom-characters). - **Default mood** is the portrait shown first. - **Mood variable override** is empty unless you fill it in. The character follows the simulation's own mood variable, whatever it is named in that simulation, so you do not need to set anything here. Fill it in only when the journey should read a different variable. A simulation block made before this field became optional stores the earlier default, `Char_Mood`. That value is treated as empty, and the field shows it as empty, so the character on an older journey follows the simulation's own mood variable too. See [Storyline variables a simulation or coach writes](https://docs.devlin.ai/publish-and-embed/storyline-variables) for the mood variable. - When the simulation's custom character is ready, the panel shows the note "This simulation uses a custom character. Choosing a library character or entering portrait addresses replaces it." When the character is not ready, it instead shows the warning "This simulation uses a custom character that is not ready. The journey cannot be published until it is, or until you pick another." On a plan that no longer includes custom characters, the note still appears so the character is not replaced unknowingly. You choose one under **Your characters**, and an AI tool can point a simulation at a custom character from this workspace too. Choosing a built-in character or typing a portrait address replaces it. Opening the address fields and going back without typing leaves the custom character in place. Until that custom character is ready, a learner sees no character beside the simulation, which is centered and wider as it is with **Nothing**, the canvas shows a silhouette in the character's place, and the journey cannot be published. This is checked when you select **Publish Changes**, not in the count beside the save indicator, and the refusal names the character: "The custom character "" is not ready. Finish its images in the Brain, or choose another character for the simulation." A custom character that is no longer in this workspace is refused with "A simulation uses a custom character that is not in this workspace. Choose another character for it." - A simulation is shown on a screen of its own and takes the size of the stage. A height stored on an older journey is ignored. - A simulation opens in the mode it is built for. One with voice turned on opens in voice, and the learner taps to start it. Any other opens as a text chat. The journey has no setting of its own for this: to have a journey open a simulation in voice, turn voice on in that simulation. The same holds for each simulation in a bank. See [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey) for what the learner sees. ### Simulation banks A simulation bank gives each learner a few simulations out of a larger set, so learners do not all practice the same one. - **Add a simulation** lists the workspace's simulations that are not yet placed in this journey, with the status of any that are not published, for example "(draft)". Choosing one adds it to the bank. In the bank's list, a row whose simulation is not published is marked **Draft** or **Archived**. A new bank starts with one row that is not connected, and your first choice fills it. A bank holds up to 20 simulations, and a bank must keep at least one. A draft can be saved while a row is not connected yet, but the journey cannot be published until every row in the bank holds a simulation. - Each row has buttons to move it up or down and to remove it. While the bank holds only one row, that row cannot be removed. - **Simulations each learner gets** is how many of the bank's simulations a learner is given. It cannot be more than the number of simulations in the bank, and lowering the bank below it lowers it to match. - **Pass mark** is the percentage the bank's score needs to count as passed. It must be a percentage, and a draft with anything else is not saved. The bank's score is the plain average of the simulations the learner was given. - A simulation can be in one place in a journey: one simulation block or one bank. The bank's **Add a simulation** list leaves out simulations already placed anywhere in the journey, and a simulation block's **Simulation** list shows simulations held by a bank as unavailable, marked "In a simulation bank". A second use that involves a bank is refused when the draft is saved. Two simulation blocks that use the same simulation still save, but the journey cannot be published. - **Beside the simulation** and **Side** work as on a simulation block, for every call. With **Character**, each simulation in the bank has its own **Character** picker, so choose one for every simulation in the bank. A simulation in the bank with no character chosen is shown without one: its screen is centered at full width, and the simulation keeps its own portrait. Publishing does not stop it. ### Knowledge checks - **Title (optional)** names the check. The name is used where you pick the check in checkpoints, paths and the scorecard. - **Pass threshold** is the percentage a learner needs to pass. - **Limit attempts** turns on **Number of attempts**. With it off, attempts are unlimited. - **Shuffle question order** presents the questions in a random order. - **Use a random subset of questions** turns on **Questions per attempt**, which cannot exceed the number of questions in the check. - Each question has a **Prompt**, **Allow multiple answers**, **Shuffle options**, and a list of options. Each option has its text, an optional feedback line, and a control that marks it correct. **Add option** and **Add question** add more, and questions can be moved up and down. - A check needs at least one question, and a question needs at least two options. A draft that breaks either rule is not saved. - To publish, every question needs a prompt, every option needs its text, and each question needs at least one correct option. A question that does not allow multiple answers needs exactly one correct option. A draft is saved before these are done. The panel shows a message under a question that still has the wrong number of correct options. ## Journey settings ### Checkpoints A checkpoint locks a chapter or a page until the learner meets every requirement you set. With no checkpoints the journey is fully unlocked. - **Add checkpoint** adds one. **Lock** chooses the chapter or page. - **Add requirement** adds a requirement. The types are **Simulation passed**, **Simulation completed**, **Knowledge check passed**, **Pages viewed**, **Simulation bank completed** and **Simulation bank passed**. These two are offered once the journey contains a simulation bank. - **Simulation bank completed** is met when the learner has finished every simulation they were given from the bank. **Simulation bank passed** is met when they have, and the bank's score reaches its **Pass mark**. A simulation inside a bank cannot be required on its own: the journey cannot be published until the requirement points at the bank instead. - Simulation and knowledge check requirements can refer only to blocks already placed in this journey, and a simulation block appears only once it is connected. A simulation is listed by the first page it sits on. - A **Pages viewed** requirement needs at least one page ticked, and a **Knowledge check passed** requirement needs a knowledge check chosen. Until then the draft is saved, but the journey cannot be published. - When you change which simulation a simulation block uses, the requirements, paths and scorecard components that pointed at it follow it to the new simulation, and one undo reverts both. Disconnecting the block leaves them with no simulation chosen; the draft is saved, but the journey cannot be published until you choose one or remove them. A requirement, path or scorecard component that points at a simulation or knowledge check that is no longer in the journey, for example after an AI tool replaced the content, is kept in the draft and blocks publishing until you choose another or remove it. - **Let learners jump to any page** lets a learner open any page from the menu. With it off, which is how a journey starts, the menu opens only pages the learner has already visited, the first page and the next page. Pages locked by a checkpoint stay locked either way. - **Move on when a simulation finishes**: after a simulation, or a call of a simulation bank, has been evaluated, the journey moves to the next screen by itself after a 10 second countdown, shown beside **Continue** as "Moving on in" and the seconds left. The learner can choose **Stay here** to stop it and read the simulation's feedback, then **Continue** when ready. The countdown waits while the menu or the coach is open. It never finishes the journey, never moves past a checkpoint's lock, and does not start again when a learner comes back to a simulation they finished. It is on for a new journey and off for a journey made before it existed. With it off, the learner chooses **Continue**. - **Restarts allowed** sets how many times a learner can choose **Restart journey**: **No limit**, which is how a journey starts, **None**, or a number up to 10. Each restart is a new attempt at every simulation in the journey, so a simulation's own attempt limit still applies. The best result of any run is the one the journey reports, also to an LMS. See [Publish and share a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey) for what the learner sees. - A checkpoint whose requirement sits inside the chapter or page it locks can never be met. The panel shows a warning that begins "This checkpoint can never be satisfied", and the journey cannot be published until you change it. ### Paths A path sends the learner to a chapter or page of your choice when a simulation or knowledge check is passed or failed. - **Add path** adds one. Choose the simulation or check, the condition (passes or fails) and the destination. - Order sets priority: the first matching path wins. **Move path up** and **Move path down** change the order. - A bank cannot start a path: a simulation inside a bank is refused with "a simulation inside a simulation bank cannot start a path. Choose another or remove the branch". - A path jump ignores checkpoint locks. - A path for a passed knowledge check applies as soon as the learner passes. A path for a failed knowledge check applies only once the learner has no attempts left, so the learner can still retry. With **Limit attempts** off, a path for a failed knowledge check never applies. ### Scorecard A scorecard combines simulation and knowledge check results into one weighted final score, shown to the learner on the completion page. - **Enable scorecard** turns it on. - **Add simulation**, **Add simulation bank** and **Add knowledge check** add components. **Add simulation** is unavailable until the journey contains a simulation block that is connected to a simulation, and **Add knowledge check** until it contains a knowledge check. **Add simulation bank** appears once the journey contains a simulation bank. - A bank is one line on the scorecard. Its score is the plain average of the simulations the learner was given. A simulation inside a bank cannot be scored on its own: it is refused with "this simulation is inside a simulation bank. Score the bank instead". - Each component has a weight greater than zero. The panel shows the share of the final score each one counts for. - **Label learners see** is the name shown for the component on the completion page. A new simulation or knowledge check component starts with the name the picker shows, and choosing a different simulation or check updates a label you have not changed. A bank component starts with no label, and learners see "Simulation bank" until you type one. - A component with no simulation or check chosen shows **Choose…**. The draft is saved, but the journey cannot be published until one is chosen. - **Pass threshold** sets the percentage needed to pass. - **Require every component complete before scoring** holds the score until the learner has finished every component. - A scorecard needs at least one component to be published. If you turn the scorecard on and add none, the draft is saved, and publishing is blocked until you add a component or turn the scorecard off. ### Theme - **Background**, **Surface**, **Text** and **Accent** set the journey's colors. Contrast badges beside the text and accent colors show whether they are readable against the background, and a further badge checks text on the surface color. The badges inform you; they do not stop you saving or publishing. - Each color is a hex code with three or six digits after the #, such as #1a2b3c or #abc. Color names and other color formats are not used: while a color is anything else the draft is still saved, learners see the default color in its place, and the journey cannot be published. - **Corner radius** rounds the corners of panels and buttons. - **Font** is **Outfit**, **System** or **Serif**. - **Scene**, **Scene dimming**, **Character side** and **Card style** are grouped under **Stage**. A journey that has not set them, including one made before they existed, has no scene and uses **Medium**, **Right** and **Glass**. - **Scene** is the picture behind every screen, unless a page has its own scene, which replaces it on that page. A video screen shows no scene. With no scene, the stage shows a gradient of the background and surface colors. A page's own scene that cannot be shown gives way to the journey's scene, and a journey scene that cannot be shown gives way to the gradient; the journey can still be published. The editor has no control for a page's own scene: an AI tool sets it and removes it. In a workspace that has custom characters, the **Scene** group generates the journey's scene: 1. In **Describe the place**, type one line of up to 300 characters, for example "a hospital corridor at night". Describe a place only: the image is drawn with no people, no text and no logos, in soft focus so that content stays readable over it. 2. Select **Generate scene**. The price is shown beside the button: "One image, 150 credits." A scene is not checked automatically like a custom character's image, so it is charged at the plain image rate. 3. While the image is made, the group reads "Waiting its turn." or "Generating the scene.", and says how many images are ahead of yours when there are any, for example "3 images are ahead of yours." When the image service is busy, it reads "The image service is busy. Retrying on its own." and tries again by itself. You can keep editing, and open other sections. Until the image arrives, the journey shows the gradient. 4. When the image is ready it is shown in the group, and it appears on the canvas at once, without a save, whichever section is open. **Regenerate** makes the same place again from the description it was made from, and **Regenerate with feedback** opens **What should change?**, where you type a change such as "brighter, with windows" that is added to that description; each is charged as another image, at the price shown on the button. **Replace scene** makes a new one from a new description, charged as another image; the gradient is shown until the new image arrives, and the earlier image is not deleted. **Remove scene** takes the journey's scene off at no cost. It does not remove a page's own scene. The description is checked before anything is generated. A description of a real person, a brand or graphic detail is refused with "This description cannot be used to generate a scene. Describe an ordinary place, with no real people, brands or graphic detail, and try again." and nothing is charged. An image that fails, or that the image service declines, is not charged. The scene is stored up to 2,560 pixels wide, in widescreen proportions. Once it is ready, anyone who has the image's address can load it without signing in, like a custom character's mood images. If image generation is turned off for the workspace, the group says "Image generation is turned off for this workspace, so a scene cannot be generated." and a scene the journey already has keeps showing. A workspace on a plan without custom characters sees the **Scene** group faded, with **Not on this plan**, a message that starts "Custom characters are not included on this workspace's plan." and names the plans that include them, and a **See plans** link. It cannot generate a scene there, and on the Core plan or higher can still remove one the journey already has. A scene on a published journey reaches learners when you publish the change, like any other edit. - **Scene dimming** is **Light**, **Medium** or **Strong**: how much the scene is dimmed behind the content, by a layer of the background color. The journey never dims a scene less than the text needs to stay readable, whichever you choose, and covers the scene completely when nothing less keeps the text readable. - **Character side** is **Right** or **Left**: the side a simulation's character or notes stand on when its block has no **Side** of its own, and the side of the coach dock's button and panel. A block's own **Side**, including the one a page layout sets, wins over it. It is mirrored for a language read from right to left. - **Card style** is **Glass**, which lets the scene show softly through the card, or **Solid**. - **Character framing** is **Automatic**, **Full body**, **Waist up** or **Headshot**: how close the stage shows a simulation's character. **Automatic**, the setting for a new journey, shows each character as it was made. A closer framing zooms in from the top of the image, so the head stays in view and the figure is cut lower down, on the bottom edge of the screen. A character made closer than the framing asks for is shown as it was made: a head-and-shoulders character is never shown full body. A built-in character, or one given by portrait addresses, is always shown as it is. It is layout, not part of the theme's look, so it can be changed on every plan and is kept below the Core plan or higher. An AI tool can set it too. - **Use the journey's colors in simulations** is on for every journey until you turn it off. While it is on, the simulations and coaches in the journey take its background, surface, text and accent colors while learners use them in the journey, so the journey and its simulations look like one piece. Their own appearance, and how they look at their own links or in a course, is not changed. Turn it off to show each simulation in its own colors. It is part of the theme, so it applies where learners see the journey's own theme, and a journey still in the default devlin.ai colors hands no colors over. When devlin builds a journey together with its simulations and coaches, it also gives those simulations and coaches the journey's colors in their own appearance, so their links outside the journey match it. - **Journey title in the menu** is **Shown** or **Hidden**: whether the menu shows the journey's title at its top. The learner's top bar always shows the current page's heading, or the page's name when the heading is hidden. It is layout, not part of the theme's look, so it can be changed on every plan and is kept below the Core plan or higher. - A journey's own theme is shown to learners on the Core plan or higher. A workspace that devlin.ai has granted journeys keeps its own theme on any plan. Below those plans and without that grant, the theme already set is kept, so it shows as soon as the workspace upgrades, but learners see the default theme and no scene. The **Theme** section is faded with a note that says so, and its controls are unavailable, so the theme, including the scene, cannot be changed, generated or removed in the editor until the workspace is on the Core plan or higher. The canvas and the preview show the default theme too, so you see what a learner will see. - A new journey starts with the devlin.ai dark theme: a near-black background, white text, a blue accent and the Outfit font. ### Title & completion - **Show a title page before Chapter 1** adds an opening page with a **Heading**, **Body**, **Image URL (optional)** and **Button label**. It is off for a new journey, and the button label starts as "Begin". The opening never shows the journey's characters; they appear on the simulation screens. - The completion page always exists. Set its **Heading** and **Body**, and use **Show the scorecard on this page** to show or hide the scorecard there. ### Ask learners who they are once The **Title & completion** section has **Learner identity** between the title page settings and the completion page settings. It asks each learner once, on a card shown after the opening, and every simulation in the journey then records the answers without asking again. A simulation's start screen hides the identity inputs the journey already asked for and still asks for any the journey did not, so a simulation that collects an identifier keeps asking for it when the journey asks only identity fields. - **Ask each learner for an identifier** turns on an identifier field. **What to ask for** is the label above it, and it starts as "Your name". - **Identity fields** lists the identity fields the workspace has defined, each marked "(required)" when required. Tick the ones to ask. With none defined, the section points to **Settings → Data & privacy**. - While learner identity is off for the workspace, the controls stay visible but unavailable, under a notice. See [Learner identity](https://docs.devlin.ai/workspace-and-team/learner-identity) for turning it on. - When the workspace collects learner identity per simulation, a simulation records the answers only when its own **Collect learner identity** switch is on. When the workspace collects it for every simulation, every simulation in the journey records them. When the journey asks for identity and some of its simulations would not record it, the section warns "This journey asks for learner identity, but" some of its simulations "will not record it", names them, and adds "Turn on Collect learner identity in each simulation's Publish stage." - An identity setting that is not valid stops the draft from being saved (the save indicator reads "Changes are not being saved"), with a message that names the field, for example that a field is not an identity field key or is listed twice. See [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey) for what the learner sees. ### Coach dock **Enable the coach dock** gives learners a coach they can open at any time to ask questions as they go. It is a round button at the bottom of the screen, on the side the theme's **Character side** sets, named by the **Label**. Selecting it opens the coach in a panel on that side of the screen, or over the whole screen when the screen is narrow, and **Close** or Escape closes it. The conversation is kept when the learner moves to another screen, and when the panel is closed and opened again, until the learner restarts the journey. Opening the menu closes the panel, and opening the panel closes the menu. The button is offered on every screen of a content page, not on the title page or the completion page. Choose the **Coach** and set the **Label**, which starts as "Ask a coach". A draft can be saved before a coach is chosen, but it cannot be published until one is. ## Name The journey name is set in the **Journey name** field when you create the journey, and changed in the name field in the editor's top bar. It is required and holds up to 120 characters. Spaces at the start and end are removed. If you clear the name in the editor and click away, the last saved name comes back. There is no default name: **Create journey** stays unavailable until you type one. ## Saving There is no save button. The editor saves the draft automatically a moment after you stop editing, and saves the name the same way. - "Saved" means the draft is stored. "Unsaved changes" and "Saving…" mean a save is pending or under way. - "Changes are not being saved" means the draft breaks a rule that stops it being stored. A count beside it opens the list of what is wrong, in the same plain wording as the publishing list. Nothing is saved while it shows, including your other edits. Undo the last change or fix what is listed, and the editor saves again. - If a save fails, a "Could not save changes" message appears and your edits stay on screen. Editing again retries the save. - Using the back arrow or the breadcrumb, or switching workspace, with unsaved changes asks whether to save or discard them. Closing or reloading the browser tab triggers the browser's own warning. A draft has these limits: - Up to 30 chapters, and at least one. - Up to 60 pages in a chapter, and at least one. - Up to 80 blocks on a page. - Up to 524,288 characters for the whole journey, counted across all of its stored content, not only the text learners read. ### Draft and published content A journey keeps two copies of its content: the draft you edit and the published copy learners see. Everything in the editor changes the draft only. Editing a published journey does not change what learners see until you select **Publish Changes**, which copies the draft to the published copy. Unpublishing leaves the draft untouched. ## Version history **Version history** in the top bar lists the journey's saved versions, newest first, each with a **Saved**, **Published** or **Restored** badge, when it was made, and the email address of the workspace member who made it. - A version holds the journey's name and its draft content. - A version is recorded when the journey is created, when the draft or name is saved, when the journey is published and when a version is restored. - Saves you make within 10 minutes of your previous save update that version instead of adding a new one. - devlin.ai keeps the most recent 30 versions of each journey. - **Restore** on an earlier version asks you to confirm, then sets the name and draft back to that version. Restoring changes the draft only: a published journey keeps showing learners its published copy until you publish again. The restore is recorded as a new version, so you can go back. - A restore is checked like any other save. A version whose content no longer meets the rules for saving a draft, for example one that holds an invalid address, is refused and the journey is left as it is. A version that is only unfinished restores normally. - If you have unsaved changes, the confirmation warns that they will be discarded. ## Folders A journey can belong to one of the workspace's folders, and a journey that does shows the folder name on its card while the folder filter is set to **All**, and is included when you filter the **Journeys** tab by that folder. By default a journey is in no folder. To file a journey, select **Move to folder…** in its card menu and choose a folder or **Unfiled**, or drag its card onto a folder in the folder filter. Folders are described in [Organizing Studio with folders](https://docs.devlin.ai/get-started/organize-studio-with-folders). ## The card menu On the **Journeys** tab, each journey's menu has these actions. - **Open** opens the editor. - **Preview** appears for a published journey and opens its draft preview in a new tab, the same view as **Preview** in the editor. It shows the draft, not the published copy. - **Move to folder…** files the journey in a folder, or under **Unfiled**. - **Delete** asks you to confirm, then permanently removes the journey and its published link. This cannot be undone. A published journey can be deleted without unpublishing it first. The card menu has no rename or duplicate action. Rename a journey in the editor's top bar. Journeys cannot be duplicated, and they cannot be selected for bulk actions. ## Working from an AI tool If your workspace has the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) turned on, a connected AI tool can work with the same journeys. devlin, the built-in assistant, uses the same capabilities. - `list_journeys` lets an AI tool list the workspace's journeys, most recently edited first, with each one's status, chapter count and simulation count. It returns up to 100 journeys. - `get_journey` lets an AI tool read one journey: a compact outline and, unless the journey is large, the complete draft content. When the draft is too large to return, the tool gets the outline only and cannot replace the content. Over MCP the result also carries links to the editor and the preview. - `create_journey` lets an AI tool create a new draft journey from a name and, optionally, one of the four blueprints. It never publishes. - `update_journey_content` lets an AI tool replace a draft journey's whole content, rename it, file it in a folder, or any of these together. The content is checked against the same rules as the editor, and nothing is saved if it fails. As in the editor, an unfinished draft is saved and what is unfinished blocks publishing. Over MCP, content and name changes work on draft journeys only: a published journey is refused until it is unpublished. When devlin is asked to change a published journey, it proposes the change for you to apply. The content it writes can put simulations in a bank and turn on learner identity, under the same rules as the editor. A theme it writes is always saved. When learners in this workspace would not see it, because the workspace is not on the Core plan or higher and has no journeys grant, the result says that the theme was saved but learners see the default theme, so devlin or the AI tool tells you. - `generate_journey_scene` makes a journey's scene from a one-line description of a place and puts it on the draft's theme, or on one page when a page is named. It spends 150 credits for the image, and asks first when that is over the plan's approval limit for one call. It needs a workspace that has custom characters, with image generation on. Over MCP it works on draft journeys only, and in a workspace that requires approval for changes made by AI tools it starts nothing and reports the price instead. - `regenerate_journey_scene` makes the scene a journey (or one page) shows now again, from the description it was made from, with the user's feedback added when there is some, or from a new description. It costs the same as `generate_journey_scene`, asks first in the same cases, and has the same limits. It is the same path as **Regenerate** and **Regenerate with feedback** in the **Theme** section. In ask devlin the result shows the scene card, which only shows the image (see "The scene card" in [Building and managing content with devlin](https://docs.devlin.ai/ask-devlin/build-and-manage-with-devlin)). An AI tool can file a journey in one of the workspace's folders, or unfile it. A folder move on its own is applied at once, on a published journey too, because it changes nothing learners see. ## Related - [Publishing and sharing a journey](https://docs.devlin.ai/journeys/publish-and-share-a-journey) - [Creating a simulation](https://docs.devlin.ai/simulations/create-a-simulation) - [Building and publishing a coach](https://docs.devlin.ai/coaches/build-a-coach) - [Organizing Studio with folders](https://docs.devlin.ai/get-started/organize-studio-with-folders) - [Storyline variables a simulation or coach writes](https://docs.devlin.ai/publish-and-embed/storyline-variables) - [MCP server and AI tool connectors](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors)