feat: docs for batch spec library and templates

docs/admin/config/batch_changes.mdx

@@ -344,12 +344,37 @@ However, if the user deletion is permanent, deleting both account and data, then
 
 ## Batch Spec Library
 
-<Callout type="note"> Batch Spec Library is currently in Experimental.</Callout>
+The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level.
 
-The Batch Spec Library is a collection of Batch Specs that can be used to create Batch Changes. Sourcegraph provides a few Batch Specs out of the box.
+The library distinguishes between [templates](#templates) and [library examples](#library-examples), where library examples are complete batch specs and templates are library examples with variables.
+
+Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library).
+
+As a site admin, you can [feature records](#featured-records) to highlight the most useful examples for your organization.
+
+### Library examples
+
+Library examples are complete batch specs intended for advanced users who are comfortable working with YAML and writing code. These examples serve as inspiration and starting points for custom batch changes, providing reference implementations that can be adapted to specific use cases.
+
+Library examples are visible in the library pane when you are in the batch spec editor. They are not displayed by default in the templates list which is the entry point for users creating a batch change. See [choosing a template](/batch-changes/create-a-batch-change#choosing-a-template) for more details.
+
+### Templates
+
+<Callout type="note">Templates are supported in Sourcegraph v6.6 and more.</Callout>
+
+Templates are like library examples, but with variables for easy reuse across multiple batch changes. Templates provide the simplest path for users to create batch changes without needing to learn Batch Spec YAML syntax. Users select from a curated list of templates and complete a form with the required parameters, making batch change creation accessible to all team members regardless of their technical background.
+
+A library example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed on the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change).
+
+You can use variables to replace any text in the batch spec, allowing for flexible customization of repository queries, commands, commit messages, and more, but not for the name of the batch change.
+
+### Managing the Batch Spec Library
+
+<Callout type="note">Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more.</Callout>
 
 Site admins can manage the library through the GraphQL mutations `createBatchSpecLibraryRecord`, `updateBatchSpecLibraryRecord`, and `deleteBatchSpecLibraryRecord`. Use the query `batchSpecLibrary` to list all available Batch Spec examples.
 
+
 ```graphql
 createBatchSpecLibraryRecord(name: "example", spec: "version: 2\nname: example") {
   id
@@ -371,16 +396,12 @@ batchSpecLibrary(first: 100) {
 }
 ```
 
-### Featured Templates
-
-<Callout type="note">Featured templates are supported in Sourcegraph v6.4 and more.</Callout>
+### Featured Records
 
-Site-admins can mark a template as featured by either clicking the star button next to the list of library records. Featured records will automatically move to a section atop the remaining library records.
+Site-admins can mark a record as featured by either clicking the star button next to the list of library records. Featured records will automatically move to a section atop the remaining library records. This will add or remove the `"featured"` [label](#labels).
 
 ### Labels
 
-<Callout type="note">Labels are supported in Sourcegraph v6.4 and more.</Callout>
-
 Batch Spec Library records support an optional `labels` field for categorization and filtering. Common labels include:
 
 - `"featured"` - Marks popular or recommended batch specs that are displayed in a "Featured Templates" section above the remaining examples
@@ -409,3 +430,38 @@ batchSpecLibrary(first: 100, labels: ["featured"]) {
   }
 }
 ```
+
+### Variables
+
+<Callout type="note">Variables are supported in Sourcegraph v6.6 and more.</Callout>
+
+Templates use variables to make batch specs adaptable to different scenarios. When creating a template, you can define placeholders for values that will vary between different uses of the template. Users filling out the template see these variables as form fields where they can enter specific values like repository names, file paths, or commit messages.
+
+<Callout type="note">You cannot use a variable for the batch change name.</Callout>
+
+The `libraryVariables` field accepts an array of variable objects, each with the following configuration options:
+
+- **Name**: The variable identifier used in the template
+- **Display name**: Optional human-readable name shown in the form interface
+- **Pattern**: Regular expression for input validation
+- **Description**: Help text shown to users explaining what the variable is for
+- **Mandatory**: Boolean field indicating whether the variable is required
+- **Level**: Validation message severity level (`INFO`, `WARNING`, or `ERROR`)
+
+You can create templates by adding the `libraryVariables` field to the `createBatchSpecLibraryRecord` mutation. Here's an example that creates a simple template:
+
+```graphql
+createBatchSpecLibraryRecord(name:"Hello World Template",
+libraryVariables: [{
+    name:"REPOSITORY_QUERY",
+    displayName:"Repository Search Query",
+    pattern: ".+",
+    description:"The search query to find repositories.",
+    mandatory:true,
+    level:ERROR
+  }], spec: "version: 2\nname: hello-world\ndescription: Add Hello World to READMEs\n\non:\n  - repositoriesMatchingQuery: $REPOSITORY_QUERY\n\nsteps:\n  - run: echo Hello World | tee -a README.md\n    container: alpine:3\n\nchangesetTemplate:\n  title: Hello World\n  body: Add Hello World to README\n  branch: hello-world\n  commit:\n    message: Add Hello World to README") {
+    id
+  }
+```
+
+To update or remove variables from an existing template, you will need to recreate the entire batch spec library record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations.

docs/batch-changes/create-a-batch-change.mdx

@@ -4,14 +4,91 @@
 
 Batch Changes are created by writing a [batch spec](/batch-changes/batch-spec-yaml-reference) and executing that batch spec with the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli) `src`.
 
+There are two ways of creating a batch change:
+
+1. On your Sourcegraph instance, with [server-side execution](#on-your-sourcegraph-instance)
+2. On your local machine, with the [Sourcegraph CLI](#using-the-sourcegraph-cli)
+
+## On your Sourcegraph instance
+
+Here, you'll learn how to create and run a batch change via server-side execution.
+
+To get started, click the **Batch Changes** icon in the top navigation or navigate to `/batch-changes`.
+
+### Create a batch change
+
+Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.
+
+![create_batch_change_button](https://sourcegraphstatic.com/docs/images/batch_changes/2025/create_batch_change_button.png)
+
+You will be redirected to a page showing you a list of curated templates.
+
+### Choosing a template
+
+<Callout type="info">Templates is a feature available in Sourcegraph 6.6 and later.</Callout>
+
+From the template selection page, you can either:
+
+- **Pick a template** from the list of curated templates that best matches your use case
+- **Click "Start from Scratch"** if you prefer to start with a blank spec
+
+![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png)
+
+Your site admin can curate the list of available templates to match your organization's specific needs and use cases.
+
+### Filling out template fields
+
+If you selected a template, you will need to fill out the form fields specific to that template. These fields will customize the batch spec to your specific requirements.
+
+![templates_form](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_form.png)
+
+The form fields are validated by regular expressions. If the validation fails, look at the description of that field to see what kind of value is required. If you have suggestions for improving the field descriptions, reach out to your site admin who can update these template fields.
+
+### Choose a name for your batch change
+
+After you've filled out the template form fields, or after you clicked "Start from Scratch", you will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.
+
+![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)
+
+Once done, click **Create**.
+
+### Previewing batch spec and workspaces
+
+You can now see the batch spec and run a preview of the affected repositories and workspaces from the right-hand side panel. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.
+
 Batch Changes can also be used on [multiple projects within a monorepo](/batch-changes/creating-changesets-per-project-in-monorepos) by using the `workspaces` key in your batch spec.
 
-There are two ways of creating a batch change:
+The library contains examples that you can apply right into your batch spec if you need inspiration. Your site admin can manage the library of examples.
+
+![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)
+
+### Executing your batch spec
 
-1. On your local machine, with the [Sourcegraph CLI](#create-a-batch-change-with-the-sourcegraph-cli)
-2. Remotely, with [server-side execution](/batch-changes/server-side)
+When the spec is ready to run, ensure the preview is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:
 
-## Create a batch change with the Sourcegraph CLI
+- Run statistics at the top
+- All the workspaces, including status and diff stat, in the left panel
+- Details on a particular workspace on the right-hand side panel where you can see steps with:
+  - Logs
+  - Results
+  - Command
+  - Per-step diffs
+  - Output variables
+  - Execution timelines for debugging
+
+Once finished, you can proceed to the batch spec preview, as you know it from before.
+
+![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)
+
+### Previewing and applying the batch spec
+
+On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**.
+
+Congratulations, you ran your first batch change server-side 🎊
+
+![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)
+
+## Using the Sourcegraph CLI
 
 This part of the guide will walk you through creating a batch change on your local machine with the Sourcegraph CLI.
 
@@ -83,7 +160,7 @@ src batch preview -f YOUR_BATCH_SPEC.yaml
 
 After you've applied a batch spec, you can [publish changesets](/batch-changes/publishing-changesets) to the code host when you're ready. This will turn the patches into commits, branches, and changesets (such as GitHub pull requests) for others to review and merge.
 
-You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/create-a-batch-change#viewing-batch-changes).
+You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/view-batch-changes).
 
 If a user viewing the batch change lacks read access to a repository in the batch change, they can only see [limited information about the changes to that repository](/batch-changes/permissions-in-batch-changes#repository-permissions-for-batch-changes) (and not the repository name, file paths, or diff).
 
@@ -114,88 +191,3 @@ src batch preview -f your_batch_spec.yaml -namespace <SOURCEGRAPH_USERNAME_OR_OR
 ```
 
 When creating a batch change server-side using the UI, you can select the namespace to which the batch change belongs when you create it.
-
-### Administration
-
-Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.
-
-## Create a batch change with server-side execution
-
-Here, you'll learn how to create and run a batch change via server-side execution.
-
-Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.
-You will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.
-
-![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)
-
-Once done, click **Create**.
-
-### Editing the spec file
-
-You should see the editor view now. This view consists of three main areas:
-
-- The library sidebar panel on the left
-- The editor in the middle
-- The workspaces preview panel on the right
-
-![ssbc_editor_panels](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_editor_panels.png)
-
-You can pick from the examples in the library pane to get started quickly or begin working on your batch spec in the editor right away. Site admins can configure the examples. The editor will provide documentation as you hover over tokens in the YAML spec and supports auto-completion.
-
-### Previewing workspaces
-
-Once satisfied or to test your batch change's scope, you can run a new preview from the right-hand side panel at any time. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.
-
-![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)
-
-### Executing your batch spec
-
-When the spec is ready to run, ensure the preview is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:
-
-- Run statistics at the top
-- All the workspaces, including status and diff stat, in the left panel
-- Details on a particular workspace on the right-hand side panel where you can see steps with:
-  - Logs
-  - Results
-  - Command
-  - Per-step diffs
-  - Output variables
-  - Execution timelines for debugging
-
-Once finished, you can proceed to the batch spec preview, as you know it from before.
-
-![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)
-
-### Previewing and applying the batch spec
-
-On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**.
-
-Congratulations, you ran your first batch change server-side 🎊
-
-![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)
-
-## Viewing batch changes
-
-You can view a list by clicking the **Batch Changes** icon in the top navigation bar:
-
-![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png)
-
-### Title-based search
-
-You can search through your previously created batch changes by title. This search experience makes it much easier to find the batch change you’re looking for, especially when you have large volumes of batch changes to monitor.
-
-Start typing the keywords that match the batch change’s title, and you will see a list of relevant results.
-
-![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png)
-
-## Filtering Batch Changes
-
-You can also use the filters to switch between showing all open or closed Batch Changes.
-
-![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)
-
-## Filtering changesets
-
-When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:
-
-![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)

docs/batch-changes/view-batch-changes.mdx

@@ -0,0 +1,33 @@
+# Viewing Batch Changes
+
+<p className="subtitle">Learn how to view, search, and filter your Batch Changes.</p>
+
+## Viewing batch changes
+
+You can view a list by clicking the **Batch Changes** icon in the top navigation bar:
+
+![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png)
+
+### Title-based search
+
+You can search through your previously created batch changes by title. This search experience makes it much easier to find the batch change you're looking for, especially when you have large volumes of batch changes to monitor.
+
+Start typing the keywords that match the batch change's title, and you will see a list of relevant results.
+
+![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png)
+
+## Filtering Batch Changes
+
+You can also use the filters to switch between showing all open or closed Batch Changes.
+
+![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)
+
+## Filtering changesets
+
+When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:
+
+![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)
+
+## Administration
+
+Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.

src/data/navigation.ts

@@ -280,19 +280,27 @@ export const navigation: NavigationItem[] = [
 						href: '/batch-changes/create-a-batch-change',
 						subsections: [
 							{
-								title: 'Update a Batch Change',
-								href: '/batch-changes/update-a-batch-change'
+								title: 'Sourcegraph UI',
+								href: '/batch-changes/create-a-batch-change#on-your-sourcegraph-instance'
 							},
 							{
-								title: 'Close a Batch Change',
-								href: '/batch-changes/delete-a-batch-change'
-							},
-							{
-								title: 'Run Server Side',
-								href: '/batch-changes/server-side'
+								title: 'Sourcegraph CLI',
+								href: '/batch-changes/create-a-batch-change#using-the-sourcegraph-cli'
 							}
 						]
 					},
+					{
+						title: 'View Batch Changes',
+						href: '/batch-changes/view-batch-changes'
+					},
+					{
+						title: 'Update a Batch Change',
+						href: '/batch-changes/update-a-batch-change'
+					},
+					{
+						title: 'Close a Batch Change',
+						href: '/batch-changes/delete-a-batch-change'
+					},
 					{
 						title: 'Bulk Operations',
 						href: '/batch-changes/bulk-operations-on-changesets',