docs: Restructure documentation organization for clarity

fern/docs.yml

@@ -29,19 +29,47 @@ navigation:
           path: ./docs/index.mdx
         - page: Setup & Quickstart
           path: ./docs/getting-started.mdx
+        - page: Core Concepts
+          path: ./docs/core-concepts.mdx
         - page: Pilot Overview
           hidden: true
           path: ./docs/pilot-guide.mdx
-    - section: Core Concepts
-      icon: fa-regular fa-lightbulb
-      path: ./docs/core-concepts/index.mdx
+    - section: Configuring Promptless
+      icon: fa-regular fa-gear
       contents:
-        - page: Triggers
-          path: ./docs/core-concepts/triggers.md
-        - page: Context Sources
-          path: ./docs/core-concepts/context-sources.md
-        - page: Doc CMSs
-          path: ./docs/core-concepts/doc-locations.md
+        - section: Triggers
+          path: ./docs/configuration/triggers.md
+          contents:
+            - page: GitHub PRs
+              path: ./docs/configuration/triggers/github-prs.md
+            - page: GitHub Commits
+              path: ./docs/configuration/triggers/github-commits.md
+            - page: Slack Messages
+              path: ./docs/configuration/triggers/slack.md
+            - page: Microsoft Teams Messages
+              path: ./docs/configuration/triggers/microsoft-teams.md
+            - page: Zendesk Tickets (Beta)
+              path: ./docs/configuration/triggers/zendesk.md
+        - section: Context Sources
+          path: ./docs/configuration/context-sources.md
+          contents:
+            - page: Linear
+              path: ./docs/configuration/context-sources/linear.md
+            - page: Jira
+              path: ./docs/configuration/context-sources/jira.md
+        - section: Doc Collections
+          path: ./docs/configuration/doc-collections.md
+          contents:
+            - page: GitHub Repos (Docs as Code)
+              path: ./docs/configuration/doc-collections/github-repos.md
+            - page: Document360
+              path: ./docs/configuration/doc-collections/document360.md
+            - page: Zendesk
+              path: ./docs/configuration/doc-collections/zendesk.md
+            - page: Intercom (Beta)
+              path: ./docs/configuration/doc-collections/intercom.md
+            - page: Webflow (Beta)
+              path: ./docs/configuration/doc-collections/webflow.md
     - section: How to use Promptless
       icon: fa-regular fa-star
       path: ./docs/features/index.mdx
@@ -176,4 +204,3 @@ typography:
     style: normal
 
 favicon: ./docs/assets/favicon.ico
-

fern/docs/configuration/context-sources.md

