Merge branch 'main' into migrate-lg

Author: lnhsingh

src/docs.json

@@ -22,6 +22,10 @@
       {
         "label": "Forum",
         "href": "https://forum.langchain.com/"
+      },
+      {
+        "label": "Trust center",
+        "href": "https://trust.langchain.com/"
       }
     ]
   },
@@ -502,18 +506,15 @@
                   "labs/swe/index"
                 ]
               },
-              {
-                "group": "Examples",
-                "pages": [
-                  "labs/swe/examples"
-                ]
-              },
               {
                 "group": "Usage",
                 "pages": [
                   "labs/swe/usage/intro",
                   "labs/swe/usage/ui",
-                  "labs/swe/usage/github"
+                  "labs/swe/usage/github",
+                  "labs/swe/usage/best-practices",
+                  "labs/swe/usage/custom-rules",
+                  "labs/swe/usage/examples"
                 ]
               },
               {
@@ -525,11 +526,17 @@
                   "labs/swe/setup/monorepo",
                   "labs/swe/setup/ci"
                 ]
+              },
+              {
+                "group": "FAQ",
+                "pages": [
+                  "labs/swe/faq"
+                ]
               }
             ]
           }
         ]
       }
     ]
   }
-}
+}

src/images/gh_app_token_screenshot_1.png

