Add end-to-end tutorial for PR-triggered docs updates

src/content/docs/docs/getting-started/tutorial-first-pr-triggered-docs-update.mdx

@@ -0,0 +1,220 @@
+---
+title: "Tutorial: Your First PR-Triggered Docs Update"
+description: >-
+  Follow along as you make a code change, watch Promptless analyze it, and
+  review your first documentation suggestion
+slug: docs/getting-started/tutorial-first-pr-triggered-docs-update
+sidebar:
+  hidden: false
+  order: 3.5
+---
+import { Steps } from '@astrojs/starlight/components';
+import Info from '@components/fern/Info.astro';
+import Note from '@components/fern/Note.astro';
+import Success from '@components/fern/Success.astro';
+import Tip from '@components/fern/Tip.astro';
+import Warning from '@components/fern/Warning.astro';
+
+This tutorial walks you through the complete Promptless workflow. You'll make a small code change, open a pull request, and watch Promptless analyze it and create a documentation suggestion—all in about 15 minutes.
+
+## What You'll Learn
+
+By the end of this tutorial, you'll know how to:
+
+- Trigger Promptless from a GitHub pull request
+- Review a documentation suggestion in the Promptless dashboard
+- Provide feedback and request edits
+- Publish the final documentation update
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- A Promptless account ([sign up here](https://accounts.gopromptless.ai) if you haven't already)
+- GitHub connected as a trigger source
+- At least one documentation repository configured
+- A code repository where you can open a test pull request
+
+<Info>
+Haven't completed setup yet? Follow the [Setup & Quickstart](/docs/getting-started/setup-quickstart) guide first, then return to this tutorial.
+</Info>
+
+## Step 1: Prepare Your Test Change
+
+For this tutorial, make a small code change with clear documentation implications. This helps Promptless recognize that docs need updating.
+
+Good examples of documentation-triggering changes:
+
+- Adding a new API endpoint or parameter
+- Changing default configuration values
+- Adding a new feature flag or environment variable
+- Updating error messages users might encounter
+
+<Tip>
+If you don't want to modify production code, create a test branch with a README change that describes a fictional new feature. Promptless analyzes PR content, not just code syntax.
+</Tip>
+
+### Example: A Simple Feature Addition
+
+For this walkthrough, imagine you're adding a new `--verbose` flag to a CLI tool. Your change might look like:
+
+```diff
+ def run_command(args):
++    if args.verbose:
++        print("Starting operation with verbose logging enabled")
+     # existing logic
+```
+
+The key is making a change that a technical writer would want to document.
+
+## Step 2: Open a Pull Request
+
+Create a pull request with your change. Write a clear title and description—Promptless uses this context to understand what changed and why.
+
+<Steps>
+1. Push your branch to GitHub
+2. Open a pull request against your main branch
+3. Write a descriptive title (e.g., "Add --verbose flag for detailed output")
+4. Include context in the description about what the change does and who it affects
+</Steps>
+
+<Note>
+Promptless skips draft pull requests by default. Make sure your PR is marked as ready for review, or convert it from draft status.
+</Note>
+
+**What to expect:** Within a few seconds of opening the PR, Promptless receives a webhook notification and begins analyzing your changes.
+
+## Step 3: Watch Promptless Analyze Your PR
+
+After you open the PR, Promptless:
+
+1. Reads the code diff, PR title, and description
+2. Checks your existing documentation to understand current coverage
+3. Determines whether the change requires documentation updates
+4. If relevant, drafts a documentation suggestion
+
+**Where to see progress:**
+
+- **Slack notification** (if configured): Promptless sends a message when analysis starts and when the suggestion is ready
+- **GitHub PR comment**: Promptless posts a comment on your PR linking to the documentation suggestion
+- **Dashboard**: Visit [app.gopromptless.ai](https://app.gopromptless.ai) to see all suggestions
+
+<Info>
+Analysis typically takes 1–3 minutes depending on the size of your change and how much context Promptless needs to gather.
+</Info>
+
+### What If Promptless Doesn't Create a Suggestion?
+
+Not every code change needs documentation. Promptless might determine your change is:
+
+- Internal refactoring with no user-facing impact
+- A bug fix that doesn't change documented behavior
+- Test or CI configuration changes
+
+If you expected a suggestion but didn't get one, trigger Promptless manually by @mentioning it in a PR comment:
+
+```
+@promptless please document this change
+```
+
+## Step 4: Review the Documentation Suggestion
+
+When the suggestion is ready, click the link in your Slack notification or GitHub PR comment to open it in the Promptless dashboard.
+
+### Understanding the Suggestion View
+
+The dashboard shows you:
+
+- **Proposed changes**: The documentation updates Promptless drafted
+- **Affected files**: Which documentation pages would be updated
+- **Citations**: The sources Promptless used (your PR, related code, existing docs)
+- **Reasoning**: Why Promptless made specific decisions
+
+### Checking the Diff
+
+Review the proposed documentation changes carefully. Ask yourself:
+
+- Is the information accurate?
+- Does it match how the feature actually works?
+- Is anything missing that users would need to know?
+- Does the tone match your existing documentation?
+
+<Tip>
+Click on citations to see exactly what context Promptless used. This helps you understand why it made specific choices and catch any misinterpretations.
+</Tip>
+
+## Step 5: Provide Feedback and Request Edits
+
+Promptless suggestions are drafts, not final copy. Refine them through feedback.
+
+### Editing Through the Dashboard
+
+In the suggestion view, you can:
+
+- Edit the documentation directly in the web interface
+- Request changes by leaving comments
+- Ask Promptless to expand, clarify, or restructure sections
+
+### Editing Through Slack
+
+If you have Slack connected, reply in the Promptless thread with instructions:
+
+```
+Please add an example showing the verbose output format
+```
+
+```
+Move the configuration section before the usage section
+```
+
+### Editing Through GitHub
+
+Once Promptless opens a documentation PR, you can leave comments directly on the PR. Promptless monitors for feedback and can push additional commits in response.
+
+<Note>
+Promptless remembers the conversation context, so you can give incremental feedback like "Also add..." or "Same thing for the other section."
+</Note>
+
+## Step 6: Publish the Documentation Update
+
+When you're happy with the suggestion, you have two paths to publish:
+
+### If Auto-Publish Is Enabled
+
+Promptless automatically creates a PR in your documentation repository. You can:
+
+1. Review the PR like any other code change
+2. Request additional edits through PR comments
+3. Merge when ready
+
+### If Auto-Publish Is Disabled
+
+1. Click **Create PR** in the dashboard to generate the documentation PR
+2. Review and merge the PR in your docs repository
+
+<Success>
+Congratulations! You've completed your first PR-triggered documentation update with Promptless.
+</Success>
+
+## What You Learned
+
+In this tutorial, you:
+
+- Made a code change and opened a pull request
+- Watched Promptless automatically detect and analyze the change
+- Reviewed a documentation suggestion in the dashboard
+- Learned how to provide feedback through multiple channels
+- Published the documentation update through your normal workflow
+
+## Next Steps
+
+Now that you've completed the basic workflow, explore these topics:
+
+- **[Working with Slack](/docs/how-to-use-promptless/working-with-slack)**: Trigger and manage suggestions directly from Slack
+- **[Providing Feedback](/docs/how-to-use-promptless/providing-feedback)**: Learn more ways to refine Promptless suggestions
+- **[GitHub PRs](/docs/configuring-promptless/triggers/git-hub-p-rs)**: Configure when and how PR triggers fire
+- **[Core Concepts](/docs/getting-started/core-concepts)**: Understand triggers, context sources, and doc collections
+
+<Warning>
+Having trouble? Check [Getting Support](/docs/getting-started/getting-help) or contact us at [help@gopromptless.ai](mailto:help@gopromptless.ai).
+</Warning>