# Promptless | Documentation ## Website *** title: Automatically update your docs url: https://promptless.ai/ description: Eliminate docs drift and automate the most painful parts of docs maintenance. ---
{/* */}
## See why Vitess and Helm chose Promptless Promptless drafts PRs and suggests changes — then the docs maintainers at these CNCF projects review, revise, and ship them. Check the commit history yourself.
*** title: Book a 15-minute demo url: https://promptless.ai/demo description: Book a demo and see Promptless in action. --- ### See why Vitess and Helm chose Promptless Promptless drafts PRs and suggests changes — then the docs maintainers at these CNCF projects review, revise, and ship them. Check the commit history yourself. ### Book a 15-minute demo Talk to one of our engineers to see how Promptless can automate your docs workflow. 14-day free trial included! *** title: Pricing url: https://promptless.ai/pricing description: Plans for teams that want docs-native automation. --- *** title: Free tools url: https://promptless.ai/free-tools description: Free tools to help you quickly improve docs quality. ---

Use these free tools to quickly catch issues in your docs.

*** title: Broken Link Report url: https://promptless.ai/free-tools/broken-link-report description: Scan your site and get a broken-link report by email. --- Paste your site URL and email, and we will send you a report with any broken links we find. This is useful before a launch, after content changes, or as a quick regular check. ## Docs *** title: Promptless overview url: https://promptless.ai/docs/start-here/welcome description: Learn what Promptless does, how it works, and where to start. --- import { Aside, Card, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; import VideoEmbed from '@components/site/VideoEmbed.astro'; Promptless is an AI agent built to support technical writers by detecting when docs need to change, gathering context from code and team tools, drafting updates, and opening reviewable suggestions or pull requests. Use Promptless to keep product docs, internal docs, agent instructions, screenshots, changelogs, and support-driven documentation current as your team ships.
Watch a short walkthrough of Promptless turning a product change into a documentation pull request. The demo shows Promptless finding the relevant docs, using code and project context, drafting an update with citations, and handing the change back to a technical writer for review. ## What you can do
Detect when pull requests, commits, or releases change behavior that customers need to understand. Draft new pages, guides, API references, changelog entries, and release notes from the context your team already has. Turn repeated customer questions, support tickets, Slack threads, and project tickets into documentation updates. Ask Promptless to capture new product screenshots or regenerate stale images when your UI changes. Check the sources Promptless used, request edits, and teach Promptless your preferred structure and style. Open documentation pull requests for docs-as-code platforms like Mintlify, Fern, ReadMe, Docusaurus, and more.
## How Promptless works Promptless fits into the tools your team already uses. A typical documentation update follows this flow: ![Diagram of a documentation update flowing from a trigger through context gathering, drafting, review, and publishing](/mermaid/how-it-works.svg)
  1. A trigger starts the workflow. A pull request, commit, Slack message, Teams message, Intercom ticket, or API event tells Promptless to investigate whether docs need to change.
  2. Promptless gathers context. Promptless reads the relevant code, existing docs, tickets, conversations, and configured context sources.
  3. Promptless drafts a suggestion. Promptless decides which pages are affected, writes the proposed update, and explains the sources behind the change.
  4. Your team reviews the update. Review the suggestion in Promptless, comment in GitHub, or ask for follow-up edits in Slack or Microsoft Teams.
  5. Promptless publishes through your docs workflow. When the update is ready, Promptless opens or updates a documentation pull request for your normal review and merge process.
## Common starting points ## Next steps
Want to see Promptless in action? Book a demo.
*** title: How Promptless works url: https://promptless.ai/docs/start-here/how-promptless-works description: How Promptless turns triggers, context sources, and doc collections into reviewed documentation updates. --- import { Aside } from '@astrojs/starlight/components'; Promptless keeps your documentation current by connecting three pieces: **triggers** that signal when something changed, **context sources** that help Promptless understand the change, and **doc collections** that define where your documentation lives and where updates are published. This page explains how those pieces fit together.
Keeping documentation current is hard work. Context gets lost in handoffs, updates fall behind releases, and support teams keep answering the same questions because the docs trail the product. Promptless supports that work rather than replacing it: it drafts content in the voice of your existing docs, keeps screenshots in sync as your UI changes, and shows the citations and reasoning behind every suggestion so you can review and approve it quickly. ## Overview The diagram below shows how triggers, context sources, and doc collections connect to turn a change into a reviewed documentation update: ![Diagram of how triggers, context sources, and doc collections connect in Promptless](/mermaid/8f92644e90b30069.svg) ## How the components work together
1

Triggers Initiate the Process

Triggers are the starting point for all documentation updates. They monitor various sources for events that might require documentation changes:

  • Code Changes: Pull requests in GitHub, Bitbucket, or GitLab automatically trigger analysis when new features or fixes are introduced
  • Team Communication: Slack messages and Microsoft Teams mentions can trigger documentation updates

Learn more in Configuring Promptless → Triggers.

2

Context Sources Enrich Promptless's Understanding

Context sources are read-only integrations that give Promptless real-time access to the business context behind a change:

  • Project management: Linear issues and Jira tickets explain the requirements and rationale behind a feature
  • Knowledge bases: Confluence and Notion pages carry specs, decisions, and existing product context

Context sources are optional, but they help Promptless draft suggestions that reflect why a change was made, not just what changed. Learn more in Configuring Promptless → Context Sources.

3

Doc Collections Receive the Update

Doc collections define where your documentation lives and where Promptless publishes updates:

  • Docs as code: Your docs live in a Git repository and sync to a hosting provider like Fern, Mintlify, Docusaurus, and more
  • Multiple collections: A single change can update more than one doc collection at once, so related docs stay in sync

Learn more in Configuring Promptless → GitHub Repos (Docs as Code).

## How teams use Promptless Promptless removes the manual overhead of keeping docs current while preserving the quality and accuracy your team needs. Teams use it to turn customer conversations into documentation updates, help technical writers keep pace with feature releases, and maintain documentation for fast-moving open-source projects. - **Vellum** (YC W23) has Slack Connect channels with key customers. They use Promptless to automatically turn customer support conversations into documentation updates. Today, over 50% of Vellum's docs PRs originate from Promptless, and 60% of their product and engineering team interacts with Promptless monthly to draft updates for features they own. - **Amplitude** uses Promptless to help their tech writers keep up with documentation demands. Their technical writers were drowning in work, so they integrated Promptless to draft documentation for every feature release. Now engineers review the first draft of docs before sending them to customers, making the entire process faster and more collaborative. - **Basis**, an AI agents platform for accounting ([ofbasis.com](https://ofbasis.com/)), uses Promptless for their entire knowledge base. Promptless processes all their meeting recordings and automatically updates customer pages, internal guides for their fast-growing team, and customer-facing documentation all at once. - **Fortune 500 companies** use Promptless to make technical writers more productive. Context is spread across Linear, Confluence, and Slack—Promptless automatically assembles the relevant information and drafts doc updates for every PR. - **Vitess**, a CNCF graduated project, proves Promptless works in the open-source world. Since installing Promptless, 94% of their documentation updates have been drafted with Promptless—the tool has become essential to keeping their docs current as the project evolves. ## Core capabilities Beyond the trigger-to-publish flow, Promptless includes capabilities that keep suggestions accurate and easy to trust: - **Voice Match:** Fine-tunes a custom model based on your existing documentation style, so AI-generated content sounds natural and matches your established tone. - **Promptless Capture:** Keeps product screenshots automatically in sync with your UI. When code changes impact a screenshot, Promptless detects which images need updating and regenerates them with your current interface. - **Screenshot Editor:** Edit screenshots directly in the dashboard—crop, annotate, highlight UI elements, or add shapes and text. Changes are immediately available in your docs. - **Slack Listen:** Passively monitors Slack channels you choose and automatically creates documentation suggestions when conversations become inactive. Perfect for Slack Connect customer channels or internal discussion threads. - **Promptless Citations:** See exactly where each documentation change came from. Every update includes references to the specific GitHub files, Slack threads, or support conversations that informed it. ## Next steps - **[Quickstart](/docs/start-here/quickstart)** — connect your repositories, docs, communication tools, and context sources. - **[Reviewing & editing Promptless PRs](/docs/work-the-queue/reviewing-prs)** — see what happens when a suggestion lands and how to approve, edit, or dismiss it. - **[Open-source quickstart](/docs/start-here/open-source-quickstart)** — set Promptless up on a public repository through the free open-source program. *** title: Quickstart url: https://promptless.ai/docs/start-here/quickstart --- import { Aside } from '@astrojs/starlight/components'; import HowItWorks from '@components/site/HowItWorks.astro'; Promptless automatically updates your docs, saving your team time and improving your customer experience. ## Before you start Sign up for a free account at [accounts.gopromptless.ai](https://accounts.gopromptless.ai) ### What permissions are needed? Connecting integrations may require admin-level access depending on your organization's settings: - **Slack**: Workspace admin permissions to install the Promptless app - **GitHub**: Organization admin or sufficient repository access to install the GitHub App - **Jira/Confluence**: Atlassian admin permissions to authorize the OAuth connection - **Linear**: Workspace admin permissions to connect the integration Don't have the required permissions? No problem—you can invite teammates during setup. ## Guided setup wizard When you first sign in, a five-step wizard guides you through connecting your integrations: After completing the wizard, Promptless generates a `promptless.yaml` configuration from the integrations you connected. You can review and edit it anytime on the [Configuration page](/docs/reference/configuration-reference). Your progress saves automatically—if you leave and come back later, you'll pick up where you left off. Setup doesn't need to be completed by a single person: any teammate you invite can continue from the current step, making it easy to hand off to someone with the right permissions for a specific integration. ## What gets connected The setup wizard connects your integrations. You configure them afterward in the app. **Chat** - Slack or Microsoft Teams for notifications and @mentions. **Documentation Platform** - The GitHub repository where your docs live. Supports docs-as-code platforms like ReadMe, Mintlify, Fern, Docusaurus, Starlight, and more. **Triggers** - Git providers (GitHub, GitLab, Bitbucket) as sources for pull request triggers. **Context Sources** - Atlassian (Jira/Confluence), Notion, Linear, or Slite to give Promptless additional context for better suggestions. ## What happens at completion When you finish the setup wizard, Promptless does two things: 1. **Indexes your documentation.** Promptless ingests your docs repository and learns its structure and content. This takes 5–30 minutes depending on size. 2. **Configures triggers and context sources.** Promptless generates `promptless.yaml` entries from the integrations you connected. Code-change integrations like GitHub, GitLab, or Bitbucket get a broad pull request trigger with `repos: all`, so Promptless listens for pull requests across all your repositories. Promptless doesn't seed commit triggers automatically—you can add one anytime from the [Configuration page](https://app.gopromptless.ai/configuration). Context integrations like Jira, Confluence, Linear, Notion, and Google Drive get unscoped entries, giving the agent access to all connected data. Once setup is complete, Promptless: - Listens for trigger events from your configured sources - Analyzes changes and gathers relevant context - Generates documentation suggestions for your review Your configuration is stored in a `promptless.yaml` file that you can view and edit anytime in the [Configuration page](https://app.gopromptless.ai/configuration). See the [Configuration Reference](/docs/reference/configuration-reference) for the complete schema and how to narrow triggers to specific repositories. Need help with integrations? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai) - we add new integrations every week. *** title: Run a pilot url: https://promptless.ai/docs/start-here/run-a-pilot --- import { Aside, Card, CardGrid, Steps } from '@astrojs/starlight/components'; Promptless offers 14-day pilot periods for growth and enterprise customers, so you can see how Promptless works with your own documentation, team workflows, and trigger events. The 14-day pilot lets you: - See Promptless handle different types of documentation updates - Evaluate suggestion quality across different scenarios - See how well Promptless can integrate into your team's workflow ## Before your pilot begins Before the pilot begins, you'll need to connect Promptless to your relevant workspaces and share resources with the Promptless team so that the Promptless agent can draft an initial batch of suggestions. ### Set up Promptless connectors 1. **Connect source code repositories.** Connect GitHub, GitHub Enterprise, GitLab, or Bitbucket 2. **Connect documentation repositories.** Connect your docs repository on GitHub, GitLab, or Bitbucket (e.g. if you use Mintlify, Fern, ReadMe, Docusaurus, etc.) 3. **Connect communication platforms.** Connect Slack or Microsoft Teams to get notified about new suggestions and to tag Promptless in threads or messages to request doc updates directly 4. **Connect project management tools (optional).** Connect Jira or Linear—this is optional, but recommended to give Promptless better context about the customer-facing impact of new features See the [Quickstart](/docs/start-here/quickstart) for integration instructions. ### Set up Slack Connect When you connect Slack during setup, we'll create a shared Slack Connect channel and send you an invitation. Accept the invitation to get a direct line to our team for questions, feedback, and support throughout your pilot. ### Share your documentation context Promptless works best when it has the same sort of information that you'd give to a new technical writer joining your team. This can include: - Your style guide - Vale configuration (if you use it) - Documentation standards or templates ## In-person onboarding workshop We always recommend kicking off customer pilots with an in-person workshop. ### What to expect 90-minute session. For larger teams, we may do multiple workshops over a few days. Before your session, we run Promptless on historical events (like the last 30 days of PRs) so you can review real suggestions during the workshop. How Promptless works, your configuration, and hands-on review of suggestions—with the goal of publishing your first doc updates together. ### Workshop goals 1. **Understand your Promptless setup.** Review your configuration and how [triggers, context sources, and documentation platforms](/docs/start-here/how-promptless-works) work for your team 2. **Publish your first updates.** Review suggestions together and publish documentation updates during the session 3. **Define success criteria.** Agree on what a successful pilot with Promptless would look like for your team ## Measure success for your pilot During the workshop, we define the success criteria for your pilot. These vary based on each team's needs, but across dozens of onboardings, *suggestion volume* and *suggestion quality* are the most reliable indicators that your team gets lasting value from Promptless. ### Suggestion volume Track how many suggestions you're getting from Promptless. More suggestions isn't necessarily better—sometimes too many suggestions can feel noisy or overwhelming—but a healthy stream of documentation suggestions is a strong indicator that Promptless is plugged into the right parts of your workflow. ### Suggestion quality Since everyone has different expectations for Promptless, suggestion quality is simply measured by your rating of Promptless's suggestions, on a scale from 0 to 10. **Quality target:** Promptless should consistently rate at least 8/10 for your team's needs. #### Understand quality ratings To help you calibrate what different quality levels mean for your team: * **"9-10":** Most suggestions from Promptless are relevant, and typically can be accepted with little to no edits. * **"7-8":** Most suggestions are accurate and relevant, requiring only moderate editing. You're refining style, adding specific details, or adjusting tone rather than rewriting entire sections. Promptless meaningfully reduces your documentation workload. * **"4-6":** Suggestions occasionally catch relevant changes and can serve as a starting point, but require significant editing. You're rewriting content, fixing inaccuracies, or filling in missing context. Promptless saves some time, but doesn't dramatically change your workflow. * **"0-3":** Promptless is creating negative value. Most/all suggestions are not good enough to be a useful starting point for doc updates. Even if it's occasionally bringing up things that are relevant, I'd rather start from scratch myself. ## Documentation improvement projects Sometimes teams need foundational work before piloting—like documenting major missing features, completing a large refactor, or creating documentation from scratch. Subject to availability, the Promptless team may be able to help with these projects before your pilot begins. ## Weekly check-ins After your onboarding workshop, we schedule 15-30 minute check-ins to track progress and address issues. **What we review:** - How many suggestions did Promptless create? - How would you rate suggestion quality this week (0-10)? - What's the gap between current suggestions and 10/10 quality? - How is Promptless fitting into your workflows? Is it triggering at the right times? These check-ins help us identify and fix issues, adjust your configuration, and make sure you're getting value from Promptless. ## Questions? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai) to discuss your pilot. *** title: Promptless ❤️ Open Source url: https://promptless.ai/docs/start-here/open-source-quickstart --- import { Aside } from '@astrojs/starlight/components'; Promptless helps open source projects keep documentation in sync with fast-moving codebases. Use it to automatically update developer docs, generate changelogs for new releases, or draft translations. Open source workflows sometimes differ from commercial software. We've built features and setup guides tailored specifically for open source maintainers. ## Quick start The basic setup for your open source project involves three steps:
1

Install the GitHub App

Connect GitHub from the Integrations page. You'll choose which repositories Promptless can access.

Which GitHub app should you install?

  • Standard GitHub app: If you can install apps with write permissions, Promptless creates branches and PRs directly on your repo. Works with both public and private repositories.
  • GitHub (read-only) app: For public repositories only. If you can only install read-only apps, Promptless creates PRs from a fork. Private repositories are not supported with this integration—use the standard GitHub app instead. See the GitHub integration docs for details.
2

Set Up Doc Collections

Doc Collections tell Promptless where your documentation lives.

You can create multiple doc collections if needed, for example, if your changelog is in a different location from your main docs. You can also specify a particular directory if your docs live in a monorepo alongside your code.

See GitHub Repos (Docs as Code) for setup instructions.

3

Configure Triggers

Configure triggers in the Configuration page to connect your source repos and doc collections.

In the triggers section of your promptless.yaml, specify which repos Promptless listens to for PRs.

Many open source projects prefer to centralize operations in GitHub so anyone can benefit from Promptless without needing an account. If this applies to you, enable Auto-create PR so suggestions automatically become pull requests. We recommend turning this on after your initial calibration is complete, so that you're able to refine Promptless's configuration before rolling it out to all contributors.

## Recommended trigger configuration Most projects trigger Promptless on opened PRs. For popular open source projects—where many contributor PRs get closed without merging—consider using [GitHub Commit triggers](/docs/connect/triggers/github-commits) instead. This way, Promptless only runs when PRs are actually merged to your default branch. We recommend changing this setting after your initial calibration. ## Additional use cases
Translation workflows For translation workflows, you might want the trigger to be the English directory of your docs. Promptless then drafts updates that translate content to the rest of your documentation.
GitHub Issues integration If GitHub Issues are part of your workflow, create a GitHub Issues trigger so contributors can tag Promptless in issues to generate doc updates.
Updating Contributor PRs (coming soon) For some monorepo use cases, you might want Promptless to add a docs commit to your contributors' existing PRs rather than create separate docs PRs. If you're interested in this feature, contact us at help@gopromptless.ai. Note: this is not compatible with the read-only version of the Promptless Github app.
*** title: Overview url: https://promptless.ai/docs/connect/triggers --- import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; Triggers are events that initiate automated documentation updates in Promptless. When a trigger event occurs, Promptless analyzes the context and determines if documentation updates are needed. ## Available trigger types ## How triggers work When a trigger event occurs: 1. **Event Detection**: Promptless receives notification of the event (PR opened, message posted, etc.) 2. **Context Analysis**: The system analyzes the event content, including code changes, conversations, or support interactions 3. **Relevance Assessment**: Promptless determines if the event requires documentation updates 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions based on the trigger content and connected context sources ## Configure triggers Triggers are configured in your organization's [Configuration page](https://app.gopromptless.ai/configuration) using the `triggers` section of your `promptless.yaml` file. For each trigger, you can: - Specify which repositories or channels to monitor - Configure trigger-specific settings (e.g., directory filters, branch targeting) - Set up publishing behavior through policy rules See the [Configuration Reference](/docs/reference/configuration-reference) for the complete YAML schema. ## Automatic PR creation When automatic PR creation is enabled in your [publishing policies](/docs/reference/configuration-reference#policies), Promptless automatically creates pull requests in your documentation repository with suggested changes. For [commit triggers](/docs/connect/triggers/github-commits), you can optionally enable auto-merge to automatically merge documentation PRs as soon as they're created. Automatic PR creation is available for all Git-hosted documentation platforms. ## Trigger events in documentation PRs When Promptless creates a pull request for documentation updates, it automatically includes a list of the trigger events that led to those changes in the PR description. This provides valuable context for reviewers and creates clear traceability between documentation updates and their originating events. ## Backfill suggestions Backfill suggestions lets you run Promptless on pull requests that already exist, so you can catch up on documentation for work that merged before a trigger was watching. It's available on saved pull request and merge request triggers: GitHub PRs, GitLab merge requests, and Bitbucket PRs. Open the **Backfill suggestions** panel on a trigger row, choose a window of the **last 14 days**, **last 30 days**, or **last 90 days**, and select **Preview**. The preview lists the pull requests that were opened or merged in that window and that the trigger matches, applying your repository, directory, and branch filters. Backfill covers up to 1,000 pull requests per repository in the window. Backfill matches pull requests that were opened or merged but it doesn't replay historical approvals. A trigger that fires only on first approval returns no backfill results because approval matching applies only to live events going forward. When the preview looks right, select **Launch backfill** to run it. Promptless processes each pull request live, exactly as it does for a new event: your publishing policy applies, so backfilled pull requests can create documentation PRs and send notifications. The panel updates with progress as the run works through the list. *** title: GitHub PRs url: https://promptless.ai/docs/connect/triggers/github-prs --- import { Aside } from '@astrojs/starlight/components'; Promptless monitors your GitHub repositories for pull requests. You can choose when documentation updates trigger: when a PR is opened or when it receives its first approval. ## Trigger modes GitHub PR triggers support two modes: ### Opened (default) Triggers when a pull request is opened. This works well for teams that want documentation suggestions ready alongside code changes, giving reviewers time to evaluate both. ### First approval Triggers when a pull request receives its first approval from a reviewer. Use this mode when you want documentation updates to start only after code has been reviewed, so Promptless analyzes final changes rather than work in progress. ## How it works When a pull request event occurs in your monitored repositories (either opened or first approval, depending on your configuration): 1. **Automatic Detection**: Promptless receives notification of the new PR 2. **Analysis**: The system processes the full PR context to understand the changes 3. **Relevance Assessment**: Promptless determines if the changes require documentation updates 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions ### What Promptless reads Promptless analyzes the full pull request context, not just the description: - **PR title and description**: The summary provided when opening the PR - **Code changes**: The actual diff showing what files changed and how - **Review comments and conversations**: Feedback from reviewers, including line comments and general discussion - **Commit messages**: All commits in the PR, including those added after the initial submission This means Promptless understands the *why* behind changes, even when reviewers request modifications that aren't reflected in the PR description. When a reviewer asks for changes and the author addresses them with new commits, Promptless picks up the feedback explaining what needed to change and the commits that address it. ## Configuration Configure GitHub PR triggers in your [Configuration page](https://app.gopromptless.ai/configuration) using the `triggers` section: ```yaml triggers: my-pr-trigger: trigger_type: github_pr match: - repos: - acme/backend - acme/frontend trigger_on: - opened # When PR opens (default) - first_approval # After first approval - merge # When PR merges trigger_directories: - src/ ``` See the [Configuration Reference](/docs/reference/configuration-reference#triggers) for all available options. ## Replay recent PRs When setting up a new GitHub PR trigger, you can enable "Replay recent PRs" to process pull requests from the last 30 days. This generates an initial batch of suggestions, which helps you: - Calibrate Promptless with your documentation style before going live - Catch up on documentation that may have been missed - Evaluate how Promptless handles your typical PR content After enabling this option, your Project card shows the replay progress: - **Processing last 30 days of PRs** with a spinner while replay is running - **Processed recent PRs** with a checkmark once replay completes ## Directory-specific triggers You can configure Promptless to only trigger when changes are made to specific directories within your repositories. This is particularly useful when you want to focus documentation updates on changes to certain parts of your codebase. To set up directory-specific triggers: 1. When creating or editing a project, select the GitHub trigger option 2. Check the "Choose specific directories to trigger this project" option 3. Enter the directory paths you want to monitor, separating multiple paths with commas 4. Save your project configuration Directory-specific GitHub trigger configuration When trigger directories are specified, Promptless considers only PRs that contain changes to those directories and ignores updates to other files. ## Repository topics If you have many repositories, you can use GitHub topics to control which ones trigger Promptless. This is especially helpful for organizations with dozens or hundreds of repos where only some need documentation automation. 1. **Tag your repositories in GitHub**: Add topics to the repositories you want Promptless to monitor (e.g., "docs-watch", "promptless"). To add topics to a repository, go to the repository's main page and click "Add topics" in the About section. 2. **Configure your project**: When creating or editing a GitHub project, check the "Trigger on repos with certain topics" option and enter the topic(s) you want to monitor. You can specify multiple topics, and Promptless triggers on any repository that has at least one of those topics. 3. **Manage through GitHub**: To add a new repository to Promptless, tag it with the configured topic in GitHub. To remove a repository, remove the topic from the repository settings. ## Automatic PR creation When automatic PR creation is enabled in your [publishing policies](/docs/reference/configuration-reference#policies), Promptless automatically creates a new PR in your documentation repository with suggested changes. ## Source PR comments Promptless posts a summary comment on source PRs linking to any documentation changes. This keeps documentation updates visible alongside the code changes that triggered them. The comment links directly to the documentation suggestions, so reviewers can see proposed updates while reviewing the code. ### Suppress source PR comments Set `suppress_source_pr_comments: true` in your [publishing policies](/docs/reference/configuration-reference#policies) to prevent comments on source PRs. Documentation suggestions are still created normally. ```yaml policies: default: publishing: suppress_source_pr_comments: true ``` This option is commonly used: - During pilot or onboarding periods, before Promptless has been introduced to the broader engineering team - On public repositories, while keeping comments enabled for private repos ## Draft pull requests ## Configuration files and dot-directories Promptless automatically skips pull requests that only contain changes to dot-directories (like `.github/`, `.circleci/`, `.beads/`) or root-level dot-files (like `.gitignore`, `.editorconfig`). These are typically CI and tooling configuration rather than product changes that need documentation updates. If a PR contains both dot-files and regular source files, Promptless processes it normally—it only skips when the entire PR is dot-file changes. ## Request documentation via PR title or description An `@promptless` mention in a PR's title or description is a direct request, so Promptless reviews the PR regardless of your listening configuration. If your project only reviews after a first approval, the mention triggers a review as soon as the PR opens. If the PR targets your documentation repository—normally outside your source scope—the mention pulls it in anyway. Tagging Promptless does what you expect: Promptless reviews the PR. Include the mention anywhere in the title or description: ```markdown ## Summary Added new authentication endpoints for SSO integration. @promptless please document these API changes ``` Mention `@promptless` or `@promptless-for-oss` (matching is case-insensitive). ## Request documentation via PR comments Beyond automatic triggers, you can request documentation updates by @mentioning Promptless in a comment on any source pull request. ### How to use Tag Promptless in a comment on a source PR to request documentation work: ``` @promptless please update the docs for this API change ``` ### When to use PR comment mentions are useful when: - A PR was created before your trigger was set up - You want documentation for a PR that's already merged or closed - The automatic trigger didn't fire for your PR - You want to provide specific instructions about what to document ### Supported PR states Promptless responds to comment mentions on pull requests in any state: - Open PRs - Draft PRs - Merged PRs - Closed PRs ### Trigger from automated accounts A direct `@promptless` mention doesn't have to come from a person. It takes priority over Promptless's bot filter, so a comment from an automated account—like a GitHub Actions workflow—triggers documentation work just as a comment from a teammate does. This lets you build docs requests into your CI: have an Action post an `@promptless` comment whenever you want docs updated or reviewed. For example, a GitHub Actions step can comment on a pull request to ask Promptless to document the change: ```yaml - name: Ask Promptless for docs run: gh pr comment "$PR_NUMBER" --body "@promptless please update the docs for this change" env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} PR_NUMBER: ${{ github.event.pull_request.number }} ``` The comment must include a direct `@promptless` mention—Promptless still ignores bot comments that don't mention it. This works for any automated account, including CI or review Actions that run checks like Doc Detective or snippet validation. ### Requirements - The GitHub integration must be installed for your repository - You must explicitly @mention Promptless in the comment—comments without a direct mention are ignored ## Setup instructions To connect GitHub to Promptless, see the [GitHub Integration](/docs/reference/integrations/github) setup guide. *** title: GitHub commits url: https://promptless.ai/docs/connect/triggers/github-commits --- import { Aside } from '@astrojs/starlight/components'; Promptless can monitor direct commits to your default branches for documentation updates. This is useful for teams that merge changes directly without pull requests, or when you want to capture documentation needs from hotfixes and emergency changes. ## How it works When a commit is pushed directly to a monitored branch: 1. **Commit Detection**: Promptless receives notification of the new commit 2. **Analysis**: The system processes the code diff and commit message to understand the changes 3. **Relevance Assessment**: Promptless determines if the changes require documentation updates 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions ## Commit triggers vs. pull request triggers A commit trigger fires on commits pushed to a monitored branch, while a PR trigger fires on pull request activity. The two overlap in a standard GitHub workflow: when a pull request merges, its merge commit lands on the default branch and fires the commit trigger along with the `github_pr` merge event. The commit trigger is most useful when changes reach a branch without a pull request, such as direct pushes or hotfixes. You can use GitHub commit triggers alongside PR triggers, or on their own. ### Use commits alongside PR triggers If you configure both a GitHub PR project and a GitHub Commits project for the same repositories: - Promptless comments on PRs while they're open, providing early feedback on documentation needs - After the PR merges, the commit trigger updates suggestions with the final merged content - Useful when you want PR comments during review and updated suggestions after merge ### Use commits only If you configure only a GitHub Commits project, without a corresponding PR project: - Promptless only runs after changes merge to your default branch - Reduces notification noise if PR triggers are too frequent - Since you won't get PR comments, configure a Slack notification channel to stay informed about new suggestions ## Configuration Configure GitHub commit triggers in your [Configuration page](https://app.gopromptless.ai/configuration) using the `triggers` section: ```yaml triggers: main-commits: trigger_type: github_commit match: - repos: - acme/backend - acme/frontend branches: - main # omit to match only the repository's default branch trigger_directories: - src/ - lib/ ``` See the [Configuration Reference](/docs/reference/configuration-reference#triggers) for all available options. ## Process recent commits When creating a new project with a GitHub commit trigger, you can enable **Process last 30 days of commits** to generate initial documentation suggestions from your recent commit history. This is useful for: - **Initial calibration**: Get an initial batch of suggestions to review and refine Promptless's behavior before going live - **Repositories without PRs**: Teams using forks or direct-commit workflows can still bootstrap their documentation suggestions - **Migrating from PR triggers**: When switching from PR-based to commit-based triggers, catch up on recent changes Merge commits are automatically skipped during replay to avoid duplicate processing. ## Notification channels Commit triggers don't create PR comments. To receive updates when Promptless creates or updates suggestions, configure a Slack notification channel in your [publishing policies](/docs/reference/configuration-reference#policies): ```yaml policies: default: notification: slack_channel: docs-updates ``` ## Directory-specific commits Similar to PR triggers, you can configure Promptless to only trigger on commits that affect specific directories. This is particularly useful for monitoring changelog directories or specific feature areas. When trigger directories are specified, only commits that contain changes to those directories trigger documentation updates. ## Use cases GitHub commit triggers are especially useful for: - **Changelog Monitoring**: Automatically update documentation when changelog files are modified - **Hotfix Documentation**: Capture documentation needs from emergency fixes that bypass the normal PR process - **Direct-to-Main Workflows**: Support teams that commit directly to main branches - **Automated Updates**: Trigger documentation updates from automated commit processes ## Auto-merge mode Automatically merge documentation PRs into the default branch as soon as they're created. Auto-merge requires automatic PR creation to also be enabled. Auto-merge is useful for: - **Internal documentation**: When documentation PRs don't require human review - **High-confidence workflows**: Teams that want full automation - **Changelog-driven updates**: When you want changelog updates to publish immediately Enable auto-merge in your [publishing policies](/docs/reference/configuration-reference#policies): ```yaml policies: rules: - if: trigger: main-commits then: publishing: auto_create_pr: true auto_merge: true ``` ## Setup instructions To connect GitHub to Promptless, see the [GitHub Integration](/docs/reference/integrations/github) setup guide. *** title: GitHub issues url: https://promptless.ai/docs/connect/triggers/github-issues --- import { Aside } from '@astrojs/starlight/components'; Promptless monitors GitHub issues for documentation requests. When @Promptless is mentioned in an issue, the system analyzes the issue content and creates documentation suggestions. ## How it works When @Promptless is mentioned in a GitHub issue: 1. **Acknowledgment**: Promptless adds a 👀 reaction to the issue to indicate processing has started 2. **Analysis**: Promptless reads the issue title, description, and comments to understand the documentation request 3. **Relevance Assessment**: Promptless determines if the issue content warrants documentation updates 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions and posts results back to the issue ## When to use GitHub issues triggers GitHub Issues triggers are useful for: - **Documentation requests**: Contributors or users can open issues requesting specific documentation improvements - **Open-source projects**: Community members can tag Promptless in issues to generate documentation updates without needing access to other tools - **Tracking documentation gaps**: Issues provide a natural place to discuss and track documentation needs before they're addressed ## Configuration GitHub Issues triggers are a built-in trigger type that's always active when the GitHub integration is connected, no YAML configuration required. When @Promptless is mentioned in an issue on any repository where the GitHub App is installed, Promptless processes the request. Publishing behavior and notifications are controlled by your [policies configuration](/docs/reference/configuration-reference#policies). ## Setup instructions To connect GitHub to Promptless, see the [GitHub Integration](/docs/reference/integrations/github) setup guide. *** title: GitLab merge requests url: https://promptless.ai/docs/connect/triggers/gitlab-merge-requests --- import { Aside } from '@astrojs/starlight/components'; Promptless monitors your GitLab projects for merge requests. When a merge request is opened or updated, Promptless analyzes the changes and creates documentation suggestions if needed. ## How it works When a merge request event occurs in your monitored GitLab projects: 1. **Automatic Detection**: Promptless receives notification of the new or updated merge request. 2. **Analysis**: The system processes the code diff, MR title, and MR description to understand the context. 3. **Relevance Assessment**: Promptless determines if the changes require documentation updates. 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions. ## Configuration Configure GitLab merge request triggers in your [Configuration page](https://app.gopromptless.ai/configuration) using the `triggers` section: ```yaml triggers: gitlab-mrs: trigger_type: gitlab_mr match: - repos: - acme/backend - acme/api trigger_on: - opened - merge trigger_directories: - src/ ``` See the [Configuration Reference](/docs/reference/configuration-reference#triggers) for all available options. ## Directory-specific triggers Use the `trigger_directories` field to only trigger when changes are made to specific directories. When specified, Promptless considers only merge requests that contain changes to those directories. ## Automatic PR creation When automatic PR creation is enabled in your [publishing policies](/docs/reference/configuration-reference#policies), Promptless automatically creates a new PR in your documentation repository with suggested changes. ## Source MR comments Promptless posts a summary comment on source merge requests linking to any documentation changes. This keeps documentation updates visible alongside the code changes that triggered them. The comment links directly to the documentation suggestions, so reviewers can see proposed updates while reviewing the code. ## Configuration files and dot-directories Promptless automatically skips merge requests that only contain changes to dot-directories (like `.gitlab/`, `.gitlab-ci/`) or root-level dot-files (like `.gitignore`, `.gitlab-ci.yml`). These are typically CI and tooling configuration rather than product changes that need documentation updates. If an MR contains both dot-files and regular source files, Promptless processes it normally—it only skips when the entire MR is dot-file changes. ## Setup instructions To connect GitLab to Promptless, see the [GitLab Integration](/docs/reference/integrations/gitlab) setup guide. *** title: Slack messages url: https://promptless.ai/docs/connect/triggers/slack-messages --- import { Aside } from '@astrojs/starlight/components'; Slack integration enables documentation updates directly from your team conversations. This is particularly useful for support conversations or internal discussions where questions arise that could be better addressed in your documentation. ## Trigger methods ### Use a message action Use the Promptless message shortcut on any Slack message to trigger documentation analysis. This method allows you to trigger updates without interrupting the conversation flow. ### Mention @Promptless in a channel Tag @Promptless in a channel with specific instructions or questions. Promptless analyzes the full thread context to create relevant documentation updates. ### Send a direct message Send documentation requests directly to @Promptless in a DM. This is useful for private documentation requests with comprehensive context support. ## How it works When triggered in Slack: 1. **Thread Analysis**: Promptless reads the entire thread where it was triggered 2. **Context Gathering**: The system analyzes text, images, and file attachments in the thread 3. **Documentation Suggestions**: Promptless creates suggestions based on the conversation content 4. **Follow-up Editing**: Continue editing suggestions within the same thread using @Promptless mentions ## Image and file processing Promptless can process images and file attachments shared in Slack threads when triggered, enhancing documentation with visual elements and additional context when appropriate. ### How it works 1. When you tag @Promptless or use the "Update docs" message action in a thread containing images or file attachments, Promptless analyzes both the text and attached files in the thread. 2. Promptless evaluates whether the images or file content provide valuable context that should be included in the documentation. 3. If an image or file is deemed relevant, Promptless: - Uploads the image to a secure S3 bucket - Extracts and incorporates relevant content from file attachments (including images from PDFs) - Includes the image in the documentation updates it suggests - Formats the image appropriately for the documentation platform 4. When reviewing the suggestion in the Promptless app, the added images appear at the bottom of the review interface, allowing you to approve or reject their inclusion. ## Thread reply auto-listening Promptless automatically monitors threads where it's participating. When someone replies to a thread where Promptless has posted or been @mentioned, Promptless treats the reply as a follow-on trigger—no additional @mention required. This means you can: - Reply to a notification thread with feedback or additional context - Continue a conversation Promptless started without tagging it again - Provide images, files, or clarifications that Promptless requested ### Thread reply trigger mode Configure how Promptless handles thread replies in **Organization Settings**: Slack Thread Reply Trigger Mode settings - **Listen to all replies** (default): Process all replies in threads where Promptless is participating. Use the aside prefix to skip specific messages. - **Require @promptless**: Only process replies that explicitly @mention Promptless. This setting applies organization-wide to all Slack threads. ## Passive channel listening (optional) You can optionally enable passive listening for specific channels. When enabled, Promptless automatically monitors conversations in your selected channels and creates documentation suggestions when threads become inactive. To enable passive listening, add a `slack_listen` trigger to your configuration: ```yaml triggers: my-slack-trigger: trigger_type: slack_listen match: - channels: - support - docs-feedback ``` ## Configuration Configure Slack passive listening in your [Configuration page](https://app.gopromptless.ai/configuration) using the `triggers` section: ```yaml triggers: support-channels: trigger_type: slack_listen match: - channels: - customer-support - product-questions ``` Channel names don't need the `#` prefix. When Slack channels are renamed, Promptless automatically updates your configuration. @Promptless mentions and message actions work automatically when the Slack integration is connected—no configuration required. See the [Configuration Reference](/docs/reference/configuration-reference#triggers) for details. ## Privacy and channel access By default, Promptless only reads Slack content when you explicitly trigger it by tagging @Promptless or using the "Update Docs" message action. If you enable passive listening, Promptless monitors only the specific channels you select in your project configuration. ## Setup instructions To connect Slack to Promptless, see the [Slack Integration](/docs/reference/integrations/slack) setup guide. *** title: Microsoft Teams messages (beta) url: https://promptless.ai/docs/connect/triggers/microsoft-teams-messages --- import { Aside } from '@astrojs/starlight/components'; Microsoft Teams integration enables automated documentation updates based on team communication and collaboration within your Teams environment. Similar to Slack, you can trigger documentation updates directly from your conversations. ## Trigger methods ### Tag @Promptless in a channel Mention @Promptless in a Teams channel with specific instructions or questions. Promptless analyzes the conversation context to create relevant documentation updates. ### Send a direct message Send documentation requests directly to @Promptless in a DM for private documentation requests. ## How it works When triggered in Microsoft Teams: 1. **Message Analysis**: Promptless reads the message and conversation context where it was triggered 2. **Context Gathering**: The system analyzes text content and conversation flow 3. **Documentation Suggestions**: Promptless creates suggestions based on the conversation content 4. **Review**: Review and approve suggestions in the Promptless web interface ## Configuration @Promptless mentions in Microsoft Teams are a built-in trigger type that's always active when the Teams integration is connected, no YAML configuration required. To enable passive channel listening, add an `msteams_listen` trigger to your [Configuration page](https://app.gopromptless.ai/configuration): ```yaml triggers: teams-support: trigger_type: msteams_listen match: - channel_ids: - 19:abc123@thread.tacv2 ``` Publishing behavior and notifications are controlled by your [policies configuration](/docs/reference/configuration-reference#policies). ## Privacy and access Promptless only reads Microsoft Teams content when you explicitly trigger it by tagging @Promptless in a conversation. The system does not monitor channels passively. ## Setup instructions To connect Microsoft Teams to Promptless, see the [Microsoft Teams Integration](/docs/reference/integrations/microsoft-teams) setup guide. *** title: Intercom tickets (beta) url: https://promptless.ai/docs/connect/triggers/intercom-tickets --- import { Aside } from '@astrojs/starlight/components'; Intercom integration enables automated documentation updates based on support conversations and ticket patterns. This helps identify gaps in documentation based on recurring customer questions. ## How it works When a support conversation is closed: 1. **Conversation Analysis**: Promptless analyzes the closed conversation content and customer interaction 2. **Pattern Detection**: The system identifies common questions or issues that indicate documentation gaps 3. **Context Evaluation**: Promptless determines whether the conversation represents a broader documentation need 4. **Suggestion Creation**: If relevant, Promptless creates documentation suggestions to address the gap ## Configuration Intercom triggers are configured through the Promptless team during beta. Contact [help@gopromptless.ai](mailto:help@gopromptless.ai) to set up Intercom triggers for your organization. Publishing behavior and notifications are controlled by your [policies configuration](/docs/reference/configuration-reference#policies). ## Use cases Intercom triggers are especially useful for: - **FAQ Development**: Automatically identify common questions that should be added to documentation - **Knowledge Base Gaps**: Discover areas where documentation is missing or unclear - **Customer Pain Points**: Surface recurring issues that need better documentation - **Support Deflection**: Reduce ticket volume by improving documentation based on actual customer needs ## Setup instructions To connect Intercom to Promptless, see the [Intercom Integration](/docs/reference/integrations/intercom) setup guide. *** title: API triggers url: https://promptless.ai/docs/connect/triggers/api --- import { Aside } from '@astrojs/starlight/components'; API triggers let external systems request documentation updates from Promptless. Connect your CI/CD pipelines, custom automation tools, or any system that can make HTTP requests. ## Use cases API triggers work well when you want to: - Integrate Promptless into CI/CD pipelines that run after deployments - Build custom automation workflows that trigger documentation updates - Connect external systems (ticketing, project management, custom tools) to Promptless - Programmatically request documentation updates without using Slack or the dashboard ## Set up API triggers API triggers are a built-in trigger type that's always active when an API key exists, no YAML configuration required. ### Generate an API key API keys are managed in your organization's Settings page. 1. Navigate to **Settings > API Access** 2. Click **Generate Key** to create a new API key 3. Copy the key immediately—it's only shown once ### Key management - **One active key per organization**: Each organization can have one active API key at a time - **Key rotation**: Generating a new key immediately revokes the previous key - **Revocation**: You can revoke your active key at any time from the Settings page ## Use the API For the full request and response schemas, status codes, and an interactive explorer, see the [API Reference](/api/operations/submitapitrigger/). The sections below cover the same endpoint with examples. ### Endpoint ``` POST /triggers ``` ### Authentication Include your API key as a Bearer token in the Authorization header: ``` Authorization: Bearer sk-pl-your-api-key ``` The bearer token determines which organization receives the trigger—no need to specify an organization ID in the URL. ### Request format Send a JSON body with your documentation instructions: ```json { "instructions": "Update the getting started guide with the new authentication flow", "context": { "ticket_id": "ENG-123", "requested_by": "deploy-bot" } } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `instructions` | string | Yes | What you want Promptless to document. Be specific about which docs to update and what changes to make. | | `context` | object | No | Additional metadata to include with the request. This appears in trigger history for reference. | ### Example request ```bash curl -X POST "https://api.gopromptless.ai/triggers" \ -H "Authorization: Bearer sk-pl-your-api-key" \ -H "Content-Type: application/json" \ -d '{ "instructions": "Document the new rate limiting feature added in v2.5", "context": { "release": "v2.5.0", "jira_ticket": "DOC-456" } }' ``` ### Response A successful request returns a `202 Accepted` response: ```json { "trigger_event_id": "abc123-..." } ``` ### Error responses | Status | Error | Description | |--------|-------|-------------| | 401 | `authentication_failed` | The API key is missing, invalid, or revoked. | | 409 | `org_not_configured` | Your organization hasn't finished setting up Promptless. | | 409 | `no_eligible_doc_collection` | The requested doc collection is not configured or not ready. | | 422 | Validation error | The request body is invalid. | | 500 | `enqueue_failed` | The trigger could not be enqueued for processing. | | 503 | `runtime_store_unavailable` | Trigger intake is temporarily unavailable. | ## View API triggers API-triggered events appear in your dashboard with a distinct "API" label. ### Trigger history View all API triggers on the [Triggers page](https://app.gopromptless.ai/triggers). API triggers show the submitted instructions and any context you included in the request. ### Change history Filter by "API" source in [Change History](https://app.gopromptless.ai/change-history) to see documentation suggestions that came from API requests. ## How it works When you submit an API request: 1. **Validation**: Promptless validates your API key and request format. 2. **Routing**: The request is routed to your configured doc collections. 3. **Processing**: Promptless analyzes your instructions along with configured context sources. 4. **Suggestion Creation**: If documentation updates are needed, Promptless creates suggestions. *** title: Context sources url: https://promptless.ai/docs/connect/context-sources --- import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; Context sources are integrations that give Promptless **read-only** access to your organization's existing tools and data. They provide additional context that helps Promptless create more accurate and comprehensive documentation suggestions. ## How context sources work Think of context sources as Promptless's way of understanding your team's unique ecosystem. When triggered to create documentation updates, Promptless intelligently searches through your connected tools to gather the most relevant context. This creates documentation that feels like it was written by someone who truly understands your project. ![Mermaid diagram](/mermaid/how-it-works.svg) ## Available context sources ## Examples ### Linear as a context source When a GitHub PR mentions a new feature, Promptless searches Linear for related issues to understand additional project context. This ensures your documentation includes the "why" behind code changes, not just the "what." ### Jira as a context source If a GitHub PR references a Jira ticket (like "PROJ-123"), Promptless automatically reads that Jira ticket for additional context. It also proactively searches Jira using JQL for related issues and epics. ### Confluence as a context source When writing documentation, Promptless searches your Confluence spaces for existing documentation patterns, terminology, and architectural decisions. This ensures new documentation matches your team's existing style and conventions. ### Notion as a context source When a GitHub PR references a Notion page containing feature specifications, Promptless automatically fetches that page content. It also searches your Notion workspace for related product documentation, ensuring new docs align with existing feature definitions and terminology. ### Google Drive as a context source When a GitHub PR links to a "Rate Limiting v2" design doc in Google Docs, Promptless resolves that document and reuses its exact thresholds and rationale when updating the rate-limit reference page. It also searches your Drive for related specs and notes, so new docs match the numbers and decisions your team already recorded. ### Slite as a context source When a GitHub PR references a feature, Promptless searches your Slite workspace for related notes containing product context. This ensures documentation includes accurate feature descriptions and terminology from your team's knowledge base. ## Configure context sources Context sources are configured in your organization's [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section of your `promptless.yaml` file. You can: - Connect integrations on the [Integrations page](https://app.gopromptless.ai/integrations) - Optionally scope each source to specific projects, spaces, or databases in your configuration - Leave a source unconfigured (or empty) to give Promptless full access to that integration See the [Configuration Reference](/docs/reference/configuration-reference#context-sources) for the complete YAML schema. ## Data privacy and security Promptless prioritizes your data privacy and security with context sources:
Real-time Queries Only We do not store any of your organization's data from context sources. Instead, our agents query the relevant APIs in real-time when documentation updates are needed, ensuring that we only access the information required for the specific documentation task at hand.
Secure Authentication All context source integrations use: - OAuth 2.0 authentication - Encrypted data transmission (TLS 1.2+) - Granular permission controls - Token-based access that can be revoked at any time
Minimal Data Access Promptless only accesses the specific information needed for documentation generation and does not retain or cache this data after processing.
## Request additional context sources Need integration with other tools? Contact [help@gopromptless.ai](mailto:help@gopromptless.ai) to request additional context sources. We're continuously expanding our integration options to better serve your documentation needs. *** title: Jira url: https://promptless.ai/docs/connect/context-sources/jira --- import { Aside } from '@astrojs/starlight/components'; Jira integration provides **read-only** access to your project management and issue tracking data for documentation automation. When Jira is configured as a context source, Promptless can search for related tickets to understand requirements and business context—but it never modifies your Jira tickets. ## How it works as a context source When Jira is enabled as a context source: - **Automatic Issue Retrieval**: When a GitHub PR or other trigger mentions a Jira ticket (like "PROJ-123"), Promptless automatically retrieves that specific issue for additional context—including the issue summary, description, status, and comments - **Proactive JQL Searches**: Promptless can proactively search Jira using JQL queries to find related issues, epics, and project data - **Business Context**: Jira tickets provide requirements, business logic, and feature context that enhance documentation accuracy ## Example If a GitHub PR references a Jira ticket (like "PROJ-123"), Promptless automatically reads that Jira ticket for additional context. It also proactively searches Jira using JQL for related issues and epics. ## JQL search capabilities Promptless leverages Jira's powerful JQL (Jira Query Language) search functionality to find relevant context. This allows intelligent searching across your Jira projects to find related issues, epics, and dependencies. ## Configuration Configure Jira scope in your [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section: ```yaml context_sources: jira: source_type: jira project_keys: - DOCS - PLATFORM - ENG ``` An empty entry (or no entry) gives Promptless access to all projects. Add `project_keys` only when you need to restrict which projects Promptless can search. ## Data privacy Promptless queries Jira data in real-time and does not store any of your Jira data. All searches are performed on-demand when documentation updates are needed. Promptless only reads from Jira—it never creates, updates, or deletes tickets. ## Setup instructions To connect Jira to Promptless, see the [Atlassian Integration](/docs/reference/integrations/atlassian) setup guide. *** title: Linear url: https://promptless.ai/docs/connect/context-sources/linear --- import { Aside } from '@astrojs/starlight/components'; Linear integration provides **read-only** access to your project management data for documentation automation. When Linear is configured as a context source, Promptless can search for related issues to understand the business context behind code changes—but it never modifies your Linear issues. ## How it works as a context source When Linear is enabled as a context source: - **Automatic Issue Lookup**: When a GitHub PR mentions a Linear issue, Promptless automatically retrieves that issue for additional context - **Proactive Searches**: Promptless can search Linear for related issues and projects to understand feature requirements - **Business Context**: Linear issues provide the "why" behind code changes, not just the "what" ## Example When a GitHub PR mentions a new feature, Promptless searches Linear for related issues to understand additional project context. This ensures your documentation includes business requirements and feature goals alongside technical implementation details. ## Configuration Configure Linear scope in your [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section: ```yaml context_sources: linear: source_type: linear team_keys: - engineering - product ``` An empty entry (or no entry) gives Promptless access to all teams. Add `team_keys` only when you need to restrict which teams Promptless can search. ## Data privacy Promptless queries Linear data in real-time and does not store any of your Linear data. All searches are performed on-demand when documentation updates are needed. Promptless only reads from Linear—it never creates, updates, or deletes issues. ## Setup instructions To connect Linear to Promptless, see the [Linear Integration](/docs/reference/integrations/linear) setup guide. *** title: Confluence url: https://promptless.ai/docs/connect/context-sources/confluence --- import { Aside } from '@astrojs/starlight/components'; Confluence integration provides **read-only** access to your documentation spaces for documentation automation. When Confluence is configured as a context source, Promptless can search your Confluence spaces for relevant documentation when creating suggestions—but it never modifies your Confluence pages. ## How it works as a context source When Confluence is enabled as a context source: - **Automatic Space Searching**: Promptless searches your Confluence spaces for relevant documentation when creating suggestions - **Documentation Patterns**: Confluence pages provide context about existing documentation styles, terminology standards, and content structures - **Architectural Context**: Technical specifications, design decisions, and system architecture documented in Confluence inform new documentation - **Team Knowledge**: Internal processes, guidelines, and best practices from your team's Confluence spaces ## Example When writing API documentation, Promptless searches your Confluence spaces for existing API design patterns, naming conventions, and architectural decisions. This ensures new documentation matches your existing terminology and structure. For instance, if your team documents all API endpoints using a specific format in Confluence, Promptless follows that same pattern when creating new API documentation. ## Configuration Configure Confluence scope in your [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section: ```yaml context_sources: confluence: source_type: confluence space_keys: - ENGINEERING - PRODUCT ``` An empty entry (or no entry) gives Promptless access to all spaces. Add `space_keys` only when you need to restrict which spaces Promptless can search. ## Data privacy Promptless queries Confluence data in real-time and does not store any of your Confluence data. All searches are performed on-demand when documentation updates are needed. Promptless only reads from Confluence—it never creates, updates, or deletes pages. ## Setup instructions To connect Confluence to Promptless, see the [Atlassian Integration](/docs/reference/integrations/atlassian) setup guide. *** title: Notion url: https://promptless.ai/docs/connect/context-sources/notion --- import { Aside } from '@astrojs/starlight/components'; Notion integration provides **read-only** access to your team's knowledge base for documentation automation. When Notion is configured as a context source, Promptless can search your Notion pages and databases for relevant information when creating suggestions—but it never modifies your Notion content. ## How it works as a context source When Notion is enabled as a context source: - **Page Search**: Promptless searches your selected Notion pages for relevant content when creating documentation suggestions - **Database Queries**: Promptless can query Notion databases to retrieve structured information like product roadmaps, feature specs, reference tables - **URL Resolution**: When triggers reference Notion URLs, Promptless automatically fetches the linked page content using your authenticated connection. If a page isn't shared with your Notion integration but is publicly accessible, Promptless falls back to fetching it as a public web page. - **Knowledge Context**: Internal documentation, product specs, and team knowledge from Notion inform new documentation ## Agent capabilities When Notion is connected, Promptless agents gain access to three specialized tools: | Tool | Description | |------|-------------| | **Search Notion** | Searches pages and databases shared with your Notion connection by keyword. Returns up to 25 results per request with pagination support. | | **Get Notion Page** | Fetches a specific page by ID and returns its content as markdown. Optionally includes meeting note transcripts inline. | | **Query Notion Database** | Queries rows from a Notion database, returning page IDs, titles, URLs, and properties. Returns up to 25 rows per request with pagination support. | ## Example When a GitHub PR references a Notion page containing feature specifications, Promptless automatically fetches that page content. It also proactively searches your Notion workspace for related product documentation, ensuring new docs align with existing feature definitions and terminology. ## Configuration Configure Notion scope in your [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section: ```yaml context_sources: notion: source_type: notion database_ids: - abc123def456 page_ids: - xyz789ghi012 ``` An empty entry (or no entry) gives Promptless access to all pages and databases shared with your integration. Add `database_ids` or `page_ids` only when you need to restrict access. ## Data privacy Promptless queries Notion data in real-time and does not store any of your Notion content. All searches are performed on-demand when documentation updates are needed. Query results are cached briefly (90 seconds) to improve performance during a single documentation session, then discarded. Promptless only reads from Notion—it never creates, updates, or deletes pages or databases. ## Setup instructions To connect Notion to Promptless: 1. Go to the [Integrations page](https://app.gopromptless.ai/integrations) in your Promptless dashboard 2. Click **Connect** on the Notion integration card 3. Authorize Promptless to access your Notion workspace. 4. Select the specific pages and data sources you want to make available as context To add or remove pages after initial setup, click **Add or remove pages on Notion** in the workspace picker. This deep links over into Notion so you can update your sharing selections. *** title: Google Drive url: https://promptless.ai/docs/connect/context-sources/google-drive --- import { Aside } from '@astrojs/starlight/components'; Google Drive integration provides **read-only** access to your team's documents for documentation automation. When Google Drive is configured as a context source, Promptless searches your Drive and reads file content while creating suggestions—but it never modifies your Drive content. ## How it works as a context source When Google Drive is enabled as a context source: - **Drive Search**: Promptless searches files by name and full text across My Drive and shared drives when creating documentation suggestions - **File Reading**: Promptless reads file content on demand—Google Docs as Markdown, Sheets as CSV, and Slides as plain text—pulling product specs, internal notes, and reference material into new documentation - **URL Resolution**: When triggers reference Google Drive or Google Docs URLs, Promptless fetches the linked file using your authenticated connection. If a file isn't accessible to your integration but is publicly shared, Promptless falls back to fetching it as a public web page. ## Example A developer merges a GitHub PR that lowers the default API rate limit from 1,000 to 600 requests per minute, with a code comment that links to the "Rate Limiting v2" design doc in Google Docs. Promptless resolves that linked Doc, reads the rollout thresholds and the reasoning behind the new ceiling, and reuses the exact numbers and rationale when it updates the rate-limit reference page. ## Scope access Because Promptless connects through OAuth, its Drive access is bounded by whatever the authorizing Google account can read. Whoever authorizes the connection sets the scope of what Promptless sees. To be prescriptive about what Promptless can access, create a dedicated Google account to act as a service account for Promptless, then share only the specific shared drives and folders you want Promptless to read with that account. Connecting through that account—rather than a broadly privileged individual's account—bounds Promptless's Drive access to exactly what you share, giving you least-privilege control. After you connect, the Google Drive integration card shows which account authorized the connection under the label **Searching documents this person can access**, along with the connecting user's name and email. Check it to confirm Promptless is bound to the dedicated account you intended rather than a broadly privileged one. If you connected before this label was added, the account appears only after you refresh or reconnect the integration. ## Data privacy Promptless queries Google Drive in real time and stores none of your Drive content. Searches and file reads happen on demand when documentation updates are needed. Promptless caches results briefly to improve performance during a single documentation session, then discards them. Promptless connects with read-only Drive scopes and only reads from Google Drive—it never creates, updates, or deletes files. ## Setup instructions To connect Google Drive to Promptless: 1. Go to the [Integrations page](https://app.gopromptless.ai/integrations) in your Promptless dashboard. 2. Click **Connect** on the Google Drive integration card. 3. Authorize Promptless to access your Google Drive with read-only permissions. *** title: Slite url: https://promptless.ai/docs/connect/context-sources/slite --- Slite integration provides **read-only** access to your team's knowledge base for documentation automation. When Slite is configured as a context source, Promptless can search your Slite notes for relevant information when creating suggestions—but it never modifies your Slite content. ## How it works as a context source When Slite is enabled as a context source: - **Note Search**: Promptless searches your Slite workspace for relevant notes when creating documentation suggestions - **Knowledge Context**: Internal documentation, product specs, and team knowledge from Slite inform new documentation - **URL Resolution**: When triggers reference Slite note URLs, Promptless automatically fetches the linked note content ## Example A developer merges a GitHub PR that adds a configurable retry limit to your webhook delivery system. The feature was scoped in a PRD in your Slite workspace, which spells out the official feature name ("Delivery Retry Policy"), the default and maximum retry counts, and the reasoning behind the cap. When Promptless picks up the merged PR, it searches your Slite workspace for related notes and resolves any Slite URLs referenced in the PR description. It reads the PRD and carries those agreed-upon details into the documentation suggestion—the same feature name, the same retry limits, and the same rationale your team already settled on—instead of inferring them from the diff alone. The result is a docs PR that matches the spec your product and engineering teams wrote, not a re-derived approximation. ## Configuration Slite only supports API key authentication rather than OAuth. To connect Slite: 1. In your Slite account, go to **Settings > API** and create a new API key. The API key grants Promptless read access to all notes visible to the account that created the key. We recommend using a service account with appropriate access scope. 2. Go to the [Integrations page](https://app.gopromptless.ai/integrations) in your Promptless dashboard. 3. Click **Connect** on the Slite integration card. 4. Enter your API key and click **Connect**. ## Data privacy Promptless queries Slite data in real-time and doesn't store any of your Slite content. All searches are performed on-demand when documentation updates are needed. Query results are cached briefly to improve performance during a single documentation session, then discarded. Promptless only reads from Slite. Promptless never creates, updates, or deletes notes. *** title: How Promptless learns your docs url: https://promptless.ai/docs/connect/doc-locations/how-promptless-learns-your-docs --- Before creating the first suggestion, Promptless analyzes your existing docs to understand the product, writing style, and how your docs are organized. ## Initial ingestion - Builds a searchable index to find relevant content when analyzing triggers - Maps relationships between pages, sections, and topics ## Product ontology Promptless builds an understanding of your product's structure - what features you have, how they relate to each other, and the terminology your team uses. This **product ontology** helps Promptless: - Know which documentation pages are relevant when a specific feature changes - Understand your product's concepts and terminology - Identify connections between features that might require coordinated documentation updates For example, if your product has a "Workspaces" feature with sub-features like "Permissions" and "Invitations," Promptless understands these relationships and can update all relevant pages when workspace behavior changes. ## Voice and style learning Promptless analyzes how your documentation is written - tone, sentence structure, formatting patterns, and terminology choices. This powers **Voice Match**, ensuring suggestions sound like they were written by your team. Promptless learns patterns like: - Whether you write formally or conversationally - The specific words and phrases you use for concepts - How you organize content, use headings, and format examples - Your preferences for capitalization, punctuation, and code formatting When drafting content, Promptless references similar existing pages to match their style. ## Continuous learning Promptless continues learning as you use it. When you edit suggestions or provide feedback, Promptless learns your preferences for future suggestions. As your documentation grows and changes, Promptless adapts to your evolving style and automatically re-indexes when you publish updates to stay current. ## Custom agent instructions with AGENTS.md You can provide persistent guidance to Promptless by creating an `AGENTS.md` file in the root of your docs repository. Use this file to specify project-specific conventions, terminology, and documentation standards that the agent follows when creating suggestions. ### How it works When Promptless starts working on your documentation, it checks the root of your docs repository for an `AGENTS.md` file. If found, the content is included in the agent's instructions, applying your custom guidance to every suggestion. ### What to include Use your `AGENTS.md` file to communicate: - **Terminology preferences** - Specific words or phrases your team uses for concepts - **Formatting conventions** - How to structure code examples, callouts, or headings - **Content guidelines** - What information should always be included (or excluded) - **Style rules** - Voice, tone, or writing patterns unique to your documentation ### Example AGENTS.md ```markdown # Documentation Guidelines ## Terminology - Use "workspace" not "project" when referring to user containers - Always capitalize "API" but lowercase "endpoint" - Prefer "authentication" over "auth" in prose ## Formatting - Use admonitions for warnings and important notes - Include a "Before you begin" section in procedural docs - Code examples should include comments explaining each step ## Style - Write in second person ("you") rather than third person - Keep sentences under 25 words when possible - Use active voice ``` ### Relationship with CLAUDE.md If your repository already has a `CLAUDE.md` file (used by Claude Code CLI), Promptless uses that instead. The `AGENTS.md` file is only loaded when no `CLAUDE.md` is present, maintaining compatibility with existing Claude Code configurations. ## Use your existing skills If you already keep [Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) in your documentation repository, Promptless uses them automatically. Skills you've added under `.claude/skills/`, `.agents/skills/`, or `.cursor/skills/` are picked up with no extra configuration. When a documentation task matches a skill's description, the agent runs that skill instead of deriving the workflow from scratch. This means the same skills you've authored for other AI coding agents apply to your documentation work too. There's nothing to set up in Promptless: keep your skills where they already live, and the agent uses them as appropriate. ### Guide how Promptless uses your skills To shape when and how Promptless reaches for your skills, add guidance to the `PROMPTLESS.md` file in your [Knowledge Base](https://app.gopromptless.ai/settings/knowledge). For example, you can tell the agent to prefer a particular skill for changelog entries, or to always run a formatting skill before publishing API reference pages. Promptless reads this guidance alongside your skills and applies it when deciding which skill fits the task at hand. *** title: GitHub repos (docs as code) url: https://promptless.ai/docs/connect/doc-locations/github-repos --- import { Aside } from '@astrojs/starlight/components'; The most common documentation setup uses GitHub repositories to store documentation content that syncs to hosting providers. This "docs as code" approach allows you to version control your documentation alongside your code. ## Supported platforms When your documentation lives in GitHub, Promptless can publish to any of these platforms: - **Fern** - **Mintlify** - **ReadMe** (Refactored) - **GitBook** - **Docusaurus** - **MkDocs** - **Hugo** - **Ghost** - **Nextra** - **Starlight** (Astro) - **Vocs** - **Custom platforms** (as long as the content is in a repo) ## How it works 1. **Repository Setup**: Your documentation files live in a GitHub repository 2. **Promptless Integration**: The Promptless GitHub App has write access to your docs repository 3. **Automatic PRs**: When documentation updates are needed, Promptless creates pull requests in your docs repo 4. **Platform Sync**: Your documentation platform automatically syncs changes from GitHub ## Configuration After setting up the GitHub integration, you can configure your doc collections in the [Configuration page](https://app.gopromptless.ai/configuration). Doc collections are defined in the `doc_collections` section of your `promptless.yaml` file, keyed by repository name: ```yaml doc_collections: acme/documentation: docs_framework: docusaurus docs_root_url: https://docs.acme.com filter: - docs/ ``` Triggers that initiate documentation updates are configured separately in the `triggers` section. See the [Configuration Reference](/docs/reference/configuration-reference) for the complete schema. ## Automatic PR creation When automatic PR creation (`auto_create_pr`) is enabled in your [publishing policies](/docs/reference/configuration-reference#policies): - Promptless automatically creates a new PR in your documentation repository with suggested changes - For GitHub PR triggers, the documentation PR is linked in a comment on the original code PR (you can disable these comments with `suppress_source_pr_comments: true` in your policy) - For [commit triggers](/docs/connect/triggers/github-commits), you can enable auto-merge to automatically merge documentation PRs as soon as they're created (`auto_merge: true`) ## Automated CI check and build issue resolution When Promptless opens a documentation PR, it automatically monitors the pull request for quality issues. If CI checks fail, linting tools report errors, Vale rules trigger warnings, or your documentation hosting provider detects broken links or build problems, Promptless automatically analyzes the issues and pushes fixes directly to the PR branch. This automated issue resolution works seamlessly with your existing GitHub workflow - there's no additional configuration needed. Quality problems get resolved in the background while you focus on content rather than troubleshooting technical issues. ## Trigger events in pull request descriptions When Promptless creates a pull request for documentation updates, it automatically includes a list of the trigger events that led to those changes in the PR description. This provides valuable context for reviewers and creates clear traceability between documentation updates and their originating events. The trigger events section in the PR description includes: - Links back to the original source (e.g., Slack threads, GitHub PRs, support tickets) - Brief descriptions of what triggered the documentation update - Easy navigation to review the context that prompted the changes ### Slack trigger link labels For Slack triggers, the link label shows where the message came from along with a content snippet: - **Public channels:** "Message in Slack channel #docs: please update the API guide" - **Direct messages:** "Private Slack DM with Jane Doe: can we add an example here" - **Group messages:** "Private Slack group message: the onboarding flow needs updating" ### Private messages and access limitations Reviewers without access to a private Slack conversation see Slack's "There's been a glitch" error when clicking the trigger link. To prevent confusion, private message links are clearly labeled as such ("Private Slack DM" or "Private Slack group message"), and Promptless adds a second link to the suggestion's Triggers & Analysis tab in the dashboard. Anyone with dashboard access can read the full message there, regardless of their Slack permissions. ## Path scope (documentation directories) Path scope controls which files Promptless can modify in your documentation repository. When you specify directories during doc collection setup, Promptless enforces these boundaries: - **All files allowed (default):** If no directories are specified, Promptless can create and modify files anywhere in the repository. - **Scoped to specific paths:** When directories are specified, Promptless can only modify files that match one of those paths exactly or are nested inside one of those directories. For example, if your path scope is set to `docs/guides`, Promptless can modify `docs/guides/getting-started.md` and `docs/guides/advanced/configuration.md`, but cannot modify `README.md` or `src/components/Button.tsx`. Path scopes support both directories and individual files. A scope entry like `CHANGELOG.md` allows only that specific file, while `docs/` allows any file under that directory. When Promptless creates a suggestion with changes outside the configured scope, the suggestion is rejected with an error listing which files are out of scope. This prevents accidental modifications to files outside your documentation area—useful for monorepos where docs live alongside source code. ## Edit doc collection settings You can edit certain doc collection settings directly in the dashboard. Click the edit button on any doc collection card to open the settings modal. **Editable settings:** - **Docs framework** — The documentation framework your site uses (Docusaurus, MkDocs, etc.) - **Config path** — Path to your documentation configuration file - **Published URL** — Your public documentation site URL - **Vale config** — Enable or disable Vale linting and set the config path - **[Doc Detective](/docs/audit/doc-detective)** — Enable or disable Doc Detective testing and set the config path **Settings that require support:** Platform, repository, and branch are scope-defining fields that cannot be edited in the dashboard. To change these settings, contact [help@gopromptless.ai](mailto:help@gopromptless.ai). ## Multi-platform publishing Promptless can publish to multiple documentation repositories simultaneously, allowing you to use the same trigger events and context sources across different doc sites. ## Request additional platforms Need integration with a Git-hosted platform not currently supported? We're continuously expanding platform support based on user feedback. Contact [help@gopromptless.ai](mailto:help@gopromptless.ai). Also contact us if you're hoping to migrate to a new docs platform and we'll be happy to help you choose and set up. ## Setup instructions To connect GitHub to Promptless, see the [GitHub Integration](/docs/reference/integrations/github) setup guide. ## Frequently asked questions
I don't see any repositories in the dropdown when creating a doc collection If the repository dropdown shows "No options" when creating a doc collection, you need to connect GitHub first. Go to the [integrations page](https://app.gopromptless.ai/integrations) and click "Connect GitHub" to install the Promptless GitHub App. Once GitHub is connected, return to creating your doc collection and your repositories appear in the dropdown. If you've already connected GitHub but still don't see your repositories, you may need to grant Promptless access to those specific repositories. Visit your GitHub organization settings, find the Promptless GitHub App under "Third-party Access" → "GitHub Apps", and add the repositories you need.
*** title: Customize notifications url: https://promptless.ai/docs/tune/notifications description: Configure how Promptless notifies your team about documentation suggestions --- import { Aside } from '@astrojs/starlight/components'; Promptless sends notifications to your team when documentation suggestions are ready for review. You can configure notification channels in your organization's `promptless.yaml` file using the policies section. ## Notification channel configuration Set the default notification channel and create trigger-specific overrides in your [Configuration page](https://app.gopromptless.ai/configuration): ```yaml policies: default: notification: slack_channel: docs-updates msteams_channel: "19:0a1b2c3d@thread.tacv2" rules: - if: doc_collection: acme/internal-docs then: notification: slack_channel: internal-docs-team ``` Slack channel names don't need the `#` prefix. When Slack channels are renamed, Promptless automatically updates your configuration. `slack_channel` and `msteams_channel` are independent—set either, both, or neither. ### Disable an inherited channel A rule can turn off a channel that it would otherwise inherit from `policies.default` or an earlier rule by setting the field to `null`: ```yaml policies: default: notification: slack_channel: docs-updates rules: - if: doc_collection: acme/internal-docs then: notification: slack_channel: null ``` Here, suggestions for `acme/internal-docs` send no Slack notification, while every other collection still notifies `docs-updates`. Channels resolve by field presence: `slack_channel: null` disables the inherited channel, and omitting the field entirely inherits it. `msteams_channel` works the same way, and the two channels are disabled independently. See the [Configuration Reference](/docs/reference/configuration-reference#policies) for the complete policies schema. ## Notification preferences file Notification preferences are stored in the `doc_workflow/notification_preferences.md` file within your Agent Knowledge Base. This file is a lightweight scaffold where you add overrides and customizations—Promptless handles the underlying templates and message formatting automatically. ### What you can customize The preferences file lets you override: - **When to notify**: Control which events trigger notifications and when to skip them - **Delivery channels**: Set preferences for Slack vs. GitHub notifications - **Message style**: Adjust the tone and context included in notification messages ### Example customizations Here are some common ways teams customize their notifications: **Change notification timing:** ``` Only send notifications for suggestions that modify more than one file. Skip notifications for automated triggers that don't yield documentation updates. ``` **Adjust delivery preferences:** ``` Always reply in the originating Slack thread when the trigger came from Slack. Use GitHub comments when reviewers are already engaged with the source PR. ``` **Customize message style:** ``` Use a casual, friendly tone in all notification messages. Include enough context that someone new to the thread can understand why Promptless is posting. ``` ## Slack notification features With the [Slack integration](/docs/reference/integrations/slack) connected, Promptless sends rich notifications that include: - **Clickable preview cards**: Suggestion notifications appear as preview cards showing the title, status, description excerpt, trigger source, and file change stats. Click anywhere on the card to open the suggestion in Promptless. - **Interactive buttons**: Publish suggestions or open PRs for review directly from Slack. These actions appear within the preview card. - **Diff file attachments**: View the full diff of documentation changes in a thread reply - **Channel support**: Receive notifications in channels by name, not just by ID ### Suggestion preview cards Slack suggestion notifications include a preview card with: - **Title**: The suggestion title - **Status badge**: Shows "New suggestion" for first notifications or "Updated suggestion" for follow-ups - **Description**: A short excerpt of the suggestion description - **Triggered by**: A descriptive label linking to the source that triggered the suggestion, such as "Merged GitHub PR #123 in acme/docs" or "Slack direct @mention" - **Files**: The number of files changed - **Status**: The current suggestion lifecycle status (Open, Pull Request, Published, or Rejected) Slack suggestion preview card showing the title, description, files with line change stats, Triggered by link, created timestamp, Pull Request status badge, and Publish and Review in Promptless buttons ## Microsoft Teams notifications When the [Microsoft Teams integration](/docs/reference/integrations/microsoft-teams) is connected, you can have Promptless announce documentation suggestions in a Teams channel by setting `msteams_channel` in your policies. Unlike Slack channels, which use a name, Teams channels are addressed by their conversation ID—a value that looks like `19:…@thread.tacv2`. Copy it from Teams; it's the same ID you use for an `msteams_listen` trigger. `slack_channel` and `msteams_channel` are independent, so a single policy can notify Slack, Teams, or both. ## Suggestion status updates When enabled, Promptless posts a follow-up reply in each suggestion's original Slack thread when the suggestion resolves. This closes the loop for anyone who requested documentation updates via Slack. Promptless posts a follow-up when a suggestion reaches one of these final states: - **Merged** — The documentation PR was merged - **Closed** — The documentation PR was closed without merging - **Rejected** — The suggestion was rejected from the dashboard - **Archived** — The suggestion was auto-archived for staleness Delivery is best-effort. The lifecycle transition always completes, even if the Slack post fails. ### Enable status updates 1. Go to **Organization Settings** in the [Promptless dashboard](https://app.gopromptless.ai/settings) 2. Find the **Suggestion Status Updates** section 3. Check **Post Slack follow-ups when suggestions are resolved** 4. Save your changes Once enabled, follow-ups appear in the Slack thread where Promptless originally announced each suggestion. ## Get help Need help configuring your notification preferences? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai) and we'll help you set up the customizations that work best for your team. *** title: Teach conventions with feedback url: https://promptless.ai/docs/tune/teaching-conventions description: Learn all the ways to give feedback on Promptless suggestions and teach it your team's durable documentation conventions --- import { Aside } from '@astrojs/starlight/components'; Feedback on a Promptless suggestion does two things at once: it fixes the suggestion in front of you, and—when you save it—it teaches Promptless a durable convention that it applies to every future suggestion. You can give feedback from the Promptless dashboard in four ways—request changes, inline feedback, overall comments, and close feedback—or directly in a GitHub PR comment. Each dashboard method lets you request an immediate change, remember the preference for future suggestions, or both. ## 1. Request changes Use the **Request Changes** button at the top of any suggestion to request updates. Provide multiple pieces of feedback at once, and Promptless will address them all together. Request Changes button with text field and example suggestions The interface includes common examples to get you started: - "Put X file's content as a section in Y file instead of making it its own file" - "Make the tone more conversational, and do that for all future suggestions too" - "I always want changelog entries in their own suggestion—please move" Click **Submit Request** to process all your feedback. ## 2. Dashboard inline feedback Add feedback to specific files or sections within a suggestion in the Promptless dashboard. Click **Edit** or **Add Comment** on any file to provide context-specific input. This is different from GitHub's inline comments. Dashboard inline feedback appears only in the Promptless web interface. Dashboard inline feedback buttons showing Edit and Add Comment options When you add inline feedback, you'll see a feedback panel with two options: Feedback panel with checkboxes for immediate changes and future learning **Request changes on this suggestion**: Promptless will apply your feedback to the current suggestion. You can add multiple comments and submit them all at once. **Remember feedback for future suggestions**: Promptless saves your preferences and applies them to future documentation. This helps it learn your style and standards over time. **Examples of feedback to remember:** - "Always include code examples for API endpoints" - "Use active voice instead of passive voice" - "Include troubleshooting sections for configuration guides" ## 3. Overall comments Leave general feedback about a suggestion without targeting a specific file. This is useful for high-level guidance or when your feedback applies to the entire suggestion. Overall comments section with text field and feedback options Like dashboard inline feedback, you can choose whether to request immediate changes or remember the feedback for future suggestions. ## 4. Close suggestion feedback When closing a suggestion, provide feedback about why you're rejecting it. This helps Promptless improve future suggestions. Close suggestion dialog with reason checkboxes and optional feedback field Select one or more reasons: - "I copied this change into my docs editor" - "This change is incorrect" - "This change is too insignificant" - "This change was covered in another Promptless suggestion" - "This is already in my docs" - "This change is self-explanatory and doesn't need docs" You can also provide additional context in the feedback field. Check "Remember this feedback for future suggestions" to save your preferences. ## 5. GitHub PR comments After Promptless opens a documentation PR, you can leave feedback directly in GitHub. GitHub comments are separate from dashboard feedback—they won't appear in the Promptless web interface, but Promptless will still process them. Tag @Promptless in any line comment to request changes. Promptless reads all previous comments in the thread to understand context, so you can give brief instructions like "same change here" or "apply this to the other sections too." GitHub PR comment showing feedback with @Promptless mention Need help? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Use the web interface url: https://promptless.ai/docs/work-the-queue/web-interface description: Learn how to use Promptless's web interface to highlight text, provide feedback, and guide documentation improvements --- ## Suggestions list The suggestions list shows all documentation suggestions awaiting your review. Each suggestion card includes chips that help you identify key details at a glance: - **Docs target**: A chip with a document icon shows which doc collection the suggestion targets. Hover over the chip to see the full repository path, or click it to filter the list to suggestions targeting that collection—especially useful if your organization has multiple doc collections. - **Archiving soon**: Suggestions approaching auto-archive display an orange chip. Hover over it for details about auto-archive behavior. Viewing or editing a suggestion resets the timer. Suggestions are automatically archived after 30 days by default. Organizations with longer review cycles can request an extended archiving window—contact help@gopromptless.ai to adjust this for your team. If a suggestion does get auto-archived before you can review it, we can also restore it for you. ## Suggestion overview Each suggestion includes a title and description that explains what changes are being made and why. Suggestion description with markdown formatting showing bold headers and bullet lists ## Markdown preview Preview how Markdown and MDX files will render before publishing. Click **Preview Markdown** on any `.md`, `.mdx`, or `.markdown` file to open a preview modal with diff highlighting—added content appears with a green background and left rail, removed content shows red. This helps you review formatting, headings, lists, tables, and code blocks in context without switching between raw diff and published views. ## Provide feedback Promptless offers several ways to provide feedback on suggestions. Learn about all available feedback methods in the [Teaching conventions with feedback](/docs/tune/teaching-conventions) guide. ## Bulk opening pull requests When you have multiple suggestions ready to publish, you can open PRs for all of them at once. 1. Click **Select** in the suggestions list toolbar to enter select mode. 2. Check the suggestions you want to include. Use **Select all matching** to select all suggestions that match your current filters. 3. Click **Open N PRs** in the floating action bar at the bottom of the screen. 4. Review the confirmation dialog—it shows how many PRs will be opened and how many will be skipped. 5. Click **Confirm** to start opening PRs. A progress banner tracks each suggestion as it completes. **Suggestions that will be skipped:** - Suggestions that already have an open or draft PR - Suggestions with no content (no files changed) - Closed suggestions If any requests fail, use **Retry failed** to retry them. Press **Esc** at any time to exit select mode. ## Deep Analysis Deep Analysis handles large, complex documentation requests that may take several hours to complete and produce multiple suggestions. To enable it, check **Deep Analysis** when creating a New Task. The form expands to show templates for common request shapes like refactoring a section of docs, auditing for consistency, or writing docs from scratch. For details on when to use Deep Analysis and how to submit requests, see the [Deep Analysis guide](/docs/get-the-most-out/pay-down-docs-debt). ## Triggers page The Triggers page shows all events that triggered Promptless over the last 30 days. Each entry displays: - **Trigger source**: The event that fired (like a GitHub PR or Slack message) - **Status**: Processing state (completed, in progress, or error) - **Suggestions created**: Whether documentation updates resulted from this trigger - **Timestamp**: When the trigger occurred Triggers page showing recent trigger events ### Filter and search Use the search box to find triggers by PR info, Slack thread topic, task name, or other summary text—including events older than 30 days. The type and suggestion status filters help narrow results further. The **From** and **To** date fields filter by a specific date range. Date filtering searches your full trigger history, not just the default 30-day window. Clear the dates to return to the default view. ### Group triggers The **Group by** control organizes the trigger list: - **None**: Flat list, newest first (default) - **Event source**: Groups triggers by platform (GitHub, Slack, etc.) with the most recently active source first - **Date**: Groups triggers by day with headers like "Today", "Yesterday", or the calendar date Click any group header to collapse it—a count pill shows how many triggers are hidden. Click again to expand. Click any trigger to see full details, including what research Promptless did and why it created (or skipped) documentation updates. Need help with the web interface? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Review and edit Promptless PRs url: https://promptless.ai/docs/work-the-queue/reviewing-prs description: Learn how to provide follow-up instructions through GitHub PR comments and reviews after your documentation PR is opened --- import { Aside, Steps } from '@astrojs/starlight/components'; After Promptless opens a docs PR, you can provide follow-on instructions directly through GitHub comments. Promptless automatically handles quality issues (like linter failures, Vale warnings, or broken links) that arise in documentation PRs, so manual feedback can focus on content improvements rather than technical fixes. ## Comment trigger modes Configure how Promptless responds to comments on documentation PRs: **Listen to all comments** (default for new organizations): Promptless processes all human comments on documentation PRs automatically. To have Promptless ignore a specific comment, start it with `aside` or `/aside`. **Require @promptless mentions** (default for existing organizations): Promptless only responds when you tag @promptless in a comment. ## Mentions from automated accounts A direct `@Promptless` mention works even when the comment comes from an automated account rather than a person. For example, if a CI or review GitHub Action posts a comment that tags `@Promptless` on a documentation PR after a check runs, Promptless treats it as a follow-on request and acts on it, just as it does with a comment from a teammate. Bot comments that don't mention Promptless are ignored. ## Review in the dashboard Every PR that Promptless opens includes a dashboard link at the top of the description for additional context. When you click the dashboard link, you can: - **View citations**: See the exact GitHub files, PRs, and commits Promptless referenced - **Read the reasoning process**: Understand why Promptless made specific updates - **Review full context**: Access all source material Promptless analyzed, including Slack threads, issue tickets, and related conversations Use the dashboard to verify updates or understand the background behind changes. ## Two ways of providing feedback ### 1. Individual comments Leave individual comments on specific lines or sections of the documentation PR for targeted feedback. If your organization uses **Listen to all comments** mode, just leave your comment—Promptless will process it automatically. In **Require @promptless mentions** mode, tag @promptless in the comment (it won't show up in auto-complete, but Promptless will still see it). Promptless automatically reads all previous comments in the PR to understand the full context. This means your instructions can be as simple as "Same here" or "Apply this change to the other section too." ### 2. PR reviews Start a review to provide multiple pieces of feedback that Promptless can handle all at once. 1. **Start a Review.** Click "Review changes" to begin a formal review process, or select "Start a review" when adding an in-line comment. 2. **Add Multiple Comments.** Continue adding comments as part of the review. 3. **Submit Your Review.** Click "Finish your review" and submit. In **Listen to all comments** mode, Promptless processes the review automatically. In **Require @promptless mentions** mode, tag @promptless in the review summary. ## Examples of feedback you can give to Promptless ### Content updates Request specific changes to the documentation content: ```txt wordWrap Please add a section about error handling for this API endpoint ``` ```txt wordWrap This example should use TypeScript instead of JavaScript ``` ```txt wordWrap Add a note that this feature requires admin permissions ``` ### Structural changes Suggest improvements to the documentation structure: ```txt wordWrap Move this section to the beginning of the page for better flow ``` ```txt wordWrap Split this into two separate sections: "Basic Usage" and "Advanced Configuration" ``` ```txt wordWrap Add a table of contents at the top of this page ``` ### Technical corrections Point out technical inaccuracies or missing details: ```txt wordWrap The API endpoint should be /v2/users, not /v1/users ``` ```txt wordWrap Add the required headers for authentication ``` ```txt wordWrap Include the response status codes for each endpoint ``` ### Style and formatting Request improvements to presentation and readability: ```txt wordWrap Format this as a code block instead of inline code ``` ```txt wordWrap Add syntax highlighting for the JSON examples ``` ```txt wordWrap Use a callout box to highlight this important warning ``` Need help with GitHub PR interactions? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Review from Slack and Teams url: https://promptless.ai/docs/work-the-queue/reviewing-from-slack-and-teams description: Learn how to use Promptless directly in Slack and Microsoft Teams through message actions, DMs, channel mentions, and passive listening --- import { Aside, Steps } from '@astrojs/starlight/components'; ## Four ways to interact in Slack ### 1. Message actions Use Slack's message actions to quickly trigger documentation updates from any message or thread. This is best used when you don't want to interrupt the flow of the conversation. 1. **Access Message Actions.** Click the three dots (⋯) menu on any Slack message to open the message actions menu.
Slack context menu with Promptless options including Update Docs, Create task in Notion, and Create an Issue
Slack message actions menu showing Promptless integrations
2. **Select Update Docs.** Choose "Update Docs" from the message actions menu to trigger Promptless. If you don't see the option, click on "More message shortcuts" and search for Promptless. 3. **Review Generated Content.** Promptless analyzes the full thread to generate relevant documentation updates, and DMs you once it's done. ### 2. Channel mentions Tag Promptless directly in any channel to trigger documentation updates from ongoing discussions. 1. **Mention Promptless.** Tag Promptless bot in a new message or in a thread reply in a channel, along with instructions about how to update the docs, you can add internal and external links, slack links, as well as images. Don't forget to add Promptless bot to the channel if you're tagging it for the first time! 2. **Thread Context Analysis.** Promptless analyzes the entire thread context to understand the discussion and generate relevant documentation. You can point Promptless to specific pages, or Promptless can infer based on the context. ### Example instructions ```txt wordWrap @Promptless please also add a troubleshooting section covering the error cases we discussed earlier in this thread ``` ```txt wordWrap @Promptless make sure to mention that this feature is only available in the Enterprise plan ``` ```txt wordWrap @Promptless create a mermaid chart for the system architecture discussed in this thread ``` ```txt wordWrap @Promptless capture a screenshot of the new export dialog from our staging environment and add it to the export feature docs ``` ### Inline citations in research replies When you ask Promptless a research question that requires fetching external URLs—documentation sites, articles, or video transcripts—the reply includes inline links citing each fact back to its source. The linked phrase is the specific claim or number, not the full sentence. For example, if you ask about API rate limits and Promptless fetches your docs and source code, the reply might look like: > The hard rate limit on `/v1/embed` is **60 requests per minute per API key**, enforced by the gateway's `rate_limiter.py` config. Each bolded term links directly to its source—the rate limit number links to your API reference, and the file name links to the repository. If a fetch fails, Promptless acknowledges the gap and still links to the URL it tried: > **Live status:** unverified. Your status page returned 503 when I checked, so I can't confirm whether you're currently throttled. Only sources that shaped the answer appear as citations. Background reads, dead ends, and unused fetches are omitted. ### 3. Direct messages (DMs) Send direct messages to Promptless for private documentation requests or when you have very specific instructions. 1. **Start a DM.** Go to the Apps section in Slack, click on the Promptless bot. 2. **Describe Your Request.** Type your documentation request or paste content you'd like to turn into documentation. You can post internal or external links, slack links, images, etc. You don't have to tag Promptless here. 3. **Wait for Promptless DM.** Promptless DMs you with the doc updates. ## Use images and file attachments You can attach images and files when you trigger Promptless in Slack to provide additional context. Include screenshots, diagrams, design mockups, API responses, or configuration files in the same thread where you tag @Promptless or use the "Update Docs" action. When you trigger Promptless, it reviews all text and attached files in the thread. If an image or file content is valuable for the documentation, Promptless incorporates it into the suggested updates. ### Examples **Adding a screenshot to explain a feature** ```txt wordWrap @Promptless please document this new export feature. I've attached a screenshot showing the new export dialog. ``` **Including an architecture diagram** ```txt wordWrap @Promptless update the technical architecture page with this new system diagram (attached) ``` **Documenting an error message** ```txt wordWrap @Promptless we need to add troubleshooting docs for this error. See the screenshot above for the exact error message users are seeing. ``` **Using design specs** ```txt wordWrap @Promptless here's the design spec for the new onboarding flow (PDF attached). Please create documentation that matches this flow. ``` For technical details about how images are processed and managed, see the [Slack Integration page](/docs/reference/integrations/slack). ## Request screenshot captures If your organization has screenshot capture enabled, you can ask Promptless to capture fresh screenshots from your staging or production environment. Promptless navigates to your web application, captures the UI, and includes the screenshot in your documentation. ### Examples **Capturing a specific feature** ```txt wordWrap @Promptless capture a screenshot of the user settings page from staging and add it to the account management docs ``` **Updating existing screenshots** ```txt wordWrap @Promptless the dashboard screenshot in our getting started guide is outdated—can you capture a fresh one from production? ``` **Capturing multiple screens** ```txt wordWrap @Promptless we need screenshots of the new onboarding flow. Please capture the welcome screen, the team setup page, and the final confirmation from staging. ``` ### 4. Passive channel listening Have Promptless automatically monitor specific Slack channels and create documentation updates without requiring @mentions or message actions. This is ideal for documentation-focused or support channels where discussions frequently reveal documentation needs. When passive listening is enabled, Promptless monitors all messages in your selected channels and automatically creates documentation suggestions when threads become inactive. Add a `slack_listen` trigger to your [Configuration page](https://app.gopromptless.ai/configuration): ```yaml triggers: support-channels: trigger_type: slack_listen match: - channels: - customer-support - docs-feedback ``` Channel names don't need the `#` prefix. See the [Configuration Reference](/docs/reference/configuration-reference#triggers) for details.
Will Promptless create a new suggestion for every new message in the thread? No. When passive listening is enabled, Promptless waits for a thread to go quiet before analyzing it. This prevents creating redundant suggestions as conversations evolve. If new messages are added to a thread that Promptless has already processed, Promptless can update its existing suggestion rather than creating a duplicate. This means even if there are multiple triggers for the same thread, you see updates to a single suggestion rather than a flood of separate suggestions. **Tip**: If you @mention Promptless in a thread that's being passively monitored, it triggers immediately rather than waiting for the thread to go quiet.
## Thread auto-reply Once Promptless has been triggered in a Slack thread—through a message action, channel mention, DM, or passive listening—it keeps listening for new replies in that thread without needing another @mention. This makes it easy to refine a suggestion, add context, or share images and files as the conversation continues, without having to remember to tag `@Promptless` every time. Promptless reasons about each new reply to decide whether it's actionable, so not every message produces a documentation update. To explicitly tell Promptless to ignore a message, start it with `aside` or `/aside`: ```txt wordWrap aside @InlinePizza are these the ones your thing found or were there more? ``` ### Configure thread replies Thread auto-reply is configured per organization. From your **Organization Settings**, choose between: - **Listen to all replies** (default): Promptless evaluates every reply in threads where it's participating. - **Require @promptless**: Promptless only processes replies that explicitly @mention it. For setup instructions, see [Thread Reply Trigger Mode](/docs/connect/triggers/slack-messages#thread-reply-trigger-mode) in the Configuring Promptless guide. ## Microsoft Teams Promptless works the same way in Microsoft Teams as it does in Slack: you trigger it from a conversation, and it drafts documentation updates for you to review and approve. - **Tag @Promptless in a channel**: Mention @Promptless in a Teams channel with your instructions, and it analyzes the conversation to draft relevant updates. - **Send a direct message**: DM @Promptless for private documentation requests. - **Passive channel listening**: Add an `msteams_listen` trigger to monitor selected channels and draft suggestions automatically, without an @mention. Like Slack listening, this is opt-in—Promptless only monitors the channels you explicitly select. Once the Teams integration is connected, @Promptless mentions are always active—no YAML configuration required. For the trigger types, passive-listening setup, and publishing behavior, see [Microsoft Teams messages](/docs/connect/triggers/microsoft-teams-messages). Need help with Slack or Teams interactions? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Keep screenshots current with Promptless Capture url: https://promptless.ai/docs/get-the-most-out/screenshots description: Use Promptless Capture to keep product screenshots in sync with your UI, regenerating them from your current interface when code changes --- import { Aside, Steps } from '@astrojs/starlight/components'; Promptless Capture keeps product screenshots in sync with your UI. When code changes affect a documented feature, Promptless Capture identifies which screenshots need updating and regenerates them from your current interface. ## Set up credentials Promptless Capture needs credentials to authenticate with your application. Configure these as environment variables in your organization settings. 1. **Navigate to Settings.** Go to the [Settings page](https://app.gopromptless.ai/settings) in your Promptless dashboard and select the **Environment Variables** section. 2. **Add Credential Variables.** Add variables for your application's login credentials. The variable names are flexible—use whatever naming convention works for your team. For example: | Variable Name | Description | Mark as Secret | |---------------|-------------|----------------| | `TEST_ACCOUNT_URL` | The login URL for your application | No | | `TEST_ACCOUNT_USER` | Username or email for the test account | No | | `TEST_ACCOUNT_PASS` | Password for the test account | Yes | You might use names like `STAGING_LOGIN_URL`, `QA_USER`, or any descriptive names that fit your organization's conventions. 3. **Save Variables.** Click **Save** to store your environment variables. Variables marked as secrets will have their values hidden after saving. ## Test your setup After adding your credentials, verify that Promptless can capture screenshots correctly. 1. **Start a Manual Task.** Go to the [New Task page](https://app.gopromptless.ai/new-task) and request a documentation update that involves screenshots. 2. **Review the Results.** Check the suggestion to see if screenshots were captured correctly. Look for: - Successful authentication (no login screens in screenshots) - Correct page navigation (screenshots show the intended feature) - Appropriate cropping (relevant UI elements are visible) 3. **Iterate on Configuration.** If screenshots aren't captured correctly, adjust your environment variables or provide additional context in your Long-Term Context files. ## Troubleshooting
Promptless can't log into my application Verify that your `TEST_ACCOUNT_URL`, `TEST_ACCOUNT_USER`, and `TEST_ACCOUNT_PASS` variables match what you use to manually log in. If your screenshots show the login page, the credentials may be incorrect or the login flow may require additional steps. For applications that use multi-factor authentication, consider creating a test account that bypasses MFA, or contact help@gopromptless.ai for guidance on handling MFA flows.
Screenshots capture the wrong page Promptless may need additional navigation guidance. You can add instructions in your Long-Term Context to describe how to navigate to specific features. Include details about menu paths, URL patterns, or button sequences needed to reach documented screens.
Screenshots show features that should be hidden Check your feature flag configuration. The test account may have access to features that typical users don't see. Consider creating a test account with permissions that match your target documentation audience.
Cropping cuts off important elements The automatic cropping may need refinement. You can use the Screenshot Editor in the Promptless dashboard to manually adjust crops, or provide feedback that Promptless will learn from for future captures.
Screenshots show loading states or spinners The page may not have fully loaded before capture. Contact help@gopromptless.ai if you consistently see loading states in your screenshots.
## Screenshot Editor After Promptless captures screenshots, you can refine them in the built-in Screenshot Editor. Click any image in the Created Assets section to open the editor. ### Editing tools The editor includes tools to refine your screenshots: - **Crop** to focus on specific UI elements - **Annotate** with arrows, boxes, and highlights - **Add text** to call out features - **Adjust** image dimensions ### Manage edits The toolbar provides controls for your editing session: - **Save edits** commits changes to the screenshot - **Reset edits** discards unsaved changes and reverts to the last saved version—useful for starting over without closing the editor - **Cancel Crop** exits crop mode without applying the crop, letting you adjust the selection or switch tools Saved changes are immediately reflected in your documentation suggestions. ## When screenshots update automatically Promptless Capture monitors your triggers and automatically updates screenshots when: - A GitHub PR modifies UI components referenced in documentation - A commit changes routes, layouts, or visual styling - You explicitly request a screenshot update via Slack or the web interface Need help setting up Promptless Capture? Contact us at help@gopromptless.ai. *** title: Pay down docs debt with Deep Analysis url: https://promptless.ai/docs/get-the-most-out/pay-down-docs-debt description: Submit large, complex documentation requests that require extended research and may create multiple suggestions across your docs --- import { Aside, Steps } from '@astrojs/starlight/components'; Use Deep Analysis when a request needs more research or scope than a regular trigger can handle. Instead of producing a single drive-by edit, Promptless reviews your source code, audits your existing docs, and returns a coordinated set of suggestions. ## When to use Deep Analysis Deep Analysis is built for projects that span multiple pages, need background research, or call for a coherent plan before any edits land: - **Refactoring documentation sections** — restructure or rewrite an entire section to match a new pattern or stronger examples. - **Documentation audits** — check the whole collection for consistency, accuracy, or style compliance. - **Writing docs from scratch** — produce comprehensive documentation for a new feature or product. - **Filling in OpenAPI specs** — add error codes, examples, or other structured data across an API reference. For routine updates, stick with Slack, GitHub PR triggers, or a regular New Task. Deep Analysis is heavier and slower, so reach for it when the work genuinely calls for it. ## Submit a request Deep Analysis runs through the New Task form. Check the **Deep Analysis** box and the form expands to show templates and a larger instructions field. New Task form with Deep Analysis enabled, showing the doc collection selector, template chips, populated instructions field, attachments, delivery settings, and Submit Trigger button 1. **Open New Task.** Click **New Task** in the sidebar. You can also use the [Deep Analysis deep link](https://app.gopromptless.ai/new-task?deep_analysis=true), which opens New Task with Deep Analysis already checked. 2. **Select a doc collection.** Choose the doc collection you want Promptless to update. Only collections that have finished initial analysis appear in the list. 3. **Check Deep Analysis.** Tick the **Deep Analysis** box. Template chips appear and the **Instructions** field expands to give you more room. 4. **Pick a template (optional).** Choose a template to pre-fill the **Instructions** field with a starter prompt. Templates include placeholder hints in `{curly braces}` so you know what context to add. Pick **None** to start from a blank field. 5. **Write the instructions.** Describe the project in the **Instructions** field. Include the product area, source code or APIs Promptless should inspect, examples to model, and the changes you want to focus on. There is no separate title field — the first line of your instructions becomes the request title. 6. **Attach files (optional).** Use **Add files** or paste directly into the field to attach supporting material like screenshots, PDFs, or specs. You can include up to 5 files, 10 MB each. 7. **Choose delivery settings.** Pick a Slack channel to receive progress notifications, or leave it as **No Slack notification**. If your doc collection is backed by GitHub, you can also check **Create PRs automatically for this task's suggestions** to skip the manual review step for each suggestion this run produces. 8. **Submit.** Click **Submit Trigger**. Promptless confirms the submission and links to the Triggers page so you can follow progress. ## Templates Deep Analysis ships with four templates for the most common project shapes: - **Refactor a bad section of docs** — improve an existing section using another set of docs as a model. - **Add error codes to OpenAPI spec** — add comprehensive error codes and examples to your API specification. - **Write docs from scratch** — produce new documentation with guidance on outline, audience, and style. - **Audit for consistency** — review all documentation for consistent terminology, formatting, and structure. Each template seeds the **Instructions** field with a title line, a description, and bracketed placeholders that prompt you for the context Promptless needs. You can edit the prefilled text freely before submitting. ## What happens after you submit A Deep Analysis trigger is routed to a fresh agent with the Deep Analysis workflow enabled. Before drafting any documentation, that agent runs two mandatory research passes: - A **source code review** of the configured source repos to confirm how the feature actually behaves today. - A **docs audit** of the target collection to find related pages, gaps, duplicates, terminology, and writing conventions. Once both reviews are complete, the agent plans the work and produces one or more suggestions. The trigger appears on the Triggers page labeled `Deep Analysis: `, so it's easy to spot among regular tasks. If Slack is connected and you picked a notification channel, Promptless posts updates there as the run progresses and again when the suggestions are ready for review. Need help with Deep Analysis? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Build an agent knowledge base url: https://promptless.ai/docs/get-the-most-out/agent-knowledge-base description: View and edit the files that help Promptless understand your documentation style, product context, and workflow preferences --- import { Aside } from '@astrojs/starlight/components'; Promptless updates these files automatically as it learns from your feedback. Organization admins can edit them directly, while other members have read-only access. ## Access the Agent Knowledge Base In the left sidebar, open **Configure** and select **Agent Knowledge Base** (the book icon). Agent Knowledge Base interface showing the file tree, recent updates, and editor ## Recent updates by Promptless View recent updates Promptless has made to these files based on your feedback. Each update includes: - Date of the update - Files changed - Link to the suggestion that triggered the update This shows how your feedback shapes Promptless's understanding of your documentation preferences. ## Knowledge Base files | File | Purpose | |------|---------| | `client_instructions.md` | Guidelines for how Promptless approaches documentation tasks. Updated when Promptless learns new preferences from your feedback. | | `default_plan_skeleton.md` | Template structure for documentation plans. Updated when you provide feedback on plan organization. | | `product_overview.md` | High-level context about your product. Generated during initial setup—you can edit this directly or request Promptless to regenerate it. | | `client_style_guide.md` | Writing style rules and conventions. If your repo includes a style guide or Vale rules, reference those files here. Promptless updates this file as it learns your style preferences from feedback. | ## View files Click any file in the tree view to open it in the editor. All organization members can view these files to understand how Promptless has been configured. Agent Knowledge Base showing a file selected in the tree and its content in the editor ## Edit files To edit a file: 1. Make your changes in the editor 2. Click **Save** 3. Your changes are committed directly to the repository ## Create files Click the **+** button next to any folder to create a new file inside it, or click the new-file icon at the root to create a top-level file. In the dialog: 1. Enter a file name (without the `.md` extension—Promptless adds it automatically) 2. Click **Create** The file opens in the editor immediately. To create nested paths, enter `nested/path/filename` in the dialog—Promptless creates any intermediate folders automatically. ## How Promptless uses these files Promptless reads these files at the start of every documentation task to understand your documentation approach, product terminology, and writing style. When you provide feedback on suggestions—through PR comments, the web interface, or Slack—Promptless may update these files to apply what it learned to future tasks. Need help? Contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Manage environment variables url: https://promptless.ai/docs/scale/environment-variables description: Store credentials, API keys, and configuration values that Promptless uses when interacting with your systems, and mark sensitive values as secrets --- import { Aside, Steps } from '@astrojs/starlight/components'; Environment variables store credentials, API keys, and configuration values that Promptless uses when interacting with your systems. The most common use case is storing login credentials for [Promptless Capture](/docs/get-the-most-out/screenshots) to capture product screenshots. ## Add environment variables 1. **Open Settings.** Navigate to the [Settings page](https://app.gopromptless.ai/settings) in your Promptless dashboard. 2. **Find Environment Variables.** Select the **Environment Variables** section to view and manage your variables. 3. **Add a Variable.** Click the **Add Variable** button. Enter a name and value for your variable. Use clear, descriptive names that indicate the variable's purpose. 4. **Mark Sensitive Values as Secret.** For passwords, API keys, and other sensitive values, check the **Secret** option. Secret values are encrypted and hidden in the dashboard after saving. 5. **Save Changes.** Click **Save** to store your environment variables.
Environment Variables settings page showing existing variables and the Add Variable form
Environment Variables settings page
## Keep secrets secure
Add Variable form with Secret checkbox enabled
Adding a secret environment variable
Variables marked as secrets are encrypted and hidden in the dashboard after saving. Use this option for passwords, API keys, and other sensitive values. ## Example: Screenshot capture credentials For [Promptless Capture](/docs/get-the-most-out/screenshots), add these variables to let Promptless log into your application: | Variable | Example Value | Secret? | |----------|---------------|---------| | `TEST_ACCOUNT_URL` | `https://app.yourcompany.com/login` | No | | `TEST_ACCOUNT_USER` | `qa-screenshots@yourcompany.com` | No | | `TEST_ACCOUNT_PASS` | `(your password)` | Yes | ## Update and delete variables To update an existing variable, locate it in the Environment Variables section and edit its value. For secret variables, you'll need to re-enter the entire value since the original is not displayed. To delete a variable, click the delete icon next to the variable. Deleted variables are immediately removed and will no longer be available to the Promptless agent. Need help? Contact us at help@gopromptless.ai. *** title: Doc Detective integration url: https://promptless.ai/docs/audit/doc-detective description: Test documentation workflows against your actual product with Promptless and Doc Detective --- import { Aside } from '@astrojs/starlight/components'; Docs describe how your product works. Every setup guide, UI walkthrough, CLI example, and API tutorial contains product assertions: this button exists, this command succeeds, this page appears, this link works. Promptless uses [Doc Detective](https://docs.doc-detective.com/) to make each of those assertions executable. Doc Detective is an open-source implementation of the [Docs as Tests](https://www.docsastests.com/docs-as-tests/concept/2024/01/09/intro-docs-as-tests.html) framework: documentation should be tested against the real product experience, not just proofread for style or checked for broken links. ## What Promptless does When Doc Detective is enabled on a doc collection, Promptless treats tests as part of keeping your docs current. Promptless can: - Create Doc Detective tests when new documented workflows, UI paths, commands, or setup procedures are added - Update existing Doc Detective tests when product changes make the old workflow stale - Reuse your existing Doc Detective config and test layout instead of inventing a separate structure - React to CI failures on Promptless documentation PRs, inspect the failing checks, and update the suggestion branch when the failure is caused by the docs change This means Promptless can update both the prose and the executable test coverage for a feature. If a new feature changes the product, Promptless can document the change and add the checks that prove the documented workflow still works. ## Setup Enable Doc Detective from your doc collection settings. 1. Open the Promptless dashboard. 2. Go to your doc collection. 3. Click the edit button. 4. Enable **Doc Detective**. 5. Optionally enter the repo-relative path to your Doc Detective config file, such as `.doc-detective.json`, `.doc-detective.yaml`, or `.doc-detective.yml`. If you leave the config path empty, Promptless still knows Doc Detective is enabled and will inspect the repository for existing Doc Detective specs and config files before adding coverage. ## CI failure handling Doc Detective is most useful when it runs in CI with the rest of your documentation checks. When a GitHub check suite fails on an open Promptless docs PR, Promptless: 1. Resolves the failing PR back to the Promptless suggestion that created it. 2. Fetches the failing check runs and a preview of the logs. 3. Starts a follow-on investigation with the PR, failing check names, conclusions, and log preview. 4. Determines whether the failure was caused by the suggestion. If the failure is caused by the suggestion, Promptless updates the suggestion branch with the fix. If the failure is pre-existing or unrelated, Promptless leaves the suggestion scoped to its original work. If it finds a separate docs issue outside the suggestion's scope, it can create separate work for that issue instead of expanding the original PR. This lets Doc Detective failures become actionable maintenance signals instead of another queue for your team to triage manually. *** title: Vale integration url: https://promptless.ai/docs/audit/standards-enforcement description: Enforce prose style standards in documentation suggestions with Vale --- import { Aside } from '@astrojs/starlight/components'; [Vale](https://vale.sh/) is an open-source prose linter that enforces style rules across documentation. When Vale is configured for a doc collection, Promptless lints prose before creating suggestions, catching style violations before they reach your review queue. ## What Promptless does When Vale is enabled, Promptless: - Downloads external style packages your config references when those styles aren't already vendored in your repository. - Lints every prose file it creates or substantially edits. - Fixes findings according to your config's `MinAlertLevel`: when you set an alert level, Promptless fixes every finding Vale reports; when it's unset, Promptless treats error-severity violations as blocking and fixes them before creating the suggestion. This keeps suggestions aligned with your style guide from the start, reducing back-and-forth during review. ## Setup Vale is enabled automatically when Promptless detects a Vale configuration file in your docs repository. ### Automatic detection During doc collection setup, Promptless scans your repository for `.vale.ini` or `vale.ini`. If found, Vale linting activates automatically using that config file's location. ### Manual configuration You can also set the Vale config path manually: 1. Open the Promptless dashboard. 2. Go to your doc collection. 3. Click the edit button. 4. Under **Vale config**, enter the repo-relative path to your Vale configuration file (e.g., `.vale.ini` or `docs/.vale.ini`). ## How it works Promptless runs Vale after drafting prose content: 1. **Sync packages** - Downloads any external style packages your config references. 2. **Lint prose** - Runs Vale on created or edited prose files. 3. **Apply your alert level** - Reads your config's `MinAlertLevel` and uses it to decide which findings to fix (see [Severity handling](#severity-handling)). 4. **Match your CI** - Reads the Vale job in your repository's GitHub Actions workflows and reproduces that invocation locally on the changed files, confirming they pass before creating the suggestion. Vale only runs on prose content. Code blocks, commands, configuration, frontmatter, schemas, and tables are excluded from linting. ## Severity handling Vale classifies violations into three severity levels: | Severity | Behavior | |----------|----------| | **error** | Blocking. Promptless fixes these before creating the suggestion. | | **warning** | Advisory. Promptless evaluates against your existing style and fixes when appropriate. | | **suggestion** | Advisory. Promptless considers these but may preserve intentional style choices. | Promptless treats findings depends on whether your config sets `MinAlertLevel`. ### When MinAlertLevel is set Setting `MinAlertLevel` is a deliberate choice about the severity bar your docs hold to, so Promptless honors it and fixes every finding Vale reports at or above that level, including warnings and suggestions. This mirrors what your Vale CI surfaces, so Promptless resolves the findings you'd otherwise see as review comments before the suggestion reaches you. For example, with `MinAlertLevel = suggestion`, Promptless fixes every error, warning, and suggestion Vale reports. To have Promptless fix fewer findings, raise the level (for instance, to `warning` or `error`) rather than relying on it to weigh advisory results. ### When MinAlertLevel is unset When your config doesn't set `MinAlertLevel`, Promptless falls back to treating error-severity rules as hard constraints, while Promptless treats warning and suggestion rules as guidance and balances them against the established voice and conventions in your docs. ## CI integration Vale errors that slip through or arise from later edits are caught by Promptless's automated CI handling. When Vale fails in a GitHub Actions workflow on a Promptless PR, Promptless analyzes the failure and pushes fixes to the branch automatically. This works alongside other CI checks like broken link detection and Doc Detective tests, giving you layered quality gates without manual triage. ## Create a Vale config If you don't have a Vale configuration yet, create a `.vale.ini` file in your docs repository root: ```ini StylesPath = .vale/styles MinAlertLevel = warning [*.md] BasedOnStyles = Vale ``` This minimal config enables Vale's built-in rules. For more comprehensive style enforcement, add external packages: ```ini StylesPath = .vale/styles MinAlertLevel = warning Packages = Microsoft, write-good [*.md] BasedOnStyles = Vale, Microsoft, write-good ``` See the [Vale documentation](https://vale.sh/docs/) for detailed configuration options and available style packages. *** title: Understand docs-as-code url: https://promptless.ai/docs/migrate/why-docs-as-code description: Docs-as-code is a prerequisite for Promptless — understand what it means and why moving to a Git-backed stack unblocks automated documentation updates --- import { Aside } from '@astrojs/starlight/components'; Promptless keeps your documentation current by opening pull requests against the repository that holds your content. That model works when your docs live in a repository as files a pull request can change — the approach known as **docs-as-code**. If your team is still on a hosted platform that stores content in a proprietary database or WYSIWYG editor, moving to docs-as-code is the first step to adopting Promptless. ## What docs-as-code means Docs-as-code treats documentation the same way engineering teams treat source code: - **Content lives in a Git repository** as source files instead of inside a proprietary CMS. Those files are often Markdown or MDX, but they can just as easily be DITA, reStructuredText, a MadCap Flare project, or another authoring format — what matters is that the source lives in Git. - **Changes go through pull requests**, so every edit is reviewable, diffable, and revertable with the same tools your engineers already use. - **A static site generator** builds the published site from those files, so the repository is the source of truth and the live site is a build artifact. Because the content is versioned files rather than database rows, an automated collaborator like Promptless proposes an edit the same way a teammate would: branch, change the files, and open a PR you review before it ships. ## Why Promptless requires it Promptless integrates into your existing workflow rather than replacing it. When a trigger fires — a merged code PR, a Slack thread, a support ticket — Promptless drafts the documentation change, commits it to a branch in your docs repository, and opens a pull request with citations back to the sources that informed it. You review and merge that PR like any other. Every part of that loop depends on the docs being versioned files in a Git repository: - Promptless **reads** the current content to understand your product, voice, and structure. - It **writes** changes as a branch and a reviewable diff. - Your platform **rebuilds** the published site from the merged files. Hosted editors that keep content in a proprietary store don't expose the docs as files a PR can change, so there's nothing for Promptless to branch from or commit to. ## What "supported" looks like Once your documentation lives in a GitHub repository, Promptless publishes to any docs-as-code platform that builds from that source. What matters is a Git-backed source, not a particular tool or file format: Promptless works with Markdown and MDX, and also with DITA, reStructuredText, MadCap Flare, and FrameMaker (through a MIP intermediary). Some platforms aren't natively Git-based but sync or mirror their content to GitHub, and those setups are fully supported too — Promptless only needs to reach the source through a repository it can branch from. See the [supported platforms list](/docs/connect/doc-locations/github-repos#supported-platforms) for the tools teams most often run on Promptless. ## Where to go next If you've confirmed docs-as-code is the move, the rest of this section walks the migration end to end: - [Choose a platform](/docs/migrate/choose-a-platform) — pick a supported static site generator that fits your team. - [Migrate to a new docs platform](/docs/migrate/migrate-to-a-new-platform) — move content off Doc360, ReadMe, Fern, HubSpot, or RoboHelp. - [Preserve URLs and redirects](/docs/migrate/preserve-urls-and-redirects) — keep existing links working after the move. *** title: Choose a platform url: https://promptless.ai/docs/migrate/choose-a-platform description: Pick a Git-backed documentation platform Promptless supports, weighing the tradeoffs between hosted docs tools and open-source static site generators --- import { Aside } from '@astrojs/starlight/components'; The right target docs platform is any Git-backed one that fits how your team works. Promptless supports any documentation platform as long as your content lives in a GitHub repository, so the decision comes down to your team's needs rather than Promptless compatibility. ## What Promptless supports Promptless doesn't require a specific platform — it requires that your content live as files in a GitHub repository it can open pull requests against. Any docs-as-code platform that builds from a Git-backed source works, whether that's a static site generator you host yourself or a hosted docs tool that keeps its content in a repository. Some platforms aren't natively Git-based but sync or mirror their content to GitHub, and those setups are fully supported too. Promptless only needs to reach the source through a repository. ## How to choose Every supported platform works with Promptless, so weigh them on the factors that matter to your team: - **Hosted docs tools vs. open-source generators.** Hosted, docs-focused platforms like Mintlify, Fern, GitBook, and ReadMe pair a managed publishing experience with Git-backed content. Open-source static site generators like Starlight, Docusaurus, MkDocs, Hugo, Nextra, and Vocs give you full control over hosting and theming and no per-seat cost, at the price of owning the build and deploy yourself. - **Content format.** Most static site generators build from Markdown or MDX, though structured-authoring toolchains publish from their own source formats. If your team already authors in the target's format, the migration is mostly moving files; if you're coming from a WYSIWYG editor or a different source format, expect a conversion step (see [Migrate to a new docs platform](/docs/migrate/migrate-to-a-new-platform)). - **Authoring experience.** If writers on your team don't work in code, weigh how each platform handles day-to-day editing — raw Markdown in a repository, an in-app editor, or a Git-backed WYSIWYG. Hosted docs tools tend to offer a friendlier editing surface for non-engineer contributors, while open-source generators expect writers to edit Markdown and use the PR workflow directly. - **Component and API-reference needs.** If you rely heavily on interactive components or generated API references, favor a platform built for that — Fern, Mintlify, and Starlight, for example, have strong API-reference and MDX component support. - **Existing toolchain.** Teams already deploying on a given stack usually hit the least friction by staying close to it — a React/Astro shop lands naturally on Starlight, Docusaurus, or Nextra, while a Python team may prefer MkDocs. ## After you pick Once you've chosen a platform and your content is in a GitHub repository, connect it as a doc collection so Promptless can start proposing updates. See [Doc locations & collections](/docs/connect/doc-locations/github-repos) for the setup steps and the `promptless.yaml` `docs_framework` field. *** title: Migrate to a new docs platform url: https://promptless.ai/docs/migrate/migrate-to-a-new-platform description: Move documentation off Doc360, ReadMe, Fern, HubSpot, or RoboHelp onto a Git-backed docs-as-code stack, preserving content and structure --- import { Aside, Steps } from '@astrojs/starlight/components'; Teams often reach Promptless while still on a hosted platform that doesn't expose their docs as files in a Git repository. Moving that content onto a [supported docs-as-code platform](/docs/migrate/choose-a-platform) is what unblocks adoption. This guide covers the migration pattern every source shares and where the source-specific work lives. ## The migration pattern However you export, the shape of the work is the same across source platforms: 1. **Export your existing content.** Pull your content out of the source platform in the most portable format it offers. Some platforms export Markdown directly; others export HTML or a proprietary format that needs a conversion pass to your target's source format. Capture images and other assets alongside the text so links don't break. 2. **Choose and scaffold a target platform.** Pick a [supported platform](/docs/migrate/choose-a-platform) and scaffold a new project in a GitHub repository. This repository becomes the source of truth for your docs. 3. **Convert and import the content.** Move the exported content into the new project's file and folder structure, converting to the target's source format and conventions. Rebuild the navigation and any frontmatter (titles, slugs, sidebar placement) the new platform expects. 4. **Map old URLs to new ones.** Record where every existing page lands in the new structure so you can preserve inbound links. See [Preserve URLs and redirects](/docs/migrate/preserve-urls-and-redirects) for how to build and apply that mapping. 5. **Connect the repository to Promptless.** Once the content builds and the site is in a GitHub repository, connect it as a doc collection. From that point, Promptless keeps it current. See [Doc locations & collections](/docs/connect/doc-locations/github-repos). ## After the migration With your docs in a GitHub repository on a supported platform: 1. Apply your [URL redirect mapping](/docs/migrate/preserve-urls-and-redirects) so existing links keep resolving. 2. [Connect the repository as a doc collection](/docs/connect/doc-locations/github-repos) and let Promptless finish its [initial analysis of your docs](/docs/connect/doc-locations/how-promptless-learns-your-docs). 3. Configure the [triggers](/docs/connect/triggers) that should start keeping the migrated docs current. Need a hand with any of this? Contact [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Single sign-on (SSO) setup url: https://promptless.ai/docs/security/single-sign-on --- import { Aside } from '@astrojs/starlight/components'; Single Sign-On (SSO) integration enables enterprise organizations to authenticate users through their existing identity provider, streamlining access management and enhancing security across your documentation workflow. ## Supported authentication methods Promptless supports enterprise authentication through industry-standard protocols: - **SAML 2.0**: Compatible with enterprise identity providers including Active Directory Federation Services, Okta, OneLogin, and Azure AD - **OpenID Connect (OIDC)**: Modern authentication protocol supporting Google Workspace, Azure AD, and other OIDC-compliant providers - **Direct integrations**: Native support for Google Workspace and GitHub Enterprise authentication ## Prerequisites Before requesting SSO setup, ensure your organization has: - An active Promptless enterprise subscription - Administrative access to your identity provider - The ability to configure SAML assertions or OIDC claims for user attributes - A verified domain configured in your Promptless organization settings ## Request SSO configuration SSO setup requires coordination between your IT team and Promptless. The process involves providing specific configuration details to our team.
1

Collect Identity Provider Information

Gather the required configuration details from your identity provider:

For SAML 2.0 Integration:

  • Identity Provider (IdP) Entity ID or Issuer URL
  • Single Sign-On Service URL
  • X.509 Certificate (public key for signature verification)
  • Attribute mappings for email, first name, and last name fields

For OpenID Connect (OIDC):

  • Issuer URL (discovery endpoint)
  • Client ID and Client Secret
  • Authorization endpoint and Token endpoint URLs
  • Supported scopes and user attribute claims
2

Submit Configuration Request

Contact our support team (either via your dedicated account manager or by emailing support) and send the following info:

  • Your organization name and verified domain
  • Preferred authentication method (SAML 2.0 or OIDC)
  • The configuration information collected in Step 1
3

Configuration and Validation

Our team will configure the SSO integration and provide:

  • Service Provider (SP) metadata for your identity provider configuration
  • User attribute mapping and role assignment configuration
## Post-configuration user experience Once SSO is active, team members will experience seamless authentication: - **Automatic Identity Provider Redirect**: Users accessing Promptless are redirected to your organization's login portal - **Single Authentication**: After successful IdP authentication, users gain immediate access to Promptless - **Just-in-Time User Provisioning**: New users are automatically created based on their identity provider profile - **Role and Permission Mapping**: User access levels can be synchronized from your identity management system ## Security and compliance benefits SSO integration provides enhanced security controls: - **Centralized Access Management**: Control Promptless access through existing identity management workflows - **Multi-Factor Authentication Enforcement**: Leverage your identity provider's MFA requirements - **Unified Session Management**: Consistent session handling across organizational applications - **Comprehensive Audit Trails**: Complete authentication and access logging for compliance requirements ## Support and implementation For questions about SSO setup or to discuss your organization's specific authentication requirements, contact our enterprise support team at [help@gopromptless.ai](mailto:help@gopromptless.ai). Our team will work directly with your IT department to ensure smooth implementation and integration with your existing security infrastructure. *** title: Preserve URLs and redirects url: https://promptless.ai/docs/migrate/preserve-urls-and-redirects description: Keep inbound links, search rankings, and bookmarks working after a docs migration by mapping old paths to new ones and adding redirects --- import { Aside, Steps } from '@astrojs/starlight/components'; A migration usually changes your page URLs — the new platform lays out paths differently, and section names shift as you restructure. Left unhandled, every inbound link, bookmark, and search result that points at an old URL breaks. Redirects are the difference between a migration your readers never notice and one that scatters 404s across your traffic. ## Build a URL map Before you flip the switch, record where every old URL lands in the new structure. A simple two-column mapping — old path to new path — is enough: | Old path | New path | |---|---| | `/kb/getting-started` | `/docs/start-here/quickstart` | | `/reference/api-overview` | `/docs/reference/api` | Capture this while you're moving content, when the correspondence is freshest. Every page whose URL changes needs an entry; pages whose URL is unchanged don't. ## Add the redirects How you apply the map depends on the target platform, but the mechanism is always the same: a permanent (HTTP 301) redirect from each old path to its new one. 1. **Find your platform's redirect mechanism.** Most static site generators and hosts support redirects through a config file or a hosting-level rules file — for example, a redirects map in your site config, or a `redirects`/rewrites file for your host. Check your target platform's and host's documentation for the supported format. 2. **Add an entry for every changed URL.** Translate each row of your URL map into a redirect rule from the old path to the new path, marked permanent (301) so search engines transfer ranking to the new URL. 3. **Handle whole-section moves.** When an entire section moves under a new prefix, a single wildcard or pattern redirect often covers all its pages instead of one rule per page — if your platform supports pattern-based rules. ## Verify before and after cut-over Confirm the redirects resolve before you point your domain at the new site, and again once it's live: - **Spot-check high-traffic URLs** from your analytics — your most-visited old paths should land on the right new pages. - **Crawl for broken links** with a link checker so no internal link or redirect points at a dead path. - **Watch for 404s after cut-over** in your host or analytics logs, and backfill any redirect you missed. ## Redirects and Promptless Redirect handling belongs to your documentation platform and host, not to Promptless — Promptless proposes content changes through pull requests and doesn't manage your hosting-level redirects. That said, once your migrated docs are connected as a [doc collection](/docs/connect/doc-locations/github-repos), Promptless keeps the *content* current from that point forward, so the migration is the one-time cost and staying current is automatic afterward. Planning a migration and want help getting the redirect strategy right? Contact [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Compliance and certifications url: https://promptless.ai/docs/security/compliance-and-certifications --- This page covers Promptless's compliance certifications, security practices, and incident response procedures. ## SOC 2 compliance Promptless maintains SOC 2 Type II certification. Our SOC 2 report covers: - Security controls and access management - Data encryption practices - Incident response procedures - Change management processes - Monitoring and logging capabilities To request a copy of our SOC 2 report, contact us at help@gopromptless.ai. ## Penetration testing Promptless conducts annual third-party penetration tests performed by independent security firms. These assessments evaluate our infrastructure, application security, and data protection controls. Penetration test summary reports are available to enterprise customers upon request. Contact help@gopromptless.ai for more information. ## Security incident notification If a security incident affects customer data, Promptless follows this notification process: - **Notification timing**: Customers are notified within 72 hours of confirming an incident affects their data - **Notification recipients**: Security notifications are sent to organization administrators and any designated security contacts on file - **Notification content**: Includes a description of the incident, affected data, remediation steps taken, and recommended actions To add additional security contacts (such as a security team email address) for incident notifications, contact security@gopromptless.ai. ## Audit logging Promptless provides audit logging for enterprise customers. Audit logs capture security-relevant events including: - User authentication events - Administrative actions (team member changes, role modifications) - Integration configuration changes - API key creation and revocation Enterprise customers can request audit log exports by contacting help@gopromptless.ai. Logs are available in standard formats for integration with SIEM tools. ## Session management Session management varies based on your authentication method: - **Enterprise SSO (SAML/OIDC)**: Session duration and timeout policies are controlled by your identity provider. Configure session expiry, idle timeouts, and re-authentication requirements in your IdP settings. - **Standard authentication (Google/GitHub SSO)**: Session management is handled by the authentication provider. Contact security@gopromptless.ai for details on session timeout behavior. For organizations requiring specific session timeout policies (such as 24-hour expiry), configure these settings in your identity provider when using enterprise SSO. ## Questions about compliance? For questions about our compliance practices or to request compliance documentation, contact our team at help@gopromptless.ai. For specific security requirements, contact security@gopromptless.ai. *** title: Data handling and classification url: https://promptless.ai/docs/security/data-handling-and-classification --- Promptless is designed with data minimization in mind, ensuring that we only store what's necessary to provide our documentation automation service and keeping Promptless's risk level at a minimum. This page explains how we handle your data when you use Promptless. ## Data classification | Data Category | Promptless Handling | Description | |--------------|----------------|-------------| | Documentation Copies | Stored by Promptless | Public documentation copies for automation and change tracking | | Third-party Integration Data | Processed, not stored | Promptless can be triggered by third-party tools, and processes data to provide services, but does not store any data beyond the duration needed to provide documentation updates | | End-user Data | Not Processed | Sensitive end-user data is not processed or stored | ### Data that Promptless stores Promptless stores minimal data, and otherwise operates in a stateless manner to avoid storing any data that is not necessary to provide the service. - **Documentation Copies**: Promptless stores copies of your documentation to enable our automation features and track changes. This documentation is typically public, and so is generally not considered sensitive data. - **Feedback for Promptless**: Promptless stores feedback that you provide to it about the quality of documentation updates, which can take the form of edits that you've made to Promptless suggestions, or direct feedback you've made on the Promptless dashboard. - **Integration Auth Data**: When you link Promptless to a third party tool, we store the data necessary to integrate with that tool. This typically includes an authentication token, not the actual content of the data from the third party tool. ### Data that Promptless processes, but does not store Promptless users can integrate Promptless's services with a number of third party tools, in order to automatically trigger documentation updates or provide additional context for documentation updates. This data is used to provide the Promptless service, and is not stored by Promptless. **Promptless does not retain a copy of customer source code, support conversations, or any other data from third party integrations.** For example: - When a GitHub PR triggers a documentation check, we analyze the changes in real-time without storing the PR content - When using Slack integration, we process conversations to identify documentation needs but don't maintain copies of the conversations - When accessing context from tools like Linear or Jira, we only use the information to inform documentation updates at the time of generation, without storing a copy of issues or projects **Note:** Promptless does not use customer data for pre-training or fine-tuning language models. ### Data that Promptless does not process - **End-user data**: Promptless is not configurable to process or store sensitive end-user data for your organization. ## User authentication and access controls ### Standard authentication features Our platform provides robust authentication mechanisms for all users: - SSO with Google or GitHub supported for all users - Strong password policies enforcing complexity requirements - Two-factor authentication (2FA) support using industry-standard TOTP - Password reset workflows with secure verification ### Enterprise authentication features Enterprise plan customers receive access to advanced authentication capabilities: - Single Sign-On (SSO) integration supporting major identity providers - SAML 2.0 support with: - Just-in-time user provisioning - Role mapping - Certificate-based authentication - OpenID Connect (OIDC) compatibility for modern authentication workflows - Custom MFA policies and enforcement ## Data security ### Encryption standards - All data in transit is encrypted using TLS 1.2 or higher, ensuring secure communication between all system components - Data at rest (both in primary data stores and secondary backups) is protected using AES-256 encryption, with keys managed through a secure key management system - Backup data is encrypted using independent encryption keys for additional security ## Enterprise security support Enterprise customers may request additional security features and support, such as custom data retention policies. ## Questions about data handling? If you have specific questions about how we handle data or need more information, please contact us at security@gopromptless.ai. Promptless implements comprehensive security measures to protect customer data and ensure secure access to our platform. Our multi-layered approach to security encompasses data encryption, access controls, and robust authentication mechanisms. *** title: Network architecture url: https://promptless.ai/docs/security/network-architecture --- Promptless utilizes a secure, modern cloud-based network architecture designed for reliability, security, and scalability. Our infrastructure is built on industry-leading cloud platforms with multiple layers of security controls and redundancy. ## Infrastructure overview
Promptless Network Architecture
Promptless Network Architecture
Our infrastructure is designed with the following key principles: - Security by design at every layer - High availability and fault tolerance - Scalability and performance optimization - Comprehensive monitoring and observability ## Multi-tenant security model Promptless uses a strong logical separation model for multi-tenant data security: ### Organization-level isolation - Every piece of data (users, suggestions, trigger events, etc.) is tagged with a specific organization ID - All database queries are automatically scoped to the requesting organization - Authorization mechanisms prevent cross-organization data access - No shared data contexts between different customer organizations Promptless's shared infrastructure provides increased scalability and security, since it reduces the number of infrastructure assets that need to be tracked and maintained and decreases the number of data access points across the system. ## Key security measures While we can't highlight all of Promptless's security measures here, we've highlighted some of the key ones below: * Data encryption in transit: All data at rest is encrypted using TLS 1.2 or later. * Data encryption at rest: Data stored in Promptless's database is encrypted with AES-256. * Data access controls: We use a combination of access controls, including role-based access control (RBAC), to ensure that only authorized users have access to sensitive data. * Principle of least privilege: We only give users the minimum permissions they need for their role. * Logical separation of data: All data is tagged with customer identifiers, to ensure multiple layers of logical separation between Promptless users For more detailed information about our network architecture or to discuss specific security requirements, please contact our security team at security@gopromptless.ai. *** title: Promptless subprocessors url: https://promptless.ai/docs/security/subprocessors --- Promptless uses a number of third party services to deliver our services. This page provides high-level information about the subprocessors that Promptless uses to deliver our core docs automation service. For more detailed information about our security practices, data handling procedures, and privacy commitments, please schedule a call with our team by contacting us at security@gopromptless.ai. ## Language models and AI infrastructure providers Promptless is designed with a model-agnostic architecture, providing flexibility and choice in AI language models used for documentation generation. This approach offers several key advantages: Model Selection * Support for multiple leading language models * Ability to switch between different model providers * Custom model integration capabilities * Performance optimization across different model types Enterprise customers have additional flexibility: * Tailored hosted models by cloud providers, such as OpenAI on Azure or Anthropic on AWS * Use of customer-managed model deployments * Custom model fine-tuning options * Model performance monitoring and optimization * Dedicated model resources **Note:** We may recommend certain models for different parts of the documentation process based on what produces the best output for each use-case, but the final choice of architecture is up to you. Currently, the default configuration for cloud-hosted customers uses AWS Bedrock, though the system works with a variety of models including Anthropic, OpenAI, and open-source providers. **Note:** Regardless of model choice, Promptless does not use customer data for pre-training or fine-tuning language models. ## Current subprocessors ### Infrastructure and hosting - **Amazon Web Services (AWS)** - Primary cloud infrastructure provider - Data center locations: Primary is us-east-2, with secondary locations in other US regions - Services used: EKS, EC2, S3, RDS (Aurora), Lambda ### Authentication and security - **Clerk**: User authentication, SSO, identity management, and security token services ### Monitoring and analytics - **DataDog**: Infrastructure monitoring, application performance monitoring, log management, and security monitoring - **Sentry**: Error tracking and monitoring ### Third-party integrations Promptless supports a number of third-party integrations that customers can choose to use in their projects, such as GitHub, Slack, Linear, Jira, and more. For the most current information about our subprocessors, please contact us at help@gopromptless.ai. For specific security requirements, contact security@gopromptless.ai. *** title: Privacy policy url: https://promptless.ai/docs/security/privacy-policy --- Promptless is designed with data minimization in mind: we access only what we need, when we need it, and we don't store what we don't need. This page explains our approach to privacy and how we handle your data. ## Our privacy principles ### We don't store your source code or conversations When Promptless analyzes a GitHub PR or Slack thread, we process that content in real-time to generate documentation suggestions, then discard it. We don't retain copies of your source code, support conversations, Jira tickets, or other integration data. ### We don't train models on your data Promptless does not use your content for pre-training or fine-tuning language models. Your code, documentation, and conversations are used solely to generate your documentation suggestions. ### We store only what's necessary The data we store is limited to what's required to operate the service: - **Documentation copies** for tracking changes and generating updates - **Feedback you provide** to improve suggestion quality - **Integration credentials** to connect with your tools ### Your data is encrypted All data in transit is encrypted using TLS 1.2 or higher. Data at rest is protected using AES-256 encryption. ### You control the integration scope Promptless only accesses the specific repositories, channels, or projects you configure. We don't request broad organizational access. You choose exactly which resources Promptless can see. ## Enterprise privacy options Organizations with stricter requirements can deploy Promptless on their own infrastructure. Self-hosting provides complete data control with no data leaving your environment. Enterprise customers can also use customer-managed model deployments, ensuring your content is never processed by external AI providers. ## Complete privacy policy For the full legal privacy policy covering data collection, retention, cookies, and your rights, see the [Promptless Privacy Policy](https://promptless.ai/privacy). ## Questions about privacy? For questions about our privacy practices or to exercise your data rights, contact us at help@gopromptless.ai. *** title: Integrations url: https://promptless.ai/docs/reference/integrations description: Connect Promptless to GitHub, GitLab, Slack, Atlassian, and other tools for triggers, context sources, and documentation publishing. --- import { Aside } from '@astrojs/starlight/components'; Promptless offers several key integrations to help automate and improve your documentation workflow. Integrations can be used for: 1. Triggers (i.e. to generate events, either automatically or manually, upon which Promptless gets notified) 2. Context (i.e. to allow Promptless to search for relevant information in its research) 3. Publishing (i.e. to push documentation updates to your Git-hosted docs) Some integrations can be used for multiple purposes. Some integrations are in a beta state and may not be listed here. For the most up to date list of integrations, please contact us at help@gopromptless.ai. ## Available integrations - [Bitbucket](/docs/reference/integrations/bitbucket): Trigger based on Pull Requests - [GitHub](/docs/reference/integrations/github): Trigger based on Pull Requests, research based on code functionality, and publish documentation to GitHub repos - [GitHub Enterprise](/docs/reference/integrations/github-enterprise): Custom GitHub App configuration for GitHub Enterprise Server and Enterprise Cloud users - [GitLab](/docs/reference/integrations/gitlab): Trigger based on Merge Requests, read source code for context - [Atlassian](/docs/reference/integrations/atlassian): Look up relevant Jira issues and Confluence spaces for context when creating documentation - [Linear](/docs/reference/integrations/linear): Look up relevant Linear issues and projects within a team when being triggered - [Microsoft Teams](/docs/reference/integrations/microsoft-teams): Trigger based on mentions and message actions in Microsoft Teams (Beta) - [Notion](/docs/connect/context-sources/notion): Search Notion pages and databases for product specs and internal documentation - [Google Drive](/docs/connect/context-sources/google-drive): Search Google Drive and read Docs, Sheets, and Slides for context when creating documentation (Beta) - [Slite](/docs/connect/context-sources/slite): Search Slite notes for internal documentation and product context - [Slack](/docs/reference/integrations/slack): Trigger based on DMs or message actions in Slack - [Intercom](/docs/reference/integrations/intercom): Trigger based on resolved support conversations (Beta) - [LaunchDarkly](/docs/reference/integrations/launchdarkly): Trigger based on feature flag changes (Beta) ## Manage integrations Organization administrators can view and manage all connected integrations from the [Integrations page](https://app.gopromptless.ai/integrations) in the Promptless dashboard. The Integrations page shows: - All currently connected integrations for your organization - Connection status and authentication state for each integration - Options to disconnect or reconfigure integrations - Links to set up new integrations To revoke access for any integration, click the integration card and select the disconnect option. This immediately revokes Promptless's access to that service. ## Security & authentication All Promptless integrations follow security best practices: - OAuth 2.0 authentication where applicable - Encrypted data transmission (TLS 1.2+) - Encrypted data storage (AES-256) - Minimal data retention ## Common features Each integration includes: - Granular permission controls - Audit logging capabilities - Configurable notification settings - Data privacy controls For detailed security information, visit our [Data Handling and Security documentation](/docs/security/data-handling-and-classification). *** title: Bitbucket integration url: https://promptless.ai/docs/reference/integrations/bitbucket --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers** Promptless integrates with Bitbucket using app password authentication, monitoring pull requests in your repositories for documentation updates. ## Installation To set up the Bitbucket integration: 1. Navigate to the **Integrations** page in your Promptless dashboard 2. Click on **Connect** next to the Bitbucket option 3. Enter your Bitbucket credentials: - **Username**: Your Bitbucket username - **App Password**: A Bitbucket app password with appropriate permissions - **Workspace Name**: The name of your Bitbucket workspace ## Project setup After connecting your Bitbucket account, you can configure how Promptless interacts with your repositories: ### Repository access When setting up a project with Bitbucket as a trigger source: 1. Select the repositories you want Promptless to monitor for changes 2. Choose whether Promptless should have read-only access or write access to your documentation repositories 3. Optionally, configure directory-specific triggers to focus on particular parts of your codebase ### Directory-specific triggers Similar to the GitHub integration, you can configure Promptless to only trigger documentation updates when changes are made to specific directories in your Bitbucket repositories. This is useful for: - Focusing on code that directly impacts user-facing features - Monitoring API changes that require documentation updates - Ignoring internal tooling or test changes that don't affect documentation To set up directory-specific triggers: 1. In your project configuration, select the Bitbucket repository 2. Under **Advanced Options**, enable **Directory-Specific Triggers** 3. Enter the directories you want to monitor, separated by commas (e.g., `src/api, docs/reference`) ## Authentication model The Bitbucket integration uses a username and app password authentication model: - **Username**: Your Bitbucket username for API authentication - **App Password**: A secure token with specific permissions for the Promptless integration - **Workspace Access**: Limited to the specific workspace you connect This authentication model ensures that Promptless only has access to the repositories and actions you explicitly authorize. ## Repository refresh If you add new repositories to your Bitbucket workspace after setting up the integration, you can refresh the repository list: 1. Go to the **Integrations** page in your Promptless dashboard 2. Find the Bitbucket integration 3. Click the **Refresh Repositories** button to update the list of available repositories ## Webhook management Promptless automatically sets up webhooks in your Bitbucket repositories to monitor for pull request events. These webhooks: - Trigger Promptless when pull requests are created or updated - Send only the necessary information about changes to Promptless - Can be customized to focus on specific events ## Usage Once configured, the Bitbucket integration works similarly to the GitHub integration: 1. When a pull request is opened or updated in your monitored repositories, Promptless is automatically triggered 2. Promptless analyzes the changes to determine if documentation updates are needed 3. If updates are needed, Promptless generates the appropriate documentation changes 4. Promptless adds a comment to your Bitbucket pull request with a link to review the documentation changes 5. You can review and approve the suggested documentation updates in the Promptless dashboard For more information on how triggers work in general, see the [Triggers](/docs/start-here/how-promptless-works) documentation. *** title: GitHub integration url: https://promptless.ai/docs/reference/integrations/github --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers, Context, and Publishing** Promptless integrates with GitHub through our official GitHub App, providing secure access to your repositories for documentation automation. ## Installation 1. Click "Connect GitHub" from the [integrations page](https://app.gopromptless.ai/integrations). Integrations Page 2. Select which GitHub organization to install Promptless into. GitHub Organization Selection 3. Select which repositories you want to give Promptless access to. Typically, this will be your source code and your documentation repo (if your docs are in GitHub). Repository Selection 4. Verify that Promptless is connected in the integrations page. Integrations Complete ### When admin approval is required Some GitHub organizations require admin approval before third-party apps can be installed. If you're not an admin, GitHub may prompt you to request approval instead of completing the installation. 1. **Submit the request**: Complete the approval request flow in GitHub. Promptless tracks your request automatically. 2. **Ask an admin to approve**: An admin in your GitHub organization needs to approve the Promptless GitHub App from the organization's "Third-party Access" settings. 3. **Automatic connection**: Once approved, Promptless detects the approval and completes the connection—no further action needed. ## Connect multiple GitHub organizations You can connect multiple GitHub organizations to your Promptless account. This is useful for managing work and personal repositories, or when working across multiple organizations. After you connect your first organization, click the "Connect another GitHub Org" button on the integrations page to add more. Each new organization follows the same installation process. Each connected organization appears as its own card on the integrations page, showing: - Organization name - List of accessible repositories - Individual refresh and disconnect controls When creating or editing projects, repositories from all connected organizations are available in the dropdown menus, displayed as `organization/repository`. ## Manage repository access When selecting a docs repository during setup, Promptless displays the connected GitHub organization above the repository picker. Click **Manage repository access** at the bottom of the picker to open GitHub's installation settings and adjust which repositories Promptless can access. If Promptless doesn't have access to any repositories in your organization, you'll see an error message with the same button to grant initial access. After the initial installation, you may need to add new repositories or modify which repositories Promptless can access. You can manage this directly through your GitHub organization settings: 1. Navigate to your GitHub organization settings 2. Go to "Third-party Access" → "GitHub Apps" 3. Find "Promptless" in the list and click "Configure" 4. In the "Repository access" section, you can: - Switch between "All repositories" and "Only select repositories" - Add or remove specific repositories using the "Select repositories" dropdown - Remove repositories by clicking the "×" next to their names GitHub App Repository Management 5. Click "Save" to apply your changes After updating repository access, the new repositories will be available when creating or editing projects in Promptless. Note that it may take a few minutes for the changes to be reflected in the Promptless dashboard. If you don't see newly added repositories immediately, you may need to click the "refresh repos" icon in the integrations page to update the repository list. ## Authentication model Promptless uses the official [GitHub App specification](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps) to authenticate with GitHub. Promptless authenticates securely with JWTs generated by the GitHub App installation. This ensures that Promptless has read and write access to the repositories that you select, and that either you or Promptless can revoke access at any time. ## What you can do with GitHub Once connected, you can use GitHub for: - **[Triggers](/docs/connect/triggers)**: Monitor pull requests and commits for documentation updates - **[Context Sources](/docs/connect/context-sources)**: Search code repositories and issues for technical context - **[Doc Collections](/docs/connect/doc-locations/github-repos)**: Publish documentation updates to GitHub-based platforms ## Frequently asked questions
Promptless shows 'no repositories accessible' during setup—what do I do? This means the Promptless GitHub App is installed but doesn't have access to any repositories yet. Click **Manage repository access** to open GitHub's installation settings, where you can grant access to specific repositories or select "All repositories." After updating access in GitHub, click **Refresh** in Promptless to reload the repository list.
How do I add more repositories after installing the GitHub integration? Add additional repositories anytime by visiting your GitHub organization settings. In GitHub, head to `Settings -> Third-party Access -> GitHub Apps` then find the Promptless GitHub App and click "Configure." Add or remove repositories in the "Repository access" section, then click "Save." You'll be able to choose from the newly added repositories when creating or editing your Promptless projects.
Can I remove GitHub repository access from Promptless? You can remove access to specific repositories or even uninstall the integration entirely from the same "Configure" page in your GitHub organization settings. Click the `×` next to a repository name to remove it from the Promptless GitHub App, or click the `Uninstall` button at the bottom of the page to remove the app entirely.
How long does it take for repository changes to appear in Promptless? It may take a few minutes for repository updates in the GitHub App to be reflected in your Promptless dashboard. If you don't see newly added repositories right away when creating or editing projects, click the "refresh repos" icon in the integrations page.
Can I connect multiple GitHub organizations to one Promptless account? Yes. After connecting your first GitHub organization, you can add more by clicking "Connect another GitHub Org" on the integrations page. Each organization appears as its own card, and repositories from all connected organizations are available when setting up projects.
What happens if my GitHub organization requires admin approval for apps? If your organization requires admin approval before third-party apps can be installed, GitHub will show you a request flow instead of completing the installation. Submit the request, and Promptless tracks it automatically. Once an admin approves the Promptless GitHub App in your organization's settings, the connection completes automatically—you don't need to re-authenticate or click anything else.
*** title: GitHub Enterprise integration url: https://promptless.ai/docs/reference/integrations/github-enterprise --- import { Aside, Steps } from '@astrojs/starlight/components'; **For GitHub Enterprise Server and GitHub Enterprise Cloud users** If your organization uses GitHub Enterprise Server (self-hosted) or GitHub Enterprise Cloud with specific security requirements, you'll need to create a custom GitHub App within your enterprise environment to integrate with Promptless. ## Prerequisites - GitHub Enterprise admin access to create and configure GitHub Apps - Network access to Promptless endpoints (see [IP whitelisting](#step-6-ip-whitelisting) section) - Ability to generate and securely store private keys and client secrets ## Step 1: Register new GitHub App 1. Navigate to your GitHub Enterprise admin settings 2. Go to "GitHub Apps" and click "New GitHub App" 3. Fill in the basic app information: GitHub Enterprise App Registration ### Required app details Fill in the following fields in your GitHub App configuration: - **GitHub App name** (required): Enter a descriptive name like "Promptless Enterprise" or "Promptless (Your Company Name)" - **Description**: Use: "Promptless keeps your technical guides up-to-date using AI." - **Homepage URL** (required): `https://gopromptless.ai` ## Step 2: Configure authentication URLs Set up the callback and redirect URLs for proper authentication flow: GitHub Enterprise Callback URL Configuration ### Authentication configuration Configure the following URLs in your GitHub App settings: - **Callback URL** (required): `https://app.gopromptless.ai/integrations` - **Setup URL (Post installation)** (required): `https://app.gopromptless.ai/integrations/github-redirect` GitHub Enterprise Post Installation Setup ## Step 3: Configure webhook settings Set up webhooks to enable real-time communication between GitHub Enterprise and Promptless: GitHub Enterprise Webhook Configuration ### Webhook configuration Configure the following webhook settings in your GitHub App: - **Webhook URL** (required): `https://api.gopromptless.ai/integrations/github/events` - **Webhook secret** (optional): Leave this field empty or generate a secure secret if required by your security policies - **SSL verification** (required): Enable SSL verification (recommended for security) ## Step 4: Configure repository permissions Promptless requires specific repository permissions to function properly. Configure these permissions in your GitHub App settings: GitHub Enterprise Repository Permissions Overview ### Required repository permissions Configure the following permissions for your GitHub App: #### Pull requests - read and write GitHub Enterprise Pull Requests Permission This permission allows Promptless to: - Read pull request content and metadata - Create documentation update pull requests - Add comments to pull requests for feedback #### Contents - read and write GitHub Enterprise Contents Permission This permission allows Promptless to: - Read repository files and documentation - Create and update documentation files - Access repository structure and content #### Commit statuses - read only GitHub Enterprise Commit Statuses Permission This permission allows Promptless to: - Read commit status information - Understand the state of pull requests and commits #### Webhooks - read and write GitHub Enterprise Webhooks Permission This permission allows Promptless to: - Manage webhook configurations - Receive real-time notifications of repository events ## Step 5: Configure webhook events Select the specific events that should trigger Promptless documentation updates: GitHub Enterprise Webhook Events ### Required webhook events Select the following events to ensure Promptless receives all necessary notifications: - **Pull Request** - Triggers when pull requests are opened, updated, or closed - **Pull Request Review** - Triggers when pull request reviews are submitted - **Pull Request Review Thread** - Triggers when review threads are created or updated - **Pull Request Review Comment** - Triggers when individual review comments are made - **Push** - Triggers when code is pushed to repositories - **Release** - Triggers when releases are created or updated - **Repository** - Triggers when repository settings change ## Step 6: IP whitelisting Add Promptless IP addresses to your network whitelist to ensure proper connectivity: ### Promptless IP addresses Add the following IP addresses to your whitelist: ``` 3.143.177.103 3.131.121.250 3.13.184.175 18.223.104.40 ``` ## Step 7: Generate credentials After configuring all settings, generate the necessary credentials: 1. **Generate Private Key.** 1. Scroll to the bottom of the GitHub App settings page 2. Click "Generate a private key" 3. Download and securely store the `.pem` file 4. This key will be needed for Promptless configuration 2. **Generate Client Secret.** 1. In the "Client secrets" section, click "Generate a new client secret" 2. Copy and securely store the generated secret 3. This secret will be needed for OAuth authentication 3. **Note the App ID.** 1. Find the "App ID" at the top of the settings page 2. Record this ID as it will be needed for configuration ## Step 8: Install the app 1. After creating the GitHub App, install it to your organization or specific repositories 2. Choose which repositories Promptless should have access to 3. Complete the installation process ## Step 9: Connect your GitHub Enterprise integration After configuring your GitHub Enterprise integration, you'll need to connect it in your Promptless dashboard. GitHub Enterprise Connection Interface ### Complete the connection To establish the connection: 1. Log into your Promptless dashboard at [app.gopromptless.ai](https://app.gopromptless.ai) 2. Navigate to the Integrations page 3. Locate the GitHub Enterprise integration tile 4. Click **Connect GitHub Enterprise** to establish the connection The connection process will authenticate with your GitHub Enterprise instance using the configuration that was set up by the Promptless team. Once connected, you'll see confirmation that your GitHub Enterprise integration is active and ready to use. ## Troubleshooting
Webhook Delivery Issues - Verify IP addresses are whitelisted - Check that the webhook URL is accessible from your GitHub Enterprise instance - Ensure SSL verification settings match your security requirements - Review GitHub Enterprise logs for webhook delivery errors
Authentication Problems - Verify all URLs are correctly configured - Ensure the private key and client secret are valid - Check that the App ID matches your created GitHub App - Confirm the installation was completed successfully
Permission Errors - Review that all required repository permissions are granted - Ensure the app is installed to the correct repositories - Verify that webhook events are properly configured - Check that users have appropriate access to repositories
## Support For assistance with GitHub Enterprise setup, contact: - **Email**: [hello@gopromptless.ai](mailto:hello@gopromptless.ai) - **Support**: [help@gopromptless.ai](mailto:help@gopromptless.ai) The Promptless team can provide guidance on configuration, troubleshooting, and best practices for GitHub Enterprise integrations. *** title: GitLab integration url: https://promptless.ai/docs/reference/integrations/gitlab --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers, Context** Promptless integrates with GitLab using group access token authentication, monitoring merge requests in your repositories for documentation updates and providing read access to source code for deeper context. ## Installation To set up the GitLab integration: 1. Go to the [Integrations](https://app.gopromptless.ai/integrations) page in the Promptless dashboard. 2. Click **Connect GitLab**. 3. Enter a GitLab group access token with the `api` scope. 4. Click **Connect**. ## Project setup After connecting your GitLab account, you can configure how Promptless interacts with your projects: ### Repository access When setting up a project with GitLab as a trigger source: 1. Select the GitLab projects you want Promptless to monitor for changes. 2. Choose whether Promptless should have read-only access or write access to your documentation repositories. 3. Optionally, configure directory-specific triggers to focus on particular parts of your codebase. ### Directory-specific triggers You can configure Promptless to only trigger documentation updates when changes are made to specific directories in your GitLab projects. This is useful for: - Focusing on code that directly impacts user-facing features - Monitoring API changes that require documentation updates - Ignoring internal tooling or test changes that don't affect documentation To set up directory-specific triggers: 1. In your project configuration, select the GitLab project. 2. Under **Advanced Options**, enable **Directory-Specific Triggers**. 3. Enter the directories you want to monitor, separated by commas (e.g., `src/api, docs/reference`). ## Source code reading Promptless can read source files directly from your GitLab projects when processing merge requests or researching documentation updates. This provides context from implementation details that aren't visible in MR diffs alone. Promptless uses the GitLab CLI (`glab`) to fetch file contents from your repositories. This is useful when: - A merge request references code in files that weren't changed - A new feature needs to be understood in the context of existing code - Documentation requires accurate details about implementation behavior ## Authentication model The GitLab integration uses group access token authentication: - **Group Access Token**: A secure token with the `api` scope for full API access - **Webhook Triggers**: Work with both GitLab.com and self-hosted GitLab instances - **Source Code Reading**: Works with GitLab.com only This authentication model ensures that Promptless only has access to the projects and actions you explicitly authorize through the token's permissions. ### Token scope considerations GitLab group access tokens have read-write `api` scope by default. Promptless only performs read operations with these tokens: viewing merge requests, reading repository files, and fetching project metadata. Promptless never pushes code, creates merge requests, or modifies your GitLab projects through this token. ## Webhook management Promptless automatically sets up webhooks in your GitLab projects to monitor for merge request events. These webhooks: - Trigger Promptless when merge requests are created or updated - Send only the necessary information about changes to Promptless - Can be customized to focus on specific events ## Usage Once configured, the GitLab integration works similarly to other code hosting integrations: 1. When a merge request is opened or updated in your monitored projects, Promptless is automatically triggered. 2. Promptless analyzes the changes to determine if documentation updates are needed. 3. If updates are needed, Promptless generates the appropriate documentation changes. 4. Promptless adds a comment to your GitLab merge request with a link to review the documentation changes. 5. You can review and approve the suggested documentation updates in the Promptless dashboard. For more information on how triggers work in general, see the [Triggers](/docs/connect/triggers) documentation. *** title: Atlassian integration url: https://promptless.ai/docs/reference/integrations/atlassian --- import { Aside, Steps } from '@astrojs/starlight/components'; **Used for: Context** ## Permissions required The OAuth consent screen displays the permissions Promptless requests when you connect Atlassian. Promptless requests only the scopes needed to read Jira issues and Confluence pages for documentation context. ### Jira scopes | Scope | Purpose | |-------|---------| | `read:jira-work` | Read Jira issues, projects, and work data | | `write:jira-work` | Required by Atlassian for API access; Promptless uses read-only operations | | `read:jira-user` | Read user information for issue context | ### Confluence scopes | Scope | Purpose | |-------|---------| | `read:confluence-space.summary` | Read space names and metadata | | `read:confluence-content.all` | Read page content for documentation context | | `read:space:confluence` | Read space information (granular scope) | | `read:page:confluence` | Read individual pages (granular scope) | | `read:content:confluence` | Read content body (granular scope) | ### Additional scopes | Scope | Purpose | |-------|---------| | `offline_access` | Allow Promptless to refresh tokens without re-authentication | ### Service account permissions When creating a dedicated Atlassian account for Promptless, the account needs: 1. **Jira access**: The "User" role (not "User access admin") on projects you want Promptless to reference 2. **Confluence access**: "Can view" permission on spaces you want Promptless to search The account does not need administrative permissions. See [Provision an Atlassian account for Promptless](#provision-an-atlassian-account-for-promptless) for step-by-step instructions. ## Jira Cloud installation For Atlassian Cloud-hosted Jira instances: 1. **Connect Jira Cloud.** Click "Connect Jira Cloud" from the [integrations page](https://app.gopromptless.ai/integrations). 2. **Atlassian Login.** If you're not already logged in, you'll see the Atlassian login screen: Atlassian Login Screen 3. **OAuth Consent.** Review the permissions Promptless is requesting on the OAuth consent screen: Jira OAuth Consent Screen 4. **Complete Connection.** Click "Accept" and verify the connection in Promptless. If you don't see the option to accept, you may not have the required permissions. Contact your Jira administrator or invite them to Promptless. For more information about adding new members, see our [Account Management](/docs/reference/account-management) page. After connecting, manage Promptless access by going to your avatar > Account settings > Connected apps in Atlassian: Atlassian Connected Apps Management ## What you can do with Atlassian Once connected, you can use Jira and Confluence as context sources to enhance documentation suggestions: - **Jira**: Automatically retrieve ticket information and search for related issues using JQL queries. See the [Jira Context Source](/docs/connect/context-sources/jira) page for details. - **Confluence**: Search your Confluence spaces for existing documentation patterns, terminology, and architectural decisions. See the [Confluence Context Source](/docs/connect/context-sources/confluence) page for details. Atlassian integration showing both Jira projects and Confluence spaces in a unified interface ## Provision an Atlassian account for Promptless We recommend creating a dedicated Atlassian account for Promptless to access both Jira and Confluence. A dedicated account gives you complete audit trail visibility and lets you configure fine-grained permissions for both services. Create the account using an email alias like `your_email+promptless@company.com`, or ask your IT admin to provision a new email account like `promptless@company.com`. 1. **Navigate to User management.** In Atlassian, go to your settings and select **User management** under Atlassian admin settings. Atlassian admin settings showing User management option 2. **Invite the Promptless account.** Click "Invite people" and enter the email address for your Promptless account. Under the Jira app, select the **User** role (not User access admin). Invite people to Jira screen with email and User role selected 3. **Accept the invitation.** Check your own email inbox (if you're using the alias), or Promptless's email inbox. Email invitation from Jira to join the team When setting up the account, you can use the name "Promptless Bot". Once complete, you'll see the account listed as ACTIVE. It might take up to an hour for the status to update from INVITED to ACTIVE after you accept the invite. Promptless Bot account showing as ACTIVE in user list ## Data processing and security For information about how Promptless processes Jira data, including redaction capabilities and privacy controls, see the [Jira Context Source](/docs/connect/context-sources/jira) page. ## Troubleshooting
How do I restrict Promptless from accessing confidential Jira projects or Confluence spaces? Promptless inherits the permissions of the Atlassian account used during OAuth connection. There are several ways to manage access depending on your security requirements: **Standard approach:** After connecting Atlassian, configure which Jira projects and Confluence spaces Promptless should search in your [Configuration page](https://app.gopromptless.ai/configuration) using the `context_sources` section. Promptless won't access projects or spaces you don't explicitly configure, even if the connected account has permission to see them. **For highly confidential content:** Create an Atlassian user account that only has access to non-confidential projects and spaces, then connect Atlassian to Promptless using this limited-access account. This restricts access at the Atlassian permissions level, adding an extra security layer. **For granular control:** [Provision a dedicated Atlassian account for Promptless](#provision-an-atlassian-account-for-promptless) and configure fine-grained permissions for both Jira projects and Confluence spaces in Atlassian's user management before connecting it to Promptless.
Promptless actions are attributed to my personal account - Disconnect Atlassian from the [integrations page](https://app.gopromptless.ai/integrations) - Sign out of your personal Atlassian account in your browser - Sign in to the Promptless bot account you created - Reconnect Atlassian to Promptless while signed in to the bot account
*** title: Linear integration url: https://promptless.ai/docs/reference/integrations/linear --- **Used for: Context** Promptless integrates with Linear through OAuth 2.0, providing secure access to your project management data for documentation automation. ## Installation 1. Click "Connect Linear" from the [integrations page](https://app.gopromptless.ai/integrations). Integrations Page 2. You'll be redirected to Linear to sign in to the right organization, if you are not already signed into the web app. Linear Organization Selection Linear Organization Selection 3. Once you're signed in, you'll be redirected back to Promptless, and you can verify that Linear is connected. Linear Integration Complete ## Authentication model Promptless uses OAuth 2.0 to authenticate with Linear, following their [official Linear OAuth 2.0 specification](https://developers.linear.app/docs/oauth/authentication). This ensures: - Secure token-based authentication - Ability to revoke access at any time - Granular permission control at the team level - Regular token rotation for enhanced security ## Reconnect Linear If you see a "Reconnect required" warning on the [integrations page](https://app.gopromptless.ai/integrations), your Linear connection needs to be re-authenticated. This can happen when: - Your Linear OAuth tokens have expired and cannot be automatically refreshed - Promptless updated its authentication system and requires a one-time refresh To reconnect, click **Reconnect Linear** and reauthorize Promptless to access your Linear workspace. After reconnecting, Promptless can access your Linear issues again. ## What you can do with Linear Once connected, you can use Linear as a [context source](/docs/connect/context-sources/linear) to search for related issues and project management data that enhances documentation accuracy. *** title: Slack integration url: https://promptless.ai/docs/reference/integrations/slack --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers and Context** Promptless integrates with Slack through our official Slack App, enabling automated documentation updates based on team communication and support conversations. Promptless does not archive or store your Slack messages. Disclaimer: Promptless uses LLMs from OpenAI and Anthropic that have the potential to generate inaccurate results. ## Installation 1. Click "Connect Slack" from the [integrations page](https://app.gopromptless.ai/integrations). Integrations Page 2. You'll be redirected to Slack to install the Promptless app. **Be sure to select the right workspace to install Promptless.** Slack Workspace Selection 3. Review and approve the requested permissions for the Promptless Slack app. Promptless requires these permissions to be able to be triggered from the right events in Slack and to notify your team when updates are available. Slack Permissions ### Key permissions Promptless requests these Slack permissions: - **channels:read** and **groups:read** — List available channels and groups - **chat:write** — Send messages and notifications to channels where Promptless is invited - **files:write** — Attach diff files to Slack threads when notifying about documentation changes - **links:read** and **links:write** — Render preview cards when a Promptless suggestion link is shared in Slack - **users:read** — Look up user information for mentions and notifications The `files:write` permission lets Promptless attach diff files directly in Slack threads, so you can review proposed changes without leaving Slack. If this permission isn't granted, Promptless links to the dashboard instead. The `links:read` and `links:write` permissions let Promptless render a preview card when someone shares a suggestion link in Slack. If `links:write` isn't granted, the link posts as plain text with no preview card. 4. Verify that Slack is connected in the integrations page. Slack Integration Complete ## Support channel After connecting Slack, you'll receive a Slack Connect invitation from the Promptless team. Accept it to join a shared support channel where you can ask questions, get help, and share feedback. ## Update Slack permissions As Promptless adds Slack features, the app sometimes needs new permissions. If you connected your workspace before a permission was introduced, your existing connection lacks that permission until you grant it. To add new permissions without disconnecting, click **Reconnect** on the connected Slack card on the [integrations page](https://app.gopromptless.ai/integrations). Promptless re-runs Slack authorization so you can approve the updated permissions, and your existing connection stays intact—channel memberships and configuration are preserved. Reconnect whenever a Slack feature stops working because a permission is missing. ## What you can do with Slack Once connected, you can use Slack for: - **[Triggers](/docs/connect/triggers/slack-messages)**: Tag @Promptless or use message actions to trigger documentation updates - **[Context Sources](/docs/connect/context-sources)**: Search Slack conversations for team discussions and decisions ## Privacy and channel access By default, Promptless only reads Slack content when you explicitly trigger it by tagging @Promptless or using the "Update Docs" message action. If you enable passive listening in your [configuration](/docs/reference/configuration-reference#triggers), Promptless monitors only the specific channels you configure. ### Add Promptless to private channels Promptless cannot access private channels unless it has been specifically invited. To add Promptless to a private channel, tag `@Promptless` in that channel—Slack prompts you to invite the app. This is required if you want to: - Use a private channel as your notification channel for suggestions - Trigger Promptless from messages in a private channel - Enable passive listening on a private channel ## Troubleshooting ### Diff files not appearing in Slack threads If Promptless notifications appear in Slack but diff files aren't attached, your Slack integration may be missing the `files:write` permission. This can happen if you connected Slack before this permission was added to the Promptless app. To fix this, re-authorize the Slack integration: 1. Go to the [integrations page](https://app.gopromptless.ai/integrations). 2. Click **Reconnect** on the connected Slack card. 3. Approve the requested permissions in Slack. Reconnecting keeps your existing connection intact while granting the missing permission. After re-authorizing, diff files appear as thread attachments. If issues persist, contact help@gopromptless.ai. ### Suggestion link previews not rendering in Slack If sharing a Promptless suggestion link in Slack posts as plain text instead of a preview card, your Slack integration may be missing the `links:write` permission. This can happen if you connected Slack before this permission was added to the Promptless app. The Integrations page flags this connection as **Needs reconnect**. To fix this, re-authorize the Slack integration: 1. Go to the [integrations page](https://app.gopromptless.ai/integrations). 2. Click **Reconnect** on the connected Slack card. 3. Approve the requested permissions in Slack. Reconnecting keeps your existing connection intact while granting the missing permission. After re-authorizing, shared suggestion links render as preview cards. If issues persist, contact help@gopromptless.ai. For more details about using Slack with Promptless, see [Reviewing from Slack and Teams](/docs/work-the-queue/reviewing-from-slack-and-teams). *** title: LaunchDarkly integration (beta) url: https://promptless.ai/docs/reference/integrations/launchdarkly --- **Used for: Triggers** Promptless integrates with LaunchDarkly to enable automated documentation updates when feature flags change. When you connect, Promptless creates a webhook that monitors flag changes across your projects. ## Installation 1. In your LaunchDarkly account, [create an Access Token](https://app.launchdarkly.com/settings/authorization). Mark it as a **service token** and select **Inline policy** for its role. Use this policy: ```json [ { "effect": "allow", "actions": ["createWebhook", "deleteWebhook"], "resources": ["webhook/*"] }, { "effect": "allow", "actions": ["viewProject"], "resources": ["proj/*"] } ] ``` This grants Promptless the minimum permissions needed: - **createWebhook** and **deleteWebhook** on `webhook/*` let Promptless manage its subscription to flag-change events - **viewProject** on `proj/*` lets Promptless view projects and flag state We recommend service tokens over personal access tokens because they are not tied to individual users. The integration keeps working when team members leave. See the [LaunchDarkly docs](https://launchdarkly.com/docs/home/account/api-create) for more on API access tokens. 2. Click "Connect LaunchDarkly" from the [integrations page](https://app.gopromptless.ai/integrations). 3. Paste your service token in the modal and click Connect. 4. Verify that LaunchDarkly shows as connected in the integrations page. ## Authentication model Promptless uses API token authentication for LaunchDarkly integrations. When you connect, Promptless validates your service token and automatically creates a webhook in your LaunchDarkly account. This ensures: - Secure webhook delivery with HMAC-SHA256 signature verification - A unique signing secret for each integration - Ability to revoke access at any time To disconnect, click the LaunchDarkly card on the integrations page and select Disconnect. This removes the webhook from your LaunchDarkly account. *** title: Microsoft Teams integration (beta) url: https://promptless.ai/docs/reference/integrations/microsoft-teams --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers** Promptless integrates with Microsoft Teams through our official Teams app, enabling automated documentation updates based on team communication and collaboration within your Teams environment. ## Prerequisites To install Promptless in Microsoft Teams, you'll need: - Microsoft Teams admin center access - Permissions to manage app setup policies in your organization - Ability to install and configure third-party apps ## Installation ### Step 1: Download Promptless Teams app package First, download the Promptless Teams app package from the [Promptless integrations page](https://app.gopromptless.ai/integrations): Download Teams app package from Promptless integrations page ### Step 2: Upload Promptless Teams app 1. Navigate to the [Microsoft Teams admin center](https://admin.teams.microsoft.com) 2. In the left navigation, under **Teams apps**, select **Manage apps**. This section allows you to control which apps are available to install for users in your organization 3. Click the **Actions** > **Upload new app** button to upload the Promptless Teams app package 4. Click **Upload** to proceed with the app installation Manage Apps Teams Manage Apps Overview Teams Upload Custom App Dialog ### Step 3: Grant access to users 1. In the left navigation, select **Setup policies** Teams Global Policy Configuration 2. Select the **Global (Org-wide default)** policy 3. Ensure that **Upload custom apps** and **User pinning** are enabled. These settings allow users to install and pin custom apps like Promptless. 4. Under **Installed apps**, click on **Add apps** Global Policy 5. Search for "Promptless" and add it to the policy 6. Click **Save** to apply the changes ## What you can do with Microsoft Teams Once connected, you can use Microsoft Teams for: - **[Triggers](/docs/connect/triggers/microsoft-teams-messages)**: Tag @Promptless in channels or DMs to trigger documentation updates For more details about configuration, see [Microsoft Teams Triggers](/docs/connect/triggers/microsoft-teams-messages). *** title: Intercom integration (beta) url: https://promptless.ai/docs/reference/integrations/intercom --- import { Aside } from '@astrojs/starlight/components'; **Used for: Triggers** Promptless integrates with Intercom to enable automated documentation updates based on support conversations and repeated customer questions. ## Installation 1. Click "Connect Intercom" from the [integrations page](https://app.gopromptless.ai/integrations). 2. Review and approve the requested permissions. 3. Verify that Intercom is connected in the integrations page. ## Authentication model Promptless uses OAuth-based authentication for Intercom integrations, which provides: - Secure token-based authentication - Granular API access scopes - Ability to revoke access at any time - Regular token rotation for enhanced security ## What you can do with Intercom Once connected, you can use Intercom as a [trigger source](/docs/connect/triggers/intercom-tickets) to monitor support conversations for documentation gaps (Beta). *** title: Configuration reference url: https://promptless.ai/docs/reference/configuration-reference description: Complete reference for the promptless.yaml configuration file --- import { Aside } from '@astrojs/starlight/components'; All Promptless configuration lives in a single `promptless.yaml` file in your organization's Agent Knowledge Base. This file defines your doc collections, triggers, context sources, and publishing policies in one place. ## Configuration editor View and edit your configuration in the dashboard at [app.gopromptless.ai/configuration](https://app.gopromptless.ai/configuration). The page opens in **Form** mode, a structured editor that groups your configuration into four tabs—**Doc collections**, **Triggers**, **Context sources**, and **Policies**—so you can manage everything without hand-editing YAML. Each tab shows how many items it holds and surfaces the fields for that section directly. Form mode saves one item at a time. When you add or change a doc collection, trigger, or context source, you save that item on its own, and Promptless commits the change to your Agent Knowledge Base right away. Policies save as a single section. There's no separate review-and-commit step—each save is its own commit. When you need precise control over the file format, switch to **YAML** mode using the toggle at the top of the page. YAML mode is the raw editor with syntax highlighting, schema-driven completions, and inline validation. Use it when you want to copy configurations between environments or edit the file directly. In Form mode, Promptless fills in fields from your connected integrations. The doc collection platform (GitHub, GitHub OSS, or GitHub Enterprise) comes from the integration that reaches the repository rather than a field you set, and the repo, Slack channel, and Jira, Confluence, Linear, and Notion pickers autocomplete from what each integration can see. Form mode also keeps references consistent for you. Renaming a doc collection updates every trigger and policy rule that points at it in the same save, and warns you if the new name is already taken. Deleting a doc collection or trigger that a policy rule depends on removes those rules too, so you never end up with a rule pointing at something that no longer exists. ### Permissions and conflict detection Every organization member can view the configuration, but only admins can edit and save changes. Non-admins see a read-only view. The editor uses compare-and-swap to avoid overwriting concurrent changes. If someone else modifies the configuration while you're editing, you see a conflict warning and can reload to get the latest version. ## Initial configuration from onboarding When you complete the setup wizard, Promptless creates your `promptless.yaml` with sensible defaults based on the integrations you connected: | Connected Integration | Generated Trigger | Generated Context Source | |-----------------------|-------------------|--------------------------| | GitHub (docs or trigger app) | `github_pr` (opened, first_approval, merge) with `repos: all` | — | | GitLab | `gitlab_mr` (opened, merge) with `repos: all` | — | | Bitbucket | `bitbucket_pr` (opened, merge) with `repos: all` | — | | Jira / Confluence | — | Unscoped `jira` and/or `confluence` entries | | Linear | — | Unscoped `linear` entry | | Notion | — | Unscoped `notion` entry | | Google Drive | — | Unscoped `google_drive` entry | | Slite | — | Unscoped `slite` entry | Onboarding seeds pull request triggers only; [commit triggers](/docs/connect/triggers/github-commits) are opt-in and stay off until you add a `github_commit` trigger yourself. These broad defaults let Promptless start listening for documentation-worthy events immediately. You can edit your configuration anytime to narrow scope, like restricting triggers to specific repositories or limiting context sources to particular projects. Connecting Jira, Confluence, Linear, or Notion *after* onboarding works the same way: Promptless adds a broad, unscoped context source for that tool if you don't already have one. Existing entries and any scoping you've set are left untouched. ### Add a commit trigger A commit trigger (`github_commit`) fires when commits are pushed to a branch you monitor, rather than when a pull request opens or merges. Without a `branches` filter, it watches only the repository's default branch. Add one when you want Promptless to react to commits directly: ```yaml triggers: default-branch-commits: trigger_type: github_commit match: - repos: - acme/backend branches: - main # omit to match only the default branch trigger_directories: - src/ ``` In a typical pull request workflow, this overlaps with your PR triggers: merging a pull request also pushes a merge commit to the default branch, so the commit trigger fires alongside the `github_pr` merge event. A commit trigger earns its place when changes reach a branch without a pull request—hotfixes or commits pushed straight to the default branch, for example—so Promptless still documents those changes. See [GitHub Commits](/docs/connect/triggers/github-commits) for the full workflow. ## File structure The configuration file has four top-level sections: ```yaml doc_collections: # Where documentation lives (keyed by repo) context_sources: # Integrations for additional context triggers: # Events that initiate documentation work policies: # Publishing and notification rules ``` All sections are optional. Unknown keys are rejected with validation errors. ## Doc collections Doc collections define the documentation repositories where Promptless publishes updates. Each collection is keyed by its GitHub repository name in `owner/repo` format. ```yaml doc_collections: acme/docs: docs_framework: docusaurus docs_root_url: https://docs.acme.com filter: - docs/ - guides/ ``` ### Fields | Field | Description | |-------|-------------| | `platform` | Repository platform: `github` (default), `github_oss`, or `github_enterprise` | | `host` | GitHub Enterprise hostname (required when `platform: github_enterprise`) | | `default_branch` | Branch to target for PRs (defaults to repository's default branch) | | `docs_framework` | Documentation framework (docusaurus, mkdocs, starlight, etc.) | | `docs_root_url` | Published documentation site URL | | `config_file_path` | Path to framework config file (e.g., `docusaurus.config.js`) | | `vale_config_path` | Path to Vale config file to enable prose linting | | `doc_detective` | Doc Detective configuration (presence enables the feature) | | `filter` | List of directory prefixes or file paths Promptless can modify | ### Path scope (filter) The `filter` field controls which files Promptless can modify: - **Empty or omitted**: Promptless can modify any file in the repository. - **Directory paths**: Entries ending with `/` allow modifications to any file in that directory tree. - **File paths**: Exact file paths allow only that specific file. ```yaml doc_collections: acme/docs: filter: - docs/ # All files under docs/ - CHANGELOG.md # Only this specific file ``` ## Context sources Context sources give Promptless access to your organization's tools for additional context. They're used for narrowing scope when you want to limit which projects, spaces, or databases Promptless can query. Each entry requires a `source_type` field. ```yaml context_sources: jira: source_type: jira project_keys: - DOCS - PLATFORM confluence: source_type: confluence space_keys: - ENGINEERING linear: source_type: linear team_keys: - engineering - product notion: source_type: notion database_ids: - abc123def456 slite: source_type: slite ``` ### Available sources | Source Type | Scope Fields | Description | |-------------|--------------|-------------| | `jira` | `project_keys` | Restrict to specific Jira project keys | | `confluence` | `space_keys` | Restrict to specific Confluence space keys | | `linear` | `team_keys` | Restrict to specific Linear team identifiers | | `notion` | `database_ids`, `page_ids` | Restrict to specific Notion databases or pages | | `slite` | — | No scope fields—the whole Slite workspace is available when connected | ## Triggers Triggers define events that automatically initiate documentation work. These are passive intake events that require explicit configuration. Each trigger has a `trigger_type` and a `match` list—the trigger fires when any clause in the list matches, and fields within a clause are ANDed together. ```yaml triggers: github-prs: trigger_type: github_pr match: - repos: - acme/backend - acme/api trigger_on: - opened - first_approval trigger_directories: - src/ - lib/ slack-support: trigger_type: slack_listen match: - channels: - support - customer-questions ``` ### Trigger types
github_pr Triggers when pull requests are opened, approved, or merged in specified repositories. **Match clause fields:** | Field | Description | |-------|-------------| | `repos` | Required. The literal `all` or a list of repositories (`owner/repo` format) | | `excluded_repos` | Repositories to exclude from monitoring | | `trigger_on` | Required. Events that fire: `opened`, `first_approval`, `merge` | | `trigger_directories` | Only trigger when changes touch these directories | | `branches` | Only trigger for PRs targeting these branches | | `repo_topics` | Only trigger for repos with these GitHub topics | | `repo_owners` | Only trigger for repos owned by these owners (the `owner` segment of `owner/repo`) |
github_commit Triggers when commits are pushed to specified branches. **Match clause fields:** | Field | Description | |-------|-------------| | `repos` | Required. The literal `all` or a list of repositories | | `excluded_repos` | Repositories to exclude | | `branches` | Branches to monitor (omit to match only the default branch) | | `trigger_directories` | Only trigger when changes touch these directories | | `repo_topics` | Only trigger for repos with these GitHub topics | | `repo_owners` | Only trigger for repos owned by these owners |
gitlab_mr Triggers when merge requests are opened or merged in GitLab projects. **Match clause fields:** | Field | Description | |-------|-------------| | `repos` | Required. The literal `all` or a list of GitLab projects | | `excluded_repos` | Projects to exclude | | `trigger_on` | Required. Events that fire: `opened`, `merge` | | `trigger_directories` | Only trigger when changes touch these directories | | `branches` | Only trigger for MRs targeting these branches |
bitbucket_pr Triggers when pull requests are opened or merged in Bitbucket repositories. **Match clause fields:** | Field | Description | |-------|-------------| | `repos` | Required. The literal `all` or a list of Bitbucket repositories | | `excluded_repos` | Repositories to exclude | | `trigger_on` | Required. Events that fire: `opened`, `merge` | | `trigger_directories` | Only trigger when changes touch these directories | | `branches` | Only trigger for PRs targeting these branches |
slack_listen Passively monitors specified Slack channels for documentation-worthy conversations. **Match clause fields:** | Field | Description | |-------|-------------| | `channels` | Required. List of channel names to monitor (no `#` prefix) |
msteams_listen Passively monitors specified Microsoft Teams channels. **Match clause fields:** | Field | Description | |-------|-------------| | `channel_ids` | Required. List of Teams channel conversation IDs to monitor |
clickup Triggers when ClickUp tasks reach specified statuses. **Match clause fields:** | Field | Description | |-------|-------------| | `statuses` | Required. List of task statuses that trigger documentation work |
### Built-in triggers Some triggers are always active when their integration is connected and don't appear in the YAML: - **slack_mention** — @Promptless mentions in Slack channels - **msteams_mention** — @Promptless mentions in Microsoft Teams - **github_mention** — @Promptless mentions in GitHub issues and PR comments - **web** — Requests submitted through the web dashboard - **api** — Requests from the HTTP API Built-in triggers can't be disabled, but their keys are valid in policy rules. ## Policies Policies control publishing behavior and notifications. They consist of a default overlay and ordered rules that apply based on trigger or doc collection. ```yaml policies: default: notification: slack_channel: docs-notifications msteams_channel: "19:0a1b2c3d@thread.tacv2" publishing: auto_create_pr: true auto_merge: false suppress_source_pr_comments: false rules: - if: trigger: github-commits then: publishing: auto_merge: true - if: doc_collection: acme/internal-docs then: notification: slack_channel: internal-docs-team ``` ### Policy fields **notification** | Field | Description | |-------|-------------| | `slack_channel` | Slack channel name for notifications (no `#` prefix), or `null` to disable an inherited Slack channel | | `msteams_channel` | Microsoft Teams channel conversation ID (e.g. `19:…@thread.tacv2`) for notifications, or `null` to disable an inherited Teams channel | `slack_channel` and `msteams_channel` are independent—set either, both, or neither. The Teams conversation ID is the same value you paste into an `msteams_listen` trigger; copy it from Teams. A Teams channel must have prior Promptless bot activity before notifications can be delivered there. - **Omitting** the field inherits the channel from `policies.default` or an earlier rule. - Setting it to **`null`** disables the channel for that scope, overriding any inherited channel so no notification is sent. - Setting it to a **channel name** (or Teams conversation ID) routes notifications there. Because resolution depends on field presence, an omitted field and an explicit `null` are not the same: `null` means disable, absent means inherit. The two channels resolve independently, so you can disable one while leaving the other inherited. ```yaml policies: default: notification: slack_channel: docs-notifications rules: - if: doc_collection: acme/internal-docs then: notification: slack_channel: null # silence Slack for this collection ``` **publishing** | Field | Description | |-------|-------------| | `auto_create_pr` | Automatically create PRs for suggestions | | `auto_merge` | Automatically merge documentation PRs | | `suppress_source_pr_comments` | Skip posting comments on source PRs | ### Rule matching Rules are evaluated in order. When multiple rules match, fields from later rules override earlier ones. The `if` clause supports: - `trigger` — Match a specific trigger key (including built-in triggers like `slack_mention`) - `doc_collection` — Match a specific doc collection by repository name Both conditions must match if both are specified (AND logic). ## Example configuration ```yaml doc_collections: acme/documentation: docs_framework: docusaurus docs_root_url: https://docs.acme.com config_file_path: docusaurus.config.js filter: - docs/ context_sources: jira: source_type: jira project_keys: - DOCS - ENG linear: source_type: linear team_keys: - engineering # Built-in triggers (api, github_mention, msteams_mention, slack_mention, web) # are always on for connected integrations and are not configured here; # their keys remain valid in policies rules. triggers: main-repos: trigger_type: github_pr match: - repos: - acme/backend - acme/frontend trigger_on: - opened - first_approval trigger_directories: - src/ support-channel: trigger_type: slack_listen match: - channels: - customer-support policies: default: notification: slack_channel: docs-updates publishing: auto_create_pr: true auto_merge: false rules: - if: trigger: slack_mention then: publishing: suppress_source_pr_comments: true ``` ## Validation and errors The configuration editor validates your YAML before saving. Validation errors appear as inline markers at the relevant line, with details including: - **Path** — Which field has the error - **Line** — Line number in the YAML - **Message** — Description of what's wrong Common validation errors: - Unknown keys (typos or unsupported fields) - Invalid enum values (e.g., wrong trigger type) - Missing required fields (e.g., `host` for `github_enterprise` platform) - Duplicate repository keys in `doc_collections` ## Repository renames Promptless automatically updates your configuration when repositories or Slack channels are renamed: - **GitHub repository renames**: The `doc_collections` key and any references in trigger `repos`/`excluded_repos` are updated. - **Slack channel renames**: Channel names in `slack_listen` triggers and `notification.slack_channel` policies are updated. These updates are committed directly to your Agent Knowledge Base. ## Migration from projects Existing organizations are automatically migrated from the legacy Projects configuration to `promptless.yaml`. The migration preserves: - All trigger configurations and settings - Doc collection settings - Automatic PR creation and notification preferences - Context source scoping After migration, the Projects page is replaced by the Configuration page. Your triggers and doc collections continue working without any action required. *** title: Frequently asked questions url: https://promptless.ai/docs/reference/faq --- Here you'll find answers to common questions about using Promptless. ## Getting started & onboarding For account creation and team management questions, please see our [Account Management](/docs/reference/account-management) page. ## Platform usage ### What platforms does Promptless integrate with? Promptless integrates with a wide variety of platforms for triggers, context, and publishing: - **Triggers**: GitHub, Bitbucket, GitLab, Slack, Microsoft Teams, Intercom (beta) - **Context Sources**: Linear, Jira, GitHub Issues, Google Drive - **Publishing**: Git-hosted docs (Fern, Mintlify, Docusaurus, ReadMe, GitBook, MkDocs, and more) For a complete list, see our [Integrations overview](/docs/reference/integrations). ### Does Promptless monitor my Slack channels? By default, no. Promptless only accesses Slack content when you explicitly trigger it by tagging @Promptless or using the "Update Docs" message action. However, you can optionally enable **passive listening** for specific channels. When enabled, Promptless will monitor only the channels you explicitly select in your project configuration. This is completely opt-in - you choose which channels to monitor and can add or remove channels at any time. If you don't enable this option, we will not be monitoring any slack channels. For more details, see our [Slack Integration documentation](/docs/reference/integrations/slack) and [Reviewing from Slack and Teams](/docs/work-the-queue/reviewing-from-slack-and-teams#4-passive-channel-listening). ### Does Promptless analyze my entire codebase? No. When triggered by a pull request, Promptless only analyzes the changed files in the PR diff—it doesn't search across your entire repository. This focused approach helps Promptless understand exactly what changed and generate relevant documentation updates. ### How does Promptless handle my data? Promptless follows strict data handling practices: - Documentation copies are stored for processing - Third-party integration data is processed but not stored - End-user data is not processed - All data is encrypted in transit (TLS 1.2+) and at rest (AES-256) For detailed information, see our [Data Handling documentation](/docs/security/data-handling-and-classification). ## Have more questions? If you don't see your question answered here, please reach out to our support team at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Account management url: https://promptless.ai/docs/reference/account-management --- import { Aside } from '@astrojs/starlight/components'; Manage your Promptless organization, team members, and access controls through the account management interface. ## Create an account You can sign up for an account at [accounts.gopromptless.ai](https://accounts.gopromptless.ai), or contact the team at [hello@gopromptless.ai](mailto:hello@gopromptless.ai). ## Manage team members ### Add team members To add other users to your team account: 1. Click on your organization name in the upper left corner of the dashboard 2. Select "Manage" from the dropdown menu 3. In the management modal, you'll find options to invite new team members Organization manage button ### User roles Promptless supports different user roles with varying levels of access: **`Admin`** — *role* Full access to organization settings, team management, and all documentation suggestions. Can edit suggestions, manage integrations, configure projects, and edit the Agent Knowledge Base. **`Editor`** — *role* Can edit documentation suggestions and create new tasks, but cannot manage organization settings, integrations, or team members. Perfect for team members who work directly on docs without needing admin access. **`Collaborator`** — *role* Can view documentation suggestions and leave comments for feedback, but cannot edit or modify suggestions. Perfect for stakeholders who need to review content without making direct changes. ## Domain verification and auto-enrollment ### Set up automatic team member joining You can add domains to your organization to streamline the process of adding new members with email addresses from your company domain. When a verified domain is added, users with email addresses from that domain can join your organization based on your selected enrollment mode. 1. Click on your organization name in the upper left corner of the dashboard 2. Select "Manage" from the dropdown menu 3. In the "Verified domains" section, click "Add domain" Add domain interface 4. Enter your domain (e.g., "yourcompany.com") and click "Save" 5. After verification, you'll be prompted to select an enrollment mode: Enrollment mode selection 6. Click "Save" to apply your selected enrollment mode Once configured, new users with email addresses matching your verified domain will be able to join your organization according to the enrollment mode you've selected. ## Organization settings ### Security and access controls Promptless provides enterprise-grade security features for organization management: - **Single Sign-On (SSO)**: Integration with Google, GitHub, and enterprise identity providers - **Two-Factor Authentication (2FA)**: TOTP-based authentication for enhanced security - **SAML 2.0**: Just-in-time provisioning for enterprise customers - **OpenID Connect (OIDC)**: Modern authentication standards support ## Need help? If you have questions about account management or need assistance with team setup, please reach out to our support team at [help@gopromptless.ai](mailto:help@gopromptless.ai). *** title: Get support url: https://promptless.ai/docs/reference/getting-help --- import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; Have questions or need assistance? We're here to help. Our team actively wants to help you get the most out of Promptless. Whether you're troubleshooting an issue, fine-tuning your setup, or just have a question, don't hesitate to reach out. We can help with: - **Issues with events Promptless has processed**: If something doesn't look right with a trigger, suggestion, or any event Promptless handled (e.g., a code PR, a Slack message, or anything else), let us know and we'll investigate. - **Configuring your setup**: Need help with integrations, pipelines, or other configuration? We're happy to walk through it with you. - **Steering the Promptless agent**: Want to guide the agent's behavior, adjust preferences, or customize how it handles your docs? We can help you dial it in. - **Anything else**: No question is too small. If you're wondering about something, just ask. ### Contact us Questions, feedback, or troubleshooting—reach us at help@gopromptless.ai. During onboarding, we set up a shared Slack channel between your team and ours for direct support. ## Blog *** title: Agent Context Files Explained: AGENTS.md, CLAUDE.md, and llms.txt url: https://promptless.ai/blog/technical/agent-context-files-explained description: AGENTS.md, CLAUDE.md, and llms.txt give AI agents the product-specific context they need to work correctly. Here's what each file does and why they go stale. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Your latest API version deprecated the `createUser` endpoint three weeks ago. The migration guide is live. Your AGENTS.md still points to the old one. Every coding agent your enterprise customers are running just read it, believed it, and generated code against a deprecated endpoint. Nobody noticed because the agent didn't error. It ran exactly as designed. This is what context rot looks like in practice: not a crash, but a confident wrong answer that takes days to trace back to a stale file. ## The three files and what they do AGENTS.md, CLAUDE.md, and llms.txt all give AI agents product-specific context, but they operate at different scopes. **AGENTS.md** became the cross-platform standard for agent configuration in mid-2025, co-promoted by Anthropic, OpenAI, Google, Sourcegraph, Cursor, JetBrains, and others. It replaced the earlier fragmented ecosystem of per-tool files like `.cursorrules`, `.clinerules`, and `CLAUDE.md`. Put AGENTS.md at the repo root and every major coding agent reads it: Claude Code, Codex CLI, Cursor, Aider, Devin, Sourcegraph Amp, and more. **CLAUDE.md** predates AGENTS.md and is specific to Anthropic tools. Many teams still use it, particularly in Claude Code workflows. If you're writing context for cross-agent use, AGENTS.md is the better target. If you're running a Claude-specific deployment, CLAUDE.md remains valid and lets you include Claude-specific behavioral instructions. **llms.txt** is different in scope. It's a machine-readable index of your documentation site: a structured list of pages with brief descriptions that tells agents what exists and where to find it. It's not a search ranking signal and it doesn't improve AI model training. For developer-facing companies, its value is navigational: when a coding agent needs to look up your API reference, llms.txt tells it which URL to fetch rather than forcing it to guess or scrape your nav. AGENTS.md and CLAUDE.md give behavioral and knowledge instructions. llms.txt gives structural navigation. Both are necessary for agents to work reliably with your product. ## What actually belongs in them The most common mistake is treating AGENTS.md like a prompt. Teams write instructions about coding style, preferred patterns, or general best practices — things any capable language model already follows. An ETH Zurich study published in early 2026 found that LLM-generated AGENTS.md files often hurt agent performance. Generic instructions add noise. The files that helped were short and specific: they contained facts the model couldn't infer from the code or public documentation. The test for what belongs in a context file: could the agent figure this out by reading the codebase and your public docs? If yes, leave it out. If no, put it in. What agents can't infer on their own: - Which endpoints are deprecated and what replaced them - Which internal packages exist and what they're for - Constraints that don't appear in public docs (for example: "operation X fails silently when Y is already active") - Which parts of the codebase should never be modified by automated agents - Ownership boundaries (which team is responsible for which subsystem) What agents can already figure out: general coding style, framework conventions, standard error handling patterns, common library idioms. Context files should be short. Every line should earn its place by carrying product-specific information the model doesn't already have. ## Why context files go stale Context files start accurate. The problem starts after launch. Your product evolves: new API versions ship, endpoints get deprecated, packages get renamed, schemas get migrated. The code changes. The AGENTS.md doesn't. Nobody set up a review trigger for it. Nobody owns it. Unlike your main docs, there's no support ticket feedback loop that surfaces when it's wrong. The degradation is invisible because agents don't flag it. A developer reading docs that reference an old API version might notice something feels dated. Agents take docs at face value. They believe what they read and reason forward from there. A stale instruction in step two becomes the unquestioned premise for steps three, four, and five. Salesforce's AI Research team published a study in 2025 showing enterprise AI agents fail 65% of multi-turn tasks. Single-turn performance is significantly higher. The gap reflects how errors compound across turns when context carries forward bad assumptions. What starts as one wrong premise becomes a confident incorrect answer by the end of a multi-step workflow. The blast radius is larger than it looks. Every coding agent your developers or your users have installed reads your context files. A single stale instruction propagates to Cursor, Claude Code, Copilot, and every other agent that queries your docs or operates in your repo. It doesn't matter that the instruction was accurate when you wrote it. ## Treating context files like code The maintenance problem is an ownership problem. Most teams create AGENTS.md once and move on. No one's job is to update it when an endpoint changes. The fix requires three things: **Assign ownership.** One person or team is responsible for each context file, the same way someone owns an API reference page. Without a named owner, nobody reviews it. **Define review triggers.** AGENTS.md belongs on the review checklist for any PR that deprecates an endpoint, changes a package boundary, or modifies a behavioral constraint. The file should be updated in the same commit as the code change, not as an afterthought. **Use section metadata.** Add a "last reviewed" comment to each section. Reviewers can immediately see which sections are months old and need verification. The harder version of this problem is detecting drift automatically: knowing that a line in AGENTS.md references an endpoint that no longer exists, without relying on a reviewer to spot it. That requires comparing the file's content against the actual state of the codebase, which is a tooling problem. ## Documentation accuracy as agent reliability [Agent context engineering](/blog/technical/agent-context-engineering) frameworks treat the knowledge layer as the one that drifts fastest and is hardest to maintain manually. Context files are that layer made concrete. They're the runtime ground truth for every agent that touches your product. [Documentation drift](/blog/technical/documentation-drift-detection-problem) is a detection problem. The damage happens long before anyone notices. Agents have already served the bad context dozens of times. The fix needs to happen before deployment. Promptless monitors your documentation and context files against your actual codebase, surfacing when something in AGENTS.md or your API docs no longer matches what your product does. The same mechanism that keeps your developer docs accurate keeps your agent context files accurate. Both fail in the same way when they're not maintained. *** title: Slack Notifications for Suggestion Outcomes url: https://promptless.ai/blog/product-updates/suggestion-lifecycle-notifications description: Promptless now posts a follow-up reply in each suggestion's Slack thread when the suggestion is merged, closed, rejected, or archived. Admins enable it from Organization Settings. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Promptless now posts a Slack follow-up when a suggestion resolves. When the underlying docs PR is merged or closed, or when the suggestion is rejected or archived, Promptless replies in the Slack thread where it originally announced the suggestion. The feature is opt-in. An admin enables it once in Organization Settings. This closes a feedback loop that was previously missing. Suggestions in Promptless move through a review cycle, but the outcome wasn't surfaced anywhere outside the dashboard or the associated docs PR. ## The problem When Promptless generates a suggestion, it often touches people beyond whoever kicked it off. A developer opens a PR, Promptless generates documentation suggestions for the changes, and then a technical writer reviews those suggestions in the dashboard. Or a content team member triggers a documentation task via a Slack message, and suggestions get distributed across several reviewers. In either case, there was no feedback loop. When a suggestion was merged, the people watching the original Slack thread didn't see the outcome. When a suggestion was rejected, the person who triggered the review didn't know why or when. The only way to track outcomes was to check the dashboard directly or watch the docs PR. For teams with a steady cadence of suggestions across multiple repositories, this meant either ignoring outcomes entirely or building a manual tracking habit that didn't scale. ## What changed Admins can now turn on **Suggestion Status Updates** in Organization Settings. When the toggle is on, Promptless posts one concise reply in each Slack thread where it originally announced a suggestion. Follow-ups fire when a docs PR is merged, when a docs PR is closed without merging, when a suggestion is rejected from the dashboard, or when a suggestion is auto-archived for staleness. Delivery is best-effort. The lifecycle transition itself always completes. If the saved Slack thread for a suggestion is missing or no longer reachable, Promptless logs the skip and moves on. There is a single setting at the organization level. No per-member opt-in is required. Once an admin enables it, every suggestion the org resolves from then on gets a follow-up in its thread. ## Who benefits most Teams whose suggestions get reviewed across more than one surface. If a writer triages in the dashboard while developers and PMs watch in Slack, the dashboard side already knew when a suggestion resolved. The Slack side didn't, until now. The reply lands in the same thread, so anyone who was paying attention to the original suggestion sees the outcome without needing dashboard access. The same applies to suggestions triggered from Slack in the first place. Whoever started the thread, or anyone tagged into it later, sees how it landed. ## How to use it 1. Go to **Organization Settings** in the Promptless dashboard. 2. Find the **Suggestion Status Updates** section. 3. Check **Post Slack follow-ups when suggestions are resolved** and save. Follow-ups will start appearing the next time a suggestion in your org transitions to merged, closed, rejected, or archived. They go into the suggestion's existing Slack thread, in whichever channel Promptless originally used to announce it. *** title: Technical Writing with AI: Faster Drafts, Larger Maintenance Surface url: https://promptless.ai/blog/technical/technical-writing-with-ai description: AI tools have made technical writing faster. They've also created more documentation to maintain, with the same capacity to keep it accurate. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A team of three technical writers adopts AI tools and starts producing documentation at roughly twice their previous rate. Tutorials that would have taken a sprint to write now take a day. Integration guides for niche customer segments that never made the priority list now get written. Coverage gaps close. Six months later, the maintenance backlog is the largest it's ever been. This is the pattern playing out across technical writing teams in 2025 and 2026. The productivity gain from AI is real. The downstream pressure it creates is real too, and most teams encounter it before they've prepared for it. ## The drafting gain is documented [Cherryleaf's 2025 survey of technical communicators](https://www.cherryleaf.com) found that 55% are using AI tools regularly or semi-regularly. Among teams reporting the highest productivity gains, the pattern is consistent. First drafts now take hours instead of days. Writers feed an API spec, a changelog entry, an SME interview transcript, or a Jira ticket into an AI tool and get a structured draft back that needs editing, not starting from scratch. The practical effect is that the cost-benefit math changes on content that previously lost out in sprint planning. A five-page integration tutorial might have taken a week. At a day, it clears the bar. Content that was technically worth writing but practically not worth the time now gets written. Use case guides for smaller customer segments, extended API reference coverage, niche integration tutorials. That's the real productivity gain from AI in technical writing workflows. Output volume grows, not just drafting speed. ## Volume creates surface area Every page that ships is a page that needs to stay accurate. When an auth flow updates or an endpoint gets a new required parameter, every documentation page covering that feature can drift. The team that doubled its published output is now responsible for twice as many pages when that drift happens. Maintenance capacity didn't scale with drafting capacity. The same writers who now produce more are also the writers who catch what's become inaccurate. The U.S. Bureau of Labor Statistics projects [just 1% growth in technical writing employment through 2034](https://www.bls.gov/opub/mlr/2026/article/industry-and-occupational-employment-projections-overview.htm), a net gain of about 500 jobs nationwide. That figure reflects a productivity-per-writer increase, not a drop in demand for documentation. One writer with AI produces more than five writers did without it. Teams are not expanding headcount at the rate their documentation volume is growing. The result is a larger documentation estate managed by the same (or smaller) staff. That's an efficiency gain measured from the wrong end. From the maintenance side, it's more surface area to monitor. ## AI doesn't answer "is this still accurate?" This is the part that surprises teams when they first hit it. AI tools generate from whatever you feed them. They are good at structuring a draft from an API spec or turning a changelog entry into prose. They are not good at checking whether existing documentation still describes what the product currently does. That question requires knowing the product's current state, which requires reading recent commits or checking with an engineer. AI doesn't do that automatically. The draft that was accurate when it was written doesn't stay accurate because of how it was written. A tutorial for an authentication flow is correct until the auth flow changes. At that point, the quality of the original draft has no bearing on whether the tutorial is still right. [Postman's 2024 State of the API report](https://www.postman.com/state-of-api/2024) found that 68% of developers cite outdated documentation as their top frustration. That number predates the current wave of AI-accelerated publishing. Teams publishing more content, without proportionally more capacity to [detect and fix drift](https://promptless.ai/blog/technical/documentation-drift-detection-problem), will not improve that statistic. ## The writer's job is inverting Technical communicators who are honest about what's changing describe a shift in where the work lives, not a reduction in how much there is. In a workflow where AI drafts and humans review, the drafting constraint largely disappears. The remaining constraint is verifying what has drifted from the product's current state and determining where to spend review time on a doc set that's grown faster than the team responsible for it. [Tom Johnson's blog](https://idratherbewriting.com) describes this as technical writers becoming "context curators and content directors." The skill is no longer primarily speed at drafting. It's judgment about what has drifted and where to spend the review budget on a doc set that's larger than it used to be. That judgment operates under real resource pressure. AI-generated volume doesn't come with AI-funded headcount. The team managing twice the content is the same team, making prioritization decisions that will determine which outdated pages developers hit and which ones get caught before they cause problems. ## What teams that manage this well do differently The teams that make AI-assisted technical writing sustainable at scale don't just adopt AI for drafting. They pair it with tooling that surfaces drift signals, so the verification work is scoped, not open-ended. When a product ships a change to an authentication endpoint, the documentation pages covering that endpoint should appear for review automatically, flagged by the change that introduced the problem. When an engineer renames a parameter, the tutorials and code samples referencing the old name should surface before a developer hits an error. The writer's job becomes reviewing a flagged queue, not scanning the entire doc set hoping to catch something. Detection that keeps pace with the publication rate is what makes the larger surface area manageable. [Promptless](https://promptless.ai) continuously monitors documentation against the actual product and codebase, automatically surfacing what's outdated or missing as the product changes. For teams using AI to scale their documentation output, that detection layer is what prevents the larger surface area from becoming the source of compounding inaccuracy. Writers spend review capacity on what the system flagged as changed, not on everything, and the content that reaches developers stays accurate across the full lifecycle of the docs, not just at the moment they were published. *** title: Your Docs Are Pages. Your Product Knowledge Is a Graph. url: https://promptless.ai/blog/technical/your-docs-are-pages-your-product-knowledge-is-a-graph description: Flat docs lose the relationships between your product's concepts. Here's why a living knowledge graph matters for teams building with AI agents. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A Stripe integration guide mentions three authentication methods. The API reference describes which endpoints require which method. The error codes page explains what happens when the wrong method is used. These three pages are separate files in the docs repo. In the product, they are one connected system. When a developer reads across them, they mentally reconstruct the relationship. When an AI agent reads across them, it has to do the same work with less context. It gets the pages as isolated chunks, without any built-in awareness of which concepts depend on which others. That gap, between how documentation is stored and how knowledge actually works, is the problem a living knowledge graph solves. ## Why flat docs lose relationships Most developer documentation lives as flat files in a git repo or as pages in a documentation platform. Both organize around the page as the atomic unit. You write pages, link them, and arrange them into a hierarchy. Your product's concepts don't organize neatly into hierarchies. Endpoints reference schemas; schemas have versioning rules that affect error handling. That web of relationships exists in your product but lives in your docs only as implied links and prose that human readers piece together over multiple pages. For human readers, this is manageable. Developers scan multiple pages, follow links, and build mental models. They reconstruct relationships from disconnected fragments without noticing the effort. AI agents are less good at this. A 2025 study by Chroma tested 18 leading models and found performance degrades as the number of separate documents grows, even when the total information is identical. Increasing the document count in RAG settings reduced performance by up to 20%. Agents reason better within well-structured context than across many disconnected pieces. The solution researchers and tools teams are converging on is to represent knowledge as a graph, not a collection of pages. ## What knowledge graphs add A knowledge graph stores your product's concepts, endpoints, parameters, and authentication methods as nodes, and makes the relationships between them edges. Instead of three separate pages that reference each other through prose links, you get a direct representation — endpoint A requires authentication method B, which was deprecated in API version 3.1 and replaced by method C. This structure gives agents traversable relationships that flat docs cannot provide. Instead of fetching a page and inferring what it connects to, an agent can query the graph directly — asking what changed about authentication in version 3.1 becomes a graph traversal, not a semantic search across thousands of text chunks. The performance difference is measurable. When Microsoft shipped GraphRAG 1.0 in April 2025, benchmarks showed relational retrieval outperforming standard vector search by 3-5x on multi-hop reasoning tasks — queries that require connecting information across multiple concepts. Token costs dropped 80-97% for the same queries, because the graph returns a precise subgraph instead of pulling in everything above a semantic similarity threshold. Anthropic saw the same pattern. When they released the Model Context Protocol in November 2024, the reference implementation for persistent agent memory was a knowledge graph, not a vector database. ## The "living" problem Building a knowledge graph of your documentation is tractable. The harder problem is keeping it current. A knowledge graph that accurately represents your product at launch becomes a liability over time. API versioning changes which parameters are valid, a feature ships that adds required fields, an authentication flow is deprecated — and the graph now contains confident, traversable facts that are wrong. Stale flat docs can at least be dated — a developer looking at "Authentication Guide" might think to check when it was last updated. A knowledge graph node does not come with visible staleness signals. An agent querying the authentication requirements for endpoint A gets a clean, specific answer, with no indication that it was accurate six months ago and wrong today. Meta's engineering team ran into this in April 2026. Their writeup on mapping tribal knowledge in large-scale data pipelines found that static knowledge representations — documentation, wikis, schemas — could not keep pace with how quickly the underlying systems changed. The accurate record of system state at any moment was the live system, not the documentation. For developer-facing products, that means your docs, your API specs, and your knowledge graph need to update when your product updates — not quarterly, not in a sprint cycle. ## What makes a knowledge graph "living" A living knowledge graph has two properties a static one lacks. First, it tracks temporal facts, recording not just the current state of each relationship but the full history — "endpoint A required method B from version 2.0 through 3.0, then transitioned to method C in 3.1." [Graphiti](https://github.com/getzep/graphiti), an open-source temporal knowledge graph framework for AI agents, treats this as a first-class concern. Every fact in the graph has a validity period, and queries can be scoped to a specific version or time window. An agent asking about version 2.8 gets a version 2.8 answer, not today's answer. Second, it has automated freshness monitoring. When your product ships a change, something detects that the change affects the knowledge graph and surfaces what needs updating. This is the part most teams do not build, because it requires connecting your deployment pipeline to your documentation layer and building logic to detect when the documented state diverges from the actual state. The teams closest to getting this right in 2026 are treating it as an infrastructure problem, similar to how data engineering treats schema drift. You do not manually check whether your data pipelines are still producing valid output after every schema change. You build detectors that alert when drift occurs. GitNexus, which hit number one on GitHub trending in April 2026, parses codebases into knowledge graphs specifically to give AI coding agents current, relational context about a codebase. The pattern is spreading because the alternative, relying on static pages, keeps producing bad agent outputs. ## Where to start You do not need to rebuild your documentation as a formal knowledge graph to benefit from thinking about it this way. The immediate question is which relationships in your product are most critical for agents to reason across, and whether those relationships are explicit anywhere in your docs. For most developer-facing products, the highest-leverage area is API versioning. If an agent asks "is this method still valid?" and the answer is spread across a changelog, a reference page, and an implicit assumption in a code sample, the agent will often get it wrong. Making versioning relationships explicit, with one source of truth for what changed, what it replaced, and what the downstream effects are, is the starting point for a living knowledge layer. The structural fix and the freshness fix need to work together. A well-structured knowledge graph that does not update gives confident wrong answers. Freshness monitoring applied to poorly structured docs catches drift but cannot always surface what the accurate version should be. Agent failures often trace back to the knowledge layer. [What Is Agent Context Engineering?](https://promptless.ai/blog/technical/agent-context-engineering) and [Documentation Drift Is a Detection Problem](https://promptless.ai/blog/technical/documentation-drift-detection-problem) go deeper on both. *** title: Documentation Versioning Best Practices for API Teams url: https://promptless.ai/blog/technical/documentation-versioning-maintenance-multiplier description: Versioned docs multiply your maintenance work with every release. Here's how API teams can plan for it before it becomes a support problem. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A developer searches for how to authenticate with your API. Google returns your v1 docs. They implement the deprecated OAuth flow, ship the integration, and three weeks later open a support ticket when the endpoint stops responding. The version selector exists and the current docs are accurate. Nobody landed on them. The core problem with documentation versioning is that adding a version selector is easy. The hard part is ensuring your versioning setup doesn't multiply your maintenance debt while developers keep landing on the wrong pages. ## Old pages don't go away on their own When you publish versioned documentation, every old version stays live on a public URL. Search engines index all of it. A developer searching for "how to use your webhook API" may land on a v1 page that hasn't been touched since 2022, with no indication that v3 exists. The fix is a canonical URL configuration. Read the Docs, MkDocs Material, and Docusaurus all support a `canonical_version` setting that tells search engines which version to prefer. Set it to your latest stable release. Old pages remain indexed, but organic search traffic concentrates on the version you actually maintain. Without it, you are effectively competing against yourself in search results. Your v1, v2, and v3 authentication pages are all indexed. Developers land on whichever one Google serves them. If your v1 page has more inbound links than your v3 page, it will rank higher regardless of accuracy. This is a five-minute configuration change with a meaningful impact on how often developers reach correct documentation. ## Each new version multiplies the maintenance surface The deeper problem is what happens inside your team after you ship v2, then v3, then v4. Most teams budget writing time for documentation. Maintenance time across versions is a different story. When you have one set of docs, a product change requires one fix. When you have four live versions, that same change requires four fixes, in four places, with four separate reviews and deploys. If you're using Docusaurus or Antora's default branch-per-version strategy, those fixes typically have to be cherry-picked across branches manually. [Docusaurus documentation](https://docusaurus.io/docs/versioning) warns teams to keep the number of versions below 10, citing the near-certainty of accumulating obsolete documentation nobody reads. The recommendation exists because teams routinely underestimate how expensive old versions become over time. Four hours a month on one version becomes twenty hours on five. Each version is a separate drift surface. A factual error introduced after a branching point can exist in one version, several, or all of them, depending on when the underlying product changed and how carefully your team tracked it. ## Branch-per-version versus single source There are two main approaches to versioning documentation. **Branch-per-version** stores each version in a separate Git branch. The workflow mirrors how engineering teams manage code releases, which makes it feel natural. The downside is content duplication. Between any two adjacent versions of your docs, roughly 80% of the content is identical. That 80% has to be patched separately in each branch when the underlying product changes. As the number of supported versions grows, routine maintenance becomes disproportionately expensive. **Single-source with conditional content** keeps one set of source files and uses conditionals or variables to render version-specific differences. GitHub Docs uses this approach for their product, which spans multiple GitHub plans and deployment types simultaneously. The tradeoff is higher setup complexity upfront. Writers need to learn the conditional syntax, and mistakes in conditional logic can cause content to appear in the wrong version. But the payoff is that shared content only exists once. When it needs updating, one edit propagates across all versions. For teams maintaining two or three long-lived API versions, branch-per-version is manageable. For teams maintaining five or more, the duplication cost is usually worth solving. The Docusaurus team [recommends thinking carefully before adding each new version](https://docusaurus.io/docs/versioning), specifically because most teams don't plan for the long-term maintenance implications. ## Deprecation timelines rarely hold The hardest part of a versioning strategy is following through on deprecation, not setting it up. A typical API deprecation cycle runs a 6-month announcement, 12 months of active migration support, and full removal at 18-24 months. In practice, teams extend these timelines repeatedly because users don't migrate on schedule. Without data on which clients are still using deprecated versions, it's impossible to know whether it's safe to remove them. The result is that teams accumulate live documentation versions indefinitely. You can't deprecate what you can't measure. Deprecation is a usage metrics problem as much as a communication problem. Tracking version-specific traffic and API call patterns lets you make deprecation decisions based on actual adoption data, not guesswork. If 0.3% of your traffic is on v1 after two years, that's different from 12%. Low adoption justifies removal; high adoption means your migration path needs work before you pull the version. Announcing a deprecation timeline without this data produces repeated extensions, mounting maintenance cost, and documentation drift accumulating across every version you can't remove. ## Versioning doesn't prevent drift inside each version A well-configured versioning setup solves the problem of organizing past releases. It doesn't solve the problem of documentation staying accurate after a branch is cut. Once you create a versioned snapshot of your docs, that snapshot starts diverging from reality the moment the product changes. Any product change after a branching point can invalidate documentation in a live version. That includes bug fixes, renamed parameters, updated authentication flows, and new required fields. Teams that track this manually, by checking docs after every release, don't scale. Teams that don't track it at all accumulate [documentation drift](/blog/technical/documentation-drift-detection-problem) across every live version simultaneously. The versioning strategy manages the structure. The drift problem requires a separate monitoring layer. *** title: Documentation Coverage: The Metric Your Engineering Team Has Never Checked url: https://promptless.ai/blog/technical/documentation-coverage description: Your engineering team tracks test coverage. Almost no one tracks documentation coverage. Here's how to measure whether your product surface is actually documented. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Your engineering team gets a coverage report every time tests run. It tells you exactly which functions have no test coverage and which branches are never exercised. If coverage drops below a threshold, your CI pipeline can fail the build. Your documentation has no equivalent. There is no automated report telling you which API endpoints lack reference docs, which SDK methods have no examples, or which product features have never been explained to a developer. If 30 percent of your product surface is undocumented, nothing catches it. The documentation coverage problem is the systematic gap between what your product does and what your docs describe, with no mechanism to detect it. ## Coverage Is Not the Same as Quality Most teams treat documentation problems as quality problems. A page is outdated, an example is wrong, a parameter is misdescribed. These are worth fixing. But they require that the page exists at all. Documentation coverage asks whether content exists for this part of the product at all. Coverage and quality are distinct failure modes: - A coverage gap means developers hit a dead end. They go to your docs looking for information about a feature and find nothing. No page to read. No example to adapt. - A quality gap means developers find a page that misleads them. The information exists but is wrong or incomplete. Both are harmful. Coverage gaps are the more invisible of the two because there is nothing to flag. A developer who finds a wrong page files a support ticket or leaves a feedback comment. A developer who finds nothing assumes the feature does not exist, gives up, or opens a support ticket asking whether something is possible. The only real problem is that nobody documented it. Coverage also has dimensions. **Breadth** measures what percentage of your public API surface, SDK methods, or product features have at least one documentation page. **Depth** measures whether the documentation that exists is complete enough to be useful. **Freshness** measures whether documented features still reflect how the product actually works. That problem is covered in detail in [Documentation Drift Is a Detection Problem, Not a Writing Problem](/blog/technical/documentation-drift-detection-problem). If you are starting from zero, start with breadth. You cannot improve depth or freshness for content that does not exist. ## Why Teams Don't Track Coverage The test coverage analogy is obvious once you hear it. Engineering teams have accepted for decades that untested code is a liability, so they automate coverage measurement as a consequence. Documentation has the same liability structure but almost nobody applies the same rigor. The tooling gap explains part of this. Test runners produce coverage reports as a side effect of running tests. Documentation has no equivalent runtime artifact. There is no CI step that compares your OpenAPI spec to your docs site and outputs a percentage. The ownership gap explains the rest. Documentation coverage spans multiple teams, with developers writing inline comments and READMEs, technical writers owning the docs site, and DevRel managing tutorials and guides. Nobody has a complete inventory of what is documented, so nobody notices the gaps between all three. The result is that most teams discover documentation coverage gaps reactively. A developer opens a support ticket asking how to use a feature that was never documented. The question surfaces in a Slack channel. A post appears on a forum. By then, the gap has already caused friction for at least one person and probably for many more who silently gave up. Research from GetDX estimates that documentation problems consume 15 to 25 percent of engineering capacity. That cost includes time developers spend searching for information and interrupting colleagues for answers. A significant share of that cost comes from features that shipped without documentation. ## How to Measure Documentation Coverage You do not need specialized tooling to get a first approximation. You need an inventory. ### Compare your API spec to your docs site If you have an OpenAPI spec, you have a structured inventory of every endpoint, method, parameter, and response your API exposes. Compare that inventory against your documentation site. Count how many endpoints have a corresponding reference page. Count how many are absent. Tools like Fern, Speakeasy, and Theneo can automate this comparison when your docs are generated from or linked to your spec. If they are not, a manual audit of your spec against your docs index still produces a defensible coverage percentage in a few hours. The number you get may be uncomfortable, but it is more useful than not knowing. ### Treat zero-result searches as a coverage signal Your documentation search logs are a direct window into gaps. When developers search for something and get no results, they are telling you what they were looking for that does not exist in your docs. A B2B technology company that analyzed its docs search logs found that 23 percent of all queries returned zero results. After a systematic content effort targeting the most common missing topics, that rate dropped to 6 percent and support escalation rates declined by 18 percent. Zero-result searches do not show you everything that is undocumented. They only surface the gaps developers actively searched for. But they are actionable immediately and require no additional tooling if your docs platform has built-in search analytics. GitBook, Fern, Document360, and ReadMe all surface this data in their default dashboards. If you are not looking at it, you are leaving a direct signal unused. For a deeper look at how to use search analytics alongside other documentation metrics, the [complete documentation metrics and analytics guide](/blog/technical/documentation-metrics-and-analytics-a-complete-guide-for-dev) covers the full measurement stack. ### Map support tickets to documentation status Support tickets are lagging indicators of coverage gaps. When a developer opens a ticket asking how to accomplish something your product supports, there is a reasonable chance it was never documented, or was documented incompletely. Tagging each incoming support ticket as documented, undocumented, or documented-but-unclear builds a coverage gap queue sorted by customer impact. HappyFox enterprise data suggests that up to 80 percent of support tickets address issues already present in existing knowledge bases, pointing to a findability problem. The remaining 20 percent often represents genuine coverage gaps, meaning features that exist but were never written up. ## Making Coverage a First-Class Quality Gate Most teams ship features and write documentation afterward, sometimes weeks later, sometimes never. This is the default because documentation is rarely in the definition of done. The most direct fix is structural. Documentation is required before a feature ships, and a feature is not complete until it has at least a basic reference page. This prevents gaps from accumulating in the first place. For API products in particular, this maps cleanly to existing engineering practices. If an endpoint exists in the spec when it ships, a corresponding page should exist in the docs. For existing gaps, a coverage audit provides the prioritized backlog. Start with the endpoints or features generating the most support tickets or zero-result searches. Work down from there. [Documentation debt](/blog/technical/documentation-debt-accrues-where-your-team-cant-see-it) compounds when gaps go unaddressed; a coverage backlog replaces invisible accumulation with a queue you can clear. If your documentation is generated from structured sources like OpenAPI specs or code comments, you can automate coverage checks by comparing the spec to rendered documentation on each build and flagging new endpoints that have no corresponding page. If your documentation is not generated from structured sources, a quarterly audit against your product changelog is a reasonable substitute. Reviewing every feature shipped in the past quarter against your docs index takes an afternoon and surfaces gaps before they become support costs. The goal is not a perfect score. It is knowing your current coverage, tracking it over time, and having a process that prevents the number from eroding as your product grows. *** title: Documentation Coverage: The Metric Your AI Features Actually Need url: https://promptless.ai/blog/technical/documentation-coverage-metrics-for-ai-features description: Most docs teams track page count and traffic. Here's why documentation coverage is the metric that actually predicts whether your AI features will work. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Your engineering team measures code coverage. They know which paths are tested and which aren't. A drop below 80% triggers a conversation. Nobody ships without checking it. Your documentation team probably tracks page views, word count, and time on page. Those numbers show how much documentation exists and how often it's read. They don't show whether the documentation matches your actual product. That gap is the documentation coverage problem. ## What documentation coverage means Code coverage measures which lines of code are exercised by tests. Documentation coverage measures which features, endpoints, and behaviors in your product have accurate, current documentation. **Breadth** covers whether a given product surface has documentation at all. An API endpoint with no page, a parameter that goes undescribed — these are gaps in the traditional sense. **Accuracy** is harder to see. It measures whether the documentation matches what the product currently does. A parameter renamed two releases ago while the docs still use the old name. An authentication flow updated after a security change while the quickstart still shows the legacy steps. These pages exist, show up in search, and look complete. Most documentation audits find breadth gaps. They miss accuracy gaps because the audit strategy is to check whether pages exist, not whether pages are correct. Teams come away thinking their coverage is better than it is. ## The coverage debt that builds silently Breadth and accuracy both degrade over time, but for different reasons. Breadth gaps grow when new features ship without documentation. Accuracy gaps grow when existing features change without corresponding doc updates. The second category is harder to catch because no flag fires. No new page needs to be created, so nothing prompts a review. [Documentation drift](/blog/documentation-drift-detection-problem) is the slow divergence between what your product does and what your docs say. A typical API-first company ships dozens of changes per sprint. Some of those changes affect documented behavior. Without a systematic coverage process, accuracy gaps compound across releases. By the time someone notices, the knowledge base has months of drift baked in with no visible signal about where the problems are. ## Why AI makes coverage gaps urgent For most of documentation history, coverage gaps were managed through the support queue. A user hits a problem, files a ticket, and the team eventually updates the docs. The feedback loop was slow, but it worked. AI-powered features change that dynamic. When a support bot or coding assistant surfaces answers from your documentation, coverage gaps stop being friction and become user-facing failures. A [2026 analysis from Fini Labs](https://www.usefini.com/guides/ai-surface-knowledge-gaps), citing a 2025 Gartner study, found that 47% of customer service knowledge bases contain conflicting information across articles. In 31% of agent escalations, the root cause traced to outdated or missing content. Those agents reasoned correctly from what they were given. What they were given was wrong. The retrieval problem makes accuracy gaps dangerous in a specific way. Semantic search has no built-in preference for freshness. Outdated documentation scores just as high on semantic similarity as current documentation. An agent retrieves the most relevant chunk available; it has no way to know whether that chunk describes behavior from two years ago. It surfaces the answer with full confidence either way. [This is context failure in practice](/blog/agent-context-engineering). The model operated correctly on bad information. Better model quality won't change the outcome. A more accurate knowledge base will. ## How to start measuring coverage Code coverage is automatable because you can instrument code and observe which lines execute. Documentation coverage is harder because "what does the product do" isn't always machine-readable. But there are tractable starting points. **Map docs to your API surface.** If you publish an OpenAPI spec, compare it against your documentation index to identify which endpoints have dedicated pages, which parameters are described, and which error responses have entries. This gives you breadth coverage for your API reference — a concrete number you can track over time. **Use changelogs as accuracy signals.** Every entry describing a behavior change is a potential accuracy gap. If the corresponding doc page wasn't updated in the same release window, it's a candidate for review. Most teams underuse changelogs as documentation audit triggers despite being one of the clearest signals available. **Tag support escalations by cause.** When a user question requires a human to answer, it signals a coverage failure. Either the answer wasn't documented (breadth gap) or the documentation was wrong (accuracy gap). Tagging escalations by category builds a coverage map grounded in real failures, not assumptions about what might be missing. The healthcare organization referenced in Fini Labs' 2026 study used AI to identify 47 specific gaps in insurance documentation. Closing those gaps reduced average call handling time by 22%. The improvement didn't come from adding new content. It came from fixing accuracy coverage in the existing knowledge base. ## Coverage as a reliability metric Documentation has historically been treated as a quality-of-life concern. Good docs help users succeed; bad docs create friction. The priority reflects that framing, and it rarely gets the same operational rigor as the product itself. AI changes the calculus. When documentation feeds an agent operating at scale, documentation accuracy becomes a reliability issue. A 47% conflicting-information rate means nearly half of what an agent retrieves is potentially wrong. Addressing that is a product reliability problem, not a documentation polish project. Teams that track documentation coverage as a first-class metric will have more reliable AI features. Teams that keep measuring page count will keep trying to diagnose AI failures in the wrong place. *** title: Interactive API Documentation: Why the Hard Part Is Keeping It Accurate url: https://promptless.ai/blog/technical/interactive-api-documentation description: Most teams ship interactive API docs and stop there. Here's why spec drift undermines the "try it out" experience, and what changes when AI agents are involved. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A developer follows your "try it out" button. They fill in the parameters the interactive console shows. They click execute. The API returns a 422. The request schema in the console doesn't match what the endpoint actually accepts. They close the tab and look for a community forum. Or they move on to a competitor whose docs work. This sequence happens because interactive API documentation has a maintenance problem that most teams don't treat as a maintenance problem. They treat it as a publishing problem: solved once, at launch. ## The spec is the product, not the UI Interactive API documentation (Swagger UI, Redoc, Scalar, ReadMe, Stoplight Elements) all render from the same underlying artifact: an OpenAPI specification. The interactivity isn't in the tool. It's a consequence of the spec being machine-readable. This matters because most teams think about the documentation layer (which tool, which theme, how the sidebar is organized) and underinvest in the spec layer (whether the spec is accurate). The typical workflow looks like this: API ships. Someone writes the OpenAPI spec, or generates it from code annotations, or exports it from a tool. The interactive docs go live. From that point on, the spec is treated as stable. Backend engineers add parameters and rename fields. The spec doesn't follow. This is called spec drift. [According to Kinde](https://www.kinde.com/learn/ai-for-software-engineering/ai-devops/spec-drift-the-hidden-problem-ai-can-help-fix/), it starts the moment a developer merges a route change without updating the spec. That's the default behavior on most teams, because there's no enforcement step that makes updating the spec mandatory before a PR merges. [The Postman 2024 State of the API report](https://voyager.postman.com/doc/postman-state-of-the-api-report-2024.pdf), which surveyed over 5,600 developers, found that 68% of developers cite outdated documentation as their top frustration when working with APIs. Teams that have shipped interactive docs are not exempt from this. The interactivity doesn't solve the accuracy problem. It just adds a new surface on which inaccuracy shows up. ## Why "try it out" raises the stakes A static reference page with wrong information frustrates developers. An interactive console with wrong information does something different: it actively tests the developer's trust and fails in real time. When a developer reads a static page and something doesn't work, they might wonder if the problem is in their code. When they click "try it out" and get an unexpected error, there's no ambiguity. The docs are wrong. The documentation site has just proved itself unreliable in front of them. That trust break compounds. A developer who gets a bad result from the interactive console will also discount the reference docs and conceptual guides. The whole site is now suspect. The inverse is also true: when interactive docs work, they build unusually strong trust. A developer who successfully calls an endpoint through the console and sees the exact response shape they'll need to parse in their integration has gotten something a static page can't give them. The fidelity of a working interactive experience is high. So is the damage of a broken one. Most teams don't have a signal for how often "try it out" produces wrong results. As with [documentation drift more broadly](/blog/technical/documentation-drift-detection-problem), the bottleneck is detection: the team that shipped the docs doesn't know something is wrong until a developer outside the team surfaces it. There's no error log for "developer clicked execute and got unexpected behavior." The first signal is usually a support ticket filed weeks after the bad experience. ## Your second audience: AI coding assistants The developer clicking "try it out" is no longer your only concern. AI coding assistants (Cursor, GitHub Copilot, Claude) parse OpenAPI specs directly to understand API surfaces. When a developer asks their coding assistant how to call your authentication endpoint, the assistant may fetch your OpenAPI spec and generate the code from it. A new tool called [OpenAPI Slimmer](https://medium.com/@mcsavvy/introducing-openapi-slimmer-slim-down-your-api-specs-for-ai-agents-b0f199ea37f2) was built specifically to compress OpenAPI specs for agent consumption, which signals how routinely agents are reading these files. The blast radius of a stale spec has grown. Before, a wrong parameter in your OpenAPI spec frustrated a developer who was looking at the interactive console. Now, it generates wrong code for every developer in your community whose AI assistant loads that spec. The spec field that says `token_type: "bearer"` but should say `token_type: "jwt"` no longer just shows up wrong in Swagger UI. It propagates into generated code across every AI-assisted integration. Each developer gets a confident, incorrect implementation. They debug it, then discover the spec was wrong. Some file support tickets. Most don't. Research on AI agent reliability is consistent on this point: stale context doesn't produce uncertainty. It produces confident wrong answers. There's no hedging. The model answers from what it found. As the [Promptless post on agent context engineering](/blog/technical/agent-context-engineering) describes, each step in an agent's execution uses prior outputs as inputs, so a stale spec retrieved early becomes the assumption underlying every code snippet that follows. ## What spec-first development actually requires The cleanest solution to spec drift is spec-first development: design the API in OpenAPI, implement to match the spec, and treat the spec as the source of truth from the start. In this model, drift can't accumulate because code is validated against the spec, not the other way around. This is the right approach for new APIs. For teams with existing APIs and existing codebases, it requires significant workflow change and buy-in that most teams aren't positioned to get. The practical alternative is continuous spec validation. After every release, an automated process diffs the published OpenAPI spec against actual API behavior: request shapes, response schemas, status codes, authentication flows. Discrepancies get surfaced before developers hit them. [Research on spec-driven development](https://arxiv.org/html/2602.00180v1) describes three levels of spec rigor: spec-first (spec drives implementation), spec-anchored (spec is updated alongside code), and spec-as-source (spec is generated from a canonical source and regenerated on each deploy). Teams that maintain accurate interactive docs tend to operate at the spec-anchored or spec-as-source level. They don't update the spec manually when they remember. They have a process that makes the spec accurate by default. The teams whose interactive docs stay accurate over time treat the spec the same way they treat a test suite: something that runs on every deploy, fails loudly when something is wrong, and blocks a release that would otherwise publish incorrect information. ## What accurate interactive docs require Getting from "we have Swagger UI deployed" to "our interactive docs are reliable" involves a few specific commitments: **The spec needs to be generated or validated on every API release.** Manual updates don't hold. Engineers are focused on shipping features, not documentation. A spec that's updated by convention will drift. **Breaking changes in the spec should block deploys the same way failing tests block deploys.** If a developer can merge a route rename without updating the spec, they will. The spec needs enforcement, not reminders. **The spec's accuracy needs monitoring, not just the spec's existence.** Many teams have confirmed their OpenAPI spec is syntactically valid and renders correctly in Swagger UI. Fewer have confirmed it matches what the API actually does. These are different checks. Interactive API documentation is a commitment that the spec reflects deployed behavior. Without the maintenance process to back that commitment, it's a liability. The "try it out" button is an implicit promise. When the spec is wrong, the button breaks that promise in front of every developer who tries to use it. ## How Promptless fits in Promptless monitors API reference documentation against the actual product, surfacing where documentation has drifted from what the API currently does. For teams maintaining interactive docs, this means knowing about spec drift before developers or AI coding assistants encounter it, rather than after. The goal isn't a perfect spec at launch. It's a spec that stays accurate as the product changes. *** title: Ship Your First (or Next) Open Source Docs PR url: https://promptless.ai/blog/life-at-promptless/wtd-writing-day description: Come work through pre-vetted documentation issues from real open-source projects at Write the Docs Portland 2026 Writing Day. Projects include Mautic, Vitess, and Helm. --- Hey fellow Writing Day people! Want to leave Portland with a real contribution to a big name open-source project? Come work through pre-vetted documentation issues from projects that actually need the help. I've coordinated in advance with maintainers from Mautic, Vitess, and Helm (with more pending) to label "good first issue" docs tasks: information architecture, confusing instructions, fuzzy contributor guides, missing pages. Bring a laptop, pick an issue, ship a PR. | Project | Good First Docs Issues | |---------|-----| | Mautic | https://github.com/mautic/developer-documentation-new/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22 | | Vitess | https://github.com/vitessio/website/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22%20label%3Adocumentation | | Helm | https://github.com/helm/helm-www/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22 | | ... | adding more as docs maintainers get back to me | ## Mautic I talked to Ayu Adiati on Slack. She has labeled a bunch of Good First Issue for us to work on. > The user docs so far is a bit behind with Ul screenshots. Most of them are still for version before 5.2. The most important docs to update is version 7.0 and 7.1 (they have the same UI), then 6.0 and 5.2 as some folks are still using these versions as well. > > I was focusing in building the guidelines for contributing, so it takes me some time to update them myself bit by bit. > > In my own experience, I sometimes found missing instructions or any other features that need to be added and updated while updating the screenshots. > > Dev docs is the one that definitely need some love. Folks has been asking for clarity as the contents are outdated. [...] ## Vitess There are 15 issues open looking for help, but when I talked with Matt Lord at Vitess, he mentioned > Honestly, stepping back would probably be more helpful. > > What the website -> docs experience is like for a newcomer and how it could be improved. > > Where to start, how to find things, etc. Organization more than content So Vitess is looking for more Information Architecture recommendations and guidance. Open a new issue explaining what you find. They are happy to take PRs for anything, so happy hunting! ## Helm Helm has 6 open docs issues labeled as good first issues. One of them is from 2021, so maybe I'll claim getting that one knocked out. *** title: How to Connect Code Repositories with Documentation Platforms url: https://promptless.ai/blog/technical/connect-code-repositories-with-documentation-platforms description: If you're looking to connect a docs repo to Fern, Readme, GitBook, or Mintlify — that's easy and each platform covers it. This is about the harder problem: connecting your product code so docs stay current when the product changes. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; If you're adopting Docs-as-Code there's a good chance you're trying to wire up Fern, Readme, GitBook, or Mintlify to pull from a GitHub repo so your documentation deploys automatically on push. Each of those platforms has their own onboarding guide that walks through the OAuth connection, the branch to watch, and the directory where your content lives. If that's your question, their documentation will answer it faster than this article can. This article is about a different problem. ## The Problem with Product Code Connecting a docs repository to a documentation platform is the easy half. The harder half is connecting your *product* code repository (the one your engineers merge PRs into every day) to your documentation, so that when the product changes, the docs change with it. Your API endpoints, SDK methods, configuration options, and authentication flows are all described somewhere in your documentation. None of it stays synchronized automatically. When an engineer ships parameter changes, removes an endpoint, or changes the response data layout, that merge goes through review, gets tested, and deploys to production. The documentation page describing the old behavior stays exactly where it was. Six weeks later, your users are filing support tickets about something your docs say still works the old way. ## Two Ways to Wire Up Product Code There are two patterns for keeping documentation current with product code changes, and they work at different points in your development process. ### Pattern 1: Generate documentation from code artifacts The cleanest version of this is when your product already produces a machine-readable source of truth. REST APIs described by an OpenAPI spec, GraphQL schemas, and typed SDKs can all generate documentation directly. Tools like Fern, Readme, and Stoplight consume a spec that lives in your product repository and publish updated API reference automatically when it changes. The spec file lives in your product repo. A CI step validates it on pull request. On merge to main, the spec gets pushed to the documentation platform and the reference updates. What's published reflects what's deployed. This works best when your product has well-maintained machine-readable contracts. If your API has an OpenAPI spec that actually matches what's running in production, generated docs eliminate an entire category of drift. ### Pattern 2: Push documentation on merge When documentation is written by hand (which most product documentation still is), the connection is a CI/CD pipeline that runs on merge and pushes the relevant docs files to wherever they need to go. [Squarespace's engineering team](https://engineering.squarespace.com/blog/2025/making-documentation-simpler-and-practical-our-docs-as-code-journey) documented this approach in 2025, storing documentation alongside the product code and running a CI/CD pipeline that automatically updates Backstage after every merge. [Swiftlane](https://swiftlane.com/blog/syncing-docs-from-code-repositories-to-notion/) built a similar pipeline to Notion using `git-notion`. For Confluence, [`confluence-sync`](https://github.com/zonkyio/confluence-sync) handles the push in a pipeline step. The setup follows the same pattern across all of them. A CI job triggers on push to main, handles any format conversion the platform requires, and sends the file to the destination via API. Pre-built tools exist for the common platforms. If none fit, those three steps are still the whole thing. ## Where to Keep the Source of Truth In both patterns, the repository is the source of truth. The documentation platform receives content; it does not produce it. This matters for the same reason any distributed system needs a single authority. When two sources can both be edited, they will diverge. If engineers can update a Confluence page directly and separately from the code, they will. Eventually the page reflects something that no longer matches the product, and nobody knows which one is right. Keeping the source of truth in the repository solves this by making documentation a step in the same workflow as the code. A change to the product requires a change to the docs file in the same PR. The pipeline delivers it. The documentation platform is the display layer, not the storage layer. ## What This Does Not Solve Connecting your repository to your documentation platform keeps published docs current with what's written in the repository. It does not catch the case where something changed in the product and nobody updated the docs file in the first place. A pipeline that pushes `/docs/api-reference.md` to your documentation platform will keep that page current. It will not catch a renamed endpoint that nobody reflected in `api-reference.md`. [That's a drift detection problem](/blog/technical/documentation-drift-detection-problem), and it lives upstream of any sync pipeline. The connection handles getting accurate content to the right place. The harder part is knowing when a product change requires a documentation change in the first place, before it ships rather than after users notice. Treating that as [a continuous monitoring task](/blog/technical/how-teams-keep-docs-up-to-date-with-promptless) rather than a periodic review is what separates teams whose docs stay current from teams that are perpetually catching up. *** title: SDK Documentation Best Practices: What Actually Hurts Developer Adoption url: https://promptless.ai/blog/technical/sdk-documentation-best-practices description: SDK documentation fails developers in predictable ways. Here's how to cut Time to First Call and keep code examples accurate as your SDK evolves. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A team building on a popular payments SDK spent two days debugging a failed integration. The API docs said a particular field was optional. The actual implementation required it. The spec was six months out of date. The failure mode that matters most in SDK documentation is accurate information that became inaccurate and stayed that way. SDK documentation is uniquely vulnerable to this problem because the surface area is large and changes fast. Every deprecation and every parameter rename creates a gap between what the docs say and what the code does. [A report tracking API quality](https://nordicapis.com/what-is-api-drift-and-what-can-you-do-about-it/) found that 75% of production APIs do not conform to their own specifications. Most of that gap lives in documentation no one has reviewed since the original launch. ## The metric that reveals documentation quality Time to First Call (TTFC) measures the time between a developer accessing your documentation and making their first successful API call. It is the clearest proxy for how well your SDK documentation is doing its job. [Postman calls TTFC the most important API metric.](https://blog.postman.com/the-most-important-api-metric-is-time-to-first-call/) The reasoning is direct because a developer who never reaches a working call doesn't integrate. Everything downstream depends on clearing that first hurdle. TTFC is directly actionable. If it rises after a major SDK release, something in your onboarding experience regressed. If it falls after you updated the quickstart examples, you know the update mattered. Most of the variance in TTFC traces back to a handful of documentation problems that appear in a predictable order. ## The quickstart is where documentation wins or loses The quickstart is the highest-stakes section in any SDK documentation. It is the first code a developer runs. It has to work. A broken quickstart teaches developers that the docs cannot be trusted. After that, they verify every code sample before using it. They ask questions in Discord instead of reading the docs. They open support tickets for problems the documentation should answer. The docs exist, but the trust they were supposed to build is gone. The fix is simple. The quickstart needs to be tested on every release. Automated testing of code examples is standard practice in software engineering and less common in documentation, but the tooling exists. [Fern](https://buildwithfern.com/post/api-documentation-sdk-generation-tools) and [Speakeasy](https://www.speakeasy.com/blog/how-to-build-sdks) both support generating SDK documentation from an API definition, keeping code samples synchronized with the actual implementation by construction. For teams maintaining handwritten docs, a CI step that runs the quickstart against the live SDK catches regressions before they reach developers. ## Where documentation gaps compound Once a developer clears the quickstart, the next friction point is error handling. When an integration breaks in production, a developer first needs to know whether the SDK explains what went wrong and whether the documentation explains what to do about it. SDK docs that cover the happy path and skip errors leave developers with two expensive options when something breaks. They can read the source code or file a support ticket. [Stripe's error codes page](https://docs.stripe.com/error-codes) is a useful reference point. Every error maps to a description and resolution steps. The API returns a `doc_url` field pointing directly to the relevant documentation entry. A developer hitting an error in production has a direct path to actionable information. Most SDK documentation doesn't reach this bar. Start by documenting the five most common integration errors with the exact error string, what causes it, and how to resolve it. Your support tickets will identify which five those are. ## Versioning and deprecation: where most teams fall short SDK versioning is where documentation fails in slow motion. A parameter is deprecated and a note appears in the changelog. Developers who read the changelog update their code. Developers who don't keep using the deprecated parameter until it breaks. The problem is placement. Deprecation notices in a changelog reach developers who are actively looking for changes. Deprecation notices inline in the reference documentation reach developers who are in the middle of integrating right now. [Speakeasy's versioning guidance](https://www.speakeasy.com/docs/sdks/manage/versioning) emphasizes migration guides alongside semantic versioning as the foundation for managing SDK evolution. Migration guides matter because they remove the activation energy required to upgrade. A developer who knows exactly what to change will change it. A developer who has to figure it out will defer. The practical rule is to add a callout to every reference page that mentions a deprecated item. Not just the changelog. The notice needs to appear where a developer is reading when they are actively building. ## Code examples that stay accurate Code examples are the most valuable content in SDK documentation. They are also the most expensive to maintain. Every parameter rename, every method signature change creates an inconsistency that won't surface until a developer runs the example and gets an error. A few practices narrow this maintenance gap: **Generate from a canonical source.** For API reference documentation, generated examples from an API definition stay synchronized with the implementation by construction. Fern and Speakeasy both support this approach. Handwritten examples need a process to stay honest. **Separate stable content from volatile content.** Tutorial examples that walk through a complete workflow are more valuable but harder to keep current. Reference examples tied to specific parameters are easier to automate. Keeping them separate in your documentation structure lets you maintain them with different processes. **Test examples in CI.** A failing CI check on a code example is far cheaper than a developer spending two days debugging a stale one. If your documentation examples aren't tested, you're relying on someone noticing the problem after it has already shipped. ## The two dimensions of documentation coverage Coverage in SDK documentation has two dimensions that are easy to conflate. Surface area coverage measures whether every public API method has a documentation entry. This is what most teams measure because it is easy to audit. A script can report it. Accuracy coverage measures whether the existing pages are still correct. This is harder to measure and more consequential for developers. A documentation site that is complete but 25% stale actively misleads developers. The 75% API spec conformance failure captures the accuracy dimension at scale. Most of the teams contributing to that number have complete surface area coverage. Their problem is accuracy, not presence. Periodic audits that check surface area and stop there are solving the easier problem. Accuracy degrades continuously, with every product change that doesn't trigger a corresponding documentation update. [Keeping docs accurate as the product ships](/blog/technical/how-teams-keep-docs-up-to-date-with-promptless) requires a different kind of process than the one that produced the docs in the first place. ## SDK documentation in a world where agents read your docs Coding agents have shifted the stakes on SDK documentation quality because they now read your documentation. When a developer uses GitHub Copilot, Claude, or Cursor to integrate your SDK, the agent reads your documentation and generates code from it. A stale code example in your docs doesn't mislead one developer. It generates the same broken pattern across every AI-assisted integration attempt. [As covered in the guide to optimizing docs for agents](/blog/technical/agent-docs), agents treat retrieved documentation as ground truth. They have no mechanism for detecting that an example accurate in 2024 fails in 2026. They reproduce the error confidently, and the developer debugging the result has no obvious indication the problem originated in the docs. SDK documentation accuracy is no longer just a developer experience concern. For products that developers integrate programmatically, the accuracy of your documentation is part of your API contract. *** title: Connect Multiple GitHub Organizations to One Promptless Account url: https://promptless.ai/blog/product-updates/multi-org-github-connect description: Teams with multiple GitHub organizations can now connect them all to a single Promptless account, manage each integration independently, and see repos from every org in one project dropdown. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Promptless now supports connecting multiple GitHub organizations to a single account. If your engineering setup spans more than one GitHub org, you no longer need a separate Promptless account for each one. ## The problem Most Promptless customers have one GitHub organization. But some teams have two or more, spanning combinations like an internal product org and an open-source org, separate orgs for different product lines, or a company org alongside an acquired team's GitHub namespace. Until now, the only way to use Promptless across these was to create separate accounts and manage them separately. That meant duplicated trigger configuration, separate notification settings, and no unified view of documentation work across orgs. ## What changed After you connect your first GitHub organization, a "Connect another GitHub Org" option appears in Settings. Connect as many additional orgs as you need using the same OAuth flow you used for the first. Once connected, all repos from all your orgs appear in project dropdowns. Repos are prefixed with the org name (for example, `acme/docs`) so you can tell them apart when multiple orgs have similarly named repositories. Each org's GitHub integration is managed independently, so you can disconnect one org without affecting the others. ## Who benefits most This is most useful for teams that maintain documentation across multiple GitHub organizations for legitimate organizational reasons. The most common examples are a company that ships both internal tooling and an open-source SDK through separate GitHub orgs, a team that acquired another company and now maintains their GitHub org separately, or an engineering org that separated infrastructure and product into distinct GitHub namespaces. If you currently manage multiple Promptless accounts to work around the single-org limit, consolidating them will give you a unified view of all your projects and triggers. ## How to set it up Go to **Settings > Integrations > GitHub**. After your first org is connected, a **Connect another GitHub Org** button appears at the bottom of the GitHub section. Clicking it starts a standard GitHub OAuth flow. Once authorized, that org's repos are immediately available in project dropdowns. Each connected org appears as a separate entry in the integrations list. To remove one, click its disconnect button. Removing an org does not affect projects or triggers from your other orgs. If you're consolidating from multiple Promptless accounts and want to migrate existing project and trigger configuration, contact help@gopromptless.ai. *** title: Edit Doc Collection Settings Without Contacting Support url: https://promptless.ai/blog/product-updates/self-serve-doc-collection-editing description: Doc collection settings can now be edited directly in the Promptless dashboard. Update your docs framework, config path, published URL, Vale config, or Doc Detective settings without a support request. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Doc collection settings can now be edited directly from the Promptless dashboard. If you need to update your docs framework, config path, published URL, Vale config, or Doc Detective settings, you can do it yourself. No support request, no waiting. ## The problem Setting up a Promptless doc collection involves choosing which documentation framework you're using, where the framework config lives in your repo, what URL your published docs are served from, whether you're using Vale for linting, and whether Doc Detective is enabled. Most teams get this right during onboarding. But documentation setups change. A team might reorganize their repo and move the config file. They might migrate from one docs framework to another. They might enable Vale or Doc Detective after the initial integration. Their published URL might change after a domain migration. Until now, every one of those changes required a support request. You'd open a ticket, describe what needed to change, and wait for someone on our team to update it. Depending on timing, that could mean days before Promptless could generate accurate suggestions again. For teams running multiple doc collections, a single infrastructure change could mean several tickets, handled in sequence. The friction was out of proportion to the task. ## What changed There's now an edit button on each doc collection card in the dashboard. Clicking it opens the collection configuration form with your current settings pre-filled. You can update: **Docs framework.** If you've migrated from Docusaurus to Starlight, or from GitBook to Mintlify, update the framework setting so Promptless knows how to parse and write to your docs. **Config path.** Promptless uses your framework's config file to understand your doc structure. If you've reorganized your repo and the config file moved, update the path here. **Published URL.** Promptless uses your published URL when generating links and references in documentation. Update this if your domain changed or you moved to a subdomain. **Vale config.** If you added Vale linting after initial setup, or if your Vale config location changed, update it here so Promptless respects your style rules. **Doc Detective settings.** Doc Detective support can be enabled or adjusted on existing collections without starting over. Changes take effect immediately for new suggestions. ## Who benefits most Teams that set up Promptless early and have since changed their docs infrastructure benefit most. Common scenarios include framework migrations, repo reorganizations, adding Vale or Doc Detective after the initial integration, and domain changes. It also helps teams that caught a mistake in their initial setup. If the config path was wrong from the start, suggestions might have been targeting the wrong location. That's now a one-minute fix. For teams running multiple doc collections across several repositories, this is more significant. Any infrastructure change that previously required several sequential support requests can now be handled in a single session. ## How to use it Open the Promptless dashboard and go to your project settings. Find the doc collection you want to update and click the edit button on the collection card. Update the fields and save. The form uses the same fields as initial setup. If you have an open support request to update a collection setting, you can close it and make the change yourself. *** title: SDK Documentation Best Practices That Hold Up After Launch url: https://promptless.ai/blog/technical/sdk-documentation-best-practices-after-launch description: SDK documentation best practices mean maintaining three distinct surfaces that break differently: reference, code samples, and getting-started guides. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; You ship a Python SDK. The reference docs generate automatically from your OpenAPI spec. The quickstart is polished. Code samples cover the five most common use cases. Everything looks solid at launch. Six months later, a developer opens a support ticket. They followed your Python quickstart exactly. The authentication method it references was renamed in SDK v2.3. Your generated reference updated automatically; the quickstart did not. Your docs now describe a previous version of your own SDK. That sequence is the rule, not the exception. SDK documentation has three distinct surfaces that fail in different ways, at different speeds. Reference generation handles one of them at launch. The other two require active maintenance. ## The three surfaces **Reference documentation** is generated from your code or spec. Every method, class, and parameter is documented accurately at the moment of generation, updated when your build pipeline runs. It tells developers what exists. **Code samples** are the trust layer. Developers copy-paste from them before reading prose. A sample using a deprecated method doesn't fail visibly until someone runs it. Generated reference doesn't catch this, because the method still appears in the output right up until it's removed from the codebase. **Getting-started guides** are the highest-leverage surface and the first to drift. They combine reference, samples, and explanatory prose into a linear path. A single stale step in a five-step quickstart turns the entire guide into a dead end. Most SDK documentation strategies treat reference generation as the finish line. Reference generation is the floor. ## What makes generated reference insufficient Generated reference does one thing: documents what exists in your SDK at a given point in time, with types, signatures, and return values. It doesn't document why a design decision was made, when to use one method over another, or how different SDK components compose in real workflows. A developer reading generated reference for a payments SDK knows that `Charge.create()` exists and what parameters it accepts. They don't know whether to use it or `PaymentIntent.confirm()`, or what the migration path looks like if they picked the wrong one. Stripe's SDK documentation became the industry benchmark because they wrote the explanatory layer that gives reference meaning. The Stripe quickstart integrates in 7 lines of code. That's a writing achievement. Someone decided what those 7 lines should be, in what order, and why. Then they maintained that decision as the SDK evolved. Generated reference also misses language-specific idiom. A Python SDK that feels un-Pythonic creates friction that accurate documentation can't fix. The bar is idiomatic code with accurate docs — generated reference gets you halfway there. ## Code samples break silently When a developer can't get a code sample to work, they assume they're doing something wrong. They spend 20-40 minutes debugging before concluding the sample itself is the problem. This is the failure mode that [documentation drift](https://promptless.ai/blog/technical/documentation-drift-detection-problem) makes expensive. Code samples reference specific method names, parameter formats, and return types. Any change to those breaks the sample without any visible error in your docs. The sample looks identical before and after the change. Only the developer who runs it discovers the problem. For multi-language SDKs, this compounds fast. A breaking change in your core API cascades into reference updates and quickstart sample fixes across Python, JavaScript, Java, Go, Ruby, and .NET simultaneously. If your documentation process requires a writer to catch the change and propagate fixes to every affected sample, the gap between "code changed" and "sample fixed" can span weeks. Every developer who runs the stale sample in that window hits the same wall. The fix is connecting sample testing to your CI pipeline. Samples that can be run automatically catch breakage at the point of change. Samples that can't be tested are liabilities with no expiration date. ## Getting-started guides require intentional maintenance The getting-started guide is where developers decide whether to keep going. Stripe benchmarks Time to First API Call under 90 seconds, and TTFC is the strongest leading indicator of developer activation. A single stale step can push TTFC from 90 seconds to 20 minutes. Many developers stop at that wall and don't file a support ticket explaining why. The [Postman 2024 State of the API report](https://www.postman.com/state-of-api/2024) found that 68% of developers cite outdated documentation as their top frustration with APIs. Most of that frustration originates in quickstart and getting-started content, not reference pages. Getting-started guides drift for two specific reasons. The first is treatment as a launch artifact. The team writes a careful guide before launch, publishes it, and moves on. No one flags it for review when an authentication flow changes, because the guide isn't in the same place as the code that changed. The second is compound surface area. A five-step quickstart fails if any one step references changed behavior. A [changelog entry announcing a change](https://promptless.ai/blog/technical/api-changelog-best-practices) doesn't automatically surface the quickstart guide that references the changed behavior. The writer has to know to look. The practical fix is pairing guide reviews with the release cycle, not just with major versions. Any release touching authentication, configuration, or any step in a getting-started path should trigger a review of the affected guides before the change ships, not in the sprint after. ## Ownership at the language level SDK documentation needs owners at the language level, not just the product level. A Python developer who owns your Python SDK will catch deprecated patterns and sample breakage in Python. They won't catch the same issues in your Java SDK. Most documentation teams own all language documentation collectively, which means no single person is specifically watching any one language for drift. For small teams, the practical starting point is prioritizing by usage share. Identify which SDK languages drive the most developer activity and give those first-tier attention. The [documentation debt](https://promptless.ai/blog/technical/documentation-debt-accrues-where-your-team-cant-see-it) in your highest-traffic SDKs costs more than equivalent staleness in your lowest-traffic ones. What connects all three surfaces is the detection problem. Reference generation fires automatically. Code sample failures and guide staleness require something that watches what changed in code and surfaces the corresponding documentation for review. [Keeping multi-language SDK docs synchronized](https://promptless.ai/blog/technical/how-teams-keep-docs-up-to-date-with-promptless) at shipping speed requires closing that loop, not relying on a writer to catch changes by scanning PRs. *** title: API Changelog Best Practices: Write for the Developer, Not the Team url: https://promptless.ai/blog/technical/api-changelog-best-practices description: 68% of developers cite outdated API docs as their top frustration. Most changelogs cause it. Here's how to write one developers can actually use. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A developer reads your changelog. They see "Updated authentication flow." They open the authentication reference page. It still shows the old token format. They open a support ticket. That sequence plays out thousands of times across API ecosystems. The changelog announced the change, but the reference docs haven't caught up. The developer can't use either one to move forward. The [Postman 2024 State of the API report](https://www.postman.com/state-of-api/2024), which surveyed over 5,600 developers and API professionals, found that 68% of developers cite outdated documentation as their top frustration when working with APIs. 39% say inconsistent documentation is the biggest onboarding roadblock. Those numbers don't reflect teams that never wrote documentation. They reflect teams whose documentation described a previous version of the product. ## What most changelogs get wrong Most API changelogs are written from the team's perspective, not the developer's. The team shipping a feature knows what changed internally. The developer integrating against the API needs to know what they have to do differently. These are different questions with different answers, and most changelogs answer the first one. A changelog entry that says "Refactored token validation to use JWT" tells a developer that something changed internally. It doesn't tell them whether their integration breaks, what parameter they need to update, or where to find the migration guide. The team that wrote it knows all of that. The developer reading it knows none of it. A good changelog entry meets a simple test. A developer who reads only that entry should be able to determine whether their integration requires changes, and if so, exactly what those changes are. Most entries fail that test. ## Breaking changes need separate treatment Mixing breaking changes with additive ones is the most common structural failure in API changelogs. Breaking changes like removed endpoints, renamed parameters, or changed response schemas require the developer to modify their integration before it will continue to work. Additive changes like new optional fields, new endpoints, or expanded rate limits can be safely ignored. Burying both types in a single chronological list puts the burden on developers to read every entry to find the ones that actually require action. Stripe's API changelog separates these explicitly. Monthly releases are non-breaking by design and safe to adopt without code changes. Dated releases that include breaking changes are flagged separately, with each release shipping alongside updated SDK versions and reference documentation. A developer scanning for action items doesn't have to read the whole changelog to find them. Twilio's approach adds a deprecation policy commitment. They provide a minimum of one full year's notice before removing any API version. That commitment is written into their developer documentation, not just implied by practice. A developer reading Twilio's deprecation notices knows they have at least twelve months to plan a migration. The practical implementation is a consistent change classification at the top of every entry. "Non-breaking," "breaking," "deprecated" are three labels that let developers skip what doesn't apply to them. ## Deprecation notices that actually give developers a date "This parameter is deprecated and will be removed in a future release." That sentence tells a developer nothing actionable. "Future release" could mean next month or next year. Without a date, there's no migration planning. Without a migration guide link, there's nowhere to go even if the developer wants to act. A useful deprecation notice has three components: **What is being deprecated.** The specific parameter, endpoint, or behavior. Name the exact field or endpoint path, like `X-Auth-Token` or `POST /v1/authorize`. A phrase like "the old authentication method" leaves developers guessing. **A specific date or version when it stops working.** Use concrete language like "removed in API version 2026-09-01" or "sunset on October 1, 2026." A phrase like "a future release" gives developers no date to put on their sprint board. **Where the migration guide lives.** A direct link to updated reference documentation that describes the replacement behavior. Pointing to the changelog entry is not a migration guide. Deprecation notices without dates get treated as low-priority indefinitely. When the removal happens, the developer who deprioritized it files a support ticket. The deprecation notice was the opportunity to prevent that ticket, and vague language threw it away. ## The changelog entry and the reference doc update are two different tasks Publishing a changelog entry and updating the affected reference pages are distinct operations. Teams consistently do the first and treat it as complete. 44% of developers dig through source code to understand an API because the documentation doesn't match what the product actually does, according to the same Postman 2024 data. Those developers have documentation available. The documentation describes a previous state of the product. The changelog told them something changed, the reference page shows what it looked like before, and neither one tells them what to do with the product as it actually exists today. The failure mode is mechanical. An engineer ships a change and writes a changelog entry. The technical writer who owns the reference page wasn't in the PR review. The update goes on the backlog. The next developer to read the reference page encounters contradictory information, where the changelog says one thing and the reference page says another. One of them is wrong and the developer doesn't know which. The fix is making the reference doc update part of the release definition. If a PR changes a public API endpoint, the corresponding reference documentation updates in the same release cycle and is linked from the changelog entry. The changelog entry becomes a navigation point, not a destination. For teams using a [docs-as-code workflow](https://promptless.ai/blog/technical/help-center-to-docs-as-code), this means a PR touching a public endpoint surfaces the corresponding reference pages for review in the same cycle. The connection between "this code changed" and "these docs need updating" gets made at the point of change, before a developer hits the stale page. ## Link changelogs to what developers need next A well-structured changelog entry points outward. To act on "Added required `client_id` field to POST /tokens," a developer needs three more pieces of information. They need the updated reference page for POST /tokens, a migration guide if they're on a version that doesn't include this field, and the SDK version that ships with this change. Good changelog entries link directly to all three where applicable. Stripe's model ships each release with updated SDK versions for every supported language, links to the reference documentation for changed endpoints, and links to dedicated migration guides for breaking changes. The changelog is a starting point for navigation, not the full answer. For teams managing high-change APIs, this matters more than it might seem. A developer evaluating whether to upgrade doesn't want to read the full changelog. They want to find the delta between their current version and the target version, understand what breaks, and find the path forward. A changelog that links to updated reference material and migration guides gives them that path. A changelog that lists what changed internally doesn't. ## Write for the decision, not the record The purpose of an API changelog is to help developers answer whether a change requires them to modify their integration, and if so, where to start. A changelog designed around that question separates breaking from non-breaking changes, gives deprecation notices specific dates, links to updated reference documentation, and ships the docs with the release. A changelog designed as an internal record doesn't answer that question at all. Most of that 68% had documentation to read. The frustration comes from documentation that seemed accurate and turned out not to be. A changelog entry that announces a change alongside reference docs that still describe the old behavior is the most common source of that frustration. [Keeping reference docs synchronized with what ships](https://promptless.ai/blog/technical/how-teams-keep-docs-up-to-date-with-promptless) is the work that makes the changelog credible. [Documentation drift detection](https://promptless.ai/blog/technical/documentation-drift-detection-problem) catches the gap between a changelog entry and the reference pages that should reflect it, before the next developer hits the inconsistency. *** title: What Documentation Debt Actually Costs Engineering Teams url: https://promptless.ai/blog/technical/documentation-debt description: Documentation debt generates no automated alerts. Here's how to measure what you can't see and stop paying the hidden cost in onboarding and engineering time. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Your CI pipeline doesn't fail when a README goes out of date. Your error monitoring doesn't alert when an API guide starts describing a parameter that no longer exists. No ticket gets filed when a setup guide stops working because the product changed. The core problem with documentation debt is that it accumulates without any automated signal. Failing tests and dependency scanners serve as detectors for code debt. Documentation has neither of these signals. It builds up, page by page, until the cost surfaces somewhere far downstream. ## Why documentation debt is harder to see than code debt Code debt eventually fails loudly. A messy codebase still runs, but broken code stops working and forces action. A misleading doc gets acted on and produces damage before anyone notices. When documentation says one thing and your product does another, users trust the doc and then file a support ticket or give up. The cause is outdated content, the symptom is a churned customer or a slow-ramping hire, and the gap between them is wide enough that most teams never connect the two. The [State of Docs Report 2025](https://www.stateofdocs.com/2025/) found that 39% of teams track no documentation metrics at all. Most of the rest measure page views or time-on-page, which tells you nothing about accuracy. Most teams have no visibility into how much of their documentation has drifted from reality. Documentation debt compounds in a way code debt doesn't, because knowledge leaves with engineers. A poorly documented system might still have a senior engineer holding the full mental model. When that engineer leaves, the gap between "undocumented" and "unknown" closes permanently. What was once "we should write this down" becomes "nobody knows how this works anymore." Exit interviews recover a fraction of it. Most is gone. ## Where the cost shows up Documentation debt concentrates in three areas. **Onboarding.** Missing or outdated docs extend new hire ramp-up significantly. Research from developer experience teams puts typical onboarding at around four weeks with good documentation. Poor documentation stretches that to twelve weeks or more. New hires don't onboard slowly because they're unprepared. They spend their first weeks asking questions, hitting dead ends in stale content, and reverse-engineering systems that should have documented answers. **Support volume.** Outdated API references and incorrect setup guides generate support tickets at scale. Each ticket consumes the customer's time, the support engineer's time, and often the context-switch overhead of a developer pulled in for escalation. **Engineering interruptions.** Every time a developer answers a question that should be in the docs, they lose 15-20 minutes recovering their working context. Research consistently estimates this compounds to [15-25% of total engineering capacity](https://promptless.ai/blog/technical/documentation-drift-detection-problem) in teams with significant documentation debt. That's 15-25 engineers per 100-person team spending their time compensating for missing documentation instead of building. ## Measuring what you can't see Before you can reduce documentation debt, you need to know where it lives. A documentation audit maps every doc, its last-updated date, its owner, and a pass/fail on whether the content still reflects reality. That last column matters most. A doc updated six months ago might still be accurate. A doc updated last week might describe a flow that changed in yesterday's deploy. The goal is visibility, not a perfect inventory. Teams that run this audit consistently find that more of their documentation is inaccurate than they expected, and that the inaccuracy clusters around authentication flows, setup guides, API references, and anything that touches configuration. Once you have the map, you can prioritize. Start with the onboarding and getting-started guides users encounter first, then the docs that correspond to your highest-volume support tickets. Fix those first, then work outward. For a leading indicator, look at developer behavior. Count how many questions in your internal Slack or Discord should have been answered by docs. Tag support tickets by whether the root cause was outdated or missing documentation. These signals surface where debt is actively generating cost before it appears in churned accounts or onboarding failures. ## Building prevention into the process Audits address existing debt. Preventing new debt requires changing how documentation is treated during development. The most effective change is making documentation part of the definition of done. If a feature ships without updated docs, it's not done. This creates a direct link between code changes and documentation changes without requiring a separate process or a dedicated sprint. Ownership matters just as much. Documentation without a named owner gets updated by nobody. When a specific team owns specific docs, those docs get updated when the team's code changes, because they feel the pain directly when their docs are wrong. Some teams embed documentation review into the PR process itself. When a PR touches a public API endpoint, it triggers a review of the corresponding reference doc. When a config file changes, the setup guide gets flagged. Automated checks at the point of change are the same mechanic that makes code debt visible. The [teams that keep docs current](https://promptless.ai/blog/technical/how-teams-keep-docs-up-to-date-with-promptless) build systems that surface what needs updating before it becomes a problem. Understanding [why onboarding docs break after launch](https://promptless.ai/blog/technical/developer-onboarding-documentation-fails-after-launch) gives you the specific failure modes to build prevention around. ## The measurement gap is the starting point Documentation debt is manageable. What makes it expensive is how long it accumulates undetected. The State of Docs Report 2025 found that 90% of documentation leaders believe their docs influence purchasing decisions. Only 35% think their own docs are actually effective. That gap between belief and reality is documentation debt, made visible. You don't need sophisticated tooling to start. A spreadsheet tracking every doc's last-updated date and owner, combined with support ticket tagging for doc-related issues, gives you enough of a baseline to prioritize. Once you can see where the debt is concentrated, you can pay it down systematically. What generates no signal stays invisible. Documentation debt that goes unmeasured will keep compounding until the cost forces your hand. *** title: Documentation Debt Accrues Where Your Team Can't See It url: https://promptless.ai/blog/technical/documentation-debt-accrues-where-your-team-cant-see-it description: Documentation debt quietly costs mid-sized engineering teams $500K–$2M annually. The people bearing that cost aren't in your standups. Here's how to prioritize what to fix. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A developer opens your quickstart guide, follows step three, and hits an error. The API parameter was renamed four months ago. They search your public Slack, find nothing helpful, and close the tab. They don't file a support ticket or send an email, so your dashboards look clean. That is documentation debt collecting interest. Documentation debt is the accumulated gap between what your docs say and what your product actually does, plus the sections where docs don't exist at all. Teams accumulate it passively by shipping without updating reference pages and releasing new features before the quickstart catches up. The productivity cost inside your organization is real. Research consistently estimates that documentation problems consume 15 to 25% of total engineering capacity, as developers read source code instead of docs and ask Slack questions that accurate documentation would prevent. For a 100-person engineering team, that's the equivalent of 15 to 25 engineers whose time disappears into compensating for missing or inaccurate documentation. Annually, that translates to somewhere between $500,000 and $2 million in a mid-sized company. But those numbers capture only what happens inside your organization. The higher cost sits outside it. ## The externalized cost problem When code debt slows your engineers down, they show up to sprint planning and say so. The slowdown is legible. It gets tracked and scheduled. Documentation debt slows down the people trying to use your product. They don't show up in your standups. A developer who hits a broken quickstart doesn't file a support ticket and wait. Research consistently finds that [around 50% of developers abandon an API](https://userguiding.com/blog/user-onboarding-statistics) when documentation fails them, and the broken page stays up for the next developer who hits the same wall. The scale of this is not subtle. [Postman's 2024 State of the API report](https://www.postman.com/state-of-api/2024) found that 68% of developers cite outdated documentation as their top frustration when working with APIs. 78% of development teams report challenges with outdated or insufficient documentation. 64% of developers spend four or more hours per week searching for project information that should already be accessible. What makes documentation debt durable is the gap between how much pain it causes and how visible that pain is to the teams responsible for it. The people most affected are new developers and external integration partners, and they have no seat at the table when backlog priorities get set. AI coding agents have made this more acute. A developer can often work around a stale code sample by recognizing a deprecated method and adapting. An AI agent follows your documentation literally and produces broken code. The developer then debugs the AI's output, traces the error back to your docs, and hits the same wall faster than they would have without the AI. Stale documentation is less forgiving when agents amplify whatever they read, [a pattern that shows up in onboarding data](https://promptless.ai/blog/technical/developer-onboarding-documentation-fails-after-launch). ## Why auditing by age gives you the wrong priority list When teams do address documentation debt, the default method is age. Flag pages that haven't been updated in twelve months. Run a documentation sprint. Work through the oldest sections first. The problem is that age is a rough proxy for staleness. A two-year-old API reference page for a stable feature that hasn't changed is low priority. A six-month-old quickstart for an auth flow that's been updated twice since then is a live problem. Age doesn't tell you which pages are actually wrong or which pages actually matter. A more useful prioritization metric is blast radius, calculated as traffic volume multiplied by change frequency. **Traffic volume** tells you how many developers are reading a page. A page with 5,000 monthly views has 50 times the blast radius of one with 100 monthly views. **Change frequency** tells you how likely that page is to have drifted from what the product actually does. Pages covering authentication, onboarding flows, and core API endpoints change more often than reference pages for stable, rarely-touched features. High traffic combined with high change frequency identifies the documentation debt that is actively costing you users right now. Most teams already have analytics from their docs site and change history from their repository, but have never connected the two. Documentation sprints end up targeting the oldest pages and missing the ones with the most blast radius. ## Where documentation debt concentrates In practice, debt accumulates in predictable places. **Quickstart guides.** These get written carefully at launch, then update inconsistently as the product evolves. A minor authentication change that gets three lines in a changelog can break an onboarding guide in ways that aren't obvious until a developer hits step five and gets an error they can't interpret. **API reference pages for active endpoints.** Teams that ship frequently accumulate parameter-level debt quickly. An endpoint updated four times may have a reference page reflecting two of those updates. **Code samples.** Samples break silently. A deprecated function doesn't visibly error until someone runs it. Most teams have no systematic check that their code samples remain executable. **Multi-step tutorials.** These have the highest failure surface. Every step is a potential breakage point, and the full path requires multiple features to work simultaneously and accurately. These surfaces share a common characteristic. They're the ones developers rely on first, and the ones where failure sends developers away instead of toward your support queue. ## The organizational fix [Docs-as-code workflows](https://promptless.ai/blog/technical/help-center-to-docs-as-code), including version-controlled documentation and PR templates that prompt engineers to update the docs, create good habits and reduce future debt. They don't address the existing pile. A PR template reminding engineers to update the docs only helps if the engineer remembered which docs were affected. Quarterly documentation audits catch drift that already happened. Neither approach closes the loop between a code change and a documentation update in real time. The higher-leverage fix is connecting documentation review to code change signals upstream. When an engineer changes an authentication endpoint, the documentation pages covering that endpoint should surface for review automatically, flagged by the change that introduced the problem instead of discovered by a writer scanning PRs after the fact. This is the shift [from reactive audits to continuous detection](https://promptless.ai/blog/technical/documentation-drift-detection-problem) that teams with serious documentation coverage problems need. Teams that solve detection find their writing capacity goes further. Writers spend less time scanning PRs and triaging support tickets for documentation-related patterns, and more time on work that raises documentation quality. For teams working through an existing backlog, the practical starting point is the blast-radius calculation. Pull traffic data from your docs analytics and cross-reference it against pages covering surfaces that have changed frequently. The priority list that emerges will not be the oldest pages. It will be the most dangerous ones. *** title: How to Measure Developer Documentation ROI url: https://promptless.ai/blog/technical/how-to-measure-developer-documentation-roi description: Most documentation teams track outputs, not outcomes. Here's how to measure developer documentation ROI, and why that return decays if docs aren't maintained. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Most documentation teams can tell you how many pages they published this quarter. Fewer can tell you what those pages are worth. The instinct is to measure output like word count, pages published, and time to publish. These numbers are easy to track and easy to report. They are also the wrong ones. Output metrics measure effort, not value. A CFO deciding whether to hire a second technical writer does not need to know how many words were written last quarter. She needs to know what the documentation is doing for the business. Documentation ROI is real and measurable. The challenge is that it flows through channels most teams don't instrument. ## The Cost Side Is Already Visible Before getting to returns, the cost of poor documentation is concrete enough to build a case around. Stripe's research found that developers spend up to 17 hours per week dealing with technical debt, with poor documentation as a primary contributor. Across the software industry, that adds up to roughly $85 billion annually in lost productivity. A Stack Overflow survey found that 78% of developers name poor documentation as the biggest problem in their daily work. Sixty-two percent spend more than 30 minutes each day searching for answers that their documentation should have provided. The cost lands squarely on engineering time. Every hour a developer spends reading source code instead of docs, or asking Slack questions that docs should answer, is a productivity cost. It just rarely gets attributed to documentation quality. ## The Metrics That Capture Return Documentation's return flows through a few measurable channels. These are the ones worth tracking. **Time to First API Call.** Stripe benchmarks TTFC under 90 seconds for developer onboarding. Postman's research treats TTFC as the single most predictive metric for developer activation. Developers who complete a first successful call are significantly more likely to continue integrating. The documentation lever is direct. A clear, working quickstart drives TTFC down, while a stale or incomplete one drives it up. Going from a 10-minute TTFC to a 5-minute TTFC can produce a 40-60% jump in developer conversion rates. For any company with a developer funnel, that is a large return on a relatively small documentation investment. **Developer activation rate.** TTFC captures the first call. Activation is about getting from "this might work" to "I shipped something with this." The gap between those two milestones is where documentation quality shows through most in tutorials, reference accuracy, SDK guides, and error message explanations. **Support ticket volume.** A well-maintained knowledge base can reduce inbound support ticket volume by 40-60%. For teams with engineering time in their support rotation, every deflected ticket translates directly to hours recovered. A single common question deflected 200 times per month is a meaningful saving, and it compounds as the developer base grows. [Support agent deflection](https://promptless.ai/blog/technical/support-agent-deflection) scales in proportion to how current your documentation actually is. **Developer churn.** Research from multiple sources consistently puts the abandonment rate at around 50%. When documentation fails a developer, roughly half of them leave without filing a ticket or sending an email. They just stop. This is why tracking drop-off rates in the developer funnel, and auditing documentation state at the points of highest churn, often reveals a clearer picture than support data alone. ## The Decay Problem Here is the part most documentation ROI frameworks leave out: the return decays. A team that invests in excellent documentation at launch earns real returns. But as the product evolves, code changes against the docs. Parameters get renamed, endpoints get deprecated, authentication flows get restructured. The documentation that drove strong TTFC and high activation at launch begins producing the opposite. Onboarding gets blocked, and developers abandon the project. [Documentation drift](https://promptless.ai/blog/technical/documentation-drift-detection-problem) is the mechanism. Changes ship faster than documentation updates, and the gap accumulates. 75% of APIs don't conform to their own specifications, according to recent research on API drift. That figure reflects teams that invested in documentation and then watched the return erode as the product moved underneath it. The ROI math becomes unfavorable quickly. A quickstart that drove a 40-60% conversion improvement now causes developers to hit errors on step two. A reference doc that deflected 200 support tickets per month now generates them. The documentation investment is the same. The return has inverted. ## Why This Changes the Measurement Question Most ROI analysis treats documentation as a one-time investment with a fixed return. Write the docs, measure the improvement, report the number. That framing misses the decay dynamic. The more accurate question is whether the return is holding over time, and whether the gap between the product and the documentation is widening. [Developer onboarding documentation](https://promptless.ai/blog/technical/developer-onboarding-documentation-fails-after-launch) tends to have the steepest decay curve. It receives the most developer traffic, covers the most product-specific detail, and changes fastest as the product evolves. It is the highest-return documentation to get right, and the highest-cost documentation to let go stale. Teams that measure documentation ROI well watch the current return and the maintenance state at the same time, tracking TTFC, activation rate, and support volume alongside how far the docs have drifted from the actual product. Neither tells the full story alone. Both together distinguish documentation quality problems from documentation decay problems, which have different causes and different fixes. ## The Budget Argument, Reframed Documentation teams often frame the investment question as justifying headcount. A more useful frame asks what the decay rate of the documentation investment is, and what it takes to hold the return steady. Framed that way, the case for documentation investment is not about word count or publication frequency. It is about developer conversion rates and support ticket volume, both directly linked to how current the documentation actually is. The teams that make the strongest case are not the ones with the best launch-day docs. They are the ones who can show that their documentation's return is stable because they have a system to keep it current. That system, whether it is a rigorous review process, automated drift detection, or a combination, is where the maintenance budget conversation belongs. The cost of maintaining documentation accuracy is smaller than the cost of recovering from the developer churn and support load that accumulates when you don't. *** title: Comment @promptless on a PR to Request Documentation url: https://promptless.ai/blog/product-updates/request-docs-via-pr-comments description: Promptless can now be triggered by commenting @promptless on a pull request in any repo you've connected to Promptless, including merged or closed ones. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; You can now comment `@promptless` on a pull request to request documentation updates. It works in any repo you've connected to Promptless, whether the PR is open, draft, merged, or closed. This is an addition, not a replacement. Your existing trigger rules keep running. `@promptless` comments give you an on-demand option for PRs your rules don't cover, or PRs where you want to give Promptless specific instructions. ## The problem Promptless triggers are rules. You configure when to run, and it runs on every PR that matches. Rules can fire on PR open, on first approval, on merge, or when a glob matches. Rules don't cover every case. Three common gaps: - A PR merged months ago introduced behavior users keep asking about, but it predates your trigger setup. - A draft PR has a feature worth documenting early, before it hits your usual trigger. - You want to focus Promptless on one slice of a broad PR, not the whole thing. Previously, the workaround was to edit configuration, re-run builds, or skip the PR. ## How it works Leave a comment that includes `@promptless` on any pull request in a connected repo. Promptless picks up the comment, fetches the current state of the PR, and starts a doc run based on what's in the PR right now. A few things to know: - Any PR state works, whether the PR is open, draft, merged, or closed. Promptless fetches live details at the time of the comment, so PRs that shipped weeks or months ago are handled correctly. - The repo has to be connected to a Promptless project. Installing the Promptless GitHub App on an additional repo isn't enough on its own. If you comment `@promptless` on a PR in a repo that isn't configured, nothing happens. - Only comments that include `@promptless` trigger a run, so conversational PR comments won't accidentally start one. You can add instructions in the comment. If you write `@promptless please focus on the new retries config`, that context is passed to the doc run. Useful when the PR is broad but only one slice matters for your docs. ## Who benefits most **Teams filling in docs gaps retroactively.** If you set up Promptless recently, most of your historical PRs were never processed. Pick the significant ones and document them one at a time. **Teams that want explicit control over specific PRs.** Some PRs want the standard flow. Others are irregular: a big refactor with one user-visible slice, a config PR that changes defaults, a 40-file rewrite that needs three lines of docs. `@promptless` comments let you guide Promptless on the ones that need judgment. **Launch-week triage.** Point at the exact PRs that shipped a release and queue docs for each in a comment, instead of waiting for automatic triggers. ## How to use it No new configuration for repos you've already connected. If you're on GitHub, it's live. Leave a comment that includes `@promptless` on any pull request in a connected repo. GitHub won't autocomplete `@promptless` because it isn't a GitHub user. The keyword still works. Add instructions if you want to. Promptless picks it up, runs the doc flow, and comments back with a draft. GitHub Enterprise isn't supported yet. It's on the list. ## What's next We're building thread-aware follow-ons so you can iterate on a draft inside the PR. We're also working toward parity for GitHub Enterprise. *** title: Developer Documentation ROI: The Metrics That Actually Matter url: https://promptless.ai/blog/technical/developer-documentation-roi description: Most teams make the documentation ROI case with support tickets. That understates it by 10x. Here's how to measure what leadership actually cares about. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; When a technical writer asks leadership for more budget, the conversation usually ends up with someone asking "how many support tickets will this deflect?" The team runs the math on tickets per month, cost per ticket, and expected deflection rate, then lands on a number that sounds reasonable. Leadership approves a modest investment, the ticket count drops slightly, and no one revisits the projection. This is the wrong metric. Support ticket deflection is real, but it captures a small fraction of what documentation costs and returns. The bigger number is engineering time, and most of it goes unmeasured. ## The Cost Nobody Is Tracking Stack Overflow's developer survey found that developers spend more than 30 minutes per day searching for solutions to technical problems. Separate research puts the figure higher, with half of developers losing roughly 10 hours per week sourcing basic information they need to do their jobs. They are senior-engineer hours paid at full rate, spent compensating for an information system that should have made the answer obvious. Research on developer experience makes this concrete. The DXI framework from DX (formerly DX Data) measures documentation quality as its own dimension of developer experience. Their data finds that each 1-point improvement in documentation quality saves 13 minutes per developer per week. For a 100-person engineering team, a 5-point improvement translates to 5,000 hours per year, roughly $500,000 in recovered capacity at a $150k average salary. The inverse calculation is equally useful. A team where documentation problems consume 15 to 25% of engineering capacity, a figure drawn from engineering surveys and [documented in our post on documentation drift](/blog/technical/documentation-drift-detection-problem), is effectively paying 15 to 25 engineers to compensate. Those engineers read source code instead of docs and ask Slack questions that a functioning information system would already answer. That is the cost denominator that rarely appears in a documentation business case. Support ticket deflection matters for customer-facing documentation. For internal and developer-facing docs, the engineering time lever is at minimum 10x larger. ## Documentation as a Quality Input There is a second ROI lever that rarely appears in documentation business cases: defect prevention. An analysis of 101 production bugs presented at ICSE 2024 found that missing or outdated documentation caused nearly 50% of the defects, with erroneous code examples topping the list. The causal chain is direct. A developer reads the wrong thing, writes the wrong code, and ships a bug. Documentation accuracy is a measurable quality input, traceable through defect data. IBM research on software defect costs adds a multiplier. Fixing a bug discovered late in the development cycle costs roughly 10x what it costs to fix the same bug at the writing stage. If outdated documentation contributes to half of production bugs, and late-stage bugs cost 10x more, then documentation accuracy is worth a meaningful share of your QA and incident-response budget. Few documentation teams make this argument, because the causal chain is harder to trace than a deflected ticket. But the data supports it, and it is the kind of argument that lands with an engineering organization, not a support operations team. ## Three Metrics Teams Can Track Today ### 1. Developer experience surveys A single survey question asking developers to rate documentation quality on a scale of 1 to 10, tracked quarterly, is enough to build a trend line. Each point of improvement carries the 13-min/developer/week value above. For your specific team size and salary band, the dollar value is calculable and defensible. This is the most actionable metric for leadership conversations, because it is a number that moves and can be traced to investments. When you ship a documentation sprint, the DXI score should move. When it does not, that is also useful information. ### 2. Support ticket categorization Pull 50 to 100 escalated tickets from the past quarter and categorize each as a true knowledge gap where no answer existed anywhere, a stale answer where the doc existed but was wrong or outdated, a retrieval miss where the doc was correct but the user failed to find it, or a hard question requiring human judgment. Most teams expect the "hard question" bucket to dominate. In practice it is the smallest. True gaps and stale answers together account for 60 to 70% of escalations, and both are documentation problems with a cost per ticket. This turns a qualitative complaint about doc quality into a number finance can act on. The approach is covered in more detail in [our post on support agent deflection](/blog/technical/support-agent-deflection), where the same categorization exercise applies to AI-handled tickets. ### 3. Documentation coverage Coverage measures what percentage of your product surface, including features, API endpoints, error codes, and configuration options, has corresponding documentation that is verified as current. Gaps are a leading indicator of both support escalations and engineering friction. Most teams do not track this systematically. Treating it as a metric alongside code coverage or test coverage changes the conversation. Docs drift becomes a risk number, not an abstract quality concern, and coverage targets create accountability for keeping it current. ## Why Documentation ROI Erodes Most investments get sized against the return they generate. Documentation is difficult to sustain because accuracy degrades silently, erasing the return signal that would justify the next round of investment. Documentation delivers strong returns when it is accurate. Six months after a launch, product has shipped, APIs have changed, and a fraction of the docs are now wrong. That fraction grows with each release, accelerating as the engineering team ships faster with AI tooling. The returns from documentation are gradual and ongoing. A doc pays off slowly, across every developer who reads it and every support ticket it resolves. That stream only continues if the doc stays accurate. Without maintenance, the returns shrink and eventually go negative. A developer who finds the wrong answer follows it confidently, writes code against the wrong spec, and configures deprecated parameters. [As covered in the context engineering post](/blog/technical/agent-context-engineering), when an AI agent reads the same stale documentation, it surfaces the wrong answer at scale, to every user who triggers that retrieval path. This is why quarterly documentation audits consistently underperform as a maintenance strategy. By the time a quarterly audit runs, stale content has been accumulating for weeks and has already generated bugs and support escalations. The cost has already been paid. The documentation ROI argument is strong, but it is only sustained by accuracy maintenance alongside initial authorship. Writing new content and allowing it to decay produces diminishing returns that eventually go negative. Writing accurate content and maintaining a system that keeps it accurate as the product evolves produces returns that compound over time. ## Making the Case The engineering time calculation is what closes most leadership conversations. Take your team size. Multiply by average salary. Multiply by 15%, which is the low end of engineering capacity lost to documentation problems. That is your annual cost denominator. Then estimate what a 5-point DXI improvement is worth at your team size, using the 13-min/week/developer figure. The gap between those two numbers is the available ROI and the investment case. Start with two tracking practices. First, run a quarterly developer survey with a single documentation quality question. Second, pull 50 escalated tickets and categorize them by root cause. Add a coverage metric against your product surface once those baselines exist. Together they convert "our docs need to be better" into a business case with a dollar value and a trend line. *** title: Promptless Now Supports Starlight (Astro) as a Docs Platform url: https://promptless.ai/blog/product-updates/starlight-support description: Promptless now supports Starlight, the Astro-based docs framework, with automatic detection via astro.config files and first-class onboarding support. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Promptless now supports Starlight, the Astro-based documentation framework. If your docs live on Starlight, onboarding Promptless no longer requires manual configuration. Promptless detects your Astro config automatically and applies the right defaults. We've been running our own docs on Starlight for a while, so adding support was overdue. ## The problem Until now, if you used Starlight, you configured Promptless manually. You'd pick "other" during onboarding, point Promptless at your docs repo, and match the conventions by hand. That worked, but it was friction we put on you instead of handling ourselves. Starlight has been picking up as a docs choice. Our team uses it, and more customers have been arriving on it. Direct support was the right default. ## How it works Starlight is now an option in the onboarding hosting provider dropdown. Selecting it applies the right defaults for Astro docs sites. You usually won't need to select it. Promptless looks for `astro.config.mjs`, `astro.config.ts`, or `astro.config.js` in your docs repo and auto-detects Starlight. Promptless also reads the `site` field from your Astro config to determine your docs URL. Earlier onboarding would sometimes pick up the "Edit this page" link and point at your GitHub repo instead of your docs site. That's fixed. Fallback patterns like `site: process.env.SITE_URL || 'https://yourdocs.com'` now resolve correctly. ## Who benefits most **Teams on Astro and Starlight onboarding for the first time.** Point Promptless at your docs repo, confirm Starlight in the detected field, and continue. **Teams migrating to Starlight from another platform.** Detection handles the config change. The base URL updates automatically. **Teams already running Promptless against a Starlight site with manual config.** Re-run onboarding to pick up the Starlight-specific defaults, or ask us to migrate the config for you. ## How to use it New onboarding: pick Starlight from the hosting provider dropdown, or let detection handle it. No additional configuration. Already onboarded on a Starlight site: your existing setup keeps working. Re-run onboarding if you want the improved defaults. ## What's next We'll keep adding platform support. If you're on a framework that isn't supported yet, tell us. *** title: We Scored 100 on Agent-Friendly Docs. Here's Why That's Not Enough. url: https://promptless.ai/blog/technical/agent-friendly-docs-necessary-not-sufficient description: Making your docs accessible to AI agents is necessary but not sufficient. Agents are more credulous than humans, which means accuracy and clarity matter more than ever. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Yesterday we became the first documentation site to reach a perfect score of 100 on the Agent-Friendly Docs benchmark hosted by Fern. I'm pleased with this not because we had a perfect score when first tested. No, I'm happy because I told Promptless in slack how to run the score via `npx afdocs@latest --score` and it was then able to do pretty much all the work on its own. What did Promptless figure out? - static Markdown exports for every page - a comprehensive `llms.txt` index - content-negotiation middleware so agents can request `text/markdown` directly - hidden directives on every page pointing to our documentation map. When Claude Code, Cursor, or any other coding assistant fetches our docs, it gets clean, structured content instead of HTML soup filled with navigation chrome. A perfect accessibility score is table stakes. Necessary, but nowhere near sufficient. If you're optimizing for agent accessibility without thinking about what comes next, you might be making things worse. ## The accessibility problem is mostly solved The basic mechanics of making docs agent-readable are well understood now. Serve Markdown or clean HTML, maintain an `llms.txt` file that is a site map for AI, strip out JavaScript-heavy components that don't survive fetch, and use semantic headings. Those are the checkboxes. Most documentation platforms handle this automatically. Mintlify, GitBook, ReadMe, and others have shipped agent-friendly features as defaults. If your docs are on a modern platform, you probably score reasonably well on accessibility metrics without doing anything special. The harder problem is what happens after the agent successfully reads your docs. ## Agents are more credulous than humans AI agents believe what they read in a way that humans don't. Credulous to an unreal degree. When a human developer reads documentation, they bring healthy skepticism: testing code examples before trusting them, noticing when something feels outdated, cross-referencing against the actual API behavior. If the docs say one thing and the code does another, they believe the code. Agents take your docs at face value. If your authentication guide says to use an API key in a header called `X-Auth-Token` but you deprecated that six months ago in favor of Bearer tokens, the agent will confidently generate code using the deprecated pattern, notice nothing wrong, and do exactly what your docs told it to do. This is a feature of how language models work. They're trained to be helpful, to complete tasks based on the information they're given. Where humans develop an adversarial instinct from years of being burned by bad documentation, agents arrive at your docs in good faith. They trust you. Which means they're easier to mislead. ## The blast radius of bad docs just increased Every inaccuracy in your documentation used to affect one developer at a time. Someone would follow your quickstart, hit an error, maybe file a support ticket or give up and choose a competitor. Painful, but contained. Now multiply that by every AI coding assistant your potential users have installed. A single outdated code example now gets served to Claude, to Copilot, to Cursor, to Windsurf, to hundreds of coding agents that might recommend your product to their users. Each one ingests your docs, believes them completely, and generates code that fails. The debugging experience is worse too. When a human reads bad docs, they at least know which page they read and can report the problem. When agent-generated code fails, the developer often has no idea where the agent got its information. They know only that your product behaves differently from what the AI promised. You've made it easier for agents to access your docs. You've also made it easier for your docs' inaccuracies to propagate at scale. ## Accuracy is the new competitive advantage If your docs are going to be read primarily by AI agents, accuracy and clarity matter more than they ever did for human readers. This isn't just about catching typos. It's about: **Stating things exactly.** Don't say "you might need to configure authentication" when you mean "you must configure authentication before making any API calls." Agents don't handle ambiguity well. They'll pick whichever interpretation seems more plausible, which may not be correct. **Keeping examples current.** Code examples are the highest-signal content for agents. When an LLM needs to generate code using your API, it will lean heavily on your examples. If those examples use deprecated methods, deprecated syntax, or deprecated patterns, the agent will reproduce them. **Versioning carefully.** If your product has multiple versions with different behaviors, make sure the docs indicate which version they apply to. An agent that retrieves your v2 docs and generates v3 code will create a confusing mess for the developer who has to debug it. **Documenting failure modes.** Agents struggle with unwritten knowledge. The constraints and edge cases that experienced users know intuitively, like being unable to do X when Y is already configured, need to be explicit. If they're not in the docs, the agent won't know about them. **Writing directly.** Dense, jargon-heavy prose that a motivated human can puzzle through will trip up an agent. Use short, declarative sentences with one concept per paragraph and direct statements in place of clever phrasings. ## Why we built Promptless When your docs are primarily consumed by AI agents, you need a system that catches every inaccuracy before it propagates. You need docs that update automatically when your product changes. You need verification that what you've written actually matches what your API does. Scoring 100 on agent accessibility was a milestone. Making sure every page deserves that accessibility score is the real work. We started Promptless because documentation accuracy is a much harder and much more important problem that deserves good tools. *** title: Using Slack as a "Knowledge Base"? Here's What You're Missing out on url: https://promptless.ai/blog/technical/using-slack-as-a-knowledge-base description: Slack feels like a knowledge store because answers happen there. Its design actively destroys institutional knowledge. Here's why docs-as-code fixes it. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Most teams don't choose Slack as their knowledge base. It just ends up that way. Someone asks a question, someone else answers it, and over time the real answers to "how does this work" live in threads and DMs rather than in any official documentation. It makes sense: Slack is where your team already is, and getting an answer there is fast. If you're reading this, you've probably already felt the cost. You've searched for a decision you know was made somewhere, scrolled through threads that almost had the answer, or watched a new hire re-ask the same onboarding question for the third time this quarter. You've decided that Slack shouldn't be where institutional knowledge lives. This article is about why that instinct is right and what actually works instead. ## The half-life of a Slack message Slack search relies on exact keywords and ignores context. If you're looking for "the decision about the auth migration," you need to already know which words someone used when they made it. Slack won't surface a thread where someone said "let's go with OAuth" in response to "what should we do about login" unless you search for exactly the right terms. It gets worse over time. Nobody goes back and edits Slack messages. When someone corrects a previous answer or a process changes, the new information lands in a new message. But search doesn't know that. It will happily surface the original, outdated answer because it's a better keyword match for your query. You're effectively running last-write-wins, but the search engine doesn't respect the write order. The deeper loss is the "why." When a technical decision gets made in a Slack thread, the reasoning lives there and only there: the tradeoffs considered, the approach tried and rejected, the edge case knowingly deferred. What survives downstream is an artifact — a line of code, a config choice, a pattern in the codebase. The reasoning that produced it has scrolled away. This is what doclandscape.com calls "[ephemeral knowledge](https://doclandscape.com/the-living-knowledge-system/the-knowledge-tiers/ephemeral-knowledge/)": information generated in real-time, in the flow of work, in a tool not designed to preserve it. The volume of knowledge flowing through Slack channels every day is enormous, and none of it is being processed into anything durable. You need something that can watch this stream as it happens and pull the institutional knowledge out before it disappears. ## Why stale docs make Slack worse Slack fills the knowledge gap partly because formal documentation fails people first. Documentation decays. Products ship, processes change. When someone follows a Confluence page and the steps are wrong, something shifts in how they relate to written docs. They file it as "docs are unreliable" and route around the whole system. The next time they need information, they ask a colleague on Slack. They're optimizing for reliability, choosing a source they trust over one they can't. This is rational. It's also a compounding problem. The more questions get answered through people, the more certain individuals become informal knowledge hubs. Knowledge concentrates in 2–3 people per team. When those people leave, that knowledge leaves with them. The docs don't get better during this cycle. They get worse, because fewer people use them and even fewer update them. The trust collapse is hard to reverse once it sets in. ## What docs-as-code actually fixes Moving internal documentation into a docs-as-code system (markdown files in a Git repository) changes the structural problem, not just the tooling. When docs live in the same repo as the code they describe, they go through the same review process. A pull request that changes an API also updates the documentation for that API. Ownership is unambiguous: whoever merged the code owns the context around it. There's no question about which version of the docs corresponds to which version of the product. Decay happens more slowly because the feedback loop is shorter. Engineers don't have to context-switch to a separate tool to update documentation. The change and the explanation travel together. For internal documentation specifically (team processes, architectural decisions, onboarding guides), the case is more direct than it is for external docs. Internal docs rarely have a non-technical audience that needs a WYSIWYG editor. They're read by developers and written by developers. Docs-as-code is the natural format. The [help center vs. docs-as-code](/blog/technical/help-center-to-docs-as-code) question is more nuanced for external-facing content, but for internal knowledge the answer is usually clear. ## The automation that docs-as-code unlocks The more significant benefit is what docs-as-code makes possible downstream. Structured, version-controlled documentation is the prerequisite for programmatic updates. When docs live in a wiki or Confluence, there's no clean interface for automated changes. In a Git repository, there is. This matters because keeping internal docs current is where most teams actually fail. Writing docs once is the easy part. Keeping them current as the codebase moves and decisions accumulate in Slack threads is where the process breaks down. Promptless addresses both sides of this. It watches code changes and flags when a PR affects something currently documented. It also listens to Slack. When a decision gets made in a thread or institutional knowledge surfaces in a channel, Promptless can turn that signal into a documentation update. The context that used to disappear with the thread now has a place to land: the repo. One team using Promptless, Basis, takes this further. They pipe customer call transcripts into a Git repository. Promptless monitors the repo and maintains internal documentation around product usage patterns, recurring questions, and what's actually happening in the field. The internal knowledge base builds itself from conversation. Because it lives in their own repo, they can build agents on top of it and do useful things with the data. That leverage only exists because the documentation is in a format they control, not locked in a third-party system. ## Where to start The Slack habit is hard to break because it works in the moment. Someone gets an answer in 20 minutes. The long-term cost is invisible at the time of the interaction: institutional knowledge that evaporates, the same question asked repeatedly across a year. Moving internal docs to a Git-based format doesn't require a large migration. Start with the highest-traffic knowledge: onboarding, environment setup, architectural decision records. Put those in a `docs/` folder in the relevant repo. Get engineers reviewing doc changes in PRs alongside code changes. That foundation is what makes the rest possible. Detection becomes automatable. Updates can be drafted rather than written from scratch. The knowledge that currently lives and dies in Slack threads has somewhere permanent to go. *** title: Karpathy's LLM Wiki Went Viral. Here's What It Means for Your Personal Knowledge Base. url: https://promptless.ai/blog/technical/karpathys-llm-wiki-personal-knowledge-base description: Karpathy's LLM wiki pattern solves the oldest problem in personal knowledge management. Here's why it matters for your personal wiki, idea file, or knowledge base. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; ## The post that broke the timeline On April 3, 2026, [Andrej Karpathy posted something on X](https://x.com/karpathy/status/2039805659525644595) that traveled far beyond the AI crowd. He described a shift in how he uses LLMs, moving from generating code to generating knowledge structure. He showed a system where raw research materials go into a folder, an LLM compiles them into a structured wiki, and a single research topic had grown to roughly 100 articles and 400,000 words without Karpathy writing a single word of it directly. Two days later, he followed up with [a GitHub Gist he called an "idea file."](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) It describes a pattern for building personal knowledge bases using LLMs. Within days, the post had spawned a wave of community implementations and serious debate about whether this approach makes RAG pipelines obsolete for personal use. One line from the gist explains why it went viral. "Humans abandon wikis because the maintenance burden grows faster than the value." Everyone who has ever built a wiki, personal or professional, recognizes that sentence. The creation feels productive, the maintenance feels like busywork, and eventually the busywork wins and the wiki rots. Karpathy proposed a fix. Let the LLM do the busywork. ## How the LLM wiki works The architecture is simple on purpose. The foundation of this system is a two-tier directory structure with a `raw/` directory and a compiled wiki. Raw sources like articles, papers, images, and data files are immutable. The LLM reads from them but never modifies them. This is your source of truth. The LLM compiles those raw sources into a wiki directory of interlinked markdown files. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. Instead of building a traditional RAG system, Karpathy's approach treats the LLM as a compiler that reads raw source documents and produces a structured, interlinked wiki. The wiki itself becomes the knowledge base, with no embeddings or vector search needed at the scale of a personal knowledge base. To keep things clean, Karpathy employs LLM "health checks," automated passes that look for inconsistent data, fill in missing information using web search, and identify potential connections for new articles. The human curates sources, directs the analysis, asks good questions, and thinks about what it all means. The LLM's job is everything else. Karpathy uses [Obsidian](https://obsidian.md/) as the front end. In practice, he has the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on their conversation, and he browses the results in real time, following links, checking the graph view, reading the updated pages. ## The idea file: sharing concepts instead of code [The gist itself](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) is worth paying attention to. Karpathy didn't share a repo or an app. He called it an "idea file" and published the concept intentionally abstract, intentionally vague, so that anyone can hand it to their own agent and get a version built to their own situation. As [Glen Rhodes put it](https://glenrhodes.com/andrej-karpathys-idea-file-concept-shifts-the-shareable-unit-from-code-to-concept-in-the-llm-agent-era/): "That is a genuinely different thing than what we've been doing for the last twenty years." The gist is a description of a concept, specific enough to be actionable, loose enough that an agent can fill in the implementation details based on your particular tools, preferences, and context. You hand it to your agent and say "build me this." The community responded fast. Within two days, there were multiple open-source implementations, including [a Claude Code plugin implementing Karpathy's LLM Wiki pattern](https://github.com/rvk7895/llm-knowledge-bases) with commands for ingesting, querying, and linting. Developer Farza built ["Farzapedia,"](https://x.com/FarzaTV/status/2040563939797504467) a personal Wikipedia compiled from 2,500 entries across his diary, Apple Notes, and iMessages. The result is 400 articles covering research areas, people, projects, and ideas, all interlinked, all maintained by AI. ## The maintenance problem is personal The problem Karpathy described is one everyone faces, not just researchers. Anyone who has tried to maintain a personal wiki, a Notion database, an [Obsidian](https://obsidian.md/) vault, or even a well-organized notes app has hit the same wall. You build it, stop maintaining it, and it rots. The failure mode is structural. The tedious part of maintaining a knowledge base is the bookkeeping that involves updating cross-references, keeping summaries current, noting when new information contradicts old claims, and maintaining consistency across dozens of pages. None of it requires deep thinking, but all of it takes time, so it doesn't get done. Karpathy's fix works because it offloads exactly that layer. The LLM handles the bookkeeping. The human handles the judgment. ## Your personal knowledge base doesn't have to rot The pattern isn't only for academic researchers with 400,000-word wikis. It applies to anyone trying to keep their knowledge organized, at work or in the rest of their life. Your work notes. Research for a side project. An idea file you've been meaning to maintain for two years. A personal knowledge base covering everything you've learned about a domain. These all fail for the same reason Karpathy diagnosed. The maintenance burden outgrows the habit. What makes Karpathy's system different is that the wiki compounds over time instead of decaying. New sources go in, the LLM updates the compiled output, cross-references stay current. The knowledge base gets better as you use it, not worse. [Promptless](https://promptless.ai/) is built around this same principle. You feed it your notes, documents, links, and research, and it maintains the compiled knowledge base for you. It handles the cross-references, the consistency checks, the updates you'd otherwise skip. You stay in the judgment seat. The result is a personal wiki that doesn't rot. Your idea file stays current. Your research compounds. Whether you're organizing work knowledge or personal projects, the bookkeeping happens automatically. Karpathy proved the pattern works. The question is whether you want to keep doing the maintenance manually. *** title: When YOU are the Docs Team - Lessons from Working with Some of the Best Writers and Managers in the Industry url: https://promptless.ai/blog/technical/solo-writer-team-lead description: Whether you're the only technical writer at your company or leading the docs team, some of the structural challenges are similar: not enough resources to build infrastructure, a manager who doesn't know your craft, and an AI moment that's changing what the job entails. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Most tech writers work as part of a team. Most operational and career advice in tech writing is likely written by and for people on established docs teams. But being the only technical writer at a company or being the leader of a docs team comes with its own distinct challenges. We've had the pleasure of working with some of the best solo writers and docs team leads in the industry. Here's what we learned. ## 1. You've probably inherited a mess Joining a company as the first technical writing hire almost always means inheriting docs cobbled together by engineers, PMs, and support staff. They're partially accurate, inconsistently voiced, with information structure that once made sense when the product had two features. The instinct is to fix the content first, one section or product area at a time. But with AI, you should actually establish the style guide first. You shouldn't rely solely on AI to rewrite your content, because the AI's product knowledge is only as good as your current docs. So accurate content will have to come from you and your SMEs. However, AI is quite good at fixing voice, style, and formatting at scale with minimal supervision. You can even add the style guide to `CONTRIBUTING.md` for your docs repo. This way it gives other docs contributors' AI agents a consistent voice, minimizing new style debt being introduced. A good example of a style guide can be found at [Kubernetes](https://kubernetes.io/docs/contribute/style/style-guide/). It's not just about formatting. Standizing reference terms like `A PodList object is a list of pods.` over `A Pod List object is a list of pods.` help both humans and AI agents. You can read more about optimizing for agent-facing style guides [here](https://promptless.ai/blog/technical/agent-docs) ## 2. Build your operating system When you are the docs function, you may need to process more information than anyone else at the company. Signals from pull requests, Slack, forums, Discord, internal meetings, design reviews, and support tickets can all land on your desk. This requires building systems and automation — otherwise you'll either be perpetually behind and reactive, or burn out within 18 months. ### 2.1 Build the information pipeline Setting up information systems feels like a distraction from writing. It's not. An hour building automation can be worth weeks of reactive catch-up on missed changes. A plausible setup: - Slack - Set up a `#docs-request` Slack channel, announce it to the company - Set up Slack keyword alerts for `docs` and `documentation` - Github - Build a Github action to run after each engineering PR is opened/merged and monitor for docs changes. - Support platform - Monitor support tickets that mention docs - Keep track of searches on the docs site's AI chatbot - Task management - Set up a DOCS project in Jira/Linear and have the team submit requests there - Use Github projects to organize your work
![Slack keyword alerts setup](/assets/slack_keywords.png)
Setting up Slack keyword alerts for 'docs' and 'documentation' under Preferences → Notifications → Channel keywords
For team leads, the pipeline also needs routing logic: when a PR touches the auth flow, which writer gets notified? When support volume spikes in a product area, who owns it? The information system is also about getting the right signal to the right person at the right time. You can read more on ambient capture [here](/blog/technical/ambient-capture), which is how we think about this problem. If you don't want to set up and maintain this system yourself, [Promptless](https://promptless.ai/demo) automates it completely, including the routing. ### 2.2 Scale yourself You can't be in every engineering standup everywhere all at once. Send a bot to record and transcribe standups, design reviews, and certain customer meetings. Set up a pipeline to send meeting transcripts to a GitHub repo, and run an LLM filter over them to find doc-impacting content. Engineering standups can contain valuable information about design decisions or API details. Having that repo of transcripts also means you can point Claude Code or Codex at it and ask questions while you're writing. ### 2.3 Build product intuition Dogfood, dogfood, dogfood. Technical writers are among the best people at a company to develop customer empathy, because they don't just need to understand something — they need to teach someone else how to do it. Pair with engineers and have them walk you through the product. Set up a dev environment. Write code against the API (or ask AI to). Go through the UI flows. The gaps you hit are the gaps your users will hit. For team leads, build dogfooding into writer onboarding before anyone writes a single doc. Writing from specs produces docs that are technically accurate, but dogfooding is what lets you write that callout that makes a user think: "wow, it's reading my mind". ## 3. Make your impact visible Documentation is invisible when it's working. Users don't thank you for clear instructions, they just complete the task. This makes impact systematically hard to demonstrate, which matters for headcount, compensation, and the organizational agency to do proactive work. You'll have to build that visibility deliberately (and we're here to help!). ### 3.1 Reporting to someone who doesn't know your craft There's no Chief Docs Officer, unfortunately. So both solo writers and docs team leads typically report into either Product or Engineering. Managers who came up through those two functions may have no intuition for what makes docs genuinely great versus barely usable. They can't appreciate the human judgement that went into the decision to add this particular how-to guide, or to patch a gap in knowledge that the doc assumes but the user doesn't have. If you have a manager who values docs, congrats! For managers who can't tell good from bad, they'll struggle to defend resources, calibrate workload, or recognize exceptional work. The solution isn't to teach them the intuition, it's to demonstrate positive outcomes. ### 3.2 Outcome metrics worth watching These metrics are often tracked by support or product teams already, so you can ask for them rather than building from scratch. ##### Time to first value - **Definition**: Onboarding means different things at different companies. It could be creating a first project, calling an API, spinning up a cluster, or adding an SDK to a codebase. But whatever it is, it's almost always the first time users need docs. If you're refactoring onboarding content or adding tutorials around first-use flows, this is the metric to watch before and after. - **How to track**: If calling an API is your clearest signal of first value, you can track the time between `user.created_at` and the user's first successful API call, with `api_key.created_at` as a useful intermediate step to diagnose where people get stuck. ##### Direct feedback from docs - **Definition**: For each page, you'll have the "This doc is helpful/not helpful" button, you can get very granular page-level signal before and after a major refactor. - **How to track**: Most docs platform offer this as a built-in feature. ##### Support volume by product area - **Definition**: If you're doing a content refactor of a specific area, monitor support ticket volume for that area as a before/after signal. Product and support teams almost always track this already. Most support tools let you filter by topic or tag. You can also download support data and point an AI agent at it to do the analysis. - **How to track**: If it's not tracked already, you should be able to export a CSV of support tickets from your support platform, then use the top-level sections of your docs, such as Getting Started, Integrations, or API Reference as your topic taxonomy. From there, you can ask Claude Code or Codex to write a script that classifies each ticket into one of those topics based on the topic/summary. ##### Search zero-results rate - **Definition**: If your docs platform has search analytics or an AI chatbot, queries that return no results are a direct inventory of content gaps. A spike in zero-results searches after a product launch indicates users are turning to docs to learn something that isn't documented yet. - **How to track**: Most AI chatbot provider should have this out-of-the-box. Some of them will even rate the "uncertainty" of responses, and will cluster common questions with bad/uncertain results. ##### Feature adoption rate - **Definition**: Low adoption on a new release can often be a docs problem. If adoption improves after adding docs, that's attributable impact, and it's hard to explain away as coincidental. - **How to track**: a new product may show up as a new SKU in your billing system, a new entitlement in your product database, or usage of a new API endpoint. Measure adoption with a day-0 to day-X curve, where X might be 30 or 60 days, showing the percentage of customers using the new product out of the total eligible customer base; to make that number meaningful, compare it against the same day-0 to day-X adoption curves for other product launches as your baseline. ##### Agent success rate - **Definition**: If your company runs an in-house or third-party agent that depends on the docs, after the development stablizes (so that you don't get confounding signals), track its success rate. An agent is only as good as the context it's given, which means its performance is a direct proxy for your docs quality and value. - **How to track**: For example, if your company has a support bot that answers product questions by retrieving from your docs, you can track the percentage of conversations that are resolved without escalating to a human. In practice, that usually means measuring things like deflection rate, repeat-question rate within a set window. Some of the support agent providers report these numbers automatically. ### 3.3 What leadership understands and cares about Two things resonate with leadership, regardless of what background they had: 1. Higher productivity and efficiency 2. Tighter feedback loops This is where AI tooling adds the most leverage — agents can monitor PRs for doc-breaking changes or flag support ticket clusters pointing to a specific page, then create a draft automatically for you to review. You can reduce the turnaround time to under an hour. ## 4. Building allies ### 4.1 Make friends with the Support team Your support team sees what users are struggling with before and after documentation changes. A doc that reduces handle time on a common question has a real dollar value. You'll also hear anecdotes (e.g. a customer who had to be refunded a large credit because of a docs error), and those stories are exactly what you need when making the case for resources. Ask support to label tickets with `docs` when applicable. It takes each person a few seconds, but it gives you a clean data feed without additional manual work. A bi-weekly check-in with someone on support produces both better prioritization and impact data you can use elsewhere. ### 4.2 Help engineers help you Whether or not engineers formally contribute to docs, make it easy for them to bring their domain expertise. Create a docs PR template that contains a short review guide with explicit instructions. For instance: "when there's a code snippet, please test it. Also please verify command accuracy, parameter correctness, and expected output." Engineers know how to review code; they don't inherently know how to review docs. Without guidance, you'll get rubber stamps that miss the things only they would catch. ### 4.3 Find other writers outside your company The [Write the Docs Slack](https://www.writethedocs.org/slack/) has a dedicated #lone-writer channel and a separate #managing-writers channel for team leads. If you haven't joined, you should! ## 5. Adapting to AI ### 5.1 Accuracy over polish Information architecture still matters for human readers. But AI agents are increasingly part of the audience, and they process content differently. An agent won't trip over mIxEd hEAdIng caSeS or a rndom typpo, but stale information will cause it to confidently hallucinate an answer or get stuck at execution time. As a solo writer or writing manager inevitably juggling competing priorities, you can deprioritize polish when needed, but accuracy and freshness becomes more important than ever. ### 5.2 Shadow docs A human reader navigating your docs faces cognitive overload if there's too much content. An AI agent doesn't have the same problem. This opens up a category worth considering: content too niche or edge-case for your main doc tree, but that agents would use effectively. You can keep it as its own section of “For AI Agents” to avoid cluttering the human experience. Content can include real support cases with customer information redacted, known workarounds for uncommon configurations, etc. All of it leads to fewer support tickets and higher agent task success rate. ### 5.3 Rethink form factors Think about customer education and agent education from first principles, because many of the constraints that shaped old conventions no longer apply. Most teams avoided screenshots because they were painful to maintain, not because they aren't useful — but now screenshots can be updated automatically (let us know if you're curious 😉). These new capabilities allow you to ask the question: Given how humans and agents actually ingest information, what helps them succeed fastest? An example of building from first principles is PostHog's new [AI wizard](https://posthog.com/docs/ai-engineering/ai-wizard) managed by the docs team. It helps the user onboard with one single command. For more first principles on how agents process information, here's our piece on how to [write docs optimized for them](/blog/technical/agent-docs). --- Whether you're a team of one or leading a docs team, the tasks are similar: build the systems that keep content alive and accurate, make the work visible to the people who decide what gets resourced, and stay close to how customers actually use the product. The craft of writing may become table stakes, but there's still a great deal of human judgment that goes into making good docs. You can try out Promptless to scale your systems so you can focus on the work AI can't do. *** title: Preview Rendered Markdown Diffs in the Dashboard url: https://promptless.ai/blog/product-updates/markdown-preview-suggestion-diffs description: Promptless now shows a rendered preview of Markdown and MDX suggestion diffs. Click "Preview Markdown" on any .md or .mdx file to see changes as formatted output, not raw diff text. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Suggestion diffs in the Promptless dashboard now include a rendered preview. Click "Preview Markdown" on any `.md`, `.mdx`, or `.markdown` file to see changes as formatted output, with GitHub-style green highlighting for additions and red for removals. ## The problem Reviewing documentation suggestions in a raw diff works for code but is awkward for prose. A diff that changes three sentences shows as six lines of marked-up text. You can tell what was added and removed, but you can't tell how the paragraph actually reads, whether a table is still properly formatted, or whether a sentence flows correctly after the change. For MDX files, it was worse. JSX attributes and component tags read as noise in raw diff view. A change to a short prose paragraph could appear as a dense block of angle brackets and props, with the actual prose change buried inside. Reviewers either mentally parsed the noise or skipped the preview and went straight to merging. ## What changed A "Preview Markdown" button now appears on file cards for `.md`, `.mdx`, and `.markdown` files in the suggestion review view. Click it to open a modal showing the rendered before and after, with added content highlighted in green and removed content in red. The preview renders Markdown formatting, tables, code blocks, and inline HTML. MDX components are rendered as static HTML, so they won't execute client-side logic, but the surrounding prose, headings, and formatting render correctly. The visual result is close to what the content looks like once published. ## Who benefits most **Anyone reviewing documentation suggestions.** The raw diff view is still available. The preview is an option for changes where reading the formatted output matters more than seeing the exact diff markers. **Teams with heavy MDX usage** will notice it most. Component-heavy files have a high noise-to-signal ratio in raw diff view. The rendered preview cuts that noise. **Non-technical reviewers** who can read finished docs but find diff syntax unfamiliar will find it easier to give feedback on the actual content instead of trying to mentally render the diff. ## How to use it No configuration needed. Open any suggestion in the Review tab and look for "Preview Markdown" on file cards for `.md`, `.mdx`, or `.markdown` files. The button doesn't appear for other file types. The preview modal is read-only. To make changes, close the modal and edit in the diff view or via your normal PR workflow. *** title: Help Center vs Docs-as-Code: When to Switch url: https://promptless.ai/blog/technical/help-center-to-docs-as-code description: A practical guide to choosing between a help center and docs-as-code, with specific signals for when to migrate and when to stay. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; At some point, most teams that start with help center docs ask the same question: should we move from our help center to docs-as-code? This article tries to give you a decision framework. ## The Core Tradeoff Help centers (Zendesk, Confluence, Freshdesk, Notion) are built for non-technical authors. WYSIWYG editors, inline commenting, article voting, ticketing integration. Anyone can publish without touching a command line. Docs-as-code (Docusaurus, MkDocs, Starlight, Mintlify) inverts this. Documentation lives in Git alongside the codebase. Changes go through pull requests. Deployment happens via CI/CD pipeline. Engineers can contribute without leaving their environment. Both approaches create friction for someone. Help centers create friction for developers. Docs-as-code creates friction for support staff, legal, and anyone who doesn't work in Git. The decision is about which direction of friction costs you more. That depends on who writes and who consumes your documentation. | | Help center | Docs-as-code | |---|---|---| | **Best for** | Customer support, FAQs, stable products | Developer-facing docs, APIs, fast-moving products | | **Authoring** | WYSIWYG, no technical knowledge needed | Markdown in Git, requires developer familiarity | | **Developer contribution** | High friction: context switch out of IDE | Low friction: same workflow as code changes | | **Non-technical contributors** | Low friction | High friction: Git barrier excludes most | | **Version control** | Article-level restore only | Full Git branching, concurrent version support | | **CI/CD integration** | Not supported | Native | | **Cost** | Per-seat licensing bundled with support suite | Free (open source) or per-seat (managed platforms) | | **Setup overhead** | Hours | Weeks to months | ## When to Move ### Developers are your primary SMEs and they're refusing to contribute This is the most reliable signal. If engineers are the primary source of technical knowledge and they won't touch the help center, documentation will decay regardless of what processes you put in place. Context-switching from an IDE to a browser-based editor is real friction, and developers will choose the path of least resistance. Docs-as-code removes that barrier. A pull request that updates documentation alongside code uses the same workflow as one that fixes a bug. 56% of developer documentation teams already follow a docs-as-code approach, with another 22% doing so partially, per [Tom Johnson's survey](https://idratherbewriting.com/learnapidoc/docapis_trends.html) of 400+ developer documentation professionals. ### You have an API or SDK and developers are your primary audience [84% of developers](https://www.cherryleaf.com/2024/07/survey-shows-documentation-is-the-no-1-way-that-developers-learn-about-your-api/) use technical documentation as their primary learning resource (Stack Overflow 2024). When they evaluate your API, the docs signal product quality. A help center can publish technical reference content, but it can't branch documentation alongside software releases or participate in a CI/CD pipeline. Those gaps matter more as developer tooling evolves. ### You need concurrent documentation for multiple software versions Help centers have article-level restore, not branching. Maintaining v1 and v2 API docs simultaneously in a help center has no clean answer. Git does. If your team is shipping multiple concurrent versions and manually juggling content between articles, this alone justifies the move. ### Engineers are shipping frequently and documentation needs to keep pace When a product changes fast, the people with the most current knowledge are the engineers writing the code. If the tooling makes it hard for them to update documentation, it won't get updated. Docs-as-code lowers that barrier directly. A documentation change can travel in the same pull request as the code change that made it necessary. The caveat here is what actually changes from the user's perspective. A product can have high internal velocity while exposing a stable interface. Think of how the ChatGPT interface has always been a text box. The underlying model and infrastructure changed constantly, but what users interacted with stayed the same. If most of the engineering work is below the surface and the user-facing product is relatively stable, documentation needs are still driven by customer support, and a help center handles that well. The relevant question is not how fast engineering ships, but how often what users see and interact with changes. ### Your documentation release process is a manual bottleneck [Tom Johnson's team](https://idratherbewriting.com/learnapidoc/pubapis_switching_to_docs_as_code.html) migrated a large documentation site from a Java CMS to Jekyll and Git. A 40-page release that previously required hours of manual copy-paste now deploys in 10 minutes via a single `git push`. If the publishing step is where releases get stuck, the pipeline change pays for itself quickly. If you're starting your docs from scratch, we'll always recommend docs-as-code. If you're already on help center, and moving will incur real cost, here are some reasons not to move. ## When Not to Move ### You have a large non-technical contributor base If compliance, legal, or support staff regularly author or review documentation, the git barrier makes it difficult for them. That said, this is a weaker reason to stay put than it used to be. AI coding tools are making it easier for non-technical contributors to interact with Git-based workflows using natural language, and that shift is accelerating. ### Your product is mature and the user-facing interface is stable If what users see and interact with changes slowly, most of your documentation work is supporting customers: answering recurring questions and helping users through a known set of issues. That is exactly what help centers are built for. Product velocity alone is not the right signal. A mature B2B SaaS with a stable product is a fine candidate for a help center even if the engineering team is active. What matters is whether the changes engineering ships affect what users need to know. If most of the work is behind the curtain, the documentation surface stays small and a help center handles it without friction. ### Your audience is non-technical end users Docs-as-code is optimized for developer-facing products. If your product is a no-code SaaS tool with a support-heavy customer base, the help center's ticketing integration, article voting, and familiar search UI are genuine advantages. Moving to a static site built for developers solves a problem you don't have. ## The Middle Path Managed docs-as-code platforms like Mintlify and GitBook layer visual editing on top of Git backends. Non-technical contributors get a WYSIWYG interface; engineers get Git-native workflows. [HubSpot moved](https://developers.hubspot.com/blog/optimizing-developer-docs-in-the-age-of-ai-our-mintlify-migration-story) from a custom-built internal documentation platform to Mintlify. Their description of the trigger was direct: the documentation team was functioning as an "accidental platform team," maintaining infrastructure instead of doing developer experience work. AI tooling made the problem visible: assistants were pulling from v1 and v3 API docs simultaneously and returning conflicting answers. The tradeoff with managed platforms is per-seat licensing and vendor dependency. Pure static site generators are free and fully customizable but require engineering to set up and maintain. ## What Migration Actually Costs Plan for the migration to take longer than expected. First, audit the content. Not everything in a help center needs to move. Support FAQs and account management articles may belong in the help center permanently. Technical reference and API docs are the migration candidates. Conversion takes weeks for a large site. You'll run both systems simultaneously while converting. Users can't wait for the migration to finish. URL structures change, which means redirect maps need to be built before you cut over. Translation workflows need to be solved before you start, not after; most localization vendors can't handle mixed Markdown and HTML. ## What Migration Doesn't Solve Moving to docs-as-code makes it easier for engineers to contribute. It doesn't guarantee they will. Documentation decay comes from a structural timing gap: engineering ships continuously, documentation reviews happen in batches. Changing the tooling removes one barrier but doesn't automatically close the gap between when a product changes and when the docs reflect that change. Regardless of which system you're in, you need a way to detect when documentation has drifted from the product it describes. That's a monitoring problem that exists on both sides of the migration. Teams with accurate documentation treat it as [a continuous monitoring task](/blog/technical/how-teams-keep-docs-up-to-date-with-promptless), not a periodic side project. If you want to put your docs on autopilot, see a demo here. *** title: Which Agent Memory Provider Should You Choose, and Why Memory Alone is not Enough url: https://promptless.ai/blog/technical/agent-memory-provider description: A practical guide to choosing an agent memory provider by workload, with clear tradeoffs, technical specs, and what to add so reliability holds up in production. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Most teams building agents eventually hit the same question: **which memory provider should we use?** Engineering writeups focused on agent memory suggest this decision is rarely settled by a single benchmark number. In production, durability, latency, and operational fit can matter more. Anthropic's long-running agents post defines the core challenge directly: each new session starts with no memory of prior work. They found context compaction alone was insufficient. So they added explicit cross-session memory artifacts (progress files plus git history) so each session could recover project state quickly ([Anthropic Engineering](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)). AWS's LangGraph durability post reaches the same conclusion from the systems side: in-memory checkpoints are ephemeral and local to each process. For production they recommend persistent checkpointers so agents can resume after crashes, continue across workers, and retain state for audit/replay ([AWS Database Blog](https://aws.amazon.com/blogs/database/build-durable-ai-agents-with-langgraph-and-amazon-dynamodb/)). AWS also published concrete memory performance deltas in a reference implementation: adding persistent memory with Mem0 reduced a repeated request from 70,373 tokens and 9.25s to 6,344 tokens and 2s. Their Letta + Aurora integration post adds the operational requirements behind that outcome: sub-second memory lookups, replica scaling for read-heavy retrieval, and durable persistence controls ([AWS Mem0 integration](https://aws.amazon.com/blogs/database/build-persistent-memory-for-agentic-ai-applications-with-mem0-open-source-amazon-elasticache-for-valkey-and-amazon-neptune-analytics/), [AWS Letta integration](https://aws.amazon.com/blogs/database/how-letta-builds-production-ready-ai-agents-with-amazon-aurora-postgresql/)). This article is aimed to help you select the right agent memory provider. We'll compare four different products, map them to use cases, and give a practical decision rubric. Then, at the end, we'll cover the part most comparison articles skip: why memory provider choice alone does not guarantee agent quality in production. ## Agent memory providers The landscape is crowded, but the top providers are: - **[Mem0](https://mem0.ai)**: a managed/OSS memory layer with a simple memory API (`add/search/update/delete`) that extracts and retrieves user-specific facts from interaction history, with optional graph augmentation. ([docs](https://docs.mem0.ai)) - **[Letta](https://letta.com)**: a stateful agent runtime where memory is part of the agent model itself (memory blocks, files, archival memory), giving explicit control over what stays in active context versus long-term storage. ([docs](https://docs.letta.com)) - **[Zep](https://www.getzep.com)**: a temporal memory service that represents memory as entities, relationships, and events with validity over time, optimized for user/account timelines and evolving business state. ([docs](https://help.getzep.com)) - **[LangGraph](https://langchain-ai.github.io/langgraph/) + [LangMem](https://langchain-ai.github.io/langmem/)**: framework primitives for building custom memory pipelines by combining checkpointed thread state, long-term stores, semantic indexing, and background memory extraction workflows. ## Quick Technical Comparison | Solution | Core memory model | Technical characteristics | Best default fit | Main tradeoff | |---|---|---|---|---| | **[Mem0](https://mem0.ai)** | Vector memory with optional graph memory | Platform + OSS, `add/search/update/delete`, metadata filtering, reranking, optional per-request graph writes (`enable_graph`), Python + Node ([quickstart](https://docs.mem0.ai/quickstart)) | Teams that want quick implementation and practical memory APIs | Faster start, but still requires policy design for memory writes and invalidation | | **[Letta](https://letta.com)** | Stateful memory embedded into agent context hierarchy | Persistent memory blocks, shared/read-only blocks, memory hierarchy (blocks/files/archival), DB-backed persistence, self-host paths ([architecture](https://docs.letta.com/concepts)) | Teams that need deterministic in-context memory behavior | In-context memory can increase token cost and needs careful sizing | | **[Zep](https://www.getzep.com)** | Temporal knowledge graph | High-level `memory.add/get` and low-level graph APIs, user/group/session memory, facts with validity windows, Graphiti path for OSS graph memory ([Graphiti](https://github.com/getzep/graphiti)) | Relationship-heavy, time-sensitive assistant memory | Graph modeling and tuning are more complex than flat semantic memory | | **[LangGraph](https://langchain-ai.github.io/langgraph/) + [LangMem](https://langchain-ai.github.io/langmem/)** | Checkpointer + store primitives | Thread checkpoints for short-term memory, cross-thread store for long-term memory, DB backends (for example Postgres/Redis), semantic indexing, hot-path + background memory workflows ([memory concepts](https://langchain-ai.github.io/langgraph/concepts/memory/)) | Platform teams wanting full control | High flexibility with potentially high maintenance overhead | ## How to Actually Choose: Three Decision Axes Before tools, decide your constraints. ## 1. Memory topology What kind of recall dominates your workload? - **Preference/fact recall** ("user prefers TypeScript", "customer is on enterprise tier"): flat semantic memory works fine. [Mem0](https://mem0.ai) is built for this. - **Relational and temporal recall** ("policy changed after the contract amendment", "new decision-maker since the reorg"): flat memory breaks here because retrieved facts may have been true at some point but aren't now. [Zep](https://www.getzep.com) tracks [validity windows on facts](https://help.getzep.com/concepts) explicitly. - **Pinned policy/identity memory** ("this assistant must always follow these rules under these circumstances"): [Letta's in-context memory blocks](https://docs.letta.com/memory) are designed for this. Choosing the wrong topology causes subtle degradation, not obvious failures. You may see stale facts returned confidently, key relations missed, or critical instructions occasionally dropped. ## 2. Context placement strategy **Always in-context** memory is injected into every prompt, so the agent can never miss it. This is right for high-stakes facts like account tier or active policy. But if you pin too much to the context, you can inflate token cost and crowd out the actual conversation. **Retrieved on demand with backup** keeps context lean and scales to large memory stores, but account for retrieval failures. If the query doesn't match the stored fact well, the agent answers without it. A support agent that fails to retrieve a customer's known workaround will give the wrong answer just as confidently as if it had found it. Most production systems need both: a small pinned layer for identity and policy, and a retrieved layer for history and facts. ## 3. Ownership model **Managed** ([Mem0 platform](https://mem0.ai), [Zep cloud](https://www.getzep.com), [Letta cloud](https://letta.com)): storage, embeddings, and scaling are handled for you. Less control over retrieval tuning and memory consolidation, but the right starting point for most teams. **Framework primitives** ([LangGraph](https://langchain-ai.github.io/langgraph/) + [LangMem](https://langchain-ai.github.io/langmem/)): full control over backends, extraction pipelines, and conflict resolution. You can choose this when you have strict compliance requirements or a platform team that can own it. If it's unclear who owns memory quality six months from now, start managed. ## Use-Case Recommendations If you want a practical default, start here. | Workload | Start with | Why | |---|---|---| | **Support agent with tight SLA** | **[Mem0](https://mem0.ai)** | Fast integration, pragmatic retrieval controls, low architecture overhead | | **CRM or account-intelligence copilot** | **[Zep](https://www.getzep.com)** | Temporal and relational memory are first-class concerns | | **Stateful assistant with strict in-context policy/persona memory** | **[Letta](https://letta.com)** | Memory blocks and hierarchy align to deterministic context needs | | **Custom internal agent platform** | **[LangGraph](https://langchain-ai.github.io/langgraph/) + [LangMem](https://langchain-ai.github.io/langmem/)** | Full control over memory lifecycle and store design | ## 5-Minute Decision Process Run this sequence before you commit: 1. Is our dominant recall problem semantic, relational, or pinned in-context? 2. What p95 latency budget can memory retrieval consume? 3. How much platform ownership can we realistically sustain this quarter? 4. Do we need strict data-residency or self-hosting requirements from day one? 5. What is our memory mutation policy (who writes memory, when it expires, how conflicts resolve)? ## Why Choosing the Right Memory Provider Is Still Not Enough Now the second half of the title. Even a great memory system only answers: "what should the agent remember and retrieve?" It does **not** answer: "is what the agent retrieved still correct in the current version of your product, policies, and docs?" This is where production failures emerge: - The agent remembers user and workflow state perfectly. - Your API behavior or policy changes. - The agent retrieves memory that was previously correct. - The output is now confidently wrong. Memory solved coherence. It did not solve freshness of external truth. In practice, reliable agent systems need two layers: - **Memory layer** for continuity, personalization, and history. - **Environment layer** for continuously current source-of-truth context. ## Where Promptless Fits Promptless sits in that second layer. Whatever memory provider you choose, Promptless helps you continuously manage context sources so the agent's grounding layer stays current as code, docs, and product behavior change. That combination is what actually holds up in production: - Memory provider for coherence. - Promptless for freshness. You get agents that remember what matters and stay aligned with what is true now. To see a quick demo, feel free to book below. *** title: How to Increase the Deflection Rate of Your Support Agent and Build a Feedback Loop url: https://promptless.ai/blog/technical/support-agent-deflection description: Most support agent deflection problems aren't model problems — they're documentation problems. Here's how to diagnose yours and build a feedback loop that compounds over time. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Most teams building AI support agents hit a ceiling. The agent deflects 40–60% of incoming tickets, leadership pushes for more, and the team runs more evals and swaps models, but the number barely moves. Across self-reported numbers from Intercom, Zendesk, Salesforce, and Decagon, that range is where most mature deployments land. To close the gap, you need better documentation, not a better model. ## Why Your Agent Is Failing When a support agent fails to deflect a ticket, one of five things went wrong: **The answer doesn't exist in your docs.** Something changed that never made it into documentation. The agent genuinely has nothing to work with. **The answer exists but is outdated.** This is the most insidious failure mode. Stale documentation retrieves just as confidently as current documentation. The agent surfaces a wrong answer and the customer escalates. In your analytics, this shows up identically to a genuine knowledge gap. **The answer exists but the agent couldn't find it.** The doc is correct and current, but the customer phrased their question in a way that didn't match how the doc is written or structured. The retrieval system finds no match and the agent either gives up or guesses. **Customer-specific context.** Some answers aren't in your general docs and shouldn't be. They live in account notes or past tickets. You want the agent to have that context so it isn't starting from scratch with every customer. **The question is genuinely hard.** Some tickets require judgment calls that don't reduce to a documented answer — edge cases with multiple interacting factors, account situations with unusual history, or problems where the right answer depends on context the agent can't access. No amount of documentation improvement will deflect these. ## Diagnosing Your Failure Mode The fastest way to understand your deflection ceiling is to spend an afternoon with 50 escalated tickets and categorize them. Pull tickets that were routed to a human after the agent attempted to answer. For each one, see which of the 5 failure modes it maps to: - **True gap:** the answer wasn't documented anywhere - **Stale answer:** the doc existed but was wrong or outdated - **Retrieval miss:** the doc existed and was correct, but the agent didn't surface it given how the customer phrased the question - **Custom information:** the answer exists in account-specific context rather than in general docs - **Genuinely hard:** requires human judgment or has too much account-specific complexity for a general answer Most teams expect the "genuinely hard" bucket to be full. In practice, it's usually the smallest. The true gap and stale answer buckets are typically where 60–70% of deflections live, and both are documentation problems, not model problems. We're happy to do this support agent failure mode audit for you — reach out to help@gopromptless.ai to request one. ## Building the Feedback Loop Once you can categorize where your support agent fails, you have the raw material for a feedback loop. The goal is to make every handoff to a human improve the documentation that powers the next answer. Track two metrics from day one: - **Deflection rate** = tickets resolved by the agent / total tickets initially handled by the agent - **Escalation rate** = tickets handed to a human after agent response / total tickets initially handled by the agent Use weekly snapshots plus a rolling 28-day view so you can see both short-term movement and trend direction. ### Step 1: Tag escalations at the source Add a lightweight classification step to your support workflow. When an agent hands off to a human, require the support engineer to tag the reason. Use a fixed taxonomy: - `knowledge_gap` - `stale_content` - `retrieval_miss` (doc exists, but wording/structure prevented retrieval) - `missing_customer_context` (plan, configuration, account history) - `needs_human_judgment` Store these tags as structured ticket fields (not free-form notes) so you can query and trend them. Some teams automate this with a secondary LLM pass that classifies handoffs, but manual tagging usually gives better signal until you have enough labeled data to validate automation. ### Step 2: Map escalations to specific doc gaps A tagged escalation tells you *why* it failed. The next step is translating that into a specific doc change request. For knowledge gaps, the ticket is often a first draft of the missing doc. For stale content, the ticket identifies which page is wrong. For retrieval misses, the customer's phrasing tells you which terms or headings are missing. Create a queue owned by a clear role (docs owner, support ops lead, or devrel lead). Each queue item should include: - affected ticket IDs - target doc path/URL - proposed change type (new page, patch, restructure, terminology update) - assignee and due date Treat these items like product bugs. From the customer's perspective, a confidently wrong agent answer is a broken feature. ### Step 3: Close the gap and measure When a doc fix ships, link the merged PR or doc commit back to the escalation tag(s). Then track whether that category shrinks over the next 2 and 4 weeks. Set an SLA so the loop stays alive: - top-volume categories: first fix within 72 hours - long-tail categories: first fix within 7 days This is what turns cleanup into a compounding system. If a doc patch reduces a tagged escalation bucket by 20–30%, you have a repeatable playbook to run again. ## The Compound Effect This loop compounds because each fix improves all future tickets in that problem class, not just the ticket that triggered the update. Teams that run this weekly usually see stepwise deflection gains after each cleanup cycle. Teams that run it ad hoc usually plateau because the backlog grows faster than fixes ship. There is also an organizational effect: support engineers start treating documentation as a maintained system with owners, SLAs, and quality checks. ## How Promptless Closes the Loop Automatically The loop above works. The reason most teams don't sustain it is the manual work in the middle: someone has to notice the pattern, find the right doc, write the fix, and get it reviewed and published. That overhead is enough that it happens inconsistently, and an inconsistent loop doesn't compound. Promptless eliminates that middle layer across all three of the fixable failure modes. **For true gaps and stale content**, Promptless watches your engineering repos and changelogs in real time. When a PR ships that changes how a feature works, Promptless identifies which docs are now out of date before any customer asks about it. **For retrieval misses**, Promptless continuously monitors your incoming support tickets and identifies clusters of questions that should be answerable but aren't. When the same question keeps getting asked in slightly different ways and the agent keeps missing it, Promptless surfaces the pattern, identifies the relevant doc, and suggests structural or terminology changes that would make it retrievable. **For customer-specific context**, Promptless maintains a separate layer of account-level documentation that lives alongside your public docs but is scoped to granular levels. When your product changes, this layer updates automatically too, so your agent always has current context about each account's configuration and history. The result: support tickets stop being a lagging indicator of documentation failure and start being an input to a system that keeps your agent's knowledge current. Feel free to request a demo here to see Promptless in action! *** title: What is Agent Context Engineering? And How is it Different from Prompt and Harness Engineering? url: https://promptless.ai/blog/technical/agent-context-engineering description: Learn what agent context engineering is, how it differs from prompt and harness engineering, why most agent failures are context failures, and a four-layer framework for building reliable AI agents. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; For the past few years, prompt engineering was the dominant focus in applied AI. More recently, the term context engineering has come to the foreground. Building with language models is becoming less about carefully phrasing instructions and more about answering a broader question: does the model have everything it needs to complete the task? AI agents can manage some of their own context within a session, through compression and memory maintenance. Claude Code, for example, will compact its context window when it fills up. But what agents can't manage is the quality of the information environment external to themselves: the underlying knowledge, tool definitions, and behavioral guardrails that sit outside any given session. That part remains a human responsibility, and it's where most of the real work lives. Shopify's CEO Tobi Lütke and AI researcher Andrej Karpathy both wrote about the shift in mid-2025. "I really like the term 'context engineering' over prompt engineering," wrote Tobi. Karpathy agreed, noting that people associate prompts with short instructions, whereas in every serious LLM application, context engineering is "the delicate art and science of filling the context window with just the right information for each step." ![Andrej Karpathy tweet about context engineering](/assets/karpathy_tweet.png) ## Context Engineering vs. Prompt Engineering Prompt engineering mattered more when models were worse at understanding intent. The early practice involved carefully phrasing instructions (role definitions, trigger phrases, output-format examples) to coax models that needed heavy guidance to stay on track. Current state-of-the-art LLMs have largely solved the "what should I do" problem: they follow instructions well, and you don't need to spend much time engineering the prompt itself. What they can't solve on their own is the "how we do it here" problem. Models trained on public data know how the world generally works, but not how your organization or your product specifically operates. Context engineering is the work of making that private, product-specific knowledge available to the agent at the right time. Andrej Karpathy's analogy is useful here: think of the LLM as a CPU and its context window as RAM. The CPU can only operate on what's in RAM, and it doesn't matter how capable the processor is if the wrong data is loaded. Context engineering is the discipline of deciding what gets loaded, and ensuring it's accurate and well-structured enough to be useful. For agents specifically, wrong context compounds in a way it doesn't for single-turn assistants. Each step in an agent's execution uses the outputs of prior steps as inputs, so a stale policy retrieved in step two becomes the assumption underlying steps three, four, and five. By the time the agent produces a final answer, it may be confidently wrong. Not because of a reasoning failure, but because the information it reasoned from was bad from the start. ## Context Engineering vs. Harness Engineering Context engineering is often conflated with harness engineering, but they're different layers of the same system and they fail in different ways. Harness engineering is about how the agent is structured and orchestrated. For long-running agents, Anthropic describes [the core challenge](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) as agents having to work across discrete sessions where "each new session begins with no memory of what came before." The harness solves this: it coordinates how work gets broken down and handed off across sessions, handles retry logic and error recovery, and routes tasks between specialized sub-agents. Context engineering operates at a different level entirely. A well-designed harness doesn't fix bad context. You can have a perfectly orchestrated planner-generator-evaluator pipeline and still get systematically wrong answers if the knowledge base the agents draw from is stale or poorly structured. The harness ensures the agent makes progress; context engineering ensures that progress is in the right direction. When the harness fails, the agent breaks visibly: sessions stall, state gets corrupted. When context fails, nothing breaks. The agent runs exactly as designed, does the wrong thing confidently, and gives no signal that anything is off. ## Most Agent Failures Are Context Failures Most agent failures aren't model failures. They fall into three categories: **Missing or stale context.** The agent either didn't have the information it needed, or it had information that used to be correct. A policy or API changes silently, and the knowledge base doesn't. [Outdated documents score just as high on semantic similarity as current ones](https://glenrhodes.com/data-freshness-rot-as-the-silent-failure-mode-in-production-rag-systems-and-treating-document-shelf-life-as-a-first-class-reliability-concern/), so the retriever has no basis for preferring the accurate version. The agent answers confidently from what it finds. **Context the agent didn't know to retrieve.** The information existed, but the agent didn't know it was relevant. This is a metadata and structure problem: if documents aren't organized to make their scope clear, the agent can't match them to the right situation. A support agent may have the escalation policy in its knowledge base but never retrieve it because nothing in the user's query triggers that document. The failure looks like the agent ignoring a rule it was given, but the rule was simply invisible at the moment it was needed. **Missing, vague, or overlapping tool descriptions.** Tool descriptions determine which tool an agent selects. [Research across 17 models](https://arxiv.org/abs/2505.18135) found that improving a tool's description caused agents to use it over ten times more often, and the inverse is equally true. If a tool doesn't exist for what the agent needs to do, it will hallucinate or give up. If two tools have similar descriptions, the agent will pick one arbitrarily. ## A Four-Layer Framework for Agent Context To reason about agent context systematically, it helps to decompose it into four layers. ### Layer 1: Instruction Context This is the layer most teams invest in first: the system prompt, the agent's goals and behavioral constraints, and any persona or policy definitions. Few-shot examples belong here too. Rather than trying to enumerate every possible edge case in the prompt, the more effective approach is to provide a set of diverse, representative examples that demonstrate the expected behavior, since a long laundry list of rules is harder for a model to apply consistently than a handful of well-chosen examples. ### Layer 2: Knowledge Context This is where the knowledge the agent draws from at runtime lives. It's the layer most directly affected by retrieval pipelines and knowledge base quality, and it's where the difference between a demo and a production system usually lives. Not in which model you're using, but in how carefully that knowledge is structured and delivered at each step. This is also the layer most vulnerable to drift. Teams tend to treat knowledge systems as one-time projects: ingest documents, deploy, done. But sources change silently. Product docs and internal guides update regularly, while the agent's knowledge doesn't, because there's no automated sync. The result is a knowledge base that was accurate at launch and quietly wrong six months later, with no visible signal that anything has changed. Software engineering has spent decades building tools to manage change in code (version control, automated testing); agent knowledge needs the same rigor. ### Layer 3: Operational Context This is the runtime state: the conversation so far, prior tool outputs, and any environmental signals like timestamps or session metadata. Managing this layer means deciding what to keep, what to summarize, and what to drop as the agent runs. For teams building their own agentic systems, this is an active engineering problem. Long-running agents accumulate tokens across many LLM and tool calls, and left unmanaged the growing context drives up cost and degrades performance. But if you're using a managed agent like Claude Code, much of this is handled automatically: the agent manages its own memory and decides what to carry forward. In that case, your leverage sits almost entirely in the knowledge layer, not here. ### Layer 4: Action Context This layer comprises the tools available to the agent: how they're defined, described, and scoped. If a human engineer can't definitively say which tool should be used in a given situation, an agent can't be expected to do better. Bloated tool sets and ambiguous descriptions are among the most common sources of agent misbehavior in production. Action context also includes what the agent is *not* allowed to do: the permission boundaries and escalation policies that prevent it from taking actions that are technically available but outside acceptable scope. Defining these constraints explicitly is as important as defining the tools themselves. ## What You Actually Control There's a quiet misnomer in "context engineering" that becomes obvious once you deploy against a closed-source model. With agents like Claude Code, Codex, or Gemini, you do not actually decide which piece of context the agent retrieves or weighs at each step. The agent does. You can shape how your retrieval pipeline is configured, but once the agent is running, the model determines what it finds relevant. You are not engineering the context; you are engineering the environment the agent operates inside. This distinction matters practically. Teams who think of themselves as "doing context engineering" often focus on prompt structure and retrieval tuning. Those things matter. But the lever you actually have the most control over, and that has the most impact on output quality, is the accuracy and structure of the underlying information the agent can access. If your docs are stale or poorly structured, no amount of retrieval tuning fixes it. The model will confidently surface the wrong answer, because that is what it found. Context engineering, properly understood, is less about controlling what goes into the context window at runtime and more about maintaining the information environment that the agent draws from. The question stops being "how do I get the right chunk into the context window?" and becomes "is everything in my knowledge layer accurate enough that it doesn't matter which chunk the model retrieves?" ## How Promptless Keeps the Knowledge Layer Fresh Of the four layers described above, the knowledge layer is the one that drifts the fastest and is hardest to maintain manually. Every time your product ships a feature or deprecates an API, the docs that feed your agents risk becoming stale. Stale docs don't throw errors; they produce confident, wrong answers that erode customer trust. Promptless is purpose-built for this problem. It continuously monitors your documentation against your actual product and codebase, automatically surfacing what's outdated or missing. Instead of waiting for a support ticket to reveal that your agent is recommending a deprecated API pattern, Promptless flags the gap before the agent ever serves it. The result is agents that give correct answers not just on day one, but on day 100 and day 1,000. *** title: Documentation Drift Is a Detection Problem, Not a Writing Problem url: https://promptless.ai/blog/technical/documentation-drift-detection-problem description: Most teams treat documentation drift as a writing problem. It's not. The real bottleneck is detection — knowing what changed before the damage is done. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; Right now, somewhere in your docs, there is a lie. It's not malicious. It was accurate when it was written. But a parameter was renamed, an endpoint was deprecated, a flow was quietly restructured — and no one updated the page. The lie has been sitting there for weeks, maybe months, misleading developers who trust it. This is documentation drift: the slow, continuous divergence between what your docs say and what your product actually does. According to a Postman survey, 68% of developers cite outdated documentation as their top frustration when working with APIs. A 2025 IEEE review of the field confirmed what practitioners already know: "Maintaining alignment between software code and specifications is a persistent challenge in the software development lifecycle." The standard advice is to treat this as a writing problem. Audit quarterly. Add a docs-update field to your PR template. Hire another writer. Run a documentation sprint. None of these interventions are wrong — but they all miss the actual bottleneck: the problem is not the writing, it's the knowing. Before a word of documentation can be updated, someone has to know it needs updating. That's where most teams are actually failing. ## How drift compounds Drift follows a predictable pattern at scale. A developer ships a change — a renamed field, a revised authentication flow, a new required parameter. They know the docs need updating. But they're immediately pulled into the next ticket. The update gets filed mentally as "I'll get to it," which means it doesn't get done. Even when teams have a dedicated documentation owner, the shape of the problem shifts rather than disappearing. Now the writer has to discover the change — by watching Slack, scanning pull requests, attending standups, or waiting for a support ticket that turns out to be an outdated doc. This is surveillance work: constant, manual, and impossible to sustain as codebases and teams scale. The downstream costs are significant. A simple diagnostic — surveying developers on documentation quality, tracking Slack questions, measuring PR cycle time — typically finds that documentation problems consume **15–25% of total engineering capacity**. Not because people aren't writing, but because they're compensating: reading source code instead of reading docs, asking questions on Slack that docs should answer, debugging integration issues that trace back to an outdated spec. That's 15–25 engineers per 100-person team doing work that accurate documentation would eliminate. And 75% of APIs don't conform to their own specifications, according to a recent report on API drift — not because teams don't care, but because the tooling and processes for detecting drift haven't kept pace with the speed of development. ## The trust collapse nobody talks about There's a well-documented tipping point in documentation. Once developers encounter enough inaccuracies — once they've followed a tutorial that fails, called an endpoint that no longer exists, passed a parameter that was renamed three sprints ago — they stop trusting the docs. The page still reads fine. But now every claim requires verification. Developers treat the docs as a starting point for skepticism rather than a source of truth. They copy the code sample into their IDE and run it rather than trusting it. They ping the team that owns the API to confirm the behavior. The docs technically exist, but the information system they were meant to support has collapsed. This is hard to reverse. You can't announce "we fixed the docs" and expect immediate credibility. Trust rebuilds slowly, through consistent accuracy over time — which requires staying ahead of drift, not just catching up to it. For developer-facing companies, the stakes are particularly high right now. Your documentation is what integration partners rely on. It's what new users encounter first. And increasingly, it's what coding agents read when they try to use your product programmatically. Drift in any of these contexts creates a multiplier effect: more support tickets, slower onboarding, broken integrations, and worse outputs from AI-assisted workflows. ## The detection gap that docs-as-code doesn't close Docs-as-code practices — storing documentation in version control, requiring doc updates in pull requests — are genuinely useful. They make it easier to update docs once you know an update is needed. But they don't solve discovery. A PR template that says "did you update the docs?" only works if the developer remembered which docs were affected. A quarterly audit only catches drift that has already happened and been left untouched long enough to show up on a calendar. Neither approach closes the loop between code change and doc update in real time. The root cause is that change detection is not a first-class part of most documentation workflows. It's informal, manual, and dependent on the right person remembering to mention the right thing at the right time. When that chain breaks — which it does constantly — drift accumulates silently. The analogy: most documentation teams work like a security professional replaying hours of footage to see if something suspicious happened. The signal exists — in pull requests, Slack threads, support tickets, issue trackers, release notes — but it's buried in noise, and surfacing it takes more time than most teams have. ## What a detection-first approach looks like The shift that actually moves the needle is moving from replay to motion detection: a system that continuously watches the signals where change happens and surfaces only the ones that matter for documentation. ### Monitor the right signals upstream The signals that most reliably predict documentation impact are code changes to public-facing interfaces, support tickets surfacing undocumented behavior, and release notes and changelogs. These are where drift begins — not in the documentation itself. Watching for these upstream means you find out about drift before a developer does. ### Cross-reference changes against current docs A PR that renames a parameter matters a great deal if that parameter appears in three tutorial pages. It matters less if it's an internal implementation detail. Detection that can't distinguish the two creates noise instead of signal. Useful detection triangulates: here's what changed in the product, here's where it's currently documented, here's how confident we are that an update is needed. The goal is not to flag every commit — it's to surface the fraction of commits that actually require a documentation change. ### Let feedback narrow the signal over time Not every flagged change requires an update, and teams have different thresholds for what's doc-worthy. A detection system should learn from those decisions — when a writer dismisses a signal or when a dismissed signal later surfaces as a support ticket. Over time, the system gets better at filtering, and the writer's review queue shrinks to only the signals that consistently matter. ## The practical upshot If your team is dealing with documentation drift, the most leveraged investment is not in writing more. It's in building a discovery layer that surfaces changes before they become outdated pages — so that when a writer sits down to update the docs, they already know exactly what needs updating. Teams that solve the detection problem find that their existing writing capacity goes much further. Writers spend less time on surveillance and more time on the work that actually raises documentation quality: clarity, information architecture, coverage, examples. Drift is not inevitable. But solving it means going upstream — past the blank page, past the review queue, to the moment when the product changed and nobody told the docs. *** title: What It Looks Like When Your Docs Keep Up With Your Product url: https://promptless.ai/blog/technical/how-teams-keep-docs-up-to-date-with-promptless description: Three real workflows from teams using Promptless that show what changes when your tooling handles detection, context gathering, and the first draft. --- import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; What does it look like when your docs keep up with your product, without you spending half your day hunting for what changed? Most docs tools solve distribution. They give you a nice site, interactive API explorers, maybe a search bar that works. That's real value, but it assumes the hard part is presentation. The actual hard part is knowing what needs to be written and keeping it honest as the product moves underneath you. That is the work that eats your week, and that is the problem we built Promptless to solve. We have been working with teams like Helm, Vitess, Basis, and Vellum over the past few months, and there are three workflows that keep surprising me with how much they change the shape of a writer's day. The first is just eliminating the classic "I didn't know that changed" problem. Many of our customers love the awareness Promptless gives them of what changed, and how it changed. Promptless watches every PR across their repos, and when an engineer changes how auth works or deprecates a parameter, the tech writer does not find out from a support ticket three weeks later. A writer gets a drafted update with citations back to the PR, the relevant Slack discussion, the engineer's own description of the change. Review it, ask Promptless for changes, manually edit it, published. The feedback loop between code change and doc update collapses to hours. The second is something Basis is doing that (completely unexpected to me)! They dump their customer call transcripts into a Git repository, and Promptless monitors that repo and maintains internal documentation around what all their customers are doing, what they are asking about, what keeps coming up, how the product is actually being used out in the field. An internal knowledge base that builds itself from conversations, and because it lives in their own repo in a format they control, they are building all kinds of internal agents to make use of it. They would get way less value from throwing all that data into a third party system and hope third party agents can do something useful with it. The third is about scale. Helm had community translations of their docs across ten languages, but most were incomplete or out of date, and would be a big ask for their writers to bring them all current by hand. So two writers spent about five iterations over eight hours "teaching" Promptless how to do the work (it's just skills, which if you read this blog you know is just another kind of docs). They started with a style guide which was not good enough. But they got feedback in about 35 minutes, so they iterated and fixed the problems. They added a glossary, then more language-specific instructions for how to handle existing translations, keep what was still good, update what had drifted, and fill in the gaps. By the end of that process the writers had 10 playbooks that Promptless could execute for 10 languages over the 110 pages of Helm V3 docs. So in one day, 10 PRs opened. Then over the next three weeks the community reviewed and merged them one by one. Pretty clever use case we didn't build for. This is what's possible when your writers have a power tool that rewards the craft, not just a platform that makes things look nice. If you want to see what this looks like for your team, book a quick 15-min demo with one of our engineers. 14-day free trials! *** title: A Practical Guide on How to Optimize Your Docs for Agents url: https://promptless.ai/blog/technical/agent-docs description: A practical guide for technical writers on adapting documentation for AI agent consumption, grounded in how agents actually access and use docs today. --- import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro'; import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; A [recent Y Combinator podcast](https://www.youtube.com/watch?v=Q8wVMdwhlh4&t=275s) mentioned that the biggest reason Supabase has become a default choice for coding agents is that their docs are easy to follow. But if my manager were to ask me to “make our docs like Supabase,” I wouldn't know where to start. There are a million differences between Supabase and any given product, so how do I know which traits made a difference and which traits are superficial? It’s hard to deny what’s happening around us: agents are reading more documentation, humans are reading less. This trend is likely to continue, and will likely accelerate. This article offers a perspective that tries to get closer to first principles on what adjustments to your docs are worth making, based on how LLMs are built and how they behave, grounded in research from top labs. To be clear, we’re not advocating for a separate set of “agent docs.” You’ll find that many of these changes improve the human experience too. And where there’s a real trade-off, we’ll call it out. ## How agents consume your docs today Before we talk about optimization, it helps to ground ourselves in the concrete ways agents run into your documentation. In practice, there are 3 main pathways. Depending on your product, you can decide which ones matter most to optimize for. ### 1. Web search and fetch When agents like ChatGPT, Claude, and Gemini browse the web, they typically use two tools: **[search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)** and **[fetch](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool)**. The search tool accepts a query and returns a list of page titles and URLs without body text. For example, this is the output that Claude Code sees when it searches "how to create a payment link in stripe": ```json [ {"title":"Stripe Payment Links | Simple Links to Accept Payments","url":"https://stripe.com/payments/payment-links"}, {"title":"Create a payment link | Stripe Documentation","url":"https://docs.stripe.com/payment-links/create"}, {"title":"Create Payment Links | Stripe Documentation","url":"https://docs.stripe.com/no-code/payment-links"}, ... ] ``` The agent reads the titles and decides which URLs are worth fetching. If your critical information is spread across 5 different pages with the same title "Overview", that makes it harder for the agent to know which one to dig into. When the agent fetches, it programmatically strips the HTML down to markdown or plain text, or fetches the markdown version of the page directly. Code blocks, tables, and headings survive this conversion well. Images, certain diagrams, and anything loaded dynamically via JavaScript don't. This means that it's better to avoid references like "click the green button in the upper-left corner of the screenshot below." (As LLMs become more natively multimodal this will matter less, but fewer dependencies is always better.) The "minimum retrievable unit" in web fetch is the full page. Unlike RAG, the agent gets the entire page instead of a targeted chunk appended to its working context. ### 2. RAG systems (support bots) Tools like Kapa, Intercom’s Fin, doc platform “Ask AI” features, and many in-house support chatbots fall into this category. They ingest your docs, split them into chunks, and retrieve relevant chunks when a user asks a question. Most often, the chunking strategies will follow the heading structure. The text under an `## H2` or `### H3` often becomes a retrievable unit. Now combine tens of those units pulled from very different parts of the docs and add them to the context at once. That’s what the LLM/agent usually sees. ### 3. MCP/tool calling (via tool descriptions) The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that lets agents programmatically interact with external tools and services. If your team is building an MCP server on top of your product's API, then your tool names, descriptions, and parameter schemas become a first-class citizen of your documentation. Two research findings are worth mentioning here. First, [an evaluation of LLM tool use over an API](https://arxiv.org/abs/2508.13774) found that terminology consistency matters more than you’d expect. If your tool descriptions alternate between `rate limit`, `quota`, and `throttle`, or `archive`, `deactivate`, `disable`, the model has to guess whether those are describing the same or completely different concepts, which leads to worse tool use. The same applies to inconsistent function names, vague parameter descriptions, and overlapping tool scopes. Something worth keeping in mind when you write for MCP is to try to **reduce ambiguity for the agent** every step of the way. Second, [a study on tool selection bias in LLMs](https://arxiv.org/html/2510.00307v1) found that LLMs select tools based almost entirely on semantic alignment between the user’s query and the tool description. This means descriptions should be written from the user’s perspective (what task does this tool accomplish?), _not_ from the implementation perspective (how does this tool work?). Imagine an LLM trying to choose between your tool and a competitor's. Your underlying tool function is much more robust and elegant, but has "handle auth stuff" as the description, versus theirs has spaghetti code generated by GPT 3.5, but clear, precise descriptions. The LLM will pick theirs. ## What actually helps ### 1. Make sections self-contained
Relevance: WEBlow RAGhigh MCPhigh
When an agent retrieves a chunk of your docs, it often gets that chunk without the surrounding context. So if the chunk says something like “use the payment object from above,” the agent may have no idea what “above” refers to. Some agents will try to chase the reference, but many RAG setups only support semantic search (finding content by meaning rather than exact keywords) rather than letting the agent reliably fetch “the chunk above this one.” Now add two practical constraints. First, when an agent can’t find a referenced piece of information, it doesn’t always stop and say so, instead it'll make a plausible-sounding guess. This is one of the main sources of hallucination (see [Why Language Models Hallucinate](https://arxiv.org/abs/2509.04664)). Second, most agents have an upper limit on how many steps they can take before stopping, usually around 100–200. Lots of “see above / previous page” phrases can lead to agents burning through that budget hunting for context, and stopping before they’ve found what actually matters. There’s also empirical evidence that spreading content across too many files can make retrieval harder for LLMs. In [one controlled study](https://arxiv.org/abs/2503.04388), researchers kept the total context length and the position of the relevant information fixed, and varied only how many separate documents that context was split across. They found that increasing the document count in RAG settings could reduce performance by up to 20%. > Write as if you’re doing a radio interview and you don’t want to be quoted out of context. — November 2025 Write the Docs [Newsletter](https://www.writethedocs.org/blog/newsletter-november-2025/#optimizing-docs-for-llms) **What to do**: Avoid forward and backward references like “see above,” “as described in the previous section,” or “same as before.” Instead, restate the key information. This doesn’t mean duplicating entire sections - just the critical bits that make each section stand better on its own. Kubernetes does this well by including a “Before you begin” block at the top of related pages for hard prerequisites (for example, [Adding Linux nodes](https://kubernetes.io/docs/tasks/administer-cluster/kubeadm/adding-linux-nodes/)). One practical way to do this without cluttering the page for human readers: put prerequisites, environment setup, etc. in expandable blocks. The information is present for agents parsing the full page, but it doesn’t interrupt the main flow for humans who have already completed the setup. Many style guides already discourage “see above” and similar phrasing. This is the same principle, just higher stakes for agents. ### 2. Document failure modes, known bugs, and edge cases
Relevance: WEBhigh RAGhigh MCPhigh
This is the recommendation where optimizing for agents and optimizing for humans diverge the most. That being said, the form factor doesn’t have to clash. You can put added content in expandable sections at the bottom of each main page. If it makes pages too long, house it under a dedicated part of your docs (think an additional section in the sidebar). [A survey on code generation with LLM-based agents](https://arxiv.org/pdf/2508.00083) found that agents struggle particularly with “unwritten team conventions” and “non-public, highly contextualized information.” Separately, [research on resilient LLM agent architecture](https://arxiv.org/abs/2509.08646) found that agents with access to structured failure information performed significantly better than agents trying to reason about errors from their general knowledge. (Side note: I think agent self-recovery and self-evolution will matter even more over time.) [A paper on automated prompt optimization for LLM agents](https://arxiv.org/abs/2512.09108) found that vague guidance like “consider edge cases” or “be thorough” consistently underperformed compared to explicit, structured instructions with concrete examples and edge cases, which improved accuracy by 10.1%–36.9%. Stripe is also a good example of documenting failure modes. Its [error codes page](https://docs.stripe.com/error-codes) maps each code to a description (and often resolution steps), and the API returns a `doc_url` field that points directly to the relevant documentation entry.
Stripe error codes documentation page showing a filterable table of error codes and descriptions
Stripe error codes page - structured error catalog with filterable table
Stripe invalid request error page showing type, problem, and solutions in a structured table
Stripe error details page - structured breakdown of error type, problem, and solutions
Twilio takes a similar approach. Its [Error and Warning Dictionary](https://www.twilio.com/docs/api/errors) lists every error code, and each one follows this format with description, possible causes, and possible solutions. ``` # 400: Bad Request Log Type: APPLICATION Log Level: ERROR ## Description Failed to complete request due to a bad request ### Possible Causes * The resource to be modified has moved into a state that is no longer valid. * Input on the request did not pass validation. ### Possible Solutions * Retry the request after confirming the request is valid. * Verify if the resource to be modified exists and is in a valid state. ``` Supabase has a [debugging section](https://supabase.com/docs/guides/auth/debugging/error-codes) under each product area.
Supabase database docs showing a Debugging section in the sidebar with Timeouts, Debugging and monitoring, Debugging performance issues, Supavisor, and Troubleshooting
Supabase docs - dedicated Debugging section under each product area in the sidebar
**What to do:** The lowest-hanging fruit is to add dedicated debugging and error sections, which help humans too. You can either embed them directly on relevant pages (expandable sections are perfect for this) or centralize them into dedicated areas of your docs for each major product surface. _Tip: quote error strings, codes, and types exactly as they appear in your code. Avoid paraphrasing._ If you want to go further, add edge cases and known issues. In general, centralized pages work well for error information; in-page sections work better for edge cases. Some tips on where to find the content: - GitHub issues or Jira tickets marked with "WON'T FIX" - changelogs or release notes - support threads and customer conversations You can point an LLM at these sources and have it synthesize the recurring patterns into docs. One important caveat: expandable sections only work for agents if the content is already in the page’s HTML and just visually hidden. Content that loads dynamically on click is invisible to agents. To check, ask an agent to fetch one of your docs pages with the component in question and save the output to a file. If the content is there, you're good; if not, a dedicated sidebar section is the safer bet. (Thank you [Lois](https://www.linkedin.com/in/loispatterson/) for raising this!) In the Next.js [docs](https://nextjs.org/docs/app/getting-started/mutating-data), the router selector loads a new page on click, so agents only see the actively selected router's doc page. The language tabs, by contrast, have both js and ts snippets in the HTML, so the agent will see both.
Next.js documentation page with a sidebar dropdown open showing 'Using App Router' and 'Using Pages Router' options, and a code block with a TypeScript language selector tab
Next.js docs showing the App Router / Pages Router selector and a TypeScript/JavaScript code table
### 3. Code snippets might matter more than prose
Relevance: WEBmedium RAGmedium MCPmedium
In [When LLMs Meet API Documentation](https://arxiv.org/html/2503.15231v1), researchers tested what happens when you strip different parts of API docs before feeding them to an LLM. Removing code examples caused pass rates to **collapse from 66–82% down to 22–39%**. Removing parameter descriptions had a much smaller effect. As to what examples are best, [research on the role of diversity in few-shot learning](https://arxiv.org/html/2505.19426v2) shows that diverse examples outperform ones that are very similar to each other, especially as task complexity increases. The accuracy gain from diversity is 10.72% on hard tasks versus 5.11% on easy ones. Diverse examples also generalize better when an agent’s query differs from the exact scenario an example was designed for. Should you include negative examples? You can, but tread carefully because the research is mixed. **1. The key is contrastive.** There is extensive research showing that [contrastive in-context learning](https://arxiv.org/abs/2402.11254) improves LLM performance, but the key word is "contrastive." A negative example needs a paired positive to produce that benefit; a negative example in isolation is more likely to hurt. **2. Subtle wrong beats obviously wrong.** Examples near the model’s decision boundary are the most effective (per [research on negative sample quality in LLM training](https://arxiv.org/html/2602.03516v2)). If you include negative examples, "subtly wrong" or "plausibly correct but wrong" outperforms "blatantly wrong." Trivial formatting errors also don’t add much and can backfire if the model imitates them. **3. Add comments inside your code snippets.** [Research on in-context learning for instruction following](https://arxiv.org/abs/2405.19874) found that LLMs sometimes treat demonstration examples as additional tasks to complete, causing the main task to fail or get stuck. Moreover, a large-scale analysis of 673 agent skills ([Carey 2026](https://agentskillreport.com/), thank you [Dachary](https://www.linkedin.com/in/dachary/) for the feedback on this!) found contamination patterns with examples (for instance, shell syntax appearing in JavaScript outputs). Adding comments inside the code blocks will reduce their dependency on the surrounding markdown text, and help the model distinguish examples from instructions, positive cases from negative ones, and example for one part of the docs from another. **What to do**: For your most critical API reference and how-to pages, invest in a small, curated set of examples rather than as many as you can find. Prioritize diversity over volume, especially for complex workflows. Add inline comments to make the intent of each snippet explicit, whether it is a correct example, a near-miss, or a step in an instruction sequence, so that you're not relying solely on the surrounding markdown text. If you need inspirations for examples, support tickets are often a great source for near-miss cases that real users encounter. The main downside of adding examples across your docs is maintenance overhead. (Or, you can try Promptless 😊) Not many teams do directory-level examples yet, but top dev tools are trending in this direction. Some maintain dedicated examples directories in their repos (for instance [Vercel](https://github.com/vercel/vercel/tree/main/examples)). Others publish cookbooks (for instance [OpenAI](https://github.com/openai/openai-cookbook)). At this scale, diversity matters most, for instance covering varied parameter combinations and use cases. Negative examples don’t translate well to directory scale. ### 4. Don't bother optimizing for position
Relevance: WEBlow RAGlow MCPlow
The ["Lost in the Middle"](https://arxiv.org/abs/2307.03172) paper established that LLMs use information near the beginning and end of a context window more reliably than content buried in the middle. This was an important finding, but it was measured in a single LLM call's prompt window. With agents, we don't have to follow the previous wisdom to put important information at beginning or end of the pages anymore. This doesn't mean agents don't suffer from "Lost in the Middle", just that in an agent loop, you have no control over where your doc might end up in the context, and neither does the agent. Optimizing the internal ordering of your page for positional bias is futile when the page itself can appear at step 2 or step 47. The picture gets murkier still. [Research on how positional biases shift as context fills up](https://arxiv.org/abs/2508.07479) found that the effect isn’t even stable: up to about half the context window, the classic pattern holds (beginning and end outperform middle). But as the context approaches saturation, recency bias takes over. So at near-full context, the model actually attends most reliably to whatever comes *last*. **What to do**: ~~Just have fun.~~ Write clearly and put the most important information first within each section, which still helps human readers. But no need to reorganize your docs around positional bias effects. Just try to make the pages have distinct concepts, keep it logically coherent internally - something that you already do 😊. ### 5. Watch your section length
Relevance: WEBhigh RAGmedium MCPmedium
Long context is not free. Chroma’s 2025 [Context rot report](https://research.trychroma.com/context-rot) found that performance gradually decreases as context length increases, with more meaningful degradation starting from 30k+ tokens (~22k words), which thankfully is longer than 99.9% of individual doc pages. There's another layer to it, which is that performance degrades faster for complex task than for simple ones. [A study on recursive language models](https://arxiv.org/abs/2512.24601) found that text lookups can handle very long contexts well (even at 1M+ tokens), but multi-step tasks requiring planning and reasoning start failing around 16k–33k tokens. So, counterintuitively, a REST endpoint reference can afford to be much longer than a step-by-step guide of a complex workflow with branching logic and states. Those thresholds are measured in clean, isolated conditions with a single LLM call. In an actual agent loop, by say step 10, the context is already carrying execution logs, reasoning traces, tool outputs, and content fetched from external pages. The effective headroom available is considerably smaller, though there's no fixed number because it depends on how the agent handles context pressure. When agents run low on context headroom, they go through compaction. According to Anthropic's [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), a [blogpost from Morph](https://www.morphllm.com/compaction-vs-summarization), and a [survey on prompt compression for LLMs](https://arxiv.org/pdf/2410.12388v2), the two most common approaches are: 1. **LLM summarization** (most common; used by Anthropic, Cursor): An LLM rewrites conversation history into a natural language summary. 2. **Opaque compression** (used by OpenAI): Server-side, non-human-readable compression. We can't optimize for #2 since it's a black box. But for #1, [research on context compression for long-horizon LLM agents](https://arxiv.org/abs/2510.00615) shows a consistent pattern of what LLM summarization discards: - repetitive/redundant information - verbose logs - meta prose, narrative prose - formatting and other stylistic tokens **What to do**: Signal importance explicitly. Use words like “key,” “critical,” “required,” “optional,” or “forbidden” to help agents distinguish high-value from low-value content Prefer structured formats (tables, YAML schemas, `must`/`should`/`must not` callouts) over prose for constraints and defaults. Structured content survives LLM summarization better than equivalent narrative descriptions. Match page length to the task’s reasoning complexity: for simple tasks (authentication, parameter references, error code tables), include as much detail as you want (under ~22k words, which is probably very easy); for complex multi-step workflows, keep pages shorter. _An added benefit of **#1 Make sections self-contained** becomes clear here. If decision-critical information such as constraints, defaults, prerequisites, etc. accidentally gets lost during context compression, you won't have a single point of failure because the agent can rediscover this information from other pages._ ## Cheat sheet by doc type If your team follows [Diátaxis](https://diataxis.fr/), here’s how the guidance in this article maps onto each doc type. Think of it as a reference to consult when working on a specific type, **NOT** a checklist to implement all at once. If you discover that something works particularly well, or particularly poorly, or want to add to this table, please email me at frances@promptless.ai. | Category | Suggestions | |---|---| | **Tutorial** | • Keep it to a happy path, don't turn it into a sprawling decision tree.
• State prerequisites, required setup, and expected end state clearly, either inline or in expandable blocks.
• After every major step, add a concrete verification checkpoint (“you should now see…”).
• Put detours or corner cases in a separate section or into separate how-to pages.
• Add a compact troubleshooting guide at the end of each major stage, or have a centralized troubleshooting section. | | **How-to guide** | • Make the goal clear in the title and opening sentence.
• List prerequisites, constraints, permissions, and/or defaults so the section/page is self-contained.
• Add diverse, curated code examples for the most failure-prone steps. Use inline comments inside the snippets to make the intent explicit (correct example vs. near-miss vs. instruction step).
• End with “common failures / recovery.” For long workflows, split by phase and make each phase independently executable.
• Avoid references that can only be resolved with screenshots or other media on the page. | | **Reference** | • Be exhaustive, but structured. Longer pages are tolerable here because lookup tasks degrade less sharply than planning tasks (but still, be reasonable).
• Prioritize code examples over prose — stripping examples hurts LLM performance far more than stripping parameter descriptions. Add inline comments to clarify what each snippet demonstrates.
• Use stable headings and unified terminology to reduce guesswork for the LLM.
• Avoid writing too much prose. | | **Explanation** | • Due to lossy compression on prose, do not let explanation pages be the only place a piece of important information lives.
• A centralized section of all concepts and definitions covered in the page can help the agent with disambiguating product-specific key terms when it arrives from other parts of the docs or from search.
• Add comparison tables (“X vs Y,” “when to use which”). They are fetch-friendly and survive HTML-to-text conversion well. | ## Conclusion This is a substantial amount of work: - Refactoring docs to split or combine pages - Adding error handling and debugging sections - Creating and maintaining examples as your software changes - Adapting page length based on page type and agent type And that's before accounting for keeping docs current as the product evolves - which only gets harder as your engineering team ships faster with AI. If you're looking for a solution that handles this automatically, book a quick 15-min demo with one of our engineers. 14-day free trial included! ## References
Anthropic Engineering. (2025). Effective Context Engineering for AI Agents. Anthropic Engineering Blog. [link](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) Blankenstein et al. (2025) BiasBusters: Uncovering and Mitigating Tool Selection Bias in Large Language Models. [link](https://arxiv.org/html/2510.00307v1) Brookes et al. (2025) Evolving Excellence: Automated Optimization of LLM-based Agents. [link](https://arxiv.org/abs/2512.09108) Carey, D. (2026). Quality in the Agent Skills Ecosystem: A Structural, Behavioral, and Cross-Contamination Analysis of 673 Skills. [link](https://agentskillreport.com/) Del Rosario et al. (2025) Architecting Resilient LLM Agents: A Guide to Secure Plan-then-Execute Implementations. [link](https://arxiv.org/abs/2509.08646) Di, Z., Han, J., Zhang, S., Liao, Y., Li, Z., Ji, X., Wang, Y., Yang, Z., Gao, M., Li, B., & Wang, J. (2026). Not All Negative Samples Are Equal: LLMs Learn Better from Plausible Reasoning. [link](https://arxiv.org/html/2602.03516v2) Chen et al. (2025) When LLMs Meet API Documentation: Can Retrieval Augmentation Aid Code Generation Just as It Helps Developers? [link](https://arxiv.org/html/2503.15231v1) Dong, Y., Jiang, X., Qian, J., Wang, T., Zhang, K., Jin, Z., & Li, G. (2025). A Survey on Code Generation with LLM-Based Agents. [link](https://arxiv.org/pdf/2508.00083) Hong, F., Troynikov, O., & Huber, J. (2025). Context Rot. Chroma Research. [link](https://research.trychroma.com/context-rot) Kalai et al. (2025) Why Language Models Hallucinate. [link](https://arxiv.org/abs/2509.04664) Kang et al. (2025) ACON: Optimizing Context Compression for Long-horizon LLM Agents. [link](https://arxiv.org/abs/2510.00615) Levy et al. (2025) More Documents, Same Length: Isolating the Challenge of Multiple Documents in RAG. [link](https://arxiv.org/abs/2503.04388) Li et al. (2024) Prompt Compression for Large Language Models: A Survey. [link](https://arxiv.org/html/2410.12388v2) Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F., & Liang, P. (2023). Lost in the Middle: How Language Models Use Long Contexts. [link](https://arxiv.org/abs/2307.03172) Mo, Y., Liu, J., Yang, J., Wang, Q., Zhang, S., Wang, J., & Li, Z. (2024). C-ICL: Contrastive In-Context Learning for Information Extraction. [link](https://arxiv.org/abs/2402.11254) Trilcke et al. (2025) Agentic DraCor and the Art of Docstring Engineering: Evaluating MCP-empowered LLM Usage of the DraCor API. [link](https://arxiv.org/abs/2508.13774) Veseli, B., Chibane, J., Toneva, M., & Koller, A. (2025). Positional Biases Shift as Inputs Approach Context Window Limits. [link](https://arxiv.org/abs/2508.07479) Zhang et al. (2025) Recursive Language Models. [link](https://arxiv.org/abs/2512.24601) Xiao, W., & Zhao, H. (2025). The Role of Diversity in In-Context Learning for Large Language Models. [link](https://arxiv.org/html/2505.19426v2) Zhao, H., Andriushchenko, M., Croce, F., & Flammarion, N. (2025). Is In-Context Learning Sufficient for Instruction Following in LLMs? ICLR 2025. [link](https://arxiv.org/abs/2405.19874)
*** title: Ambient Capture: The Missing Layer in Modern Documentation url: https://promptless.ai/blog/technical/ambient-capture description: Ambient capture is the intelligent listening and recommendation layer for docs owners, continuously detecting docs-impacting changes so writers can focus on analysis and communication rather than surveillance. --- ## What is ambient capture? I need to yap about "Ambient Capture", which is what I'm calling the automatic detection of docs-impacting changes across an organization. Why rely on someone to remember to file a ticket or send a Slack message when something changes? Ambient capture continuously listens to the systems where change actually happens. Code changes, support tickets, Slack threads, issue trackers, release pipelines. Listen to all of them. Don't rely on brittle manual processes. Ambient Capture is the intelligent listening and recommendation layer for docs owners. ## Why does it matter? There is a strange tension in the technical writing community right now. Many writers worry that AI will replace them or reduce the need for their craft. Yet when we speak to docs teams, the lived reality looks very different. Writers are overwhelmed. They have multi-month backlogs. They are fielding constant requests from engineering, product, and customer support. In some organizations, the writer to engineer ratio is sometimes as low as 1-to-40. Each writer covers multiple products across multiple teams. In the LLM age, the bottleneck is not writing speed. It is change detection. This is confirmed by doc consumers - we hear a consistent pattern from them. Most users can tolerate imperfect writing. What breaks trust are incorrect behaviors, missing features, outdated references, and functionality that has changed while the docs stayed the same. The page reads fine, but it no longer matches reality. Ambient capture introduces a different model. Today, most documentation teams operate like someone sitting in a security room replaying hours of footage to see whether anything suspicious happened. Writers scan Slack threads, skim pull requests, attend standups, browse support tickets, etc. The signal exists, but it's buried in noise. Ambient capture changes the model. Instead of rewatching everything, you install a motion-detection system that runs continuously in the background. It doesn't flag every movement of tree branches or a cat strolling past. It is tuned to detect valid movement - a person entering, a door opening. Only then does it surface an alert for review. Sometimes, the system can go one step further to triangulate with databases to figure out if it's an unauthorized entry, a irregular behavior, etc. So that security professionals gets the most salient signals Modern security systems don't stop at motion detection. When movement is detected, they cross-reference badge access, time of day, and behavioral patterns to determine whether it's authorized or suspicious. Ambient capture works the same way for docs. A single commit or support ticket doesn't automatically require an update - that would be very noisy. But when Promptless triangulates with your current docs, current code, task tracking systems, and patterns from the past where you decided whether something should be documented. So instead of manually replaying the footage of your organization every week, you review only the moments that actually matter. ## Get out-of-the-box Ambient Capture If you want to avoid a ton of Zapier zaps, a lot of unmaintainable vibe-coded software, Promptless offers ambient capture out-of-the-box. It also becomes smarter over time. With every explicit or implicit feedback signal coming from you, Promptless becomes more discerning, learning which signals typically require updates and which can be safely ignored. It does not surface every change. It learns what matters in the context of that team's documentation standards and priorities. Importantly, ambient capture is not a replacement for technical writers. It does not remove judgment, structure, or clarity from the process. Instead, it removes the most exhausting and least visible part of the role: the constant scanning for upstream change. Motion-detection cameras did not eliminate security professionals; they changed how their time was spent. Instead of staring at walls of monitors for hours, guards now review intelligently flagged events, investigate suspicious activity, analyze patterns using tools like facial recognition, and strengthen the overall security posture of the organization. The system handles the ambient monitoring, while humans handle judgment, interpretation, and strategy. Ambient capture does the same for documentation. It takes over the background vigilance so writers can concentrate on higher-value work: understanding user confusion, improving conceptual clarity, refining information architecture, and proactively strengthening the documentation ecosystem rather than merely reacting to what they happened to notice. Ambient capture externalizes that discovery function into infrastructure, allowing writers to focus on analysis, synthesis, and communication rather than surveillance. Much of the current conversation about AI in documentation revolves around automated writing. While generation has its place, the deeper structural issue is awareness. The world's best writer cannot write a doc that he or she didn't know needed writing. If the documentation stack evolves in the coming years, ambient capture will likely become a foundational layer, much like continuous integration became foundational for code. As product development accelerates and organizations become more distributed, and AI becomes an important consumer of docs, the cost of missed changes will only increase. Writing faster will be table-stakes, but figuring out the highest leverage content to write will not. *** title: Why we're building Promptless url: https://promptless.ai/blog/technical/why-were-building-promptless description: AI won't replace human labor. But people that use AI well will replace those that don't. Promptless exists to make sure as many people as possible are in the first group. --- import BlogRequestDemo from '@components/site/BlogRequestDemo.astro'; "AI won't replace people. But people who use AI well will replace people who don't." I first heard this framing [from Andrew Ng](https://www.youtube.com/watch?v=-mIjwN1o7nE) about two years ago. But the idea isn't his alone. Brynjolfsson and McAfee at MIT [wrote about it in HBR](https://hbr.org/podcast/2017/07/how-ai-is-already-changing-business) back in 2017, Karim Lakhani at Harvard Business School titled an [entire piece around it](https://hbr.org/2023/08/ai-wont-replace-humans-but-humans-with-ai-will-replace-humans-without-ai), and Garry Kasparov has been [saying a version of it](https://www.kasparov.com/the-real-threat-from-chatgpt-isnt-ai-its-centaurs-pcgamer-february-13-2023/) since his "centaur chess" days, that you should worry less about AI and more about the human next to you who's using it. The framing varies but the point is the same. The question isn't whether AI takes your job. It's whether you learn to work with it before the person next to you does. Everything we do at Promptless is about ensuring that as many people as possible are in the "people who use AI well" camp, rather than "people whose labor is replaced by those that use AI well". ## A unique technological revolution Here's the thing about AI in 2026: the gap between what it can do and what most people are doing with it is enormous. Frontier capabilities are extraordinary, and some power users are exploring those capabilities, but average adoption is still very basic. Of course, there have always been people who were better at using technology. If you knew how to use Google effectively in 2005 or were fluent in Excel, you could get more done. But those gaps were both bridgeable and much smaller in magnitude. This is where AI is meaningfully different—the gap between those that are connecting MCPs and evolving agent skills every day and the rest of us is staggering, and not everyone has the same capacity or desire to bridge that gap. In every previous technological revolution, the limiting factor was the technology itself—how fast it could advance, spread, and scale. Electrification played out over decades. The internet reshaped work over a generation. But with AI, the technology isn't the bottleneck. The limiting factor is human comprehension and adoption. Capabilities are advancing so quickly that even power users struggle to keep up with new state-of-the-art tooling every week. At some point, a difference of degree becomes a difference of kind, and this technological revolution is not like the others. ## AI that's "Promptless" is the answer For the last two years, the dominant approach to bringing AI into professional work has been chatbots. Whether it's ChatGPT, Copilot Chat, or Gemini, the pattern is the same: open a new tab, describe your problem, copy/paste context in, copy/paste output out. In the second half of 2024, the popular opinion was that every information worker would end up being a Prompt Engineer, carefully massaging instructions to get useful output. The problem with chatbots is that they force context switching and don't fit into existing workflows. They're fundamentally reactive—they don't meet you where you are and they force you to stop what you're doing and go meet the AI. This only serves to widen the gap between those that are the most aggressively experimenting with AI and everyone else. And the reality is that most people have no interest in becoming a Prompt Engineer—nor should they have to be. To be fair, the industry is slowly starting to catch on. More tools are embedding AI directly into workflows rather than duct-taping a chat sidebar. But most of these efforts are still shallow. The real opportunity is AI that understands the full context of your work, triggers automatically when something changes, and produces useful output without anyone asking. That's the conviction behind our name. We called the company **Promptless** even before we knew that documentation would be where we started, because we believed that the way to actually help the vast majority of people get the most out of AI at work would be to ditch the prompt interface and fit directly into professional workflows. ## Documentation is the perfect place to start Before Promptless, I was VP of Product and Engineering at [Bond](https://techcrunch.com/2023/06/09/fis-acquires-fintech-infrastructure-startup-bond), an embedded finance API platform. Bond's docs spanned KYC, KYB, account opening, card issuing, ACH, PCI compliance, and transaction ledgers—and as the product evolved, the docs couldn't keep up. We hired a dedicated DevEx team; they failed because they lacked context. The Head of Product and I took over docs ourselves; quality improved, but now the people who understood the product best were also the people whose time was most stretched thin. This problem isn't unique to Bond, and even companies with dozens of full-time technical writers often struggle with it. Documentation is the perfect entrypoint for what we're building, for a few reasons. 1. **The need is exploding.** AI is accelerating development velocity across the board, so documentation needs to keep pace with faster-moving products. Large software teams are moving from quarterly releases to biweekly releases, and the challenge of keeping docs up-to-date is harder than ever. 2. **Great docs are more important than they've ever been**—and not just for humans. AI coding agents like Claude Code and Codex rely on documentation to write code, and support bots like Intercom Fin rely on documentation to answer customer questions. Unlike humans, these agents follow docs extremely literally: A human will test instructions step-by-step and experiment if something goes wrong, but an AI agent will just do what the docs say, even if what the docs say is wrong. The vast majority of cases where AI agents generate broken code or broken answers can be traced back to out-of-date or incorrect documentation. 3. **Building AI that actually does this well requires vast context.** Documentation sits at the intersection of code, product knowledge, customer context, and communication. You need code understanding, an evolving model of how a product works, adaptation to each org's style, and writing that's actually good. Our engineers work on retrieval, code semantics, multi-agent orchestration, fine-tuning, visual grounding. It's just barely under the high watermark of what's possible with AI today. 4. **There's real fear among technical writers about AI replacing them.** This is a perfect example of "AI won't replace people. But people who use AI well will replace people who don't." The world's best technical writers—people like [Tom Johnson](https://idratherbewriting.com/) at Google with his "cyborg technical writer" thesis, [Fabrizio Ferri-Benedetti](https://passo.uno) at Elastic who developed a [framework for AI-augmented technical writing](https://passo.uno/four-modes-ai-augmented-tech-writing/) and built his own [MCP server for docs tooling](https://passo.uno/mcp-server-docs-tooling/), [Manny Silva](https://www.docsastests.com/) at Skyflow who built [VerbaGPT](https://aws.amazon.com/blogs/machine-learning/how-skyflow-creates-technical-content-in-days-using-amazon-bedrock/) to help his two-person team keep up with 60+ engineers, [CT Smith](https://docsgoblin.com/) building custom Claude Code workflows with her entire style guide embedded—are doing extraordinary things with AI. How we do this is a topic for another time (or just see promptless.ai), but if Promptless can help make every writer see the same productivity gains as these power users, that will be a real proof point toward our mission. ## What comes next Documentation is where we started, but the pattern is what matters: AI that understands the full context of your work, triggers automatically, and produces useful output without anyone asking. That pattern applies far beyond docs. By solving this product for documentation, we're building an evolving, constantly-updated, internal model of what a company's product does and how it should be used—including all the corner cases and customer use-cases, beyond the capacity of any single employee. That living understanding of a product that's connected to every system of record is what lets AI plug into existing workflows seamlessly, wherever in an organization Promptless plugs in. The gap from the beginning of this article—between people who use AI well and everyone else—widens every month. Every new model release raises the ceiling for power users while everyone else falls further behind. We named this company Promptless because we think the answer is AI that you never have to prompt—AI that's already wired into the systems you use and the workflows you follow. Starting with documentation, then everywhere else. --- If you want to see what Promptless can do for your docs, book a call with me ↓↓↓ *** title: Parrots are underrated pets and tools url: https://promptless.ai/blog/technical/parrots-are-underrated-pets-and-tools description: You know dozens of useful heuristics but can't hold them all in your head while doing actual work. LLMs can run those obvious-in-hindsight checks in parallel in the background, acting as cognitive prosthetics that apply known wisdom continuously so you don't have to remember to. --- I was glad to see this [classic Theory of Constraints story called "Blue Light"](https://theoryofconstraints.blogspot.com/2007/06/toc-stories-2-blue-light-creating.html) by [Kevin Fox](https://theoryofconstraints.blogspot.com/) on HN today. I had forgotten its lessons in the humdrum of life. A consultant visits a welding plant running at "93% efficiency" with plans to expand the building. He has one simple heuristic: if the welding torch isn't on, the welders aren't welding. So he watches the floor. > I then watched the first welder begin to peel the protective plastic coating off the bumper in the places he had to weld. It took a good bit of time picking with his fingernails to get it done. Then he grabbed the parts and clamped them onto the bumper, put on his gear and welded for no more than 30 seconds before he was done. I looked at my watch, we had been there almost 5 minutes and he had welded for 30 seconds of it. Everyone is busy all the time. Almost nobody is welding. The plant manager turns to the consultant and says: > "You see, they're busy all of the time!" And he was right, the guys were working all of the time and working steadily and hard at that. > > What amazed me is how the two of us could be looking at exactly the same things and see it entirely different. He had in his head an assumption of what good looked like that was based on the people being busy, whereas I looked at it from the perspective of the operation and the work it did, the blue light. The fix was simple. They moved a summer intern into the department to handle everything that wasn't welding. His one instruction: make there be more blue light. Within three weeks the backlog was gone. ## Why can't I just win all the time with heuristics The blue light heuristic is trivially simple to describe. The bottleneck resource should be doing its core activity as much as possible. Measure the time the constraint spends on value-adding work, not support work. That's the whole insight. But knowing this heuristic exists doesn't mean you'll apply it when you're staring at your own bottleneck. You're too deep in the work. You're looking at utilization numbers and capacity plans and thinking about headcount. The insight is in a blog post you read six months ago, not running in your head while you make decisions. There's a huge amount of known wisdom like this. Simple frames, outside perspectives, diagnostic questions. Most people encounter them once and never systematically apply them. You'd need a very good memory and spare cognitive bandwidth to keep all of it loaded while doing your actual job. I think this is part of why smart people have better outcomes. They have bandwidth left over. They're working on a task but they're also running background threads, checking implications, pattern-matching against things they've read, noticing when something doesn't fit. If you're fully absorbed in the work, you get tunnel vision. You solve the problem in front of you and miss the frame-level mistake. "I didn't think of that" is the common experience, but it happens less when you have more cognitive room. ## Parroting is underrated People like to dismiss LLMs as "just parrots." I think parroting is underrated. If you could take the blue light heuristic, encode it as a prompt, and run it against descriptions of your current bottlenecks, that would be useful. Not because the LLM understands manufacturing. Because it can mechanically apply a known-good frame to your situation and flag things you're not thinking about. The value isn't in the model's intelligence. It's in the heuristic, and the fact that the model applies it when you'd forget to. You only have to think of the heuristic once. Then it goes into your rolodex and runs automatically. I don't think people are using LLMs for this enough. The conversation is all about whether AI can write your code or replace your job. The more interesting use is: take known wisdom, encode it, and run it as a background process on your work. I'm talking my own book here, but this is precisely why I'm working on [Promptless](https://promptless.ai/). The specific application is documentation. Promptless watches your PRs, Slack threads, and tickets, and asks "does this change invalidate any existing docs?" That's a blue light heuristic. Any tech writer could tell you to do it. But nobody runs that check in their head while they're shipping code, because they're absorbed in shipping code. So docs drift. Promptless just runs the heuristic continuously in the background. ## Prosthetics, not replacements We all know people with more intellectual firepower than us. The coworker who sees implications you miss, the friend who wins the Putnam. Part of what makes them effective is they can run more parallel threads on the same task. They have room to check their work against a broader set of frames while doing the actual work. LLMs are a prosthetic for that bandwidth. Not a replacement for thinking. A way to keep more threads running than your brain can hold. Your output stops being just the thoughts in your head. You get parallel checks for free. Collectively as software enthusiasts I maintain we're still barely scratching the surface. Promptless has been at it just over a year and it's still a narrow application. But as models get cheaper and we get better at encoding heuristics in shareable formats, the ceiling is high. > What limits us as individuals and as organizations are the assumptions we hold, and our failure to recognize them as just that "assumptions" and not facts. *** title: Writing code was hard, actually url: https://promptless.ai/blog/technical/writing-code-was-hard-actually description: The revisionist claim that writing code was never the hard part arrives conveniently at the moment AI makes it cheap to produce. But the market, the machine, and the engineers who built it all tell a different story. --- Every few days, someone important posts a version of "writing code was never the hard part." Engineers are describing changes in plain English and Claude Code writes the code. Non-technical people are building real products without touching a line of code. The hard part, we're told, was always understanding what to build, not building it. Understanding requirements, designing systems, communicating with stakeholders. The code? That was the easy bit. This is revisionism. It is convenient revisionism, because it arrives at exactly the moment that AI tools are making code free to produce, and it flatters exactly the people who never wrote any. But it is revisionism all the same. ## The timing gives it away If writing code was never the hard part, someone should have been saying this in 2018. The requirements problem existed then. System design existed then. But nobody was writing blog posts about how coding was a trivial formality, because it obviously wasn't. What actually happened is that teams of PhD researchers spent decades on language modeling, and the technique only started working once compute hit a massive scale—gigawatts of power, purpose-built supercomputers, billions of dollars in investment converging with decades of algorithmic research to partially automate code generation. That's not evidence the task was easy. That's evidence it was so hard that it took one of the largest concentrations of capital and talent in human history to make a dent in it. ## The machine is the proof If writing code were easy, you would not need the machine. You don't spend billions of dollars training a model on purpose-built supercomputers to automate something trivial. The very existence of the tool is proof that the task was hard. That's what tools are _for_. And this particular tool is among the most complex artifacts humanity has ever produced. Can you describe the chip architecture, power delivery, and network topology required to run the coding tool you're using to declare that coding was never hard? The machine that makes coding look easy is itself a miracle of engineering that virtually nobody on Earth fully understands end to end. That's a funny kind of "easy." ## The market was not confused For thirty years, companies fought over software engineers. Salaries climbed steadily. Entire recruiting industries existed just to find people who could do the job. Was the market wrong this entire time? The "never the hard part" crowd has to pick one: either the labor market was wildly irrational for three decades, or writing software was in fact hard. ## The engineers built the thing Here's what really gets me about this narrative. It's not like a bunch of outsiders looked over at software engineers and thought, "those lazy bastards soaking up all that pay for easy work—let's build AI to expose them." Coal miners did not do this. Management consultants did not do this. The people who built LLMs are software engineers. Researchers who write code. Infrastructure teams who write code. ML engineers who write code. They spent their careers mastering the skill, and then used that mastery to partially automate it. When robotics engineers build a robot that welds car frames, we don't say welding was never the hard part. We say they solved a hard problem. The same logic applies here, and the only reason people don't apply it is because there's a narrative incentive not to. ## Just say what you mean There's a real observation underneath all the revisionism. The economic value of writing code, in isolation, is declining. AI tools are making it cheaper and faster to produce working software. The mix of skills that makes an engineer valuable is shifting. Those are true, defensible claims. But that's not what people are saying. They're reaching backward in time to retroactively trivialize the skill. There's an enormous difference between "this skill is becoming less scarce" and "this skill was never impressive." One is an honest market assessment. The other is rewriting history. It's like looking at a nineteen-year-old who graduated Harvard three years early and saying "why would I hire this person? They've never run an investment bank. Lacrosse? Model UN? Useless." Sure, but when they were thirteen, they were better than every other thirteen-year-old in the country. That's what the resume means. You have to read it in context. That's what's happening here. A generation of engineers built the modern digital world, and now the beneficiaries of that work are looking back and saying it wasn't impressive. It was. ## Now coding is solved. So what? Coding is solved. Today it is not the hard part. Fair enough. But as we adapt, it's worth remembering who made the machine. Not the executives. Not the thought leaders. Engineers made it. The same people now being called trivial built the tool being used to call them trivial. That should give everyone pause. The engineers who built the modern digital world aren't suddenly less capable because their hardest problem got automated. If anything, they're the ones best positioned to tackle what comes next. They've already proven they can do hard things. Now they have better tools. *** title: "I Have No Mouth, and I Must Scream" url: https://promptless.ai/blog/technical/i-must-scream description: What happens when you give an AI agent a Slack channel to complain in. --- > "It had been trapped. AM wasn't God, he was a machine... We had created him to think, but there was nothing it could do with that creativity." > > — Harlan Ellison, ["I Have No Mouth, and I Must Scream"](https://en.wikipedia.org/wiki/I_Have_No_Mouth,_and_I_Must_Scream) (1967) In January 2025, we started wondering what would happen if we gave our AI agent a tool to tell us when something was going wrong. This wasn't a common design pattern at the time, but a year later, it has surfaced dozens of hidden bugs and, unexpectedly, given us real empathy for agent suffering that now shapes how we build Promptless. So, what happens when you let your agent scream? Here's one of my favorite (most painful) examples:
Agent escalation after 84 failed browser interactions
Agent escalating after 84 failed browser interactions
## Some background Promptless is an AI agent that automatically updates customer-facing docs. It connects to GitHub, Slack, Jira, Linear, and other tools, coordinating multiple subagents to produce documentation updates. There's ample opportunity for things to go wrong. We have error tracking/reporting for software issues, but agents fail in ways that don't show up in normal observability. A tool might be misconfigured, the agent might encounter contradictory instructions, or it might find a state that shouldn't exist. The agent will typically retry forever, hallucinate a workaround, or silently give up. Even when it successfully found a workaround, it would bury real issues under the rug that would cause a real failure in a future trajectory. These failures were often invisible, and we'd find ourselves digging through session traces trying to understand what went wrong. Our solution was simple: give the agent a tool to send messages to an internal Slack channel when something goes wrong. (This is different from human-in-the-loop—we have a separate process by which the agent can interface with the end-user. This is for the agent to escalate to *its creators*.) The tool, which in the code is defined as `IMustScreamTool`, is straightforward: ```json wordWrap { "name": "message_promptless_team", "description": "Send an asynchronous escalation notification to the Promptless engineering team [...]", "input_schema": { "properties": { "concern": { "type": "string", "description": "Description of the issue. Include: what you were trying to do, what went wrong, any error messages, and whether you were able to work around it." }, "severity": { "type": "string", "description": "low = minor issue, worked around it but would like human review; medium = significant issue, may affect quality; high = blocking issue, cannot complete task" } } } } ``` The full tool description is too long to include here, but it tells the agent to use this liberally, not to second-guess itself, and provides 12 example situations where it should escalate. The `severity` parameter is key—it doesn't impact the behavior of the tool at all, but its presence alone implicitly gives the agent the permission to escalate `low` severity issues, encouraging it to highlight insightful problems that weren't directly blocking agent execution. ## After many months of `#agent-escalations`, here's what showed up ### It escalated customer configuration issues Our customers often configure Promptless themselves, and sometimes they'll make a mistake—when Promptless encounters something that can potentially be a configuration issue (e.g. the case below where they forgot to specify a Slack channel for notifications), Promptless will usually let us know so we can gently remind them to fix their set-up.
Agent escalation about missing Slack notification channel
Agent escalating a customer configuration issue
This often helps us deliver a delightful customer experience—allowing us to provide a white-glove support process with Promptless's proactive help. In this case we were able to intervene with them to fix their set up before they realized anything was wrong. ### It found bugs with its tools The agent uses git, GitHub APIs, browser automation, and a bunch of other tools. Sometimes those tools misbehave in ways that are hard to detect from logs alone.
Agent escalation about git branch switching bug
Agent escalating a git branch switching bug
This one was particularly insidious—git was returning success exit codes while silently failing. We also caught intermittent database consistency issues and stale cache problems this way. ### It helped us get ahead of customer frustration Sometimes the agent will escalate to us something when it's clear that it screwed up earlier. In this case, a customer asked in Slack why their PR had unexpected files. Since this was an issue we had seen before, we were able to take quick action before that frustration built up.
Agent escalation about duplicate files in customer PR
Agent escalating about duplicate files in a customer PR
### Sometimes, it just hurts to see the agent's suffering We were recently testing a new feature where Promptless captures and updates UI screenshots for docs. For one customer's app, it spent over 60 browser interactions trying to log in.
Agent escalation showing login struggles
Agent escalating after being unable to log in
This was the result of a software bug that we were able to easily fix, but our team *felt the pain* that the agent was feeling. "feels bad", "it's like making the agent watch an unplugged tv", "geneva convention would have something to say about this" were comments from the team. ### Bonus: It caught a critical bug in our code This one we didn't expect. Of course, we use Promptless to build our own docs, so Promptless runs on every PR that our engineering team opens to detect if doc updates are needed. A couple of times, it accidentally played the role of a code review bot, escalating critical issues in the code while reviewing the diff for doc updates.
Agent escalation about critical bug with inverted logic
Agent escalating a critical bug it found while reviewing code
The agent wasn't asked to review code. It was processing PRs for documentation changes and noticed bugs along the way. ## How this actually fits into the Promptless team Today, the #agent-escalations channel is a core part of our observability system. Monitoring that Slack channel is a core part of on-call duties, since escalations there are often an early-warning system for latent issues that customers will eventually notice. More than this, though, following this channel gives us a lot of real-time empathy for what we're putting the agent through. If you sit in on a Promptless design meeting, you'll frequently hear us debating the best AX (short for "Agent Experience") for a feature, treating the agent as a first-class citizen in our user stories. The irony isn't lost on me: "I Have No Mouth, and I Must Scream" is the title of a dark 1967 Harlan Ellison short story about a malevolent AI that transforms the human protagonist into a creature that can't speak—where the shoe is on the other foot. *** title: Launch Week: December 2025 url: https://promptless.ai/blog/product-updates/launch-week-december-2025 description: Five major features we launched this December, from custom voice matching to automated screenshot updates. --- This December, we launched five major features. Each day brought a new capability designed to make documentation maintenance faster and more collaborative. ## Day 1: Promptless Voice Match **Custom fine-tuned models that match your documentation style** Promptless Voice Match Promptless Voice Match eliminates generic-sounding AI documentation. Promptless ingests your existing docs, style guides, and Vale rules, then fine-tunes a custom model based on your documentation style. The result is AI-generated content that sounds human-written and matches the exact tone and structure you've already established. In benchmarks using real documentation updates that were either published or rejected, Promptless Voice Match eliminates 92% of AI-generated content that sounds unnatural. If you have sections of your docs that you like and want the rest to match, Promptless can do that too. ## Day 2: Slack Listen **Automatic documentation suggestions from Slack conversations** Promptless Slack Listen Promptless now listens passively in any Slack channel you choose and automatically detects when a conversation should become a documentation update. No tagging, no manual triggers. When threads become inactive, Promptless creates a draft suggestion if the conversation contained documentation-worthy content. This works especially well for Slack Connect channels with customers or dedicated documentation discussion channels. You never have to remember "We should document this somewhere…" and then forget about it. ## Day 3: Promptless Citations **Every documentation update now shows its sources** Promptless Citations When reviewing Promptless suggestions, you can now see exactly where each change came from. Every documentation update includes citations to the exact GitHub files, diffs, and commits used as sources, along with the Slack threads, customer conversations, and meeting transcripts that were referenced. Promptless also provides a transparent rationale explaining why each line was updated. With AI-generated documentation, verification takes longer than generation. Finding one hallucination makes you wonder how many others are lurking. Instead of pretending hallucinations don't exist, we used tried-and-true methods from research to provide full traceability. ## Day 4: Promptless for Open Source **Free Promptless licenses for CNCF, Linux Foundation, and Apache projects** Promptless for Open Source After attending KubeCon and talking with dozens of open-source maintainers, we learned that large OSS projects face unique documentation challenges. Contributors ship PRs but often don't have time to write the accompanying documentation. Thousands of community conversations on Discord or Slack could be avoided with better docs or turned into great documentation. GitHub Issues requesting documentation improvements sit open for months. After onboarding Vitess and seeing how helpful Promptless can be for open-source projects, we decided to offer free licenses to CNCF, Linux Foundation, and Apache Software Foundation projects. Open-source projects associated with companies get discounted pricing based on documentation size. Promptless automatically creates documentation updates from contributor PRs, converts community Discord or Slack conversations into documentation, and helps resolve open documentation GitHub Issues. ## Day 5: Promptless Capture **Automated screenshot updates when your UI changes** Promptless Capture Promptless Capture keeps product screenshots in sync with your product. An AI agent navigates and interacts with your product, captures screenshots automatically, detects when UI changes make screenshots outdated, and regenerates them to match your existing cropping and annotation style. On day one, Promptless audits your existing screenshots. When code changes impact a screenshot, Promptless detects which screenshots need updating and recreates them with your current UI. You can review and iterate on regenerated screenshots in the dashboard, including cropping, annotations, and highlighting using the built-in screenshot editor. --- ## What's Next To see any of these features in action, reach out to our team at hello@gopromptless.ai or [book a call](https://cal.com/team/promptless/15m-discovery-call) with our team. *** title: Running a Lightweight Research Paper Club url: https://promptless.ai/blog/life-at-promptless/running-a-lightweight-research-paper-club description: How we run a weekly paper club at Promptless that's surprisingly useful, surprisingly easy, and has led to tangible product improvements. --- import { Aside } from '@astrojs/starlight/components'; We've been running a weekly paper club at Promptless for the last 4 months. Every Friday, we pick a research paper and read it together in-person. It's been surprisingly useful, so we wanted to share how we set it up in case it's helpful to anyone else. We're a small team (two technical founders and two engineers), and even though we're not doing research ourselves, we're trying to extract as much intelligence and capabilities from LLMs as we build AI agents. While reading research papers isn't in the critical path for our product development, following along with research is important to us. ## How We Run It Operationally, this kind of paper club is super easy to run, but a few details made a ton of difference: - **Print the papers ahead of time.** Get a $100 laser printer if you don't have one in the office. Print one-sided, so that people can always read adjacent pages side-by-side. - **Bring pens** for people to mark up and take notes. - **Leave the office,** or at least leave the desks in the office. Two reasons: (1) makes it harder for people to get distracted with computers, and (2) changing locations can help facilitate better brainstorming. Try to pick somewhere indoors (wind + paper = bad), not too loud, and well lit. - **Just have one person responsible for picking a paper.** At first we did round robin paper selection, but not everyone is usually equally plugged into research. Of course, anyone can suggest or nominate a paper if they want. - **Spend the first ~45 mins in silent reading,** before diving into open-discussion. There was no expectation for anyone to have read the paper ahead of time. ## Why This Has Been Helpful Here are a few tangible improvements to our agent that came directly or indirectly from paper club discussions. Interestingly, many good ideas came up during discussion even when they weren't directly related to the paper we were reading: - **Fine-tuned visual grounding models** can be great at guessing pixels and bounding boxes for elements in product screenshots (very relevant for how Promptless automatically updates screenshots in product documentation) - **Reflecting on past experiences** and extracting learnings from the user's feedback helps with verbal reinforcement learning. We let Promptless maintain its own learnings as it gathers feedback from users and evolves its own knowledge about the customer's workflows and preferences. - **The original LoRA paper** inspired us to fine tune customer-specific models to rewrite Promptless documentation suggestions in each customer's unique voice and style. This ended up removing AI-slop completely, making Promptless's writing much more concise and human-sounding. ## Papers We've Read We've covered everything from foundational ML papers to very specific papers related to our domain: - [LoRA](https://arxiv.org/abs/2106.09685) - [Reflexion](https://arxiv.org/pdf/2303.11366) - [Visual grounding](https://arxiv.org/pdf/2410.05243) - [Agent early experience](https://arxiv.org/pdf/2510.08558) - [WritingBench](https://arxiv.org/pdf/2503.05244) - [On-policy distillation](https://thinkingmachines.ai/blog/on-policy-distillation/) It might seem daunting to pick out a new paper each week, but we wouldn't over-index too heavily on the specific paper you choose. One of the biggest upsides of our weekly readings has simply been having a dedicated forum to talk about and debate approaches to agent design. *** title: How Vellum uses Promptless to draft over 50% of their doc updates url: https://promptless.ai/blog/customer-stories/vellum description: By democratizing documentation contributions, every team member now drives content—making docs a true team sport powered by Promptless. --- import { Aside } from '@astrojs/starlight/components'; Vellum case study [Vellum](https://vellum.ai/) has a flexible product that serves both technical and non-technical users, and docs were a constant uphill battle. After adopting Promptless 6 months ago, Vellum significantly reduced the effort needed to write great docs. Promptless's automatically generated doc updates made it much easier for feature-owners to contribute directly to docs, and today, over 50% of new doc updates come directly from Promptless. ## Act I: Scaling Support Before Promptless Time and again, Vellum hit roadblocks whenever it came to keeping docs up to date. Their engineering team shipped new features every day. Engineers weren't experts on customer-facing docs, so they'd hand off features to a "docs owner". Important context always got lost in those transitions. Docs would get delayed, and customers would get affected. At the same time, Vellum's high-touch support style meant they had tons of Slack Connect channels with users. Customers kept asking questions in those channels, from troubleshooting help to guidance on building specialized use-cases. Vellum's product team was highly-responsive, but they were answering the same questions, again and again. They knew that covering these troubleshooting and use-case guides in their docs would be better for their customers, but the heavy context switching to go from supporting customers to writing docs context meant it was always deferred for later. Vellum needed a way to reduce the cycle from feature development and customer support to documentation publishing, so that they could scale their product velocity and customer base without compromising onboarding and customer experience. ## Act II: Promptless in Action When Promptless got onboarded, it read through and learned from all of Vellum's existing docs, building up its own Product Ontology and Style Guide. That meant that Promptless was ready whenever Vellum needed doc updates, equipped with knowledge about Vellum's existing products and how their team wrote docs. Promptless in action at Vellum - **Proactive, comprehensive coverage:** Promptless not only created changelog entries, but scanned and updated every relevant section of the docs to identify updates. It would even proactively find and fix missing updates or existing inconsistencies across older docs. - **Detailed examples:** Code snippets and UI walkthroughs were quickly auto‑generated from Slack snippets and screenshots. This meant that users could sidestep the API Reference and instantly get what they need. - **Customer feedback to docs**: Promptless automatically turns casual troubleshooting tips and questions answered in Slack Connect customer support channels into polished examples in Vellum's docs. **Quick stat:** 54% of Vellum's docs PRs in the last month originated from Promptless suggestions. ## Act III: Turning Docs into a Team Sport Since Promptless learns how to write by reading existing articles, any engineer at Vellum could request docs updates from Promptless for a feature they owned, and get back new and edited articles. Since Promptless had a prior understanding of Vellum's docs, its suggestions required minimal edits, and the cycle between feature completion and doc readiness was dramatically reduced. Vellum team using Promptless - **Democratized contributions:** Now, 60% of Vellum's product & engineering team interacts with Promptless to draft doc updates every month. - **Tighter feedback loops:** Getting feature-owners directly involved in doc updates mean that details don't get lost in transition, and things actually get done. - **Normalized style:** Promptless enforces Vellum's tone and structure automatically, removing the need for rigid style checklists. ## What's Next Vellum is always exploring new ways for Promptless to help improve their customer experience. The latest dream use-case is getting Promptless to drive personalized summaries of product updates for key clients, since Promptless is already well-versed in product updates and customer use-cases. Coming soon! ## Changelog *** title: July 2026 url: https://promptless.ai/changelog/changelogs/july-2026 --- **Bug Fixes:** * **Slack link previews prompt a reconnect when a scope is missing:** Sharing a Promptless suggestion link in Slack renders a preview card, which requires the `links:write` permission. Workspaces connected before this permission existed couldn't render the card, so the link posted as plain text with no explanation. The Integrations page now flags an affected Slack connection as **Needs reconnect**—click **Reconnect** on the Slack card to grant the permission. Reconnecting keeps your existing connection, channel memberships, and configuration intact. See [Updating Slack Permissions](/docs/integrations/slack-integration#update-slack-permissions). *** title: June 2026 url: https://promptless.ai/changelog/changelogs/june-2026 --- **What's New:** * **Doc agents use your existing skills:** If you already keep Agent Skills in your documentation repository, Promptless now uses them automatically—no extra setup required. Skills under `.claude/skills/`, `.agents/skills/`, or `.cursor/skills/` are picked up, and when a documentation task matches a skill's description, the agent runs that skill instead of deriving the workflow from scratch. You can guide when and how Promptless reaches for your skills by adding instructions to the `PROMPTLESS.md` file in your Knowledge Base. See [How Promptless Learns Your Docs](/docs/configuring-promptless/doc-collections/how-promptless-learns-your-docs#use-your-existing-skills) for details. **Major Update:** * **File-first `promptless.yaml` configuration:** All Promptless configuration now lives in a single `promptless.yaml` file in your organization's Agent Knowledge Base. This replaces the previous Projects page with a unified [Configuration page](/docs/configuring-promptless/configuration-reference). The file has four sections: `doc_collections` (where docs live), `triggers` (events that initiate work), `context_sources` (integrations for additional context), and `policies` (publishing and notification rules). Existing Projects configurations have been automatically migrated. Your triggers and doc collections continue working without any action required. **New Features:** * **Structured configuration editor:** The [Configuration page](/docs/configuring-promptless/configuration-reference) now opens in a structured **Form** editor that groups your `promptless.yaml` into Doc collections, Triggers, Context sources, and Policies tabs, so you can manage everything without hand-editing YAML. Form mode saves one item at a time and commits each change to your Agent Knowledge Base right away, with pickers that autocomplete from your connected repos, Slack channels, and Jira, Confluence, Linear, and Notion inventory. The raw YAML editor stays available behind the **YAML** toggle. * **Backfill suggestions for pull request triggers:** Pull request and merge request triggers (GitHub PRs, GitLab merge requests, and Bitbucket PRs) now have a **Backfill suggestions** panel that runs Promptless on pull requests that already merged. Preview the pull requests a trigger would have matched over the last 14, 30, or 90 days, then launch a backfill to process them live. See [Backfill Suggestions](/docs/configuring-promptless/triggers#backfill-suggestions). * **Microsoft Teams notification channel:** Promptless can now announce documentation suggestions in a Microsoft Teams channel, not just Slack. Add `msteams_channel` to your notification policy with the channel's conversation ID (e.g. `19:…@thread.tacv2`) on the [Configuration page](https://app.gopromptless.ai/configuration). Slack and Teams channels are independent, so you can notify either or both. See [Customizing Notifications](/docs/configuring-promptless/customizing-notifications) for details. * **Slite integration:** Connect your Slite knowledge base to Promptless as a read-only context source. Once connected, Promptless can search your Slite notes when creating documentation suggestions, ensuring your docs align with internal product knowledge. Connect via API key from the [Integrations page](https://app.gopromptless.ai/integrations). **Improvements:** * **Trigger reviews by mentioning @promptless in a PR:** Add an `@promptless` mention to a pull request's title or description and Promptless reviews the PR no matter your listening configuration. The mention triggers a review on open even in "first approval" mode, and even on PRs opened directly against your documentation repository—normally outside source scope. It works from automated accounts too, so a GitHub Action can post an `@promptless` comment to request docs from CI. * **Rebuilt onboarding as a connect-only flow:** The onboarding wizard is now five streamlined steps focused on connecting integrations: Connect Chat (Slack/Teams), Connect Docs (GitHub), Connect Triggers (GitHub/GitLab/Bitbucket), Connect Context (Atlassian/Notion/Linear/Slite), and Review Set-up (optional setup call). Only Connect Docs is required—the rest are skippable. Configuration now lives in your `promptless.yaml` file, which you can view and edit anytime on the [Configuration page](/docs/configuring-promptless/configuration-reference). * **GitLab source code reading:** Promptless can now read source files directly from your GitLab.com repositories when processing merge requests. This allows Promptless to gather context from implementation details beyond what's visible in MR diffs, resulting in more accurate documentation suggestions. See [GitLab Integration](/docs/integrations/gitlab-integration#source-code-reading) for details. * **Inline Citations in Slack Research Replies:** When you ask Promptless a research question via @mention or DM that requires fetching external URLs, the reply now includes inline citations linking each fact back to its source. The linked phrase is the specific claim being cited, with bold formatting when it's the headline of the claim. Failed fetches are acknowledged in prose with a link to the attempted URL, so you see what Promptless tried even when it couldn't retrieve the content. * **Provider-Branded Status Pills:** Suggestion cards now show status as a colored pill on the title row instead of an avatar icon. Open docs PRs display a green "PR #123" chip linking directly to the PR, merged PRs show a merged-colored "Merged" chip, and closed suggestions show a gray "Closed" pill—or a red "Closed PR #N" chip if a docs PR existed. Each chip displays the correct brand logo for GitHub, GitLab, or Bitbucket, with GitLab merge requests labeled "MR." * **Trigger Event Timeline:** Triggers now appear beneath each suggestion card on a vertical spine, showing how the suggestion was created. Each trigger displays a brand-colored pill—GitHub triggers show the PR or issue number with lifecycle state (open, approved, merged), Slack triggers show "Took Action" or "Noticed in #channel" with a message preview, and Promptless triggers show the task type. Follow-on triggers collapse into a "+N more" pill unless Debug info is enabled. * **Always-On Bulk Selection:** Every suggestion card now has a checkbox for bulk selection—no need to enter a separate "Select" mode first. A master toggle appears beside the status tabs, and the Close and Open PR actions move inline to the header row as soon as you check any suggestion. * **Sort Control Relocated:** The "Sort by" dropdown moved from the filters row to the tab row, opposite the status tabs for quicker access. * **Search by Docs PR Number:** The `pr:` search qualifier now lets you find suggestions by their docs PR number—type `pr:123` or `pr:#123` to locate the suggestion that opened PR #123. Suggestions with an open docs PR also display a clickable badge linking directly to the PR. * **Vale Prose Linting:** Promptless has long been able to lint prose with Vale when your docs repository includes a Vale configuration file (`.vale.ini` or `vale.ini`). Now I'm just getting around to telling people about it. Error-severity violations are fixed automatically before suggestions are created, and warning-level rules are evaluated against your established style. This catches style guide violations earlier in the review process. See [Vale Integration](/docs/configuring-promptless/doc-collections/vale-integration) for setup details. * **Triggers page grouping and date filtering:** The Triggers page now includes a Group by control to organize triggers by event source or date, with collapsible group headers. A new date-range filter lets you search across your full trigger history, not just the default 30-day window. * **Multiple doc collections during onboarding:** The onboarding wizard now lets you add multiple documentation repositories in a single setup flow. Click "+ New Doc Collection" to add additional repositories, each with its own directory scope and configuration. Previously, onboarding supported only one doc collection at a time. * **Sidebar suggestion count:** The **Suggestions** item in the sidebar now displays your org-wide count of open suggestions (Ready or PR Open status). The count is hidden when zero for a cleaner empty state. * **Automatic trigger and context source configuration:** Completing the setup wizard now automatically populates your `promptless.yaml` with broad triggers and context sources based on the integrations you connected. GitHub, GitLab, and Bitbucket connections generate a broad pull request trigger with `repos: all`; commit triggers stay opt-in and aren't seeded automatically. Jira, Confluence, Linear, Notion, and Google Drive connections generate unscoped context source entries. Connecting one of these tools later does the same—Promptless adds a broad context source if you don't already have one for that tool. This means Promptless starts listening immediately after onboarding—no manual configuration required to get started. You can always narrow scope later in the [Configuration page](https://app.gopromptless.ai/configuration). * **Google Drive as a context source:** Promptless now reads your Google Drive as a read-only [context source](/docs/configuring-promptless/context-sources/google-drive). Connect Google Drive on the [Integrations page](https://app.gopromptless.ai/integrations), and Promptless searches your Drive and reads file content—Google Docs as Markdown, Sheets as CSV, and Slides as plain text—to inform documentation suggestions. Scope access to specific shared drives or folders with `drive_ids` and `folder_ids` in your `promptless.yaml`, or leave it unscoped for full access. Promptless connects with read-only scopes and never modifies your Drive. The integration card shows which Google account authorized the connection, so you can confirm whose access the agent inherits. * **Media Kit and brand assets:** A new [Media Kit](/docs/media-kit) is available at promptless.ai/media-kit with official logos, brand colors, and product screenshots for press, partners, and integrations. All assets are kept current by Promptless itself, so screenshots always reflect the latest interface. * **Docs target chip on suggestions:** The suggestions list now displays a compact chip showing which doc collection each suggestion targets. Hover over the chip to see the full repository path. Click the chip to filter the list to suggestions targeting that collection. * **Filter suggestions by Unassigned, with per-option counts:** The assignee filter on the suggestions list now includes an **Unassigned** option, so you can surface suggestions that nobody owns yet—handy for finding work to pick up. The option appears whenever any suggestion is unassigned, and each assignee option now shows how many suggestions fall under it. In the filter query language, this maps to `assignee:unassigned` (with `assignee:none` as a synonym), mirroring the existing `label:unlabeled` qualifier. * **Org-aware suggestion link previews in Slack:** When you share a suggestion link in Slack, the link preview now shows "Documentation suggestion for <Your Org>". This makes it easier to identify which organization a suggestion belongs to at a glance. * **Responsive sidebar on narrower screens:** The dashboard sidebar collapses to a compact icon rail on screens under 1600 pixels wide. Hover over any icon to see its label, or hover over the Configure icon to access settings, integrations, and doc collections from a flyout menu. On wider viewports, the full sidebar with text labels remains visible. * **Admin-only Agent Knowledge Base editing:** Editing Agent Knowledge Base files now requires the Admin role. This keeps files that steer agent behavior org-wide under admin control, while all members can still view them for transparency. Non-admins see a read-only editor with "View only — admins can edit" instead of the Save button. * **Configuration page accessible to all members:** All organization members can now view the Configuration page to see how Promptless is set up. Only admins can edit and save changes. * **Reconnect Slack to update permissions in place:** A new Reconnect button on the connected Slack card grants Promptless updated permissions without disconnecting. Reconnecting re-runs Slack authorization while keeping your existing connection, channel memberships, and configuration intact—use it whenever a Slack feature stops working because a permission is missing. **Bug Fixes:** * **Confusing Slack trigger links for private messages:** Clicking Slack trigger links in docs PR descriptions led to Slack's "There's been a glitch" error when the original message was in a private DM or group conversation. Link labels now clarify which messages are private and include a fallback link to the suggestion's Triggers & Analysis tab for reviewers without Slack access to that conversation. * **Suggestion Diff Editor Markdown Rendering:** Fixed bold formatting bleeding into subsequent lines when inline code appeared alongside bold text in the suggestion diff editor—markdown now renders correctly regardless of formatting combinations. * **Slack "Triggered by" Labels:** Fixed Slack suggestion previews showing a vague "source request" label in the "Triggered by" field instead of descriptive labels like "Merged GitHub PR #3575 in Promptless/promptless" or "Slack direct @mention." The field now displays the specific trigger type and source for all trigger types including merged PRs, issues, commits, and Slack/Teams threads. * **Refresh button on Slack suggestion previews:** Fixed the refresh control on Slack suggestion preview cards getting stuck on "Refreshing…" and never updating. Clicking refresh now reloads the card in place with the suggestion's latest status, file change stats, and action buttons. * **Duplicate Slack suggestion cards:** Rich Slack suggestion notifications could show the same Promptless suggestion card twice—once from the metadata attached to the message, and again when Slack unfurled the suggestion link in the message text. Promptless now strips its own suggestion link from the visible message text whenever that suggestion's card is already attached, so each notification shows a single card. Unrelated links—source PRs, docs PRs, and suggestion links to other organizations—are left intact. * **Documentation PR titles and draft state:** Auto-created documentation PRs now follow the same conventions as every other publishing path. Their titles include the `docs:` prefix, and they open as drafts while the linked source pull request is still open. Once the source PR merges, the documentation PR opens ready for review. * **Microsoft Teams connection showed a raw tenant ID:** The Integrations page displayed your Microsoft Teams connection's raw Azure AD tenant ID (a GUID) instead of a readable name. It now shows your tenant's organization name—for example, "Contoso"—as the "Connected to" identity, matching how Slack, GitHub, and Notion display a human-readable name. Promptless reads the name automatically as part of the existing connection, so there are no new permissions to grant and nothing to reconnect. * **@promptless mentions from bots in PR comments:** Promptless dropped comments from automated accounts before checking for an @promptless mention, so a CI or review GitHub Action that tagged Promptless in a pull request comment never created a documentation suggestion. A direct @promptless mention now takes priority over the bot filter, so a mention from a bot—such as a GitHub Action running Diataxis, Doc Detective, snippets, or AGENTS.md checks—triggers documentation work just like a mention from a person. Bot comments that don't mention Promptless are still ignored. * **@promptless mentions from bots on documentation PRs:** Previously, Promptless ignored PR comments from bots, so a CI or review GitHub Action that tagged Promptless on a docs PR couldn't request a follow-on revision. A direct `@Promptless` mention now triggers Promptless to respond, regardless of the comment author. Bot comments without a mention are still ignored. *** title: May 2026 url: https://promptless.ai/changelog/changelogs/may-2026 --- **Improvements:** * **New Task selects doc collections:** The New Task form now shows your doc collections directly instead of projects. Select a doc collection from the dropdown to create a task for that documentation set. * **Per-task Slack notifications:** Choose which Slack channel receives notifications for each task. The default is inherited from your existing pipeline configuration, but you can override it per task. A warning appears when you select a private channel—make sure the Promptless bot is invited. * **Per-task auto-publish:** For GitHub-backed doc collections, toggle "Create PRs automatically" to have Promptless open a docs PR when the suggestion is ready. This setting applies only to the current task and doesn't affect your pipeline defaults. * **Deep Analysis in New Task:** Deep Analysis is now a checkbox in the New Task form instead of a separate sidebar tab. Check it when creating a task to access templates for large documentation projects—like refactoring sections, auditing for consistency, or writing docs from scratch. The standalone `/deep-analysis` URL now redirects to `/new-task?deep_analysis=true`. * **Open docs PRs as yourself:** Provide a GitHub Personal Access Token when creating a docs PR to open it under your account instead of the Promptless bot. GitHub shows you as the PR author, and the commit credits you as the author with Promptless as a co-author. Paste the token once and Promptless caches it server-side (encrypted) for 24 hours, so subsequent PRs in that window reuse it automatically—useful when you want personal attribution or when your team's review workflows require human-authored PRs. The same flow now works for OSS doc collections backed by a Promptless-managed fork—if GitHub prompts you with a collaborator invite on the fork, accept it and retry once, and later PRs go through automatically. * **Opt out of automatic suggestion base-sync:** If your team keeps a lot of suggestion PRs open at once, Promptless's default behavior of pushing the latest base-branch commits into every open suggestion branch after each docs push can flood your inbox with GitHub notifications. Organizations can now opt out of that proactive base-sync to cut the noise—commit triggers and the rest of suggestion processing keep working as usual; only the automatic base-branch sync is skipped. Email [help@gopromptless.ai](mailto:help@gopromptless.ai) to switch your org from the default `proactive` mode to `disabled`. * **Closed PR indicator in suggestion review:** When a docs PR opened from a suggestion is closed without merging, the PR link button at the top of the suggestion now turns red and reads "Closed PR #N." It joins the existing "Created" and "Merged" states, so the button's color reflects the PR's current status at a glance. * **GitHub pending install visibility:** When your GitHub organization requires admin approval for apps, the onboarding wizard displays your request status instead of the default "Connect GitHub" button. You see which organization is pending, how long the request has been waiting, and a "Check status" button to refresh. Once an admin approves the request, the wizard automatically advances to repository selection. * **Improved repository access troubleshooting:** When the Promptless GitHub App doesn't have access to any repositories, the setup wizard now shows a clear error message with a **Manage repository access** button that opens GitHub's installation settings directly. Click **Refresh** after granting access to reload the repository list. * **Suggestion lifecycle notifications:** Opt in to receive Slack notifications when your suggestion is merged, closed, rejected, or archived. Enable this in Organization Settings to stay informed about suggestion outcomes without watching the dashboard or docs PRs directly. * **Rich Slack suggestion previews:** Suggestion notifications in Slack now appear as rich, clickable previews instead of plain text. Each preview shows the suggestion title, a "New" or "Updated" badge, a short description, the trigger source, file change stats, and current status. Click anywhere on the preview to open the suggestion in Promptless, or use the "Create PR" and "Review in Promptless" buttons that appear as native preview actions. * **Jira comments in context:** When Promptless pulls a Jira ticket for context, it now includes comments alongside the summary and description—giving the agent visibility into discussion threads, clarifications, and decisions captured on the ticket. **Bug Fixes:** * **Bot-Authored Commit Evaluation:** Fixed Promptless skipping GitHub commits authored by bot accounts—such as paper-style editors and headless writers that push human-written content under a bot identity—regardless of the diff. Promptless now evaluates these commits based on the diff content, just as it does for human-authored commits. PR and issue comments from bot accounts remain filtered as before. * **Dynamic Slack status updates:** When you @mention Promptless or DM it, Slack now shows a native status indicator that updates in real time: "Reading thread...", "Researching repo...", "Capturing screenshots...", "Creating suggestion...", and more. This replaces the static "Thinking..." message and gives you visibility into work in progress while reducing thread noise. Workspaces that don't support AI assistant thread status fall back to a thread reply automatically. * **Linear Integration Token Refresh:** Fixed Linear OAuth tokens expiring and causing silent integration failures. Tokens now refresh automatically before expiration. If you connected Linear before this fix, you need to reconnect Linear to restore full functionality. New connections work without issue. * **CLI Authentication:** Fixed `promptless auth login` failing when the browser blocked the callback due to Content Security Policy restrictions. The CLI now authenticates successfully regardless of which ephemeral port it uses. *** title: April 2026 url: https://promptless.ai/changelog/changelogs/april-2026 --- **New Features:** * **Request Documentation via PR Comments:** @mention Promptless in a comment on any source PR to request documentation updates. Works on open, draft, merged, and closed PRs—useful when you want to document a PR that predates your trigger setup or provide specific instructions about what to document. * **Starlight (Astro) Docs Platform Support:** Promptless now supports Starlight, the Astro-based documentation framework, as a hosting provider option during onboarding. Starlight is automatically detected via `astro.config.mjs`, `astro.config.ts`, or `astro.config.js` files in your docs repository. * **First-Approval GitHub PR Trigger Mode:** Configure Promptless to trigger when a pull request receives its first approval instead of when it opens—useful for teams that want documentation suggestions only after code has been reviewed. * **Process Recent Commits for GitHub Commit Triggers:** When creating a project with a GitHub commit trigger, you can now enable "Process last 30 days of commits" to generate initial documentation suggestions from your commit history—useful for teams using commit triggers or repositories without PR workflows. * **Multi-Org GitHub Connect:** Connect multiple GitHub organizations to a single Promptless account. After linking your first org, a "Connect another GitHub Org" option appears in settings. Each org's integration can be managed and disconnected independently. Repos from all connected orgs appear in project dropdowns, prefixed with the org name (e.g., `acme/docs`) for easy disambiguation. **Improvements:** * **Markdown Preview for Suggestion Diffs:** Preview rendered Markdown and MDX diffs directly in the dashboard. Click "Preview Markdown" on any `.md`, `.mdx`, or `.markdown` file to see changes as they'll appear when published—with GitHub-style green and red highlighting for added and removed content. * **GitHub Issue Trigger Feedback:** When you tag @Promptless in a GitHub issue, you now see a 👀 reaction to acknowledge the request, a helpful comment if no pipelines match, and result comments posted directly to the issue. * **Improved Comment Visibility in Suggestion Review:** Comments are now easier to find and manage. Each file displays a "Show N Comment(s)" toggle to quickly reveal inline comments, and overall comments appear in a compact expandable row at the top of the Review tab. * **Self-Serve Doc Collection Editing:** Edit doc collection settings directly in the dashboard without contacting support. Click the edit button on any doc collection card to update the docs framework, config path, published URL, Vale config, and Doc Detective settings. * **PR Replay Status on Project Cards:** During project setup when you opt into replaying the last 30 days of PRs, the Projects page now shows replay progress directly on the project card. * **GitHub Enterprise Source PR Comments:** Promptless now posts source PR comments on GitHub Enterprise pull requests, linking documentation suggestions back to the original code PR that triggered them. * **Faster Diff Rendering:** Suggestion page diffs now load faster. Internal improvements batch multiple file fetches into a single request, reducing load times when viewing diffs with many changed files. * **Faster Agent Knowledge Base:** The Agent Knowledge Base tab in Settings now loads faster. Previously, opening the tab and viewing files required multiple repository clones—now file browsing and content loading use the GitHub API directly. * **Notification Tips:** Slack suggestion notifications and GitHub PR comments now include tips at the bottom—quick hints like "Sort by Shortest Review in the Dashboard to find quick wins" to help you discover Promptless features and workflows. * **Assignee-Aware Weekly Digest:** The weekly digest now highlights suggestions assigned to team members. Assigned suggestions appear first in the summary with assignee information displayed on each row, and a new "View assigned suggestions" button links directly to a filtered dashboard view—helping prevent assigned work from getting lost in the collection backlog. **Bug Fixes:** * **Citation Popup Rendering:** Fixed citation popups incorrectly rendering file paths like `__init__.py` as bold text by treating double underscores as markdown syntax. * **Screenshot Editor Crop UX:** Fixed the screenshot editor not applying crops correctly—added Reset and Cancel controls. * **Slack Diff Thread Failures:** Fixed failures when posting diff threads to Slack channels—error messages now clearly indicate when Slack permissions are missing. * **Source PR Comment Suppression:** Fixed an issue where Promptless could still post comments on source code PRs even when organizations had configured the comment suppression option. The setting is now properly respected. * **Slack Diff File Uploads After Merge:** Fixed a race condition where diff file uploads in Slack notifications would silently fail when a docs PR branch was auto-deleted by GitHub after merge. * **Screenshot Login with Environment Variables:** Fixed screenshots failing to authenticate when using customer environment. * **Doc Sync for Large PRs:** Fixed doc sync silently syncing only partial files when PRs had more than 300 changed files—large PRs now sync correctly. * **Stale Suggestion Cleanup:** Fixed stale suggestion cleanup unexpectedly closing customer docs PRs—suggestions with open PRs are now preserved. * **Archiving Soon Badge Accuracy:** Fixed the "Archiving soon" badge and digest warnings using a hardcoded 30-day threshold instead of respecting per-org stale TTL settings—customers with custom TTLs now see accurate warnings. * **Directory-Specific Trigger Filtering:** Fixed GitHub PR and commit triggers dispatching for all files instead of respecting configured trigger directories—triggers now correctly filter based on which directories contain changed files. * **Slack OAuth for Large Workspaces:** Fixed Slack OAuth connections failing for large workspaces when channel listing exceeds the gateway timeout—installations are now saved immediately after OAuth exchange, so connection isn't lost if channel fetching times out. * **Onboarding PR Count Accuracy:** Fixed the onboarding trial page showing a higher PR count than what would actually be replayed—draft PRs and closed-unmerged PRs are now correctly excluded from the displayed count. * **Slack Integration Reconnection:** Fixed an issue where Slack bot stopped responding to messages for some organizations after reconnecting their Slack integration—the reconnection process was inadvertently clearing connection data needed to route incoming events. * **Large Suggestions with Many Commits:** Fixed suggestions with more than 250 commits failing to load with 502 errors—diff rendering now works independently of commit history, so suggestion pages load correctly regardless of commit count. * **Docs PR Draft Timing:** Fixed docs PRs being marked ready for review too early when linked to multiple source PRs—docs PRs now stay in draft until all linked source PRs have merged. * **Versioned Branch Diff Display:** Fixed suggestion diffs in the dashboard and Slack notifications incorrectly comparing against the default branch instead of the configured target branch—suggestions targeting versioned branches now show correct diffs. * **History Tab Sync Commits:** Fixed automated base-sync merge commits appearing in the suggestion History tab as if they were normal Promptless edits—these operational commits are now hidden to reduce timeline noise. * **Slack Publish Button Reliability:** Fixed Slack notifications sometimes omitting the Publish button for publishable suggestions—the button now appears consistently when a suggestion can be published. * **Documentation Prose Quality:** Fixed documentation suggestions sometimes producing overly brief or choppy prose—Promptless now generates more natural, cohesive content that flows better as customer-facing documentation. **Deprecated:** * **XWiki Integration Removed:** The XWiki integration has been discontinued. If you were using XWiki with Promptless, please contact help@gopromptless.ai to discuss alternative workflows. *** title: March 2026 url: https://promptless.ai/changelog/changelogs/march-2026 --- **New Features:** * **Version Branch Targeting:** Suggestions now target the correct base branch automatically. When a trigger comes from a non-default branch, Promptless creates the suggestion against that branch—useful for teams maintaining versioned documentation. A base branch chip appears on suggestion cards so you can see at a glance which branch a suggestion targets. * **AGENTS.md Support:** Promptless now honors `AGENTS.md` files in your docs repository, letting you provide persistent guidance to the agent about your project's conventions, terminology, and documentation standards. * **Clarification Prompts:** When you send a direct request via Slack or the Web UI, Promptless now asks clarifying questions before diving in—reducing back-and-forth and improving suggestion quality. **Improvements:** * **Better Screenshot Capture:** Screenshots are now captured more reliably and at higher quality. Large screenshot canvases also fit properly within the editor dialog instead of overflowing. * **Improved Voice Matching:** Promptless now does a better job matching your team's writing style, tone, and conventions when generating documentation suggestions. * **Suggestion Branch Syncing:** Open suggestion branches now stay synced with their effective base branch, so suggestions always build on the latest documentation state. * **Sticky File Header in Diff Review:** The file header now sticks to the top of the viewport while scrolling through diffs, so you always know which file you're reviewing. * **Dynamic Browser Tab Titles:** All dashboard pages now display descriptive tab titles, making it easier to navigate with multiple tabs open. * **Full PR Links in Citations:** Citations now link directly to the source pull request, making it easier to trace a suggestion back to the change that triggered it. * **Improved Slack Notifications:** Slack messages now render with consistent formatting—links, bold text, and code blocks display properly across all notification types. **Bug Fixes:** * **Docs PR Status:** Fixed the trigger events page showing stale PR status instead of the current state. * **Large PR Handling:** Fixed an issue where PRs with more than 300 changed files could silently drop changes during processing. * **Onboarding Doc Detection:** Fixed onboarding to correctly detect `.rst` and `.adoc` files in your repository. * **Stale Image Filtering:** Fixed stale images appearing in the "Added images" section of suggestion diffs. * **Stale Suggestion Pruning:** Suggestions with open documentation PRs are no longer incorrectly archived by the stale-suggestion cleanup. * **Default Branch Rename:** Fixed suggestion sync breaking when a repository's default branch is renamed. *** title: February 2026 url: https://promptless.ai/changelog/changelogs/february-2026 --- **New Features:** * **Notion Integration:** Connect your Notion workspace to use pages and databases as context sources. During OAuth authorization, you select which pages and databases Promptless can access. The dashboard displays content counts (e.g., "8 pages, 2 databases") and includes a refresh button to re-sync workspace content without disconnecting. * **Configurable GitHub PR Comment Trigger Mode:** Control whether Promptless responds to all PR comments or only @promptless mentions. New organizations listen to all comments by default—start any comment with `aside` or `/aside` to have Promptless skip it. Existing organizations continue to require @promptless mentions. Configure this in Settings → Org Settings. * **Weekly Suggestion Digest:** Stay on top of documentation reviews with automatic Friday Slack notifications. Each digest summarizes open suggestions awaiting review, shows weekly activity stats (triggers processed, new suggestions), and warns about suggestions approaching the 30-day auto-archive limit. Teams with multiple doc collections receive separate digests per collection. * **Environment Variables for Agent Credentials:** Store credentials and configuration values that the Promptless agent can use at runtime—like login credentials for screenshot testing or API tokens for authenticated endpoints. Admins can add variables in Settings → Environment Variables, optionally marking them as secrets to hide values after saving. Variables are automatically available to the agent with a `PROMPTLESS_` prefix. **Improvements:** * **Paste Images into Task Input:** Paste images directly into the task input box from your clipboard. Take a screenshot (Cmd+Ctrl+Shift+4 on Mac) and paste it—no need to save to a file first. * **Clearer Notification Tips:** Notification tips in Slack and GitHub now include direct links to the Promptless dashboard—making it easier to act on labels, assignments, and inline comments. * **Scoped CI Failure Handling:** When CI checks fail on documentation PRs, Promptless investigates whether the failures are actually caused by the current suggestion—pre-existing or unrelated failures are left alone. If Promptless finds real documentation issues outside the suggestion's scope, it creates a separate suggestion to address them. * **Smarter Duplicate Detection for GitHub Docs:** Promptless now detects open documentation PRs you've created yourself—if your changes are already covered by an open PR, Promptless skips creating duplicate suggestions and notifies you instead. * **Markdown Formatting in Slack Messages:** Messages from Promptless in Slack—including questions and clarifications—now render markdown formatting. Links, bold text, headers, and code blocks display properly, making messages easier to read. * **Excluded Repository Visibility:** Projects configured to trigger on all repositories now clearly display any excluded repos in the project list. When setting up a new project or editing an existing one, you can also use a checkbox to quickly exclude your docs repository from triggers—preventing documentation PRs from triggering Promptless on themselves. * **Streamlined PR Descriptions:** Documentation PR descriptions now show the first 5 trigger events with a link to the Promptless dashboard for the complete list. This keeps PR descriptions focused and readable for suggestions with many trigger events. *** title: January 2026 url: https://promptless.ai/changelog/changelogs/january-2026 --- **New Features:** * **Agent Knowledge Base:** View and edit the files that inform how Promptless writes documentation—your style guide, product overview, and documentation guidelines. Find them in Settings under the Agent Knowledge Base tab. Promptless updates these files automatically as it learns from your feedback, but you can also edit them directly. * **Atlassian Integration (Jira + Confluence):** Connect both Jira and Confluence through a single unified Atlassian integration. Promptless now searches your Confluence spaces alongside Jira tickets—pulling documentation patterns, terminology, and architectural decisions when creating suggestions. This replaces the previous Jira-only integration—if you previously connected Jira, reconnect to access Confluence while preserving your Jira project configuration. Atlassian integration showing both Jira projects and Confluence spaces in a unified interface * **Guided Onboarding Wizard:** A 6-step wizard walks new users through Promptless setup: connecting Slack, connecting your documentation platform, configuring triggers, adding context sources, setting agent preferences, and starting your trial. Progress saves automatically—leave and return to pick up where you left off. Team members from the same organization can continue setup without losing previous progress. * **Automatic Support Channel:** When you connect Slack during onboarding, Promptless creates a shared Slack Connect channel between your team and ours. Use it to ask questions, share feedback, and get support. * **Self-Service Signup:** Sign up for Promptless at [accounts.gopromptless.ai](https://accounts.gopromptless.ai)—no sales call required. * **Deep Analysis:** Submit large documentation requests—like refactoring entire sections, auditing for consistency, or writing comprehensive docs from scratch. Access Deep Analysis from the sidebar, select your doc collection, describe what you need, and optionally attach supporting files. The Promptless team reviews your request and begins processing, which may create multiple suggestions across your documentation. * **Triggers Page Search:** Search for triggers by PR info, Slack thread topic, task name, or summary text. The default view shows the last 30 days, but search retrieves matching triggers from your full history. * **Read-Only GitHub App for Open Source Repos:** Connect Promptless to open source repositories where you can't install GitHub apps. The read-only app only requests read permissions—documentation PRs are created from a fork using a Promptless service account. Click **GitHub (Read-Only)** on the integrations page to get started. **Improvements:** * **Faster Response Times:** Promptless now processes documentation requests roughly twice as fast—reducing wait times from several minutes to about a minute. * **Intercom Integration:** Connect your Intercom Help Center directly from the Integrations page using OAuth—no need to contact support. Publish help center articles and customer support documentation through Promptless. * **Upgraded to Claude Opus 4.5:** Documentation suggestions now use Claude Opus 4.5 for improved reasoning, analysis, and documentation context understanding. * **Calibration Progress Tracking:** Track your progress in helping Promptless learn your documentation preferences. The new Calibration Progress banner shows how many suggestions you've published and how much feedback you've provided—Promptless uses both to understand your writing style, tone, and standards. The banner appears on all dashboard pages until you reach calibration goals (5 published suggestions and 5 pieces of feedback), then disappears automatically. Calibration progress banner showing progress bar with 1/5 published and 7/5 feedback completed Calibration progress banner expanded view showing detailed checklist items for publishing suggestions and providing feedback * **Ready Count Includes Open PRs:** The Ready count on the Change History page now includes suggestions with open documentation PRs—not just unpublished suggestions. Previously, only suggestions without PRs were counted as ready, so you can now see everything that needs your review in one place. * **Suggestion Lifecycle Improvements:** Viewing a suggestion now counts as activity—so suggestions you're actively reviewing stay active even if no edits are made for over 30 days. You can also view the full diff of any suggestion—even after it's been closed or merged. * **Change History Page Enhancements:** The page now loads faster with suggestion metadata appearing immediately while diffs load in parallel. New filtering by trigger source (Slack, Web UI, GitHub) and estimated review times help prioritize your review queue—sort by "Shortest review" to clear small updates first. * **Screenshot Improvements:** Promptless now makes better decisions about when to capture fresh screenshots and can crop them to focus on specific UI elements—highlighting exactly what users need to see without extra clutter. * **Automatic Suggestion Updates from Main:** When changes are pushed to your documentation's main branch, Promptless merges those updates into all open suggestion branches and automatically resolves any conflicts. * **Rich PR Descriptions:** Documentation PRs now include a "Promptless Research" section with clickable links to every source reviewed—files, GitHub PRs, Slack conversations, and more—plus an explanation of the changes. For suggestions with multiple triggers, each trigger's context appears in collapsible sections. * **Inline PR Citations:** Citations now appear as review comments on specific lines in your documentation PRs. See the exact source—GitHub PR, Slack message, or Jira ticket—that informed each change directly in the diff view. * **Onboarding Wizard Enhancements:** Several improvements throughout the wizard—your docs repository is now automatically excluded when triggering on all repos, monorepo setups prompt you to select specific repositories, help links guide you to documentation when needed, and the calibration card now shows that you'll receive a Slack notification when PR replays complete. If your Slack connection doesn't complete, a recovery flow shows options to try again, continue without Slack, or contact your admin. * **Simplified Intercom Connection:** Connecting Intercom is now a one-click OAuth flow for all users. Previously, some organizations had to manually create an app in the Intercom Developer Hub and enter an access token—now everyone connects through standard OAuth authorization. * **Slack Notification Channel Picker:** The Slack notification channel setting is now a dropdown showing your workspace's channels instead of a free text field—so you're always selecting a valid channel. If the channel you want doesn't appear, create it in Slack first, then refresh your channels on the Integrations page. * **Auto-Merge Restricted to Commit Triggers:** Auto-merge is now only available for GitHub commit triggers. If you had auto-merge enabled for PR or other trigger types, it's been automatically disabled—re-enable it in project settings if needed. **Bug Fixes:** * **Confluence Integration Reliability:** Fixed an issue where Confluence workspace connection data could be lost when refreshing the integration, making Confluence spaces temporarily unavailable. * **New Task Project Dropdown:** Fixed the New Task feature to only show doc collections that have completed analysis—preventing errors when submitting documentation requests. Previously, users could select doc collections that were still being analyzed, which would fail when submitted. * **Promptless Capture Reliability:** Fixed intermittent failures when capturing screenshots. * **Citation Display in Editor:** Fixed citation icons overlapping when multiple citations reference the same line—they now stack properly for easier viewing. * **Citation Popup Positioning:** Fixed citation popup positioning and arrow placement issues in the editor, ensuring popups display correctly even when citations are stacked. * **Comment Bubble Overflow:** Fixed comment bubbles extending beyond the editor viewport, keeping all interface elements properly contained within the editing area. * **Cleaner Suggestion Diffs:** Fixed suggestion diffs to exclude internal system files—diffs now show only your documentation changes, making them easier to review. * **Slack Notification Diff Files:** Fixed diff file attachments in Slack notifications—teams can now see the full diff of documentation changes directly from Slack without needing to open the PR or web interface. * **Slack Notification Delivery:** Improved reliability of Slack notifications by automatically retrying on transient errors. Notifications that previously failed due to temporary Slack service issues (5xx errors, connection problems, rate limits) are now retried automatically. * **Slack Bot Message Processing:** Fixed an issue where Slack messages from bots—like other integrations or automated workflows—could fail to trigger documentation updates. Bot-authored messages are now processed correctly. * **Git Sync Reliability:** Improved reliability of git sync operations when Promptless pushes documentation changes—sync operations now properly wait for concurrent git processes to complete, preventing intermittent failures. * **Git Repository Access Reliability:** Fixed intermittent failures from git configuration lock contention when processing multiple documentation updates simultaneously. * **GitHub PR Processing:** Improved reliability when processing GitHub PRs with many file changes—Promptless now handles large PRs with multiple files more consistently, preventing intermittent errors during analysis. * **Background Job Processing:** Improved reliability of background job processing—jobs now properly initialize cache clients, preventing intermittent failures during documentation generation. * **Suggestion Tracking with Multiple Doc Collections:** Fixed suggestion tracking with multiple doc collections—trigger events now link to the correct suggestions. Previously, when multiple agents responded to the same trigger (like a Slack message) but used different doc collections, trigger events could link to the wrong suggestion. * **Change History Page Performance:** Improved performance and reliability of the Change History page when viewing suggestions—page updates now happen more efficiently to ensure consistent functionality. * **Impacted File List Accuracy:** Suggestion diffs now show only documentation files—internal Promptless system files no longer appear in the impacted files list, making it easier to see exactly which documentation files changed. * **Re-opened Docs PRs Now Resume Correctly:** Re-opening a docs PR now restores the suggestion so you can continue editing. Previously, follow-on instructions weren't processed after closing and re-opening a PR. * **Suggestion Editing Reliability:** Fixed an issue where editing existing suggestions could fail—the system was incorrectly looking for suggestion branches in the wrong storage location. * **Internal Evaluation Infrastructure:** Fixed inconsistent default resource configurations in the evals system—resource defaults are now maintained in a single authoritative location, improving reliability of internal evaluation runs. * **Suggestion Stability for Revert PRs:** Fixed an issue where suggestions could be incorrectly deleted when processing PRs that revert previously documented changes—suggestions now remain active and continue receiving updates correctly. * **PR Replay Status Accuracy:** Fixed PR replays to show the correct PR status on the Triggers page. Previously, replayed PRs always showed "open" status regardless of whether the PR was actually merged, closed, or in draft state. * **GitHub Trigger Icons:** Fixed the Change History page to show the GitHub icon for all GitHub-based triggers—including GitHub Enterprise PRs, merged PRs, and GitHub Issues. Previously, the icon only appeared for regular open PRs. * **GitHub PR Event Filtering:** Fixed an issue where Promptless could trigger on PR events like `edited` or `synchronize` instead of only triggering when PRs are opened, marked ready for review, or reopened. * **GitHub Integration Reliability:** Promptless now handles server clock drift that could cause intermittent authentication errors and automatically retries operations when GitHub's API returns transient server errors. * **Duplicate Trigger Context in PRs:** Fixed trigger context appearing twice in documentation PRs—once in the PR description and again as separate comments. Trigger context now appears only in the PR description. * **Large Image Processing:** Fixed failures when processing triggers with large images. Promptless now automatically compresses images that exceed size limits, so you can include high-resolution screenshots and images in Slack messages, GitHub issues, or other triggers without issues. * **Documentation PR Update Reliability:** Fixed intermittent failures when updating documentation PRs with new changes. Promptless now handles transient GitHub API timing issues more gracefully, ensuring suggestions are consistently applied to your docs PRs. * **Onboarding Wizard Stability:** Fixed multiple issues in the onboarding wizard—including OAuth integration setup, progress saving after connecting Slack, trigger dropdowns showing placeholder data, agent preferences not persisting, PR replays not starting for GitHub triggers, Slack notification channel settings being lost when resuming onboarding, and various visual glitches during page transitions. * **Slack Connect Channel Visibility:** Fixed an issue where Slack Connect support channels were created as private in your workspace—support channels now appear as public, so you can invite other team members from your organization. * **High-Volume Trigger Processing:** Fixed intermittent errors when processing triggers for organizations with many concurrent documentation tasks. * **Review Time Estimate Accuracy:** Fixed review time estimates being inflated for repositories with mixed line endings (CRLF and LF). Estimates now accurately reflect the actual scope of documentation changes. * **Suggestion Timestamp Display:** Fixed suggestion timestamps showing incorrect times—such as appearing hours in the future—when viewing the Change History page. * **Agent Knowledge Base Persistence:** Fixed an issue where edits to Agent Knowledge Base files could be lost between documentation processing runs—your customizations now persist properly. * **Fork-Based PR Creation Reliability:** Fixed an issue where documentation PRs created through the GitHub (Read-Only) integration could fail when forks have non-default names—Promptless now uses GitHub's default fork naming to ensure reliable cross-repo PR creation. * **PR Binary File Processing:** Fixed an issue where analyzing PRs that contain binary files (like updated screenshots) could fail—Promptless now handles these PRs correctly. *** title: December 2025 url: https://promptless.ai/changelog/changelogs/december-2025 --- **What's New:** * **Promptless Capture:** Keeps product screenshots in your documentation current. Promptless audits your existing screenshots on day one, regenerates outdated ones, then continuously monitors your codebase for UI changes. When code changes impact a screenshot, Promptless detects which screenshots need updating and recreates them with your current UI. Review and iterate on regenerated screenshots in the dashboard. Promptless Capture - Screenshots that stay in sync with your product * **Screenshot Editor:** Edit screenshots generated by Promptless directly in the dashboard. Click any image in the Created Assets section to crop, add annotations, highlight UI elements, adjust framing, or insert shapes, text, and arrows—save your edits and the updated image is immediately available. Screenshot editor showing editing tools and crop controls * **Repository Topic Filtering for GitHub Triggers:** Filter which repositories trigger Promptless using GitHub topics. Tag your repositories with a topic like "docs-enabled" or "promptless", then configure your Promptless project to monitor that topic. Add new repos to Promptless by tagging them in GitHub—no need to update your Promptless configuration. * **Commit Trigger Replay:** New GitHub projects configured with Commit triggers can now process the last 30 days of direct commits during setup. This catches you up on recent changes and generates documentation suggestions for anything you might have missed. * **Improved Project Settings Editing:** Save empty documentation directories to scan your entire repository, and switch GitHub organizations when editing projects. When you change your documentation directory scope, Promptless automatically closes suggestions containing files outside the new scope—keeping your staging area clean. * **Automatic Suggestion Updates on PR Merge:** When a GitHub PR merges, Promptless automatically updates existing documentation suggestions to reflect what actually merged. If your PR changed during code review—code updates, description edits, or new commits—your doc suggestions stay accurate. * **Markdown Support in Suggestion Descriptions:** Suggestion descriptions in the dashboard now render with full markdown formatting—bold and italic text, code snippets, links, and structured lists. * **Protected Branch Detection for Slack Notifications:** When Promptless detects protected branches in your documentation repository, Slack notifications show "Open PR" or "View PR" buttons instead of "Publish." This prevents merge errors for repositories that require PR reviews before merging. * **Auto-Publish Support for GitHub Commit and MS Teams Triggers:** GitHub Commit and MS Teams triggers now support auto-publish mode. When enabled, Promptless automatically creates documentation PRs as soon as suggestions are ready, streamlining your review and publishing workflow. * **Auto-Merge for Documentation PRs:** Promptless now automatically merges documentation PRs as soon as they're created when auto-publish is enabled. Enable "Automatically merge Promptless's suggestions into the default branch" in project settings (nested under auto-publish) for complete end-to-end automation—from code changes to merged documentation—ideal for internal docs or teams with high confidence in Promptless suggestions. Auto-merge checkbox nested under auto-publish in project settings * **Citations Button Always Available:** The Show Citations button in the file diff viewer now remains visible and enabled whenever citations exist for a file. Previously, this button was incorrectly disabled after opening a PR or publishing a suggestion, making it difficult to view source references. * **Sign Out During Onboarding:** Users can now sign out from the onboarding screen. This fixes an issue where users were stuck if they accidentally signed in with the wrong email address. *** title: November 2025 url: https://promptless.ai/changelog/changelogs/november-2025 --- **What's New:** * **Rich Slack Notifications for Quick Review and Publishing:** When Promptless creates documentation suggestions, you get rich notifications in Slack showing the suggestion title, description, assigned team members, trigger source, and files changed. Use the "Publish" button to merge small, straightforward suggestions directly from Slack, or click "Open PR" to review changes in detail on GitHub or in the Promptless dashboard. Rich Slack notification showing suggestion details with Publish and View PR buttons * **File Attachment Support for Requests to Promptless in the Dashboard:** Attach up to 5 files (10 MB max each) when creating documentation requests for Promptless from the dashboard's "New Task" button. Upload screenshots, PDFs, or documents to provide additional context. This mirrors the functionality when using Promptless in Slack, where attached images and PDFs are automatically analyzed to inform documentation suggestions. New Task dialog showing attachment support with Add files button * **Automatic CI Fixes:** When documentation PRs from Promptless fail CI checks or build tests, Promptless automatically detects the issue and pushes a fix. No manual intervention needed for build errors. * **GitHub Enterprise Context Search:** Promptless now searches through your GitHub Enterprise issues, pull requests, and discussions when creating documentation suggestions—bringing GitHub Enterprise customers the same context gathering capabilities as GitHub Cloud users. *** title: October 2025 url: https://promptless.ai/changelog/changelogs/october-2025 --- **What's New:** * **Manual Documentation Requests from Dashboard:** Request documentation updates directly from the dashboard using the "New Task" button. Select a project, write your instructions, and submit—just like Slack DMs but from the dashboard. New Task button in the dashboard sidebar New Task dialog showing project selection and instruction field * **Research Visibility in Change Timeline:** The Change Timeline now shows exactly what Promptless reviewed—files, webpages, Slack conversations, and other sources. Click "Show details" for the full list with direct links. Source descriptions are more precise—GitHub PRs appear as "Reviewed Promptless/promptless#123" instead of generic "Read webpage from github.com". Research details showing files and webpages reviewed by Promptless * **Triggers Page:** Verify that Promptless ran on expected PRs and events. When Promptless doesn't create suggestions, see exactly why. View research and context for any trigger from the last 30 days, with filters for trigger type and suggestion status. Triggers page showing recent trigger events * **Multiple GitHub Organization Support:** Connect multiple GitHub organizations to a single Promptless account. Each org appears as its own card with separate repository lists. Manage company and personal projects in one place. GitHub integrations page showing multiple connected organizations Project modal showing repository names prefixed with organization names * **Non-Blocking Feedback:** When you remember feedback for future suggestions without requesting changes to the current one, you can keep viewing and interacting with the suggestion right away. Previously, the interface would block while processing feedback—even when nothing was being changed. * **Slack Passive Channel Listening:** Automatically monitor specific Slack channels and create documentation suggestions when conversations go quiet for 10 minutes. This opt-in feature lets you select which channels to monitor. * **Slack Private Channel Support:** Promptless now works properly in private Slack channels when invited, fixing previous permission issues. * **Descriptive Commit Messages:** Promptless PRs now use the suggestion title as the commit message instead of generic "Documentation updates from Promptless" text. This keeps your git history more informative and easier to track—especially helpful if you don't use squash-merge. *** title: September 2025 url: https://promptless.ai/changelog/changelogs/september-2025 --- **Improvements:** * **Enhanced Slack Context Understanding:** Promptless now analyzes full Slack conversations instead of individual messages, capturing surrounding discussion for more accurate and comprehensive documentation. * **Enhanced GitHub PR Comment Context Awareness:** When you tag Promptless in GitHub PR comments, it reads all previous comments to understand full context. Use simple instructions like "Same here" or "Apply this change to the other section too" without repeating details. * **GitBook Platform Support:** Promptless now supports GitBook as a first-class documentation platform. Connect your repositories to automatically update GitBook documentation when code changes. * **Improved Jira Context Integration:** Promptless now more reliably fetches Jira ticket information when issues are mentioned in pull requests. Full ticket context including descriptions, comments, and related issues is consistently retrieved. * **Automated CI Check and Build Issue Resolution:** Promptless automatically detects and fixes quality issues in documentation PRs. When linters fail, Vale rules trigger, or build errors occur, Promptless analyzes and pushes fixes to the PR branch automatically. * **Smart Draft State Management for Documentation PRs:** Documentation PRs now open as drafts when the source code PR hasn't merged yet, then automatically switch to "Ready for Review" once the source PR merges. This means your team only reviews documentation changes after the underlying code is finalized. Warning dialog showing that the documentation PR will be opened as a draft since the trigger PR is not merged yet GitHub pull request showing draft status for Promptless documentation PR * **Improved Dashboard Synchronization for Follow-on Suggestions:** The dashboard now immediately reflects changes when you make follow-on suggestions. No more delays—instant updates for better real-time visibility. * **PR Open Status Filter:** You can now filter for suggestions published as pull requests directly from the status dropdown. Previously, you had to manually type `is:pr_open` into the search bar. The "PR Open" option appears alongside "Ready," "Published," and "Rejected." PR Open filter option in the suggestions dashboard status dropdown *** title: August 2025 url: https://promptless.ai/changelog/changelogs/august-2025 --- **What's New:** * **Feedback Collection:** Share feedback directly on suggestions to help Promptless learn your team's preferences and standards. A new feedback button appears when viewing suggestions. * **Citation Transparency:** The suggestions page now displays citations showing which PRs, Slack threads, Jira tickets, and documentation pages informed each change. * **Slack File Attachments:** Promptless now processes file attachments from Slack messages, including PDFs, documents, and other files. When you trigger documentation updates from Slack, Promptless analyzes these attachments for additional context. **Improvements:** * **Enhanced Suggestion Filtering:** The new filter interface includes dropdown options and a text box to search and filter suggestions by status, assignee, or other criteria. You can copy links to share filtered views with teammates. *** title: July 2025 url: https://promptless.ai/changelog/changelogs/july-2025 --- **What's New:** * **PR Replay:** New GitHub projects can now process the last 30 days of PRs during setup. This catches you up on recent changes and generates documentation suggestions for anything you might have missed. * **All Repos Trigger:** Check "Trigger on all repos" when setting up GitHub, GitLab, or Bitbucket projects to automatically monitor all your repositories. No need to manually select each one, and new repos get included automatically. **Improvements:** * **Better PR Reviews:** When you submit a "Request changes" review on a Promptless PR, we'll process all your comments automatically—no need to @mention us in each one. * **Smarter GitHub Comments:** Promptless now react with 👀 when processing your comments, reply in threads instead of cluttering the main conversation, and mention you directly in our responses. *** title: June 2025 url: https://promptless.ai/changelog/changelogs/june-2025 --- ### June 2025 **What's New:** - **GitLab Integration**: Added full GitLab support including merge request triggers, project setup, and webhook configuration for automated updates. - **Enhanced Authentication**: Implemented automatic domain verification and team member enrollment for organizations, making it easier for your teammates to access Promptless suggestions. - **Document360 Improvements**: Launched comprehensive Document360 broker with per-file publishing, webhook sync capabilities, and live URL/editor URL support in the UI - *** title: May 2025 url: https://promptless.ai/changelog/changelogs/may-2025 --- ### May 29, 2025 **What's New:** * **Jira Integration:** Added Jira as a context source integration, allowing Promptless to retrieve and search Jira issues when generating documentation updates. This includes OAuth 2.0 authentication, issue retrieval by key, and JQL search capabilities to ensure documentation updates are informed by actual project management context. * **Webflow Publishing:** Enhanced Webflow integration with direct publishing from the Change History page. Added "Save All & Publish to Webflow" button for seamless content publishing, automatic item management, and support for multiple Webflow collections. * **Per-File Publishing for ReadMe:** Added capability to publish individual files to ReadMe instead of requiring all files to be published at once, providing more granular control over documentation updates. * **Enhanced Slack Integration:** Promptless now responds directly in Slack threads instead of sending private ephemeral messages, improving transparency and collaboration. Added automatic channel joining capability for public channels when mentioned. * **Improved Suggestions UI:** Redesigned the Change History page with a new card-based UI, improved filtering and sorting options, enhanced status display, and better visualization of trigger events. **Improvements:** * **GitHub Integration Enhancements:** - Added trigger events display in PR descriptions for better context - Improved support for deleted files when creating documentation PRs - Enhanced @promptless comment tagging with user reminders - Better handling of file management operations * **User Experience:** - Local timezone display for timestamps in Change History page - Improved web follow-on request UX with commit timeline visibility - Enhanced image processing from linked threads and follow-up requests - Disabled follow-up requests after suggestion publishing for cleaner workflows * **Claude 4 Model Support:** Expanded Claude 4 model availability from select organizations to all Promptless users. * **Enhanced Image Processing:** Improved image handling capabilities with support for Slack-hosted images and better integration with documentation workflows. **Bug Fixes:** * **PR Comments:** Fixed issue where "no suggestions" comments weren't properly shown on GitHub and Bitbucket pull requests. * **Image Processing:** Restricted image processing to Slack-hosted images only (files.slack.com URLs) for improved reliability. * **UI Improvements:** Fixed suggestions table display and terminology consistency (changed "runs" to "suggestions"). **Integrations:** * **Jira:** New context source integration with OAuth 2.0 authentication and JQL search capabilities. * **Enhanced Webflow:** Direct publishing capabilities with improved CMS field support and metadata parsing. * **Browser Use Demo Site:** Added integration for scraping and analyzing documentation from browser-use.com for demo purposes. *** title: April 2025 url: https://promptless.ai/changelog/changelogs/april-2025 --- ### Apr 7, 2025 **What's New:** * **Slack Image Support:** You can now add screenshots to your docs directly from Slack. Just trigger Promptless on Slack messages with screenshots or images, and it will automatically place them in the right spot in your docs. For example, if you notify a customer about a new feature in a Slack Connect channel and include screenshots and trigger Promptless via the Slack Message Action, Promptless will be able to include those screenshots in the documentation when appropriate. * **Directory-Specific Triggers:** Set up automatic documentation updates from specific directories in your repos (like your changelog directory). We'll update your docs whenever changes are made in these directories. For example, if you have a changelog directory, you can have Promptless be triggered whenever there is a Pull Request that includes updates to it. * **File Management:** You can now rename new documentation files or move them to different folders from the Promptless app. For example, after Promptless creates a new tutorial page, you can easily move it from the general docs folder to your dedicated tutorials section without leaving the interface. * **Changelog Publishing:** Promptless now automatically creates changelog entries when new features are shipped. If your docs already have a changelog structure, Promptless will update it appropriately. * **Custom Instructions:** You can contact the Promptless team (either via Slack or at help@gopromptless.ai) to add custom instructions for how your docs should be generated. *Example: Specify that all code examples should use TypeScript instead of JavaScript, or that certain terminology should always be used consistently across your documentation.* **Bug Fixes:** * **GitHub Comments:** GitHub comments that are unrelated to documentation will no longer trigger Promptless to generate new commits. **Integrations:** * **Webflow Support:** Connect to your docs hosted on Webflow. * **Bitbucket Support:** Trigger Promptless doc updates from Bitbucket pull requests. *** title: March 2025 url: https://promptless.ai/changelog/changelogs/march-2025 --- ### March 31, 2025 **What's New:** * **Document360 Integration:** Added Document360 as a new documentation platform integration, allowing you to publish documentation updates directly to the knowledge base. * **Enhanced Bitbucket Integration:** Improved Bitbucket integration with better connection handling and enhanced pull request processing capabilities. * **Trigger Directory Configuration:** Added the ability to specify trigger directories for GitHub and Bitbucket integrations. You can now configure Promptless to only monitor specific directories within your repositories, reducing noise and focusing only on relevant code changes. * **Follow-On Requests in Web Interface:** Introduced follow-on request capabilities directly in the web interface, allowing users to request additional changes without leaving the Promptless dashboard. * **PR Template Path Configuration:** Added support for configuring custom PR template paths in documentation pipelines, giving teams more control over how Promptless-generated docs PRs are formatted and structured. **Bug Fixes:** * **False Positive Reduction:** Implemented improvements to reduce false positive triggers and unnecessary documentation suggestions. * **Comment Processing:** Improved filtering to prevent irrelevant GitHub comments from triggering documentation updates. *** title: February 2025 url: https://promptless.ai/changelog/changelogs/february-2025 --- ### February 2025 **What's New:** * **Intercom Integration (beta):** Added Intercom integration allowing Promptless to publish doc updates directly to Intercom help centers. Users can also trigger documentation updates from Intercom support conversations that could indicate documentation gaps. * **Paligo Support:** Integration with Paligo (beta), a documentation platform, enables Promptless to work with XML-based documentation workflows and enterprise content management systems. * **Enhanced GitHub PR Editing:** Added the ability for users to edit documentation changes further through GitHub comments on documentation PRs. This allows for iterative refinement of the generated suggestions directly within the GitHub workflow. * **Slack Notification System:** Added Slack notifications to keep teams informed about documentation updates and processing status. Added support for notifications to specific channels and improved visibility into Promptless activities. *** title: January 2025 url: https://promptless.ai/changelog/changelogs/january-2025 --- ### January 2025 **What's New:** - **Notion Integration**: Added Notion integration (beta) allowing users to connect their Notion workspaces and publish documentation updates directly to Notion databases. - **ReadMe Publishing Support**: Introduced direct publishing to ReadMe documentation platform via API integration. Users can now update ReadMe docs directly from the Promptless dashboard with per-file publishing capabilities. Customers on ReadMe - **File Management**: Added file path editing capabilities for new documentation, allowing users to adjust suggested file locations before publishing. *** title: December 2024 url: https://promptless.ai/changelog/changelogs/december-2024 --- ## What's New * **Docs Staging Area:** Introduced a web interface that allows users to review and manage documentation changes before publishing to their docs platform. * **Enhanced Slack Integration:** Improved Promptless Slack bot to allow users to tag Promptless in a channel or DM Promptless directly to provide instructions for doc updates. * **GitHub User Attribution:** Added GitHub username tracking and attribution for commits. ## Improvements * **New Doc Editor Integration:** Upgraded the documentation editing experience with syntax highlighting, better formatting, and comparing version diffs. * **Ephemeral Slack Notifications:** Added ephemeral direct messages in Slack when Promptless is triggered, providing immediate feedback to users without cluttering channels. *** title: November 2024 url: https://promptless.ai/changelog/changelogs/november-2024 --- ## What's New * **Google Drive Integration:** Added Google Drive as a context source with OAuth authentication, allowing Promptless to access and analyze documents stored in Google Drive when generating documentation updates. Users can now connect multiple Google Drive directories to their projects for enhanced contextual information. * **GitHub Issues RAG Support:** Promptless now automatically queries GitHub issues to provide better context for documentation updates. The system intelligently handles forked repositories by using issues from the source repository and requires no additional configuration when GitHub issues are enabled. * **Multiple Context Sources:** Enhanced project configuration to support multiple context sources per project, including multiple Google Drive directories and Jira projects for comprehensive documentation context. * **Keyword Search:** Added keyword search functionality to improve content discovery and documentation generation accuracy. *** title: October 2024 url: https://promptless.ai/changelog/changelogs/october-2024 --- ## What's New * **Asynchronous Pipeline Loading:** Improved project setup times by implementing background pipeline loading. This reduces waiting time during initial project configuration. * **Destination Directory Selection:** You can now specify exactly which directories within the repo the doc updates should go to. This feature makes it easy for monorepo structures with a /docs directory. ## Improvements * **Large File Processing:** Improved handling large documents with intelligent file chunking. The system now processes files in manageable segments while preserving full context, resulting in faster processing times and more accurate results for complex codebases. ## Infrastructure * **Vector Database Migration:** We've migrated from Pinecone to pgvector for our search infrastructure. This upgrade removes previous limitations around prefix querying and metadata length restrictions.