Source: https://docs.pageloop.ai/guides/where-inbox-items-come-from

# Where Inbox items come from

# Where Inbox items come from

A **docs run** is one execution of Pageloop’s documentation agent to research a task and produce drafts. The **Inbox** brings together the proposed changes and questions that need your review. A run is the work the agent does; an Inbox item is where your team reviews the result or supplies a missing decision.

A run can propose changes to several pages, update an existing proposal, or finish without changing anything. Starting a run does not publish documentation.

## What starts a docs run

You can request work directly or let an automation start it:

| Starting point      | What starts the work                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Merged pull request | A configured merged-pull-request trigger starts a run to check the product change against your docs. Connecting a repository alone is not the same as configuring the trigger. |
| Schedule            | A scheduled check starts a run at the configured interval. The schedule controls when research and drafting happen, not when docs are published.                               |
| Workflow            | A saved automation combines a trigger with plain-language steps. Each execution is a run; the workflow is the reusable instruction, not the draft.                             |
| Home composer       | You describe the documentation you want and provide relevant context, such as notes or a recording.                                                                            |
| Ask                 | You ask Pageloop to carry out documentation work. A question that only needs an answer does not necessarily need a docs run.                                                   |
| Slack               | You request documentation work through the connected Pageloop app. A direct request is different from the agent periodically checking tracked channels for suggestions.        |
| MCP                 | An authorized MCP client requests documentation work through Pageloop’s tools. Connecting the client does not replace connecting the sources the task needs.                   |

> [!NOTE]
>
> Admins and Editors can use **Ask** and **Workflows**. Contributors review the Inbox items assigned to them. An Admin manages source connections in **Integrations**.

## What the agent does during a run

The agent uses the request or workflow steps to decide what to investigate. Within the connected sources available to the run, the agent:

1. Reads the source material and checks what the change means for your readers. A merged code change, completed issue, or support conversation is evidence to evaluate, not an instruction to copy into an article.
2. Searches the existing knowledge base for the pages that own the topic. The agent checks related pages and open proposals so the work can update existing documentation instead of duplicating it.
3. Drafts supported changes, such as edits to existing pages or a distinct article when the topic needs one. When product code or a connected app is available, the agent can use it to verify behavior and screenshots.
4. Checks the proposed result and explains the changes with their supporting sources. Drafts go to the Inbox for human review; a run can also add work to an existing item rather than create another item.

If the evidence does not justify an edit, the agent can leave the documentation unchanged and explain why. A successful run is not a promise that every source record will produce a draft.

## Understand run states

Run labels describe the agent’s progress, not whether your documentation is published. Depending on the view and type of run, you can see:

| State shown                                                  | Meaning                                                                                         |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| **Queued**                                                   | The run is waiting to start.                                                                    |
| **Working** or **Drafting**                                  | The agent is researching or preparing proposed changes. A workflow’s Runs tab uses **Running**. |
| **Saving**                                                   | The agent is saving the result. The product does not let you stop the run at this stage.        |
| **Updating branches**                                        | The agent is reconciling a branch that changed while the run was working.                       |
| **Needs your answer**, **Needs answers**, or **Needs input** | The agent has paused for a decision that affects an edit.                                       |
| **Completed**                                                | The proposed changes are ready for review. This does not mean they are accepted or published.   |
| **Nothing to change** or **No changes needed**               | The run finished without a documentation change to review.                                      |
| **Failed**                                                   | The run could not finish. Read the reason and use the recovery action offered for that run.     |
| **Stopped**                                                  | A person stopped the run.                                                                       |

A workflow’s **Runs** tab also uses **Succeeded**, **Needs review**, and **Skipped**. Read the run’s explanation and follow **Open in Inbox** when a proposal is available. Do not interpret **Succeeded** as publication, or **Skipped** as a draft that someone rejected.

### Why the agent asks questions

The agent pauses when the available evidence and a safe default cannot settle a specific edit. For example, a source may not establish whether a feature has shipped or which customer roles can use it. Asking avoids turning an uncertain fact into published instructions.