@@ -0,0 +1,69 @@
+---
+title: Context Sources
+---
+
+Context sources are integrations that connect Promptless 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.
+
+<Info>
+Context sources are **optional** but highly recommended. They can significantly improve the quality and relevance of Promptless's documentation suggestions.
+</Info>
+
+## Available Context Sources
+
+<CardGroup cols={2}>
+  <Card title="Linear" icon="fa-solid fa-circle" href="/docs/configuration/context-sources/linear">
+    Access Linear issues, projects, and team workflows for project management context
+  </Card>
+
+  <Card title="Jira" icon="fa-brands fa-jira" href="/docs/configuration/context-sources/jira">
+    Query Jira tickets and project data using JQL search capabilities
+  </Card>
+</CardGroup>
+
+## 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.
+
+## Configuring Context Sources
+
+Context sources are configured at the project level in your [projects page](https://app.gopromptless.ai/projects). For each project, you can:
+
+- Select which context sources to enable
+- Configure search scope (e.g., specific teams, projects, or repositories)
+- Set permissions for what Promptless can access
+
+## Data Privacy and Security
+
+Promptless prioritizes your data privacy and security with context sources:
+
+<AccordionGroup>
+  <Accordion title="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.
+  </Accordion>
+
+  <Accordion title="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
+  </Accordion>
+
+  <Accordion title="Minimal Data Access">
+    Promptless only accesses the specific information needed for documentation generation and does not retain or cache this data after processing.
+  </Accordion>
+</AccordionGroup>
+
+## Requesting 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.

fern/docs/configuration/context-sources/jira.md

@@ -0,0 +1,47 @@
+---
+title: Jira
+---
+
+Jira integration provides 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.
+
+## How It Works as 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
+- **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 context in your [project settings](https://app.gopromptless.ai/projects):
+
+1. Enable Jira as a context source for your project
+2. Select which Jira projects Promptless can search within
+3. Promptless will only search projects you explicitly configure
+
+<Frame>
+  <img src="https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/org_2lvkgU9erOFxYhtEVVC0ymPrPdF/e3bdab51-fb59-4971-aaac-32ed7dddf07b-project-context-sources-configuration.png" alt="Project configuration screen showing context sources setup with Jira integration" />
+</Frame>
+
+<Note>
+Promptless inherits the permissions of the Jira account used during OAuth connection and will only search projects you explicitly configure.
+</Note>
+
+## Data Privacy and Security
+
+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.
+
+For information about data processing and redaction capabilities, see the Jira integration page.
+
+## Setup Instructions
+
+To connect Jira to Promptless, see the [Jira Integration](/docs/integrations/jira-integration) setup guide.

fern/docs/configuration/context-sources/linear.md

@@ -0,0 +1,41 @@
+---
+title: Linear
+---
+
+Linear integration provides secure 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.
+
+## How It Works as 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 context in your [project settings](https://app.gopromptless.ai/projects):
+
+1. Enable Linear as a context source for your project
+2. Select which Linear teams Promptless can search within
+3. Promptless will only search within teams you explicitly select
+
+<Frame>
+  <img src="../../assets/github-project.png" alt="Project configuration showing Linear team selection" />
+</Frame>
+
+<Note>
+Promptless inherits the permissions of the Linear account used during OAuth connection and will only search teams you configure in your project settings.
+</Note>
+
+## 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.
+
+## Setup Instructions
+
+To connect Linear to Promptless, see the [Linear Integration](/docs/integrations/linear-integration) setup guide.

fern/docs/configuration/doc-collections.md

@@ -0,0 +1,53 @@
+---
+title: Doc Collections
+---
+
+Doc Collections are the platforms where your documentation lives. Whether you're using Git-synced platforms such as Fern, Mintlify, or Docusaurus, or standalone platforms such as Zendesk, Intercom, and Webflow, you'll need to configure Promptless to read from and publish to your existing docs.
+
+## Git-hosted Documentation Platforms
+
+The most common setup uses GitHub repositories to store documentation content that syncs to hosting providers. A list of platforms supported through GitHub integration:
+
+- Fern
+- Mintlify
+- ReadMe (Refactored)
+- GitBook
+- Docusaurus
+- MkDocs
+- Hugo
+- Ghost
+- Nextra
+- Vocs
+- Custom platforms as long as the content is in a repo
+
+Learn more: [GitHub Repos (Docs as Code)](/docs/configuration/doc-collections/github-repos)
+
+## Direct Platform Integrations
+
+For teams using content management systems that don't sync with GitHub, Promptless offers direct integrations with popular platforms.
+
+<CardGroup cols={2}>
+  <Card title="Zendesk" icon="fa-solid fa-ticket" href="/docs/configuration/doc-collections/zendesk">
+    Help center articles and knowledge base content management
+  </Card>
+
+  <Card title="Intercom (Beta)" icon="fa-solid fa-comments" href="/docs/configuration/doc-collections/intercom">
+    Customer support documentation and help center content
+  </Card>
+
+  <Card title="Webflow (Beta)" icon="fa-solid fa-w" href="/docs/configuration/doc-collections/webflow">
+    Blog posts, collection items, and marketing site content
+  </Card>
+</CardGroup>
+
+## Multi-Platform Publishing
+
+Promptless can publish to multiple documentation locations simultaneously, allowing you to use the same trigger events and context sources across different platforms.
+
+<Tip>
+For teams using multiple platforms, create separate projects for each documentation location to maintain clear separation of content and workflows.
+</Tip>
+
+## Requesting Additional Platforms
+
+Need integration with a platform not currently supported? We're continuously expanding our platform integrations 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!

fern/docs/configuration/doc-collections/document360.md

@@ -0,0 +1,49 @@
+---
+title: Document360
+---
+
+Document360 integration enables publishing documentation updates directly to your Document360 knowledge base. This is useful for teams who manage customer-facing documentation through Document360's hosted platform.
+
+## How It Works
+
+When Document360 is configured as a documentation platform:
+
+1. **Review Suggestions**: Review documentation changes in the Promptless dashboard
+2. **Publish to Document360**: Click "Save All & Update Document360" to publish approved changes
+3. **Knowledge Base Updates**: Content is created or updated in your Document360 knowledge base
+4. **Live URLs**: Each published article includes a live URL and editor URL for easy access
+5. **Customer Access**: Updated articles are immediately available to your customers
+
+## Publishing Options
+
+When publishing to Document360, you can:
+
+- **Create New Articles**: Add new knowledge base articles and help content
+- **Update Existing Articles**: Modify existing content with new information
+- **Per-file Publishing**: Publish individual files independently for granular control
+- **Webhook Sync**: Automatic synchronization with your Document360 projects via webhooks
+- **Manage Article Metadata**: Update titles, descriptions, categories, and project organization
+- **Add Images**: Include screenshots and diagrams in your knowledge base content
+
+## Use Cases
+
+Document360 as a documentation platform is especially useful for:
+
+- **Customer Knowledge Base**: Maintain help center articles based on product updates and customer feedback
+- **Technical Documentation**: Keep API documentation and technical guides up-to-date
+- **Internal Documentation**: Manage team wikis and internal process documentation
+- **Multi-project Documentation**: Handle documentation for multiple products or services from a single workflow
+- **Support Deflection**: Update documentation to reduce recurring support requests
+
+## Project Setup
+
+Configure Document360 as your documentation platform in your [project settings](https://app.gopromptless.ai/projects):
+
+1. Connect your Document360 account
+2. Select the project where documentation should be published
+3. Configure which categories or sections to publish to
+4. Set notification preferences
+
+## Setup Instructions
+
+To connect Document360 to Promptless, contact [help@gopromptless.ai](mailto:help@gopromptless.ai) for setup assistance.

fern/docs/configuration/doc-collections/github-repos.md

@@ -0,0 +1,68 @@
+---
+title: GitHub Repos (Docs as Code)
+---
+
+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**
+- **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
+
+## Project Setup and Permissions
+
+After setting up the GitHub integration, you'll create a project in the [projects page](https://app.gopromptless.ai/projects). When creating a project, you'll select:
+
+- **Trigger repositories**: Repositories that initiate documentation updates (read-only access)
+- **Documentation repositories**: Repositories where documentation is stored (write access)
+
+<Frame>
+  <img src="../../assets/github-project.png" alt="Project Setup showing trigger and documentation repository selection" />
+</Frame>
+
+In the example above, Promptless can read the `promptless` and `promptless-dashboard` repos, but can read and write to the `promptless-docs` repo.
+
+## Auto-publish Mode
+
+When auto-publish is enabled for your project:
+
+- 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
+- Optionally enable auto-merge to automatically merge documentation PRs as soon as they're created (nested checkbox under auto-publish in project settings)
+
+## 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 will automatically analyze the issues and push 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
+
+## Setup Instructions
+
+To connect GitHub to Promptless, see the [GitHub Integration](/docs/integrations/github-integration) setup guide.