@@ -0,0 +1,41 @@
+---
+title: "FAQ"
+description: "Frequently Asked Questions"
+---
+
+<Accordion title="How much does an end to end Open SWE run cost?">
+  The cost per run varies greatly based on the complexity of the task, the size of the repository, and the number of files that need to be changed.
+
+  For most tasks, you can expect to pay between `$0.50` -> `$3.00` when using Claude Sonnet 4.
+  For the same tasks running on Claude Opus 4, you can expect to pay between `$1.50` -> `$9.00`.
+
+  Always remember to monitor your runs if you're cost conscious. The most expensive run I've seen Open SWE complete was ~50M Opus 4 tokens, costing `$25.00`.
+</Accordion>
+
+<Accordion title="Does Open SWE automatically cache tokens?">
+  Yes. When using Anthropic models, all input tokens are cached on Anthropic's servers.
+</Accordion>
+
+<Accordion title="My run failed midway through. What now?">
+  We're sorry you're experiencing this! Open SWE will automatically commit any changes it makes to a draft pull request. Please check the draft pull request and make any necessary changes.
+
+  If a run fails, you will need to start over.
+</Accordion>
+
+<Accordion title="Can I use Open SWE in a production environment?">
+  Yes! We've been using Open SWE internally at LangChain for a while now, and it's been giving us great results.
+
+  We recommend forking and deploying Open SWE yourself if you plan on using it in a production environment. For checking out the product, the [demo application](https://swe.langchain.com) will work fine.
+</Accordion>
+
+<Accordion title="I installed Open SWE on a repository in my organization, but it doesn't show up in the UI. Why?">
+  Some GitHub organizations require administrator approval to install GitHub apps. Please reach out to an administrator in your organization to approve the installation request.  
+</Accordion>
+
+<Accordion title="What sandbox environment is Open SWE running in?">
+  Open SWE's sandbox environment is powered by [Daytona.io](https://daytona.io).
+</Accordion>
+
+<Accordion title="Can I contribute to Open SWE?">
+  Yes! We're always looking for contributors to help us improve Open SWE. Feel free to pick up an [open issue](https://github.com/langchain-ai/open-swe/issues) or submit a pull request with a new feature or bug fix.
+</Accordion>

src/images/gh_app_token_screenshot_2.png

@@ -61,25 +61,25 @@ Before starting, ensure you have the following installed:
     Fill in the following variables (GitHub App values will be added in the next step):
 
     ```bash Environment Variables [expandable]
+    # API URLs for development
+    NEXT_PUBLIC_API_URL="http://localhost:3000/api"
+    LANGGRAPH_API_URL="http://localhost:2024"
+
+    # Encryption key for secrets (generate with: openssl rand -hex 32)
+    SECRETS_ENCRYPTION_KEY=""
+
     # GitHub App OAuth settings (will be filled after creating GitHub App)
     NEXT_PUBLIC_GITHUB_APP_CLIENT_ID=""
     GITHUB_APP_CLIENT_SECRET=""
     GITHUB_APP_REDIRECT_URI="http://localhost:3000/api/auth/github/callback"
 
-    # Encryption key for secrets (generate with: openssl rand -hex 32)
-    SECRETS_ENCRYPTION_KEY=""
-
     # GitHub App details (will be filled after creating GitHub App)
     GITHUB_APP_NAME="open-swe-dev"
     GITHUB_APP_ID=""
     GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
     ...add your private key here...
     -----END RSA PRIVATE KEY-----
     "
-
-    # API URLs for development
-    NEXT_PUBLIC_API_URL="http://localhost:3000/api"
-    LANGGRAPH_API_URL="http://localhost:2024"
     ```
 
     ### Agent Environment Variables (`apps/open-swe/.env`)
@@ -117,6 +117,9 @@ Before starting, ensure you have the following installed:
     PORT="2024"
     OPEN_SWE_APP_URL="http://localhost:3000"
     SECRETS_ENCRYPTION_KEY=""  # Must match web app value
+
+    # CI/CD. See the /labs/swe/setup/ci for more information
+    SKIP_CI_UNTIL_LAST_COMMIT="true"
     ```
 
     <Tip>
@@ -174,6 +177,15 @@ Before starting, ensure you have the following installed:
 
     **Account permissions:** None
 
+    This gif shows how/where to enable the permissions on the GitHub App:
+    <iframe
+      className="w-full aspect-video rounded-xl"
+      src="https://www.youtube.com/embed/FP02bprNtrA"
+      title="Permissions Walkthrough"
+      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+      allowFullScreen
+    ></iframe>
+
     ### Subscribe to Events
 
     - ✅ **Issues** - Required for webhook functionality
@@ -204,6 +216,28 @@ Before starting, ensure you have the following installed:
       2. Click "Generate a private key"
       3. Download the `.pem` file and copy its contents
       4. Format as a single line with `\\n` for line breaks, or use the multiline format shown in the example
+    - **GITHUB_APP_REDIRECT_URI**: Should be `http://localhost:3000/api/auth/github/callback` for local development, or `https://your-production-url.com/api/auth/github/callback` for production.
+    - **GITHUB_WEBHOOK_SECRET**: Generate and save this value:
+      ```bash
+      openssl rand -hex 32
+      ```
+      Add this value to `GITHUB_WEBHOOK_SECRET` in `apps/open-swe/.env` and `apps/web/.env`.
+
+    Below are screenshots showing where in the GitHub App settings you can find the values for the environment variables.
+
+    <Accordion title="GitHub App OAuth Settings">
+      The following screenshots show where to find the following values:
+
+      - `GITHUB_APP_ID`
+      - `NEXT_PUBLIC_GITHUB_APP_CLIENT_ID`
+      - `GITHUB_APP_CLIENT_SECRET`
+      - `GITHUB_APP_REDIRECT_URI`
+      - `GITHUB_APP_PRIVATE_KEY`
+
+      ![GitHub Secrets Screenshot 1](/images/gh_app_token_screenshot_1.png)
+      ![GitHub Secrets Screenshot 2](/images/gh_app_token_screenshot_2.png)
+      ![GitHub Secrets Screenshot 3](/images/gh_app_token_screenshot_3.png)
+    </Accordion>
 
     <Tip>
     Keep your GitHub App credentials secure and never commit them to version control. The `.env` files are already included in `.gitignore`.

src/images/gh_app_token_screenshot_3.png

@@ -0,0 +1,83 @@
+---
+title: Best Practices
+description: Guidelines for effective use of Open SWE
+---
+
+# Best Practices
+
+Follow these guidelines to get the best results from Open SWE.
+
+## Prompting Tips
+
+### Be Clear and Direct
+
+- Include specific file paths and function names in your requests. Open SWE preforms best when its given a clear starting point.
+- Provide concrete examples of what you want to achieve. Describe the end state you want to reach so Open SWE knows what it's working towards.
+
+### Create Custom Rules
+
+Create an `AGENTS.md` file in your repository root to provide project-specific context. This helps Open SWE understand your codebase conventions and requirements.
+
+<Tip>
+  See the [Custom Rules](/labs/swe/usage/custom-rules) page for detailed guidance on
+  setting up your `AGENTS.md` file.
+</Tip>
+
+### Keep Tasks Well-Scoped
+
+- Focus on one specific feature or fix per request
+- Break large changes into smaller, manageable tasks
+- Avoid combining multiple unrelated changes in a single request
+
+### Avoid Multiple Tasks
+
+Submit separate requests for different features or fixes. This allows Open SWE to:
+
+- Generate more focused plans
+- Provide better error handling
+- Make changes easier to review
+
+## Model Selection
+
+- **Claude Sonnet 4 (Default)**: The default model for planning, writing code, and reviewing changes. This model offers the best balance of performance, speed and cost.
+- **Claude Opus 4**: A larger, more powerful model for difficult, or open-ended tasks. Opus 4 is more expensive and slower, but will provide better results for complex tasks.
+
+### Avoid Other Models
+
+Although Open SWE allows you to select any model from Anthropic, OpenAI and Google, its prompts are tuned specifically for Anthropic models, and other providers will not preform as well.
+
+## Mode Selection
+
+### `open-swe` vs `open-swe-max`
+
+**`open-swe`**: Uses Claude Sonnet 4
+
+- Suitable for most development tasks
+- Faster execution
+- Cost-effective
+
+**`open-swe-max`**: Uses Claude Opus 4 (only for the planning and code writing agents)
+
+- For complex tasks requiring advanced reasoning
+- Higher quality output for challenging problems
+- More expensive but better for difficult tasks
+
+### Auto vs Manual Labels
+
+**Auto Mode (`-auto` labels)**
+
+It's recommended to use the auto mode for most tasks. Open SWE is very good at planning, and in most cases it does not need a manual review before execution.
+
+If you're running Open SWE against an open-ended or very complex task, you may want to use manual mode to review the plan before execution.
+
+## Label Reference
+
+- `open-swe`: Manual mode with Sonnet 4
+- `open-swe-auto`: Auto mode with Sonnet 4
+- `open-swe-max`: Manual mode with Opus 4
+- `open-swe-max-auto`: Auto mode with Opus 4
+
+<Note>
+  In development environments, append `-dev` to all labels (e.g.,
+  `open-swe-dev`, `open-swe-auto-dev`).
+</Note>