The question explains which edit your answer decides. Answer the question round and submit the answers to continue the run. Selecting an option without submitting the round does not start the continuation. Your answers inform the draft; they do not accept or publish the resulting changes.

## Proactive suggestions

Proactive suggestions start with signals in your connected tools rather than a request you write for each task. Signals can reveal that an existing page is inaccurate or that readers need a topic your knowledge base does not cover.

| Source                 | What can indicate a documentation need                                                                                                                                                    |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Merged pull requests   | A product change affects customer-visible behavior, labels, prerequisites, or steps.                                                                                                      |
| Linear and Jira issues | Completed or resolved work describes a change that affects readers. The configured scope and workflow steps determine which issues are checked.                                           |
| Slack channels         | Repeated questions, corrections, or confirmed explanations in tracked channels reveal missing or misleading instructions.                                                                 |
| Support tickets        | A resolution explains behavior or steps that customers could not find in the docs. A ticket about a single account or an unresolved bug is not automatically a general documentation gap. |

### From signal to reviewable work

Pageloop reads the configured source material, groups related information by topic, and searches the knowledge base for existing coverage. The agent evaluates whether the topic needs an update or a separate article and records the reason and supporting sources.

A source record does not have a one-to-one relationship with an Inbox item. Several records can support one topic. Related evidence can enrich an existing suggestion instead of creating a duplicate, and a signal that is already documented or does not affect readers can produce no change.

Configured proactive checks start docs runs automatically. When the agent finds a documentation gap, the run drafts supported changes and places the proposal in the Inbox, or pauses there with questions that need your input. You do not need to accept a suggestion before drafting starts. Review the source evidence and the resulting draft before deciding what to keep.

### What you control

- **Source access and scope.** An Admin chooses which tools to connect and configures product repositories, Linear teams and optional projects, Jira projects, and tracked Slack channels. Connect only the sources you want Pageloop to use.
- **Recurring work.** Use a workflow’s trigger, schedule, and plain-language steps to define when a run starts and what it should check. These instructions can describe which changes matter to your docs and which to leave out.
- **Writing context.** Supply your product description and writing guidance so drafts fit your readers and terminology.
- **Uncertain decisions.** Answer the agent’s questions with the intended edit or explain what should remain unchanged.
- **Review and publication.** Inspect, edit, accept, or dismiss proposed changes. Your team decides what to publish; automatic research and drafting do not publish the result.

> [!NOTE]
>
> Proactive sources must be enabled for your workspace as well as connected and configured. Connecting a service does not guarantee an immediate suggestion. If a configured source produces no suggestions, check the connection and scope, then ask Pageloop to confirm that the source is enabled.

## Connect the foundations first

First give Pageloop a knowledge base to read and a destination for reviewed documentation: set up Pageloop Docs or connect your existing help center. Then connect the sources you want the agent to investigate. You do not need every source to start.

| Topic           | Required connection or configuration                                                                                                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Knowledge base  | Set up your docs site or connect the help center that owns your articles.                                                                                                                                                         |
| Product code    | Connect the product repository and select the repositories Pageloop should read. A repository containing only your docs is not a substitute **_for_** product code. Configure the merge trigger if you want merges to start runs. |
| Linear          | [Connect Linear](/guides/linear-integration), including the team and any project selection.                                                                                                                                       |
| Jira            | [Connect Jira](/guides/jira-integration), including the tracked projects.                                                                                                                                                         |
| Slack           | [Connect Slack](/guides/slack-integration), including the channels to track and where notifications should go.                                                                                                                    |
| Support tickets | Connect your support service and select the service that supplies the **Ticketing** role under **Integration roles**. The ticketing source and the knowledge base have different jobs, even when the same service provides both.  |
| MCP             | Authorize your MCP client to use Pageloop, then connect the knowledge base and source tools needed by the requested work.                                                                                                         |

sdfsdFor the location of **Home**, **Ask**, **Inbox**, **Workflows**, and **Integrations**, see [The Pageloop sidebar](/guides/pageloop-sidebar).
