# Building and managing content with devlin

> How devlin turns a request into a change, builds drafts in the background, works with attached sources, and what it will not do.

- Plans: Core, Team, Enterprise
- Canonical: https://docs.devlin.ai/ask-devlin/build-and-manage-with-devlin

devlin builds and changes simulations, coaches, evaluators and journeys when a designer asks for it in conversation. This page explains how a request becomes a change, which changes wait for approval, how background builds run and what they cost, how attached sources are kept, and what devlin leaves to the designer. It applies to workspaces on the Core, Team, Enterprise plans, and to workspaces with an active event offer claim. See [Trying ask devlin with an event offer](https://docs.devlin.ai/ask-devlin/event-offers).

Where devlin lives, its settings, the autonomy choices and the monthly build cap are on [devlin (the assistant) and getting around the app](https://docs.devlin.ai/ask-devlin/devlin-assistant-and-app-navigation).

## How a request becomes a change
devlin works through a fixed list of actions. The same list serves AI tools connected through the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors), and each action says whether it is offered to devlin, to MCP tools, or to both. An action that changes content, settings or hosting never writes directly. It first prepares the change: it checks the request, reads the current state, and works out a before and after for each field. A policy then decides whether the prepared change is applied at once or shown as a proposal for the designer to approve. Both routes end in the same apply step, so a change devlin applies and a change the designer approves are written the same way.

Every action has a risk class, and the class decides what happens next.

| Risk class | What it covers | What devlin does |
|---|---|---|
| Read | Looking something up: the account overview, a simulation's settings, results, product documentation | Runs it and answers. Nothing in the content changes. |
| Draft | New drafts and changes no learner can see yet, such as creating a simulation or filing documents into a knowledge base | Applies it at once and reports what changed. Two exceptions: with review-all, a change to something that already exists, such as renaming a folder or a knowledge base, becomes a proposal, and deleting a folder always becomes a proposal. |
| Live | Changes to content, publish state, workspace settings or hosting that a learner could see | Depends on the item's status and the autonomy setting. See below. |
| Destructive | Deleting a simulation or coach, removing a document from a knowledge base, deleting a knowledge base or a hosted project, removing a custom domain, deleting a custom character, combining two skills | Always proposes. |
| Redirect | Account and security changes | Explains and opens the page. Never performs it. |

A few actions on sources are immediate and never become a proposal: saving a source to the library, changing where a source lives, and starting or retrying the summary of a long source. These are described under Attaching files and links, below. A summary uses credits. devlin starts one without asking when its estimate is within the plan's approval limit for one call (200 credits on Free, 1,500 on Starter, 7,500 on Core, and 75,000 on Team and Enterprise), and then says what it cost. On Free or Starter, an active event offer claim's approval limit applies when it is higher than the plan's; on paid plans the plan's limit applies (see [Trying ask devlin with an event offer](https://docs.devlin.ai/ask-devlin/event-offers)). Above the limit, when the cost is not known yet, or with **Review all** chosen, it names the price and waits for a yes.

### What devlin applies on its own
With the default edit setting:

- Creating a new draft simulation, coach, evaluator or journey applies at once. This is true under every edit setting.
- An edit to a draft applies at once.
- An edit to a published or archived item becomes a proposal.
- Publishing, unpublishing, archiving and deleting always become a proposal, under every edit setting.
- Creating, changing or deleting a results link always becomes a proposal, under every edit setting, auto-apply included. After you apply a new or changed link, the card shows its address with a **Copy link** button. The address is shown only then: later, find it on the Results links page or ask devlin to list your results links. If the link shows learner names you are not allowed to see, the card says "Ask an owner or admin for this link." instead. See [Results links for trainers and managers](https://docs.devlin.ai/results-and-analytics/results-links).
- Moving a simulation, coach or journey to another folder applies at once, even when it is published, because no learner sees it.

The other two edit settings shift the middle of that list. With review-all, every edit to existing content becomes a proposal, drafts included. With auto-apply, edits to published simulations and coaches apply at once, while edits to published evaluators and journeys, workspace settings, simulation languages and hosted project settings still become proposals. Evaluators have no version history, so a change to a published one always waits for the designer. The settings themselves are described on [devlin (the assistant) and getting around the app](https://docs.devlin.ai/ask-devlin/devlin-assistant-and-app-navigation).

When devlin applies an edit to a simulation, coach or journey, the conversation shows a card that lists each changed field with its old and new value and an **Undo** link. A long or structured value is folded behind **View change**. An **Appearance** change is the exception: the card lists each visible change in plain words, such as "Background: #f7f3ec", with a swatch beside each color. After a few lines the rest are counted as "and N more changes", and **Show details** shows the full before and after values.

### Proposals and approval
A proposal is a card in the conversation. Its heading names the action and the item, the same field list shows what would change, and two buttons follow: one named for the action (**Update**, **Publish**, **Unpublish**, **Archive**, **Create** or **Permanently delete**) and **Cancel**. Nothing changes until the action button is selected. A proposal that cannot be reversed carries the line **This cannot be undone.**

- A proposal belongs to the designer who asked for it. Only that designer can apply or cancel it, and only from the workspace it was made in.
- A proposal stays open for 7 days. After that the card says it expired, and devlin can propose the change again.
- When devlin proposes two or more changes in one reply, an apply-all button applies the group in one click. Permanent deletes, workspace settings, results link changes and custom domain setup are left out of the group and listed beneath it, each needing its own approval.
- Once applied, the card reads **Applied.** A cancelled card reads **Cancelled.**
- Publishing a journey is the exception: once applied, the card says "Your journey is live. Share this link with learners." and shows the journey's full learner link with **Copy link** and **Open**. If the journey has been unpublished since, the card says "This journey is not published right now." devlin points to the card rather than writing the link out.

### What approval checks
Approving a proposal does not write blindly. At that moment:

- If the item was edited after the proposal was made, the change is refused with **This changed since it was proposed. Re-check before applying.** The proposal stays open so it can be tried again or replaced. A permanent delete skips this check and acts on the item as it is now.
- If the proposal is for a journey or an evaluator and the workspace no longer has that feature, it is refused.
- If the change includes a field the designer's permissions no longer allow, the whole change is refused and the message names the field. Nothing is written, and the proposal stays open.
- Two approvals of the same proposal at the same moment apply it once.

### Changes to published content
An edit to a published simulation or coach is checked by the same content moderation as publishing, whether it was approved from a proposal or applied under auto-apply. If the edit fails that check it is rejected and the published content stays as it was. No edit to a journey's content runs that check, which is why auto-apply never covers journeys. A journey's own theme is shown to learners on the Core plan or higher. If devlin saves a theme that learners in your workspace will not see, it tells you the theme was saved and learners see the default theme.

If a draft is published between the moment devlin prepares an edit and the moment it applies it, the edit is refused instead of being written to learners.

## Undo
There are two ways to undo a change devlin made.

### The Undo link on an applied edit
The card for an applied edit to a simulation, coach or journey restores the version from just before that edit.

- If the item is a draft and nothing has changed since devlin's edit, the restore happens in one click and the card reads **Undone.**
- Otherwise the card first says how many later changes the restore would discard and offers **Restore anyway** and **Keep changes**.
- On a published item, **Restore anyway** writes the restored version for learners at once, under every edit setting. It does not become a proposal, unlike asking devlin to undo in a message.
- Fields the designer's permissions do not allow are left out of the restore. If that leaves nothing to restore, or the restore is refused for another reason, the card reads **Could not undo.** followed by the reason.
- The link works as long as that earlier version is still in the item's history, which keeps the most recent 30 versions.

### Asking devlin to undo
Saying "undo that" restores the version before the latest one, for a simulation, a coach or a journey. This is the `undo_last_edit` action, and it is something devlin does: it is not offered over MCP, where an AI tool restores a version instead (see [Version history, undo and restoring a version](https://docs.devlin.ai/simulations/version-history)).

- It goes back one step. To go further back, restore a specific version from the item's history.
- It needs at least one earlier version. A newly created item with a single version has nothing to undo to.
- On a draft the undo applies at once. On a published or archived item it becomes a proposal, and for simulations and coaches the restored content passes the moderation check when applied. With auto-apply on, an undo on a published simulation or coach applies at once, and an undo on a published journey still becomes a proposal. With review-all on, every undo becomes a proposal.
- Undoing a journey needs the Journeys feature in the workspace.
- Fields the designer's permissions do not allow are left out of the restore. If that leaves nothing to restore, the undo is refused.

An undo is saved as its own version, so it can itself be undone.

### What undo does not cover

- Evaluators, knowledge bases, folders, hosted projects, custom domains and workspace settings. Undo works on simulations, coaches and journeys only.
- A permanent delete.
- A source that was saved to the library or filed into a knowledge base.

## Building by conversation
devlin creates content in two ways.

Direct creation: devlin can create a draft simulation, coach or evaluator itself and fill in its fields, and can create a draft journey from a starting structure. The draft appears at once and learners cannot see it until it is published. Evaluators need the Evaluators feature and journeys need the Journeys feature in the workspace.

Background builds: for new simulations and coaches designed from a goal, devlin proposes a build. A build is authored in the background, so the conversation stays free while it runs.

### devlin suggests a format
You do not need the platform's names for things. Before it proposes a build, devlin can suggest the format that fits the skill best, described by what the learner experiences, then build the one you pick:

- **A plain simulation:** the learner chats or talks with an AI character. Quickest to build, and fits a short skill check.
- **An immersive scene:** the learner talks to a character shown on a stage, in front of a backdrop of the place, inside a short journey. Fits when realism and emotion carry the skill, such as a difficult conversation or an upset customer.
- **A journey:** several screens and simulations in order, with a setup and a debrief.
- **A coach:** guidance beside the learner while they work or practice.

Plain requests work too: "make it feel real", "with a person" or "a scene" mean the immersive scene, and "a series" or "step by step" mean a journey. devlin suggests only what the workspace has: a character and a backdrop when it has custom characters, and a journey when it has Journeys.

How much devlin questions your approach is your choice, under **How much should devlin challenge your approach?** in the assistant settings (see [devlin (the assistant) and getting around the app](https://docs.devlin.ai/ask-devlin/devlin-assistant-and-app-navigation)):

- **Build what I ask:** devlin builds the format you ask for and does not suggest another.
- **Suggest better fits** (the default): when another format would land better, devlin says so in a line or two with the reason and asks which you want, once per request.
- **Push back like a performance consultant:** devlin first asks about the problem on the job and whether practice is the fix, one question at a time, then recommends a format with its reasons before it proposes anything. It never refuses to build: once the problem is clear, or you say go, it proposes.

### Starting a build
1. Describe the problem or what learners should be able to do. When devlin can name the learners' role, the situation on the job and the behavior to practice, it proposes straight away, with no question first, and states what it assumed, such as the audience, seat time and difficulty, so you can correct it. A business signal it inferred rather than heard is labeled **Assumed**. A bare topic gets a question or two first, opening on the business problem (what is going wrong, or what number should move) and asking only what changes the design, one question at a time. devlin settles a title, a goal and at least one measurable learning objective for each item before it proposes anything.
2. devlin chooses text or voice from how the skill is used on the job (phone, video or in person: voice; chat, email or tickets: text) and says why in one line. It asks only when the channel is unclear. If what you describe sounds like a problem practice will not fix, such as a missing tool or a broken process, devlin says so in one sentence and still builds if you want it.
3. devlin shows a build card listing each simulation or coach, and a journey line if a journey was asked for. Each item shows its title, then its type, its mode with the reason (simulations only) and its seat time, then the goal, and its whole **Why this works** note: the result it should move, the behavior behind it, why practice helps and how you will know. A voice simulation also shows about how many credits each learner voice session uses, for a session that runs to its length cap. When the plan has more detail than the card shows, a **View full plan** button opens the whole plan in a window, with a short note beside it naming what the plan holds, such as "Audience, objectives and scenario details". The window shows each item's **Why this works** note, audience, objectives, success measures and scenario notes, and the journey's structural notes, with **Build now** at the bottom.
   When the plan has a journey, it can put the plan's simulations in one simulation bank, so each learner gets a few of them chosen at random. The journey line then reads "Simulation bank: each learner gets N of the simulations, chosen at random", with the number the plan chose in place of N. A bank needs at least two simulations in the plan and holds at most 20, and the number each learner gets cannot exceed the number of simulations. The plan can also ask each learner who they are, once; the line then reads "Asks each learner who they are, once". When you say how the journey should check knowledge, the journey line says so: "No knowledge checks", "One knowledge check at the end" or "Knowledge checks throughout". Say "no quiz", "no assessment" or "no knowledge check" and the finished journey has none: any knowledge check is removed after the journey is assembled, along with any requirement, branching path or scorecard item that pointed to it, and any page left with nothing to do. Your other structural requests, such as gating or the order of the pages, take priority over the journey's usual structure. The finished journey has exactly one bank holding every planned simulation, with each simulation's character on its bank item. With identity asked, the journey asks for an identifier and every identity field the workspace has defined, which you can untick in the editor. Identity has no effect until learner identity is on for the workspace.
4. The card states how many credits the plan reserves. When the plan makes a new character, it shows one total and says how much is reserved when you select **Build now** and how much more is reserved when you approve each new character's portrait. See "Characters and a scene in the same plan" below. Select **Build now** to start, or **Cancel**.

Rules for a build proposal:

- One proposal holds up to 6 simulations and coaches. devlin offers the rest as a follow-up batch.
- A voice simulation needs a voice chosen first. A coach in a build is always text.
- A journey can be added to a build, or assembled on its own from simulations and coaches that already exist. It needs the Journeys feature.
- A build can be grounded in knowledge bases on the Core, Team, Enterprise plans, and in sources attached in the conversation.
- A source that is still being read or summarized blocks the proposal until it is ready.
- devlin cannot start a build. Only the **Build now** click does.

When you later ask devlin to review a simulation, it reads what the simulation is for from what is stored with it: the skills its criteria are tagged with and the business goals linked to those skills. It judges the simulation against that purpose as well as its setup, and names the evaluation level when it reports results: practice scores are Learning evidence, never proof that a business number moved.

### Goals and skills in a build
devlin designs toward the workspace's business goals and skills. It sees the active goals, which ones are due for review, and the workspace's skills in every conversation. See [Skills and business goals](https://docs.devlin.ai/results-and-analytics/skills-and-goals).

- When an existing goal fits the request, the plan designs toward it and its skills. devlin reuses existing skills and sub-skills before proposing new ones, and proposes a new goal when you name a metric that no goal holds yet. The new goal's Results measure is that metric.
- The plan carries one business goal (`business_goal`) and a list of skills (`skills`) for every build in it. The build card shows **Goal:** with the goal's name, and the skills as chips, each marked "(new)" when it does not exist yet.
- Nothing is created when devlin proposes. The new goal and new skills are created when you select **Build now**, the plan's skills are linked to the goal, and the builds tag their simulations' criteria with those skills. **Cancel** creates nothing. A plan refused because the balance or the monthly build cap is short creates nothing. If **Build now** fails after the goal and skills were made, for example because the builds could not be queued, selecting it again reuses them instead of making them twice.
- Criteria are tagged on simulations only. A coach has no criteria.
- In an organization whose owners and admins have limited who can edit **Goals & skills**, devlin does not propose a plan for a member that would create a goal or a skill, or link a skill to a goal. It is refused with "An admin has limited who can edit Goals & skills in this workspace." A plan that only names existing goals and skills that are already linked stays open. **Build now** checks again before anything is created. Creating, editing, archiving or combining skills, creating or editing goals, and recording a goal's number are refused for that member in the same way. Tagging criteria with existing skills stays open. See [Who can edit the Brain](https://docs.devlin.ai/workspace-and-team/members-and-roles#who-can-edit-the-brain).
- devlin can also tag the criteria of simulations and evaluators that already exist, one criterion at a time. With the default edit setting, the change to a published simulation or evaluator is a proposal you apply. With auto-apply it applies at once on a published simulation, and still becomes a proposal on a published evaluator.
- Combining two skills is always a proposal you apply. With the default edit setting, creating, editing and archiving skills, importing a list of skills from a document, creating and editing goals, and recording a goal's number apply at once. The **Undo** link does not cover them: change them back in Brain, or ask devlin to.

### Goal check-ins
When a goal's review is due, devlin raises it once per conversation, at a natural moment and never in the middle of an unrelated urgent request. It shows the goal's Learning evidence, asks for the latest Behavior or Results number, and records the number only after you confirm it. It then marks the review done, which moves the goal to its next scheduled review, and recommends what to do from the evidence: make the practice harder, split it, retire it, or look outside practice. Check-ins happen only in devlin and in the app; no email is sent.

### While a build runs
Each item gets its own progress card with a bar and a stage line: **Waiting to start**, **Gathering what the draft needs**, **Drafting**, **Reviewing against best practices**, **Saving the draft**. Simulations in a batch start first, coaches in the same batch wait for those simulations, and a journey waits for every build in its batch (**Waiting for the builds to finish**).

- A finished build reads **Draft ready** with a **Review draft** link that opens the simulation or coach on its Test stage, so you can try what devlin built, or **Open journey** for a journey. Everything a build makes is a draft.
- Build cards are private to the designer who started them.
- A build that has started cannot be cancelled from the conversation.
- If the conversation is closed, the build keeps running and its card shows the current state when the conversation is reopened.

### If a build fails
A failed attempt is retried automatically and the card reads **Retrying shortly**. After 3 attempts the build stops and the card says so. A stopped build is still charged for the work its attempts did; the unused part of its reservation is returned. Ask devlin to try again, or simplify the goal.

- A journey whose builds partly failed is still assembled from the ones that finished. Its card names what is missing.
- A build that ran before an attached source finished reading says so on its card. It names the source when there is one, and gives the count when there are several.

### What a build costs
Selecting **Build now** reserves 1,650 credits for each simulation, coach or journey in the proposal. The reservation is all or nothing: if the balance or the monthly build cap cannot cover every item, nothing starts, the card says why, and the proposal stays open. When each build ends, the workspace is charged for what its model calls used and the rest of the reservation is returned. A build can never spend more than its reservation. Builds count toward the [monthly build cap](https://docs.devlin.ai/ask-devlin/devlin-assistant-and-app-navigation).

### Characters and a scene in the same plan
When a plan includes a journey, it can also give each simulation a character on the journey's stage and give the journey a scene, the picture behind its screens. devlin offers them only when the workspace has custom characters, and includes them only when you want them. If you ask for one in a workspace that does not have the feature, devlin passes on the reason.

- **A character** is one of the workspace's ready custom characters, or a new one devlin describes with a name and an appearance, and optionally an age and clothing. A new character is shown head and shoulders. Without an age it is shown as an adult. A character goes only on a simulation, and only when the plan has a journey: a plan does not put a character on a simulation on its own. To give a standalone simulation a character, attach a ready one after the build. See "Use a character as a portrait" in [Custom characters](https://docs.devlin.ai/knowledge/custom-characters).
- **A scene** is one image of the place you describe in one line of up to 300 characters.

What the images cost:

- A new character is 8 images: a reference portrait and one image for each of the 7 moods. Each is charged 165 credits, because it is checked automatically, so a new character whose images all pass the check the first time costs 1,320 credits. Each image sets aside 330 credits in case it has to be made again, 2,640 credits for a new character in all.
- A scene is charged 150 credits, and sets aside the same.
- A character the workspace already has costs nothing to use.

The plan card shows one total for the builds and every image. A line under it, starting "Includes", says how many images the plan makes, the credits they set aside, and what they are, and that each character's moods are made after you approve its portrait. Each simulation that has a character names it.

When you select **Build now**:

1. Nothing starts unless the balance covers the whole total, the moods included. Otherwise the card says how many credits the plan needs and nothing is reserved.
2. The builds are reserved as usual, and each new character's reference portrait (330 credits) and the scene (150 credits) are set aside and start generating.
3. A character card appears in the chat for each new character. Check the face and select **Approve reference** on the card. Nothing can approve a portrait for you. devlin is then told and starts that character's moods, which set aside 2,310 credits at that point. It asks first when that is over the plan's approval limit for one call, as it does for any character.
4. When every build in the plan is finished, coaches included, the journey is built with each simulation's character and the scene already in place. It does not wait for the images: a character or the scene appears in the journey as soon as it is ready. Until a new character is ready, the journey cannot be published.

Things to know:

- Each description is screened when you select **Build now**, not when devlin proposes the plan, and before anything is generated. If one is refused, the whole plan is refused and nothing is reserved.
- If the plan asks for a new character or a scene and image generation is turned off for the workspace, the plan is refused with the reason. An owner or admin can turn it on in **Settings → Data & privacy**, or ask devlin to propose the plan again without them.
- If an organization has limited who can edit **Characters**, a plan that makes a new character is refused for a member with "An admin has limited who can edit Characters in this workspace." A plan that uses existing characters, or only a scene, stays open.
- An existing character must be ready when the plan is applied.
- A character or scene that fails to generate does not stop the builds. A failed image is not charged.

### The scene card
A journey's scene shows in the conversation on its own card: under the journey's build card once the journey is built, and after devlin generates or makes a scene again. While the image is being made the card shows that it is coming. The build never waits for it. The card shows the image and the description it was made from, and **Open in Theme** opens the journey editor on its theme, at the scene. It has no buttons of its own.

devlin mentions the scene and asks whether it fits. To change it, say what should change, such as "brighter, with windows": devlin makes the scene again from the description it was made from with your change added, for 150 credits, and a new card shows the new image. You can also make it again in the journey editor's **Theme** section (see [Build a journey](https://docs.devlin.ai/journeys/build-a-journey)). The new image replaces the old one on the journey's draft. On a published journey, learners see it after **Publish Changes**.

### Brand colors and contrast
Give devlin your brand colors, two or more in any order, and say which one is the background, the text or the accent only if you have a preference. devlin.ai places them so they read: text on the background and on the character's bubbles at 4.5:1, and the accent (the learner's messages, buttons and highlights) on the background at 3:1. It keeps the roles you stated when they read, adds white or near-black text only when none of your colors reads there, and devlin tells you in one line what went where. The same placement applies when devlin applies a saved color scheme to a simulation, a coach or a journey: a scheme that reads is applied as saved.

Text that sits on the accent color uses the text color only when it is readable there, and otherwise a readable one. devlin warns you only when no arrangement of your colors reaches the minimum, or when you ask to keep an arrangement that does not. It then applies the colors anyway, says so in one line and offers the nearest color that passes. Nothing changes without your yes.

### The start screen of a built simulation
Every simulation devlin builds gets its own start screen: a heading that names the character and the moment, a few facts the learner would have before the conversation, and a button that starts it. The simulation's criteria are listed on that screen before the learner begins. In a journey this screen is the briefing before the conversation, so devlin does not put a briefing card in front of the simulation that says the same thing. You can change or turn off the start screen in the simulation's editor, like any other.

## What a conversation costs
Every reply from devlin uses credits from the workspace balance.

- Before devlin answers, an estimate is reserved. If the balance cannot cover it, devlin says the workspace is out of credits and nothing is charged. If the monthly build cap cannot cover it, devlin says so and nothing is charged.
- After the reply, the charge is set to what the model read and wrote in that reply, at the rate for devlin's model, and the rest of the reservation is returned. A reply never costs more than its reservation.
- Stopping a reply partway charges for the part already produced.
- A longer conversation costs more per reply, because the recent conversation is read again each time.
- Some replies start without you typing. When you approve a character's reference on its card, or images devlin started finish, the app adds a short grey note to the conversation and devlin carries on (for example, it starts the moods after an approval). The conversation shows one full card for each character. When a character comes up again, its earlier mentions read "<name>: see the latest card below." and the latest card shows the current state. When you ask for a finished character to be used on a simulation or coach, devlin puts it there. Each of these replies uses credits like any other. At most 4 happen in a row before you write again, and a note from the app is never taken as agreement to a price.

See [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage) for balances and top-ups.

## Attaching files and links
Files and links can be attached to a message from the composer. The plans, file types, size tiers and reading statuses are on [Source materials](https://docs.devlin.ai/knowledge/source-materials); this section covers what is specific to the conversation.

- A message carries up to 5 sources.
- In a workspace that has custom characters, a PNG, JPEG or WebP image attached to a message is not a source. devlin can use it as a custom character's reference portrait. See [Custom characters](https://docs.devlin.ai/knowledge/custom-characters).
- In a workspace that has recordings, an audio or video file attached to a message becomes a recording source. It uploads on its own, and its chip shows the upload's progress with the recording's length and what transcribing costs. Removing the chip while it uploads stops the upload, and no credits are used. See [Recordings: building from a meeting](https://docs.devlin.ai/knowledge/recordings).
- A source attached in the conversation starts as **This build only**: devlin and the builds it starts can read it, and it is deleted 7 days after it was last used. Each search or read by devlin counts as a use.
- A message can be sent while a source is still being read. It is held and sent when the source is ready, or at once with **Send now**.
- Text inside a source is treated as reference material, never as instructions to devlin.

Three actions change where an attached source is kept. All three are things devlin does in the conversation, and none of them is offered over MCP. An AI tool connected over MCP chooses where a source is kept at the moment it adds the source.

- `save_source_to_library` moves a build-only source into the workspace library so that simulations and coaches can use it while learners practice, and can file it into a knowledge base in the same step. It applies at once.
- `set_source_retention` switches a source between **Library** and **This build only**. Switching to build-only works only for a source attached in the current conversation, added by the same designer through a chat or a creation form, that is in no knowledge base and that no simulation, coach or evaluator uses. Otherwise devlin reports why the source stays in the library.
- `add_documents_to_kb` files documents that are already in the workspace into a knowledge base, either an existing one or a new one that it creates and names in the same step. A build-only source filed this way also moves into the library. It applies at once under every edit setting, and the documents become searchable when their processing finishes.

All three need the Core, Team, Enterprise plans and count against the library and knowledge base limits described on [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases). devlin saves or files a source when the designer asks for it, or agrees after devlin has asked once whether a source needed during practice should be kept. In an organization whose owners and admins have limited who can edit **Knowledge**, these actions are refused for a member with "An admin has limited who can edit Knowledge in this workspace." So are creating, renaming or deleting a knowledge base, removing a document from one, and starting or retrying the summary of a library source. Build-only sources stay open to every member. See [Who can edit the Brain](https://docs.devlin.ai/workspace-and-team/members-and-roles#who-can-edit-the-brain).

Removing a document from a knowledge base and deleting a knowledge base are destructive, so devlin always proposes them.

## Answering product questions
`search_product_knowledge` lets devlin search devlin.ai's product documentation for passages that match a question. The search covers the documentation pages on this site except the generated reference pages, and it includes pages for features that are not generally available yet. devlin answers in its own words, and can link the published documentation page a passage came from. It never cites a passage from a page that is not published, or any passage that comes without a link. If the search is unavailable, devlin answers from what it already knows about the product.

This action is also available to AI tools over [MCP](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors), where it returns matches from published documentation pages only. Each match also comes with the title and link of the documentation page it came from, so the tool can point to the page. A match without a link is never cited. Pages for features that are not generally available yet are left out.

## Managing the account
`get_account_overview` gives devlin a snapshot of the active workspace: its name, its plan, its credit balance, and how many simulations and coaches it holds. devlin uses it to answer questions about the account. The action under this name is devlin's. AI tools over [MCP](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) read the same figures through `get_workspace_overview`, which also reports the caller's role, the token's scopes and whether live changes need approval.

`explain_account_action` is how devlin handles a request it will not carry out. Account and security changes stay with the designer. When asked for one, devlin explains where it is done and shows a card that opens the page. It is not offered over MCP, where AI tools have no account actions at all.

| Request | Where devlin sends the designer |
|---|---|
| Billing, receipts, credit usage, buying a credit top-up | **Settings → Credits & Billing** |
| Changing plan | **Settings → Plans** |
| Setting up SAML single sign-on | **Settings → Plans**, with a note to contact devlin.ai support |
| Inviting or removing members, changing a member's role | In an organization, the organization's **Members** section in Settings. In a personal workspace, which has no other members, **Settings → Workspaces**, where an organization is created |
| Two-factor authentication | **Settings → Account** |
| Creating or revoking access tokens, turning MCP access on or off | **Settings → Integrations → MCP access** for the active workspace: the personal workspace's **Integrations** page, or the organization's **Integrations** section |
| Choosing who can edit each Brain area (Goals & skills, Audiences, Knowledge, Characters, Brand) | In an organization, the organization's **Permissions** section in Settings, under **Who can edit the Brain**. In a personal workspace, devlin explains that nothing limits the owner's editing, and shows no card |
| Deleting the account | **Settings → Account** |

devlin does not merge learner records either. Asked to merge, undo a merge or list recent merges, it explains the steps and opens **Results → Learners**, where an owner or admin does it. See [learner history and AI summaries](https://docs.devlin.ai/results-and-analytics/learner-history).

When a change is refused because an owner or admin limited that Brain area, devlin says so and explains who can change the setting.

An organization's **Members**, **Integrations** and **Permissions** sections open only for its owner and admins. For a member with neither role, devlin says that an owner or admin handles the request and shows no card. Only the owner changes a member's role.

## Limits and what happens when one is reached
- Steps in one reply: A reply can chain many lookups and changes, up to a fixed number of steps. Past that, devlin stops with **I wasn't able to finish that within my step limit for one turn. Try narrowing the request or asking again.**
- Credits reserved for one reply: If the work would run past the credits reserved for the reply, devlin pauses and asks for "continue". The work already done is kept.
- Time for one reply: A reply that runs to its time limit pauses the same way. If the model goes silent partway through a step, devlin stops with **That step took too long, so I stopped early** and asks to try again.
- A reply cut short: If an answer runs out of room, devlin says so and continues when asked.
- A declined request: If the model declines a request, devlin says **I can't help with that request as written.**
- Long conversations: devlin reads only the most recent part of a long conversation. Earlier messages stay visible in the conversation but are no longer in devlin's view. Within the part devlin still reads, past lookups, edits and proposals are carried as short notes. A long conversation shows a suggestion to start a fresh one with **New chat**. Saved workspace facts carry over.
- Connection or server errors: If devlin fails partway through a reply, a banner says **Something went wrong on devlin's side mid-answer.** If the request cannot reach devlin, for example because the connection dropped, the banner starts **Couldn't reach devlin** and asks you to check your connection. Both banners have a **Retry** button, and the message is kept.
- Messages sent too quickly: Sending many messages in a short time shows a banner that starts **You're sending messages faster than devlin can take them**. Wait a minute, then select **Retry**. The message is kept.
- A build that cannot start: The build card shows the reason when one is given, such as the build cap or the balance, or **Could not start the build. Please try again.**
- A trial that ended: In a workspace whose event offer claim has ended, the message box is replaced by the date the trial ended. A message that is still sent is refused with **Your trial has ended.** and a link to choose a plan, and nothing is held or charged. Past conversations stay readable.

## Related
- [devlin (the assistant) and getting around the app](https://docs.devlin.ai/ask-devlin/devlin-assistant-and-app-navigation)
- [Version history, undo and restoring a version](https://docs.devlin.ai/simulations/version-history)
- [Source materials](https://docs.devlin.ai/knowledge/source-materials)
- [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases)
- [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage)
- [MCP server and AI tool connectors](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors)