diff --git a/client/src/api/schema/schema.ts b/client/src/api/schema/schema.ts
index 2a72325f27a0..53e1f5ae6f21 100644
--- a/client/src/api/schema/schema.ts
+++ b/client/src/api/schema/schema.ts
@@ -14887,7 +14887,19 @@ export interface components {
             /** Message */
             message: string;
         };
-        /** InferredColumnMapping */
+        /**
+         * InferredColumnMapping
+         * @description Records that a column at a specific index was successfully parsed and mapped.
+         *
+         *     Used in parse logs to show users which columns were recognized and how they were interpreted.
+         *
+         *     Example log entry:
+         *         InferredColumnMapping(
+         *             column_index=2,
+         *             column_title="MD5 Sum",
+         *             parsed_column=ParsedColumn(type="hash_md5", type_index=0, title="MD5 Sum")
+         *         )
+         */
         InferredColumnMapping: {
             /** Column Index */
             column_index: number;
@@ -18660,7 +18672,12 @@ export interface components {
              */
             content: string;
         };
-        /** ParsedColumn */
+        /**
+         * ParsedColumn
+         * @description Serializable representation of a parsed column (Pydantic model version of HeaderColumn).
+         *
+         *     Used in API responses and logging to communicate which columns were recognized.
+         */
         ParsedColumn: {
             /** Title */
             title: string;
diff --git a/client/src/components/ActivityBar/ActivitySettings.vue b/client/src/components/ActivityBar/ActivitySettings.vue
index 9113d5eb0923..8423f4713e34 100644
--- a/client/src/components/ActivityBar/ActivitySettings.vue
+++ b/client/src/components/ActivityBar/ActivitySettings.vue
@@ -88,6 +88,8 @@ function executeActivity(activity: Activity) {
                 v-for="activity in filteredActivities"
                 :key="activity.id"
                 class="activity-settings-item p-2 cursor-pointer"
+                :data-activity-id="activity.id"
+                :data-activity-visible="!!activity.visible"
                 @click="executeActivity(activity)">
                 <div class="d-flex justify-content-between align-items-start">
                     <span class="d-flex justify-content-between w-100">
diff --git a/client/src/components/Collections/wizard/CardDownloadWorkbook.vue b/client/src/components/Collections/wizard/CardDownloadWorkbook.vue
index 9b638b161c32..e20107cc0a43 100644
--- a/client/src/components/Collections/wizard/CardDownloadWorkbook.vue
+++ b/client/src/components/Collections/wizard/CardDownloadWorkbook.vue
@@ -21,7 +21,7 @@ const emit = defineEmits(["download"]);
         <BCardTitle>
             <b>Step 1: Download</b>
         </BCardTitle>
-        <BLink :href="generateWorkbookLink" @click="emit('download')"
+        <BLink data-description="workbook download link" :href="generateWorkbookLink" @click="emit('download')"
             ><FontAwesomeIcon size="xl" :icon="faDownload" /> Download workbook.</BLink
         >
     </BCard>
diff --git a/client/src/components/Collections/wizard/CardUploadWorkbook.vue b/client/src/components/Collections/wizard/CardUploadWorkbook.vue
index 602922dfa522..264d5b273947 100644
--- a/client/src/components/Collections/wizard/CardUploadWorkbook.vue
+++ b/client/src/components/Collections/wizard/CardUploadWorkbook.vue
@@ -24,6 +24,7 @@ const emit = defineEmits(["workbookContents"]);
 </script>
 <template>
     <BCard
+        data-description="workbook upload card"
         data-galaxy-file-drop-target
         :class="dropZoneClasses"
         @drop.prevent="handleDrop"
@@ -38,7 +39,7 @@ const emit = defineEmits(["workbookContents"]);
             </BAlert>
         </div>
         <div>
-            <BLink href="#" @click.prevent="browseFiles">
+            <BLink data-description="workbook upload link" href="#" @click.prevent="browseFiles">
                 <FontAwesomeIcon size="xl" :icon="faUpload" />
                 Drop completed workbook here or click to upload.
             </BLink>
diff --git a/client/src/components/Collections/wizard/HiddenWorkbookUploadInput.vue b/client/src/components/Collections/wizard/HiddenWorkbookUploadInput.vue
index 8760e308d633..0c01a3328cdf 100644
--- a/client/src/components/Collections/wizard/HiddenWorkbookUploadInput.vue
+++ b/client/src/components/Collections/wizard/HiddenWorkbookUploadInput.vue
@@ -19,6 +19,11 @@ defineExpose({
 
 <template>
     <label style="display: none">
-        <input ref="fileInputRef" type="file" accept=".xlsx,.xls,.tsv,.csv,.tabular" @change="onFileUpload" />
+        <input
+            ref="fileInputRef"
+            data-description="workbook-file-input"
+            type="file"
+            accept=".xlsx,.xls,.tsv,.csv,.tabular"
+            @change="onFileUpload" />
     </label>
 </template>
diff --git a/client/src/components/Collections/wizard/UploadFetchWorkbook.vue b/client/src/components/Collections/wizard/UploadFetchWorkbook.vue
index 428d17fbc46b..68ce0dec6ff8 100644
--- a/client/src/components/Collections/wizard/UploadFetchWorkbook.vue
+++ b/client/src/components/Collections/wizard/UploadFetchWorkbook.vue
@@ -2,6 +2,8 @@
 import { BCardGroup } from "bootstrap-vue";
 import { computed } from "vue";
 
+import { withPrefix } from "@/utils/redirect";
+
 import type { ParsedFetchWorkbookForCollectionCollectionType, RulesCreatingWhat } from "./types";
 
 import CardDownloadWorkbook from "./CardDownloadWorkbook.vue";
@@ -25,7 +27,7 @@ const emit = defineEmits(["workbookContents"]);
 const generateWorkbookHref = computed(() => {
     let type;
     if (props.creatingWhat === "datasets") {
-        type = "dataset";
+        type = "datasets";
     } else if (props.includeCollectionName) {
         type = "collections";
     } else {
@@ -36,7 +38,7 @@ const generateWorkbookHref = computed(() => {
     if (type === "collection" || type === "collections") {
         url = `${url}&collection_type=${props.collectionType}`;
     }
-    return url;
+    return withPrefix(url);
 });
 </script>
 
diff --git a/client/src/utils/navigation/navigation.yml b/client/src/utils/navigation/navigation.yml
index 220639fb564d..d7060af29fa8 100644
--- a/client/src/utils/navigation/navigation.yml
+++ b/client/src/utils/navigation/navigation.yml
@@ -170,6 +170,12 @@ dataset_display:
     container: .dataset-display
     content: body
 
+activity_bar:
+  selectors:
+    settings: "#activity-settings"
+    show_activity: "button[data-activity-id='${activity_id}'] button"
+    additional_activities: '[data-description="Additional Activities"]'
+
 history_panel:
   menu:
     labels:
@@ -1386,6 +1392,17 @@ rule_builder:
     table: '#rules-ag-grid .ag-root'
     extension_select: '.rule-footer-extension-group .extension-select'
 
+    activity: '#activity-rules'
+    workbook_upload_button: '.workbook-upload-helper'
+    workbook_upload_file_input: '[data-description="workbook-file-input"]'
+    create_collections: '[data-creating-what="collections"]'
+    wizard_import: ".wizard-actions .btn-primary"
+    wizard_next: ".wizard-actions .go-next-btn"
+    data_import_source_from: '[data-import-source-from="${source}"]'
+    workbook_download_link: '[data-description="workbook download link"]'
+    workbook_upload_link: '[data-description="workbook upload card"] [data-description="workbook upload link"]'
+    workbook_upload_file_input_explicit: '[data-description="workbook upload card"] [data-description="workbook-file-input"]'
+
 charts:
   selectors:
     visualize_button: '.ui-portlet .button i.fa-line-chart'  # without icon - it waits on other buttons that aren't visible, need more specific class
diff --git a/lib/galaxy/managers/configuration.py b/lib/galaxy/managers/configuration.py
index 30081f547784..0c63d1312055 100644
--- a/lib/galaxy/managers/configuration.py
+++ b/lib/galaxy/managers/configuration.py
@@ -13,9 +13,9 @@
 
 from galaxy.managers import base
 from galaxy.managers.context import ProvidesUserContext
-from galaxy.managers.markdown_util import weasyprint_available
 from galaxy.schema import SerializationParams
 from galaxy.structured_app import StructuredApp
+from galaxy.util.markdown import weasyprint_available
 
 log = logging.getLogger(__name__)
 
diff --git a/lib/galaxy/managers/markdown_util.py b/lib/galaxy/managers/markdown_util.py
index 1388f79ec62d..823acf22f0fa 100644
--- a/lib/galaxy/managers/markdown_util.py
+++ b/lib/galaxy/managers/markdown_util.py
@@ -16,8 +16,6 @@
 import logging
 import os
 import re
-import shutil
-import tempfile
 from datetime import datetime
 from re import Match
 from typing import (
@@ -25,13 +23,6 @@
     Optional,
 )
 
-import markdown
-
-try:
-    import weasyprint
-except Exception:
-    weasyprint = None
-
 from galaxy.config import GalaxyAppConfiguration
 from galaxy.exceptions import (
     MalformedContents,
@@ -54,9 +45,11 @@
     ShortTermStorageMonitor,
     storage_context,
 )
-from galaxy.util.markdown import literal_via_fence
-from galaxy.util.resources import resource_string
-from galaxy.util.sanitize_html import sanitize_html
+from galaxy.util.markdown import (
+    literal_via_fence,
+    to_pdf_raw,
+    weasyprint_available,
+)
 from .markdown_parse import (
     EMBED_DIRECTIVE_REGEX,
     GALAXY_MARKDOWN_FUNCTION_CALL_LINE,
@@ -915,38 +908,6 @@ def to_basic_markdown(trans, internal_galaxy_markdown: str) -> str:
     return plain_markdown
 
 
-def to_html(basic_markdown: str) -> str:
-    # Allow data: urls so we can embed images.
-    html = sanitize_html(markdown.markdown(basic_markdown, extensions=["tables"]), allow_data_urls=True)
-    return html
-
-
-def to_pdf_raw(basic_markdown: str, css_paths: Optional[list[str]] = None) -> bytes:
-    """Convert RAW markdown with specified CSS paths into bytes of a PDF."""
-    css_paths = css_paths or []
-    as_html = to_html(basic_markdown)
-    directory = tempfile.mkdtemp("gxmarkdown")
-    index = os.path.join(directory, "index.html")
-    try:
-        output_file = open(index, "w", encoding="utf-8", errors="xmlcharrefreplace")
-        output_file.write(as_html)
-        output_file.close()
-        html = weasyprint.HTML(filename=index)
-        stylesheets = [weasyprint.CSS(string=resource_string(__name__, "markdown_export_base.css"))]
-        for css_path in css_paths:
-            with open(css_path) as f:
-                css_content = f.read()
-            css = weasyprint.CSS(string=css_content)
-            stylesheets.append(css)
-        return html.write_pdf(stylesheets=stylesheets)
-    finally:
-        shutil.rmtree(directory)
-
-
-def weasyprint_available() -> bool:
-    return weasyprint is not None
-
-
 def _check_can_convert_to_pdf_or_raise():
     """Checks if the HTML to PDF converter is available."""
     if not weasyprint_available():
diff --git a/lib/galaxy/managers/notification.py b/lib/galaxy/managers/notification.py
index 35584274b4fb..e6a0dd67a4d5 100644
--- a/lib/galaxy/managers/notification.py
+++ b/lib/galaxy/managers/notification.py
@@ -36,7 +36,6 @@
     ConfigDoesNotAllowException,
     ObjectNotFound,
 )
-from galaxy.managers.markdown_util import to_html
 from galaxy.model import (
     GroupRoleAssociation,
     Notification,
@@ -64,6 +63,7 @@
     UserNotificationPreferences,
     UserNotificationUpdateRequest,
 )
+from galaxy.util.markdown import to_html
 
 log = logging.getLogger(__name__)
 
diff --git a/lib/galaxy/model/dataset_collections/rule_target_column_specification.yml b/lib/galaxy/model/dataset_collections/rule_target_column_specification.yml
index 8df4d6561556..bdc950e620ae 100644
--- a/lib/galaxy/model/dataset_collections/rule_target_column_specification.yml
+++ b/lib/galaxy/model/dataset_collections/rule_target_column_specification.yml
@@ -1,8 +1,32 @@
-# The idea that we reserve some column names for reserved purposes in Galaxy
-# is going to span fetch workbooks and sample sheet workbooks - and we need
-# to validate it both on the backend and the frontend. So having a set of tests
-# that validate what are reserved column names that we can run across both languages
-# utilities for doing this is valuable.
+# Test Specification: Column Header to Target Type Mappings
+#
+# This file defines test cases for Galaxy's flexible column header parsing system.
+# Each test case specifies:
+#   - doc: Human-readable description
+#   - column_header: The user-provided column header (as it appears in workbook)
+#   - maps_to: The expected internal target type key
+#
+# Purpose:
+#   Galaxy needs to recognize column headers in workbooks (Excel/CSV) across different
+#   naming conventions and formats. This specification serves as:
+#   1. Test cases for backend Python parsing (column_title_to_target_type)
+#   2. Test cases for frontend TypeScript parsing (when implemented)
+#   3. Documentation of supported column header variations
+#
+# The parsing is case-insensitive and ignores:
+#   - Whitespace
+#   - Special characters: ( ) - _
+#   - The word "optional"
+#
+# Examples of flexible parsing:
+#   "Name", "name", "NAME"                     -> "name"
+#   "MD5 Sum", "MD5", "Hash MD5", "md5sum"     -> "hash_md5"
+#   "URI 1 (Forward)", "url", "URL"            -> "url"
+#   "Genome Build", "DBKey", "genome"          -> "dbkey"
+#
+# Test Execution:
+#   Python: test/unit/data/dataset_collections/test_column_to_target_mapping.py
+#   TypeScript: (future implementation)
 
 - doc: "Name (with uppercase) maps directly to the name target type"
   column_header: "Name"
diff --git a/lib/galaxy/model/dataset_collections/rule_target_columns.py b/lib/galaxy/model/dataset_collections/rule_target_columns.py
index 0737ae275553..489718d23263 100644
--- a/lib/galaxy/model/dataset_collections/rule_target_columns.py
+++ b/lib/galaxy/model/dataset_collections/rule_target_columns.py
@@ -1,3 +1,28 @@
+"""Column header parsing for workbook uploads.
+
+This module handles the flexible parsing of user-provided column headers in workbooks
+(Excel/CSV files) and maps them to Galaxy's internal column target types.
+
+Key Concept - Flexible Header Parsing:
+    Users can write column headers in many ways:
+    - "Name", "name", "NAME"           -> all map to "name"
+    - "URI", "URL", "uri"              -> all map to "url"
+    - "MD5 Sum", "MD5", "Hash MD5"     -> all map to "hash_md5"
+    - "Genome", "DBKey", "build"       -> all map to "dbkey"
+
+The parsing logic:
+    1. Normalizes the header (removes whitespace, special chars, case-insensitive)
+    2. Checks exact match against known prefixes
+    3. Checks prefix/suffix match if no exact match
+    4. Returns the target type key or None if not recognized
+
+Example Flow:
+    User workbook header: "MD5 Sum (Optional)"
+    ↓ Normalize: "md5sum" (removed spaces, parens, "optional", lowercased)
+    ↓ Match: Found in COLUMN_TITLE_PREFIXES["md5sum"] = "hash_md5"
+    ↓ Result: HeaderColumn(type="hash_md5", title="MD5 Sum (Optional)", type_index=0)
+"""
+
 import re
 from dataclasses import dataclass
 from typing import (
@@ -12,42 +37,56 @@
     target_model_by_type,
 )
 
+# Mapping of normalized column header text to target type keys
+# All keys are lowercase with no spaces/special chars
+# Used for flexible parsing: "MD5 Sum" -> normalize to "md5sum" -> maps to "hash_md5"
 COLUMN_TITLE_PREFIXES: dict[str, RuleBuilderMappingTargetKey] = {
+    # Dataset naming
     "name": "name",
     "listname": "collection_name",
     "collectionname": "collection_name",
+    # URI/URL columns - where to get the data
     "uri": "url",
     "url": "url",
     "urldeferred": "url_deferred",
     "deferredurl": "url_deferred",
+    # Genome/reference information
     "genome": "dbkey",
     "dbkey": "dbkey",
     "genomebuild": "dbkey",
     "build": "dbkey",
+    # File type/extension
     "filetype": "file_type",
     "extension": "file_type",
     "fileextension": "file_type",
     "type": "file_type",
+    # Metadata fields
     "info": "info",
+    # Tagging
     "tag": "tags",
     "grouptag": "group_tags",
     "nametag": "name_tag",
+    # Collection structure
     "listidentifier": "list_identifiers",
     "pairedidentifier": "paired_identifier",
+    # MD5 hashes - all variations
     "hashmd5sum": "hash_md5",
     "hashmd5": "hash_md5",
     "md5sum": "hash_md5",
     "md5": "hash_md5",
+    # SHA-1 hashes - all variations
     "sha1hash": "hash_sha1",
     "hashsha1sum": "hash_sha1",
     "hashsha1": "hash_sha1",
     "sha1sum": "hash_sha1",
     "sha1": "hash_sha1",
+    # SHA-256 hashes - all variations
     "sha256hash": "hash_sha256",
     "hashsha256sum": "hash_sha256",
     "hashsha256": "hash_sha256",
     "sha256sum": "hash_sha256",
     "sha256": "hash_sha256",
+    # SHA-512 hashes - all variations
     "sha512hash": "hash_sha512",
     "hashsha512sum": "hash_sha512",
     "hashsha512": "hash_sha512",
@@ -57,8 +96,39 @@
 
 
 def column_title_to_target_type(column_title: str) -> Optional[RuleBuilderMappingTargetKey]:
+    """Parse a column header string and map it to a target type.
+
+    This function implements Galaxy's flexible column header parsing logic:
+    1. Normalize the header (lowercase, remove spaces/parens/dashes/underscores/"optional")
+    2. Try exact match against known headers
+    3. Try prefix/suffix matching if no exact match
+    4. Return the target type or None if not recognized
+
+    Args:
+        column_title: The raw column header from the workbook (e.g., "MD5 Sum (Optional)")
+
+    Returns:
+        The target type key (e.g., "hash_md5") or None if not recognized
+
+    Examples:
+        >>> column_title_to_target_type("Name")
+        'name'
+        >>> column_title_to_target_type("MD5 Sum")
+        'hash_md5'
+        >>> column_title_to_target_type("URI 1 (Forward)")
+        'url'
+        >>> column_title_to_target_type("Genome Build")
+        'dbkey'
+        >>> column_title_to_target_type("Unknown Column") is None
+        True
+    """
+    # Normalize: lowercase, remove whitespace/parens/dashes/underscores and "optional"
     normalized_title = re.sub(r"[\s\(\)\-\_]|optional", "", column_title.lower())
+
+    # First, try exact match
     if normalized_title not in COLUMN_TITLE_PREFIXES:
+        # If no exact match, try prefix/suffix matching
+        # This allows "URI 1 Forward" to match "uri" prefix
         for key in COLUMN_TITLE_PREFIXES.keys():
             if normalized_title.startswith(key):
                 normalized_title = key
@@ -67,6 +137,7 @@ def column_title_to_target_type(column_title: str) -> Optional[RuleBuilderMappin
                 normalized_title = key
                 break
 
+    # If still not found, return None
     if normalized_title not in COLUMN_TITLE_PREFIXES:
         return None
 
@@ -76,14 +147,39 @@ def column_title_to_target_type(column_title: str) -> Optional[RuleBuilderMappin
 
 @dataclass
 class HeaderColumn:
+    """Represents a parsed column header with its metadata.
+
+    When processing a workbook, each column header is parsed into a HeaderColumn
+    that tracks both the original user-facing title and the normalized target type.
+
+    The type_index allows for multiple columns of the same type:
+    - First URI column: HeaderColumn(type="url", title="URI 1", type_index=0)
+    - Second URI column: HeaderColumn(type="url", title="URI 2", type_index=1)
+
+    Attributes:
+        type: The normalized target type key (e.g., "url", "name", "hash_md5")
+        title: The original user-facing column header (e.g., "MD5 Sum (Optional)")
+        type_index: Index when multiple columns of same type exist (0 for first, 1 for second, etc.)
+
+    Examples:
+        # Single name column
+        HeaderColumn(type="name", title="Name", type_index=0)
+        # -> name property returns: "name"
+
+        # First and second URI columns for paired data
+        HeaderColumn(type="url", title="URI 1 (Forward)", type_index=0)
+        # -> name property returns: "url"
+        HeaderColumn(type="url", title="URI 2 (Reverse)", type_index=1)
+        # -> name property returns: "url_1"
+    """
+
     type: RuleBuilderMappingTargetKey
     title: str  # user facing
-    # e.g. for paired data will have two columns of URIs, record types maybe have any number
-    # and after dataset hash may have multiples of those also
-    type_index: int
+    type_index: int  # 0 for first occurrence, 1 for second, etc.
 
     @property
     def width(self):
+        """Column width for Excel display - URIs need more space."""
         if self.type in ["url", "url_deferred", "ftp_path"]:
             return 50
         else:
@@ -91,6 +187,11 @@ def width(self):
 
     @property
     def name(self):
+        """Internal column name used as dictionary key.
+
+        Returns the type for first occurrence (index 0), otherwise type_index is appended.
+        Examples: "url", "url_1", "list_identifiers", "list_identifiers_1"
+        """
         if self.type_index == 0:
             return self.type
         else:
@@ -98,12 +199,13 @@ def name(self):
 
     @property
     def help(self) -> str:
+        """Get the help text for this column type from rule_targets.yml."""
         column_target = _column_header_to_column_target(self)
         return column_target.help if column_target.help else ""
 
     @property
     def parsed_column(self) -> "ParsedColumn":
-        """Return a ParsedColumn representation of this header."""
+        """Return a ParsedColumn representation of this header for serialization."""
         return ParsedColumn(
             type=self.type,
             type_index=self.type_index,
@@ -112,16 +214,23 @@ def parsed_column(self) -> "ParsedColumn":
 
 
 def _column_header_to_column_target(column_header: HeaderColumn) -> ColumnTarget:
+    """Lookup the ColumnTarget definition for a HeaderColumn."""
     return target_model_by_type(column_header.type)
 
 
 class ParsedColumn(BaseModel):
+    """Serializable representation of a parsed column (Pydantic model version of HeaderColumn).
+
+    Used in API responses and logging to communicate which columns were recognized.
+    """
+
     type: RuleBuilderMappingTargetKey
     type_index: int
     title: str
 
     @property
     def name(self):
+        """Internal column name - matches HeaderColumn.name logic."""
         if self.type_index == 0:
             return self.type
         else:
@@ -129,6 +238,18 @@ def name(self):
 
 
 class InferredColumnMapping(BaseModel):
+    """Records that a column at a specific index was successfully parsed and mapped.
+
+    Used in parse logs to show users which columns were recognized and how they were interpreted.
+
+    Example log entry:
+        InferredColumnMapping(
+            column_index=2,
+            column_title="MD5 Sum",
+            parsed_column=ParsedColumn(type="hash_md5", type_index=0, title="MD5 Sum")
+        )
+    """
+
     column_index: int
     column_title: str
     parsed_column: ParsedColumn
@@ -137,29 +258,69 @@ class InferredColumnMapping(BaseModel):
 def column_titles_to_headers(
     column_titles: list[str], column_offset: int = 0
 ) -> tuple[list[HeaderColumn], list[InferredColumnMapping]]:
+    """Parse all column headers from a workbook and convert to HeaderColumn objects.
+
+    This is the main entry point for processing workbook column headers. It:
+    1. Iterates through all column titles
+    2. Attempts to parse each one using column_title_to_target_type()
+    3. Tracks type_index for duplicate column types (e.g., url, url_1)
+    4. Handles special case: "optional" paired identifiers -> paired_or_unpaired
+    5. Returns both the headers and a log of inferred mappings
+
+    Args:
+        column_titles: List of column header strings from the workbook
+        column_offset: Offset to add to column indices (default 0)
+
+    Returns:
+        Tuple of:
+        - headers: List of HeaderColumn objects for recognized columns
+        - inferred_columns: List of InferredColumnMapping log entries
+
+    Example:
+        Input: ["URI", "Name", "MD5", "URI 2 (Optional)"]
+        Output:
+        - headers: [
+            HeaderColumn(type="url", title="URI", type_index=0),
+            HeaderColumn(type="name", title="Name", type_index=0),
+            HeaderColumn(type="hash_md5", title="MD5", type_index=0),
+            HeaderColumn(type="url", title="URI 2 (Optional)", type_index=1)
+          ]
+        - inferred_columns: [list of InferredColumnMapping for each]
+
+    Note:
+        Unrecognized columns are silently skipped (not included in results).
+    """
     headers: list[HeaderColumn] = []
     headers_of_type_seen: dict[RuleBuilderMappingTargetKey, int] = {}
     inferred_columns: list[InferredColumnMapping] = []
 
     for column_index, column_title in enumerate(column_titles):
+        # Try to parse this column header
         column_type_: Optional[RuleBuilderMappingTargetKey] = column_title_to_target_type(column_title)
         if not column_type_:
-            # make a note in parse log that this column was skipped
+            # Column not recognized - skip it (could add to parse log here)
             continue
         column_type: RuleBuilderMappingTargetKey = column_type_
+
+        # Track how many times we've seen this type to assign type_index
         if column_type in headers_of_type_seen:
             type_index = headers_of_type_seen[column_type]
             headers_of_type_seen[column_type] += 1
         else:
             type_index = 0
             headers_of_type_seen[column_type] = 1
+
+        # Create the header column
         header_column = HeaderColumn(
             type=column_type,
             type_index=type_index,
             title=column_title,
         )
+
+        # Special case: paired identifier with "optional" in title becomes paired_or_unpaired
         if header_column.type == "paired_identifier" and implied_paired_or_unpaired_column_header(header_column):
             header_column.type = "paired_or_unpaired_identifier"
+
         headers.append(header_column)
         inferred_columns.append(
             InferredColumnMapping(
@@ -172,6 +333,16 @@ def column_titles_to_headers(
 
 
 def implied_paired_or_unpaired_column_header(column_header: HeaderColumn) -> bool:
-    # URI 2 - Reverse (Optional), Optional URI 2, Optional Paired Identifier all
-    # imply paired_or_unpaired lists using this logic.
+    """Check if a column header implies optional pairing (paired_or_unpaired).
+
+    If "optional" appears in the title, it signals that this column can have empty values,
+    allowing for mixed paired and unpaired datasets in the same collection.
+
+    Examples that return True:
+    - "URI 2 - Reverse (Optional)"
+    - "Optional URI 2"
+    - "Optional Paired Identifier"
+
+    This is used to upgrade "paired_identifier" -> "paired_or_unpaired_identifier"
+    """
     return "optional" in column_header.title.lower()
diff --git a/lib/galaxy/model/dataset_collections/rule_target_models.py b/lib/galaxy/model/dataset_collections/rule_target_models.py
index bee11f31289f..f41132b28333 100644
--- a/lib/galaxy/model/dataset_collections/rule_target_models.py
+++ b/lib/galaxy/model/dataset_collections/rule_target_models.py
@@ -1,3 +1,18 @@
+"""Models for rule builder column targets.
+
+This module defines the data models and types used by Galaxy's workbook upload system
+to map user-provided column headers to specific metadata fields. When users upload
+Excel/CSV workbooks containing dataset URIs and metadata, these models define what
+column types are available and how they should be interpreted.
+
+Example workbook row:
+    URI                        | Name      | MD5                              | Genome
+    http://example.com/data.gz | Sample_1  | 5d41402abc4b2a76b9719d911017c592 | hg19
+
+The column headers "URI", "Name", "MD5", and "Genome" are parsed and mapped to
+target types "url", "name", "hash_md5", and "dbkey" respectively.
+"""
+
 from typing import (
     Literal,
     Optional,
@@ -11,7 +26,15 @@
 
 from galaxy.util.resources import resource_string
 
+# Defines whether a column target is used when importing individual datasets or collections
 RuleBuilderImportType = Literal["datasets", "collections"]
+
+# Defines the upload modes where a column target is applicable
+# - raw: Direct URI/URL upload
+# - ftp: FTP server upload
+# - datasets: Existing datasets in history
+# - library_datasets: Datasets from data libraries
+# - collection_contents: Elements from existing collections
 RuleBuilderModes = Literal[
     "raw",
     "ftp",
@@ -22,6 +45,29 @@
 
 
 class ColumnTarget(BaseModel):
+    """Defines a single column target type that can appear in a workbook.
+
+    Each target type represents a specific piece of metadata or structural information
+    that can be associated with uploaded datasets.
+
+    Attributes:
+        label: User-facing label for this column type in UI
+        help: Detailed help text explaining what this column is for
+        modes: Which upload modes support this column type (None = all modes)
+        importType: Whether used for datasets, collections, or both (None = both)
+        multiple: If True, can have multiple columns of this type (e.g., multiple tags)
+        columnHeader: Default header text when generating workbooks
+        advanced: If True, considered an advanced/optional column
+        requiresFtp: If True, only available when FTP upload is configured
+        example_column_names: Example header texts that would map to this target type
+
+    Example:
+        For the "hash_md5" target type:
+        - label: "Hash (MD5)"
+        - example_column_names: ["MD5", "MD5 hash", "MD5-Sum"]
+        - help: "This is the MD5 hash of the URI..."
+    """
+
     label: str
     help: Optional[str]
     modes: Optional[list[RuleBuilderModes]] = None
@@ -34,62 +80,93 @@ class ColumnTarget(BaseModel):
 
     @property
     def example_column_names_as_str(self) -> Optional[str]:
+        """Format example column names as a quoted, comma-separated string for display."""
         if self.example_column_names:
             return '"' + '", "'.join(self.example_column_names) + '"'
         return ""
 
 
+# All valid column target type identifiers used internally by Galaxy
+# These are the normalized keys that user-provided column headers map to
 RuleBuilderMappingTargetKey = Literal[
-    "list_identifiers",
-    "paired_identifier",
-    "paired_or_unpaired_identifier",
-    "collection_name",
-    "name_tag",
-    "tags",
-    "group_tags",
-    "name",
-    "dbkey",
-    "hash_sha1",
-    "hash_md5",
-    "hash_sha256",
-    "hash_sha512",
-    "file_type",
-    "url",
-    "url_deferred",
-    "info",
-    "ftp_path",
-    "deferred",
-    "to_posix_lines",
-    "space_to_tab",
-    "auto_decompress",
+    "list_identifiers",  # List structure identifiers (e.g., "Sample_A")
+    "paired_identifier",  # Paired-end indicator (1/2, forward/reverse)
+    "paired_or_unpaired_identifier",  # Optional paired-end indicator
+    "collection_name",  # Name for grouping datasets into collections
+    "name_tag",  # Name-based tags (propagated to derived datasets)
+    "tags",  # General purpose tags
+    "group_tags",  # Group tags for factorial experiments
+    "name",  # Dataset name in history
+    "dbkey",  # Genome build (e.g., hg19, mm10)
+    "hash_sha1",  # SHA-1 checksum for verification
+    "hash_md5",  # MD5 checksum for verification
+    "hash_sha256",  # SHA-256 checksum for verification
+    "hash_sha512",  # SHA-512 checksum for verification
+    "file_type",  # Galaxy datatype (e.g., fastqsanger, bam)
+    "url",  # URI/URL to download file from
+    "url_deferred",  # URI/URL for deferred download (on-demand)
+    "info",  # Unstructured text displayed in history
+    "ftp_path",  # Path relative to user's FTP directory
+    "deferred",  # Boolean: defer download until needed
+    "to_posix_lines",  # Boolean: convert line endings
+    "space_to_tab",  # Boolean: convert spaces to tabs
+    "auto_decompress",  # Boolean: auto-decompress if compressed
 ]
 
 
+# Mapping of target type keys to their full ColumnTarget definitions
 ColumnTargetsConfig = dict[RuleBuilderMappingTargetKey, ColumnTarget]
 ColumnTargetsConfigRootModel = RootModel[ColumnTargetsConfig]
 
 
 def target_models() -> ColumnTargetsConfig:
+    """Load all column target definitions from rule_targets.yml.
+
+    Returns:
+        Dictionary mapping target type keys (e.g., "name", "url") to their ColumnTarget definitions
+
+    Example:
+        targets = target_models()
+        name_target = targets["name"]
+        # name_target.label == "Name"
+        # name_target.help == "This is just the name of the dataset..."
+    """
     column_targets_str = resource_string(__name__, "rule_targets.yml")
     column_targets_raw = yaml.safe_load(column_targets_str)
     return ColumnTargetsConfigRootModel.model_validate(column_targets_raw).root
 
 
 def target_model_by_type(type: RuleBuilderMappingTargetKey) -> ColumnTarget:
+    """Get the ColumnTarget definition for a specific target type.
+
+    Args:
+        type: The target type key (e.g., "url", "name", "hash_md5")
+
+    Returns:
+        The ColumnTarget definition with label, help text, and other metadata
+
+    Example:
+        md5_target = target_model_by_type("hash_md5")
+        # md5_target.label == "Hash (MD5)"
+        # md5_target.example_column_names == ["MD5", "MD5 hash", "MD5-Sum"]
+    """
     return target_models()[type]
 
 
-# Any URI-based workbook should allow specifying these metadata column types.
+# Common metadata column types that should be available for any URI-based workbook upload.
+# These columns are universally applicable across different upload modes and provide
+# standard dataset metadata (names, genome builds, tags) and file integrity verification (hashes).
+# This list is used when generating workbook templates to show users what optional columns they can add.
 COMMON_COLUMN_TARGETS = [
-    target_model_by_type("name"),
-    target_model_by_type("dbkey"),
-    target_model_by_type("info"),
-    target_model_by_type("file_type"),
-    target_model_by_type("tags"),
-    target_model_by_type("group_tags"),
-    target_model_by_type("name_tag"),
-    target_model_by_type("hash_md5"),
-    target_model_by_type("hash_sha1"),
-    target_model_by_type("hash_sha256"),
-    target_model_by_type("hash_sha512"),
+    target_model_by_type("name"),  # Dataset name
+    target_model_by_type("dbkey"),  # Genome build
+    target_model_by_type("info"),  # Description text
+    target_model_by_type("file_type"),  # Galaxy datatype
+    target_model_by_type("tags"),  # General tags
+    target_model_by_type("group_tags"),  # Group tags
+    target_model_by_type("name_tag"),  # Name tags
+    target_model_by_type("hash_md5"),  # MD5 checksum
+    target_model_by_type("hash_sha1"),  # SHA-1 checksum
+    target_model_by_type("hash_sha256"),  # SHA-256 checksum
+    target_model_by_type("hash_sha512"),  # SHA-512 checksum
 ]
diff --git a/lib/galaxy/selenium/cli.py b/lib/galaxy/selenium/cli.py
index 04feb67de292..71ff7a64212a 100644
--- a/lib/galaxy/selenium/cli.py
+++ b/lib/galaxy/selenium/cli.py
@@ -6,17 +6,26 @@
 HEADLESS_DESCRIPTION = "Use local selenium headlessly (native in chrome, otherwise this requires pyvirtualdisplay)."
 BACKEND_DESCRIPTION = "Browser automation backend to use (selenium or playwright)."
 
-from typing import Literal
+import os
+from typing import (
+    Literal,
+    Optional,
+)
 from urllib.parse import urljoin
 
 from .driver_factory import (
     ConfiguredDriver,
     virtual_display_if_enabled,
 )
-from .navigates_galaxy import (
-    galaxy_timeout_handler,
-    NavigatesGalaxy,
+from .navigates_galaxy import galaxy_timeout_handler
+from .stories import (
+    NoopStory,
+    SectionMode,
+    SectionProxy,
+    Story,
+    StoryProtocol,
 )
+from .stories.data.upload import UploadStoriesMixin
 
 
 def add_selenium_arguments(parser):
@@ -60,11 +69,70 @@ def add_selenium_arguments(parser):
         choices=["selenium", "playwright"],
         help=BACKEND_DESCRIPTION,
     )
+    parser.add_argument(
+        "--timeout-multiplier",
+        type=float,
+        default=1.0,
+        help="Multiplier to apply to all timeout values (for slower environments).",
+    )
+    return parser
+
+
+def add_story_arguments(parser):
+    """Add story generation arguments for CLI scripts.
+
+    All the browser automation arguments (add_selenium_arguments) are also added.
+    """
+    add_selenium_arguments(parser)
+    parser.add_argument(
+        "--story-output",
+        default=None,
+        help="Directory to generate story documentation (markdown, HTML, PDF)",
+    )
+    parser.add_argument(
+        "--story-title",
+        default=None,
+        help="Title for the generated story",
+    )
+    parser.add_argument(
+        "--story-description",
+        default=None,
+        help="Description for the generated story",
+    )
+    parser.add_argument(
+        "--only-sections",
+        type=str,
+        default=None,
+        help='Comma-separated list of section anchors to generate (e.g., "basics,advanced")',
+    )
+    parser.add_argument(
+        "--skip-sections",
+        type=str,
+        default=None,
+        help="Comma-separated list of section anchors to skip",
+    )
+    parser.add_argument(
+        "--list-sections",
+        action="store_true",
+        help="List all available sections and exit (requires running the script)",
+    )
+    parser.add_argument(
+        "--merge-into",
+        type=str,
+        default=None,
+        help="Path to existing markdown file to merge sections into",
+    )
+    parser.add_argument(
+        "--section-mode",
+        choices=['replace', 'append', 'standalone'],
+        default='standalone',
+        help="How to handle sections: replace existing, append to existing, or standalone (default)",
+    )
 
     return parser
 
 
-class DriverWrapper(NavigatesGalaxy):
+class DriverWrapper(UploadStoriesMixin):
     """Adapt argparse command-line options to a browser automation driver."""
 
     def __init__(self, args):
@@ -81,9 +149,8 @@ def __init__(self, args):
             self.display = virtual_display_if_enabled(args.selenium_headless)
 
         # Create configured driver with the specified backend
-        # TODO: parameterize timeout multiplier
         self.configured_driver = ConfiguredDriver(
-            galaxy_timeout_handler(1.0),
+            galaxy_timeout_handler(args.timeout_multiplier),
             browser=browser,
             remote=args.selenium_remote,
             remote_host=args.selenium_remote_host,
@@ -93,6 +160,39 @@ def __init__(self, args):
         )
         self.target_url = args.galaxy_url
 
+        # Initialize story (real or noop)
+        # Scripts opt-in by calling add_story_arguments()
+        if hasattr(args, "story_output") and args.story_output:
+            if not os.path.exists(args.story_output):
+                os.makedirs(args.story_output)
+
+            title = args.story_title or "Galaxy Tutorial"
+            description = args.story_description or ""
+
+            # Parse section filters
+            only_sections = None
+            skip_sections = None
+            if hasattr(args, "only_sections") and args.only_sections:
+                only_sections = {s.strip() for s in args.only_sections.split(',')}
+            if hasattr(args, "skip_sections") and args.skip_sections:
+                skip_sections = {s.strip() for s in args.skip_sections.split(',')}
+
+            # Get section mode
+            section_mode: SectionMode = getattr(args, "section_mode", "standalone")
+            merge_target = getattr(args, "merge_into", None)
+
+            self.story: StoryProtocol = Story(
+                title,
+                description,
+                args.story_output,
+                only_sections=only_sections,
+                skip_sections=skip_sections,
+                merge_target=merge_target,
+                section_mode=section_mode,
+            )
+        else:
+            self.story = NoopStory()
+
     @property
     def _driver_impl(self):
         """Provide driver implementation from configured_driver."""
@@ -101,11 +201,35 @@ def _driver_impl(self):
     def build_url(self, url="", for_selenium: bool = True):
         return urljoin(self.target_url, url)
 
-    def screenshot(self, label: str) -> None:
-        """No-op in this context, not saving debugging/testing screenshots.
+    def screenshot(self, label: str, caption: Optional[str] = None) -> None:
+        """Save screenshot if story tracking is enabled.
 
-        Consider a verbose or debug option for saving these.
+        Args:
+            label: Base filename for screenshot
+            caption: Optional caption for the screenshot in the story
         """
+        if self.story.enabled:
+            # Generate screenshot path with sequential numbering
+            target = os.path.join(self.story.output_directory, f"{self.story.screenshot_counter:03d}_{label}.png")
+            self.story.screenshot_counter += 1
+
+            # Save screenshot
+            self.save_screenshot(target)
+
+            # Add to story
+            self.story.add_screenshot(target, caption or label)
+
+    def section(self, title: str, anchor: str) -> SectionProxy:
+        """Create a story section context manager.
+
+        Args:
+            title: Display title for the section
+            anchor: Unique identifier for the section (used for filtering/merging)
+
+        Returns:
+            SectionProxy context manager
+        """
+        return SectionProxy(self, title, anchor)
 
     @property
     def default_timeout(self):
@@ -130,3 +254,6 @@ def finish(self):
 
         if exception is not None:
             raise exception
+
+    def _screenshot_path(self, label: str, extension: str = ".png") -> Optional[str]:
+        return None
diff --git a/lib/galaxy/selenium/context.py b/lib/galaxy/selenium/context.py
index b6996fa160fd..de5385fd4620 100644
--- a/lib/galaxy/selenium/context.py
+++ b/lib/galaxy/selenium/context.py
@@ -6,7 +6,11 @@
 import yaml
 
 from .driver_factory import ConfiguredDriver
-from .navigates_galaxy import NavigatesGalaxy
+from .navigates_galaxy import (
+    galaxy_timeout_handler,
+    NavigatesGalaxy,
+)
+from .stories import SectionProxy
 
 
 class GalaxySeleniumContext(NavigatesGalaxy):
@@ -31,21 +35,100 @@ def build_url(self, url: str, for_selenium: bool = True) -> str:
             base = self.url
         return urljoin(base, url)
 
-    def screenshot(self, label: str):
-        """If GALAXY_TEST_SCREENSHOTS_DIRECTORY is set create a screenshot there named <label>.png.
+    def screenshot(self, label: str, caption: Optional[str] = None):
+        """Take a screenshot and optionally add to story.
 
-        Unlike the above "snapshot" feature, this will be written out regardless and not in a per-test
-        directory. The above method is used for debugging failures within a specific test. This method
-        if more for creating a set of images to augment automated testing with manual human inspection
-        after a test or test suite has executed.
+        Saves screenshot to the configured directory (story directory if story is enabled,
+        otherwise screenshots directory). In test framework, if both are configured,
+        screenshot is saved to both locations.
+
+        Args:
+            label: Base filename for screenshot
+            caption: Optional caption for the screenshot in the story
         """
         target = self._screenshot_path(label)
         if target is None:
             return
 
         self.save_screenshot(target)
+
+        # Add to story (noop if NoopStory)
+        if hasattr(self, "story"):
+            self.story.add_screenshot(target, caption or label)
+
         return target
 
+    def document(self, markdown_content: str):
+        """Add markdown documentation to the story.
+
+        This method appends markdown content to the story if story tracking
+        is enabled. Content will be interleaved with screenshots in the final
+        story document.
+
+        Args:
+            markdown_content: Markdown-formatted documentation to add to story
+        """
+        if hasattr(self, "story"):
+            self.story.add_documentation(markdown_content)
+
+    def document_embed(self, file_path: str):
+        """Embed a Markdown document right into the story."""
+        if hasattr(self, "story"):
+            with open(file_path) as f:
+                contents = f.read()
+            self.document(contents)
+
+    def document_file(self, file_path: str, caption: Optional[str] = None):
+        """Document the contents of a file in the story.
+
+        This method reads a file and adds its contents to the story as a code block,
+        along with the filename and an optional caption. Useful for documenting
+        data files used in tests and tutorials.
+
+        Args:
+            file_path: Absolute path to the file to document
+            caption: Optional caption/description for the file
+
+        Example:
+            self.document_file("/path/to/workbook.tsv", "Example workbook with dataset metadata")
+        """
+        if not hasattr(self, "story"):
+            return
+
+        # Get just the filename, not full path
+        filename = os.path.basename(file_path)
+
+        # Read file contents
+        try:
+            with open(file_path) as f:
+                contents = f.read()
+        except Exception as e:
+            # If we can't read the file, document the error
+            self.document(f"**File: `{filename}`**\n\n*Error reading file: {e}*\n")
+            return
+
+        # Build markdown with filename, contents, and optional caption
+        markdown_parts = []
+
+        markdown_parts.append(f"**File: `{filename}`**\n")
+        markdown_parts.append(f"```\n{contents}```\n")
+        if caption:
+            markdown_parts.append(f"**{caption}**\n")
+
+        self.document("\n".join(markdown_parts))
+
+    def section(self, title: str, anchor: str) -> SectionProxy:
+        """Create a story section context manager.
+
+        Args:
+            title: Display title for the section
+            anchor: Unique identifier for the section (used for filtering/merging)
+
+        Returns:
+            SectionProxy context manager
+        """
+        return SectionProxy(self, title, anchor)
+
     @abstractmethod
     def _screenshot_path(self, label: str, extension=".png") -> Optional[str]:
         """Path to store screenshots in."""
@@ -60,14 +143,31 @@ class GalaxySeleniumContextImpl(GalaxySeleniumContext):
 
     def __init__(self, from_dict: Optional[dict] = None) -> None:
         from_dict = from_dict or {}
-        self.configured_driver = ConfiguredDriver(**from_dict.get("driver", {}))
+        self.timeout_multiplier = from_dict.get("timeout_multiplier", 1)
+        timeout_handler = galaxy_timeout_handler(self.timeout_multiplier)
+        self.configured_driver = ConfiguredDriver(timeout_handler=timeout_handler, **from_dict.get("driver", {}))
         self.url = from_dict.get("local_galaxy_url", "http://localhost:8080")
         self.target_url_from_selenium = from_dict.get("selenium_galaxy_url", self.url)
-        self.timeout_multiplier = from_dict.get("timeout_multiplier", 1)
+        # Optional properties...
+        self.login_email = from_dict.get("login_email", "")
+        self.login_password = from_dict.get("login_password", "")
 
     def _screenshot_path(self, label, extension=".png"):
         return label + extension
 
+    # mirror TestWithSelenium method for doing this but use the config.
+    def login(self):
+        if self.login_email:
+            assert self.login_password, "If login_email is set, a password must be set also with login_password"
+            self.home()
+            self.submit_login(
+                email=self.login_email,
+                password=self.login_password,
+                assert_valid=True,
+            )
+        else:
+            self.register()
+
 
 def init(config=None, clazz=GalaxySeleniumContextImpl) -> GalaxySeleniumContext:
     if os.path.exists("galaxy_selenium_context.yml"):
diff --git a/lib/galaxy/selenium/has_driver.py b/lib/galaxy/selenium/has_driver.py
index 66658bcbfb97..c0ddcc71ca0c 100644
--- a/lib/galaxy/selenium/has_driver.py
+++ b/lib/galaxy/selenium/has_driver.py
@@ -611,6 +611,34 @@ def get_screenshot_as_png(self) -> bytes:
         """
         return self.driver.get_screenshot_as_png()
 
+    def highlight_element(self, element: WebElementProtocol):
+        """
+        Highlight element with red border for screenshots (context manager).
+
+        Returns context manager that places thick red border around element
+        and removes it on exit.
+
+        Args:
+            element: Element to highlight
+
+        Returns:
+            Context manager that highlights on enter and clears on exit
+        """
+
+        @contextmanager
+        def _highlight_context():
+            # Store original border style
+            original_border = self.execute_script("return arguments[0].style.border;", element)
+            try:
+                # Apply thick red border
+                self.execute_script("arguments[0].style.border = '3px solid red';", element)
+                yield
+            finally:
+                # Restore original border
+                self.execute_script(f"arguments[0].style.border = '{original_border}';", element)
+
+        return _highlight_context()
+
     def close(self) -> None:
         """Cleanup the current browser tab/page."""
         self.driver.close()
diff --git a/lib/galaxy/selenium/has_driver_protocol.py b/lib/galaxy/selenium/has_driver_protocol.py
index bbe93bc85b5c..542a72d272f4 100644
--- a/lib/galaxy/selenium/has_driver_protocol.py
+++ b/lib/galaxy/selenium/has_driver_protocol.py
@@ -500,6 +500,28 @@ def get_screenshot_as_png(self) -> bytes:
         """
         ...
 
+    @abstractmethod
+    def highlight_element(self, element: WebElementProtocol) -> "ContextManager[None]":
+        """
+        Highlight element with red border for screenshots (context manager).
+
+        Returns context manager that places thick red border around element
+        and removes it on exit. Useful for debugging and visual verification.
+
+        Args:
+            element: Element to highlight
+
+        Returns:
+            Context manager that highlights on enter and clears on exit
+
+        Usage:
+            element = driver.find_element_by_id("test")
+            with driver.highlight_element(element):
+                driver.save_screenshot("highlighted.png")
+            # Border removed after context exits
+        """
+        ...
+
     # Timeout utilities
     @abstractmethod
     def _timeout_message(self, on_str: str) -> str:
diff --git a/lib/galaxy/selenium/has_driver_proxy.py b/lib/galaxy/selenium/has_driver_proxy.py
index 4dd95f3e0a7d..e9e7d28ff199 100644
--- a/lib/galaxy/selenium/has_driver_proxy.py
+++ b/lib/galaxy/selenium/has_driver_proxy.py
@@ -438,6 +438,10 @@ def get_screenshot_as_png(self) -> bytes:
         """
         return self._driver_impl.get_screenshot_as_png()
 
+    def highlight_element(self, element: WebElementProtocol):
+        """Highlight element with red border for screenshots."""
+        return self._driver_impl.highlight_element(element)
+
     # Timeout utilities
 
     def _timeout_message(self, on_str: str) -> str:
diff --git a/lib/galaxy/selenium/has_playwright_driver.py b/lib/galaxy/selenium/has_playwright_driver.py
index 665894d52b64..16b76c16d0ee 100644
--- a/lib/galaxy/selenium/has_playwright_driver.py
+++ b/lib/galaxy/selenium/has_playwright_driver.py
@@ -1124,6 +1124,38 @@ def get_screenshot_as_png(self) -> bytes:
         """
         return self.page.screenshot()
 
+    def highlight_element(self, element: WebElementProtocol):
+        """
+        Highlight element with red border for screenshots (context manager).
+
+        Returns context manager that places thick red border around element
+        and removes it on exit.
+
+        Args:
+            element: Element to highlight
+
+        Returns:
+            Context manager that highlights on enter and clears on exit
+        """
+        return self._highlight_element(self._unwrap_element(element))
+
+    def _highlight_element(self, element: ElementHandle):
+        """Internal implementation of highlight_element."""
+
+        @contextmanager
+        def _highlight_context():
+            # Store original border style
+            original_border = self.page.evaluate("element => element.style.border", element)
+            try:
+                # Apply thick red border
+                self.page.evaluate("element => element.style.border = '3px solid red'", element)
+                yield
+            finally:
+                # Restore original border
+                self.page.evaluate(f"element => element.style.border = '{original_border}'", element)
+
+        return _highlight_context()
+
     def close(self) -> None:
         """Cleanup the current browser tab/page."""
         self._playwright_resources.browser.close()
diff --git a/lib/galaxy/selenium/jupyter_context.py b/lib/galaxy/selenium/jupyter_context.py
index 972a84088a1d..a78e03aa779b 100644
--- a/lib/galaxy/selenium/jupyter_context.py
+++ b/lib/galaxy/selenium/jupyter_context.py
@@ -1,3 +1,5 @@
+from typing import Optional
+
 from .context import (
     GalaxySeleniumContextImpl,
     init as c_init,
@@ -9,8 +11,8 @@ def init(config=None):
 
 
 class JupyterContextImpl(GalaxySeleniumContextImpl):
-    def screenshot(self, label):
-        path = super().screenshot(label)
+    def screenshot(self, label, caption: Optional[str] = None):
+        path = super().screenshot(label, caption)
         from IPython.display import Image
 
         return Image(filename=path)
diff --git a/lib/galaxy/selenium/navigates_galaxy.py b/lib/galaxy/selenium/navigates_galaxy.py
index b6b40f1b9cc6..1a42032fa246 100644
--- a/lib/galaxy/selenium/navigates_galaxy.py
+++ b/lib/galaxy/selenium/navigates_galaxy.py
@@ -5,6 +5,7 @@
 
 import collections
 import contextlib
+import json
 import random
 import string
 import time
@@ -964,6 +965,10 @@ def click_center(self):
     def hover_over(self, target):
         self.hover(target)
 
+    def wait_for_upload_modal(self):
+        self.components.upload.build_button.wait_for_visible()
+        self.components.upload.build_button.wait_for_clickable()
+
     def perform_single_upload(self, test_path, **kwd) -> HistoryEntry:
         before_latest_history_item = self.latest_history_entry()
         self._perform_upload(test_path=test_path, **kwd)
@@ -1160,6 +1165,25 @@ def upload_queue_local_file(self, test_path, tab_id="regular"):
             file_upload = self.wait_for_selector(f'div#{tab_id} input[type="file"]')
             file_upload.send_keys(test_path)
 
+    def workbook_upload(self, test_path: str, which: Literal["shortcut", "card"] = "shortcut"):
+        rule_builder = self.components.rule_builder
+        if self.backend_type == "playwright":
+            with self.page.expect_file_chooser() as fc_info:
+                if which == "shortcut":
+                    rule_builder.workbook_upload_button.wait_for_and_click()
+                else:
+                    rule_builder.workbook_upload_link.wait_for_and_click()
+            file_chooser = fc_info.value
+            file_chooser.set_files(test_path)
+        else:
+            if which == "shortcut":
+                rule_builder.workbook_upload_button.wait_for_and_click()
+                file_upload = rule_builder.workbook_upload_file_input.wait_for_present()
+            else:
+                rule_builder.workbook_upload_link.wait_for_and_click()
+                file_upload = rule_builder.workbook_upload_file_input_explicit.wait_for_present()
+            file_upload.send_keys(test_path)
+
     def upload_paste_data(self, pasted_content, tab_id="regular"):
         tab_locator = f"div#{tab_id}"
         self.wait_for_and_click_selector(f"{tab_locator} button#btn-new")
@@ -1208,6 +1232,29 @@ def upload_rule_set_dataset(self, row=1):
         upload.rule_dataset_selector.wait_for_visible()
         upload.rule_dataset_selector_row(rowindex=row).wait_for_and_click()
 
+    def ensure_rules_activity_enabled(self):
+        self.sleep_for(self.wait_types.UX_RENDER)
+
+        if self.components.rule_builder.activity.is_absent:
+            activity_bar = self.components.activity_bar
+            # Odd problems here - settings bar may be clickable but not yet wired up?
+            self.sleep_for(self.wait_types.UX_RENDER)
+            self.sleep_for(self.wait_types.UX_RENDER)
+            activity_bar.settings.wait_for_and_click()
+            activity_bar.additional_activities.wait_for_present()
+            self.sleep_for(self.wait_types.UX_RENDER)
+            assert activity_bar.show_activity(activity_id="rules").wait_for_present()
+            activity_bar.show_activity(activity_id="rules").wait_for_and_click()
+            self.components.rule_builder.activity.wait_for_visible()
+            activity_bar.settings.wait_for_and_click()
+
+    def click_rules_activity(self):
+        self.components.rule_builder.activity.wait_for_and_click()
+
+    def rule_builder_import(self):
+        rule_builder = self.components.rule_builder
+        rule_builder.wizard_import.wait_for_and_click()
+
     def rule_builder_set_collection_name(self, name):
         rule_builder = self.components.rule_builder
         name_element = rule_builder.collection_name_input.wait_for_and_click()
@@ -1367,6 +1414,19 @@ def rule_builder_set_source(self, json):
         rule_builder.main_button_ok.wait_for_and_click()
         rule_builder.view_source.wait_for_visible()
 
+    def rule_builder_show_and_get_source(self) -> str:
+        rule_builder = self.components.rule_builder
+        rule_builder.view_source.wait_for_and_click()
+        source_elem = rule_builder.source.wait_for_visible()
+        source_value = source_elem.get_attribute("value")
+        rule_builder.main_button_ok.wait_for_and_click()
+        rule_builder.view_source.wait_for_visible()
+        return source_value
+
+    def rule_builder_show_and_get_source_as_json(self) -> dict:
+        source_text = self.rule_builder_show_and_get_source()
+        return json.loads(source_text)
+
     def rule_builder_enter_source_text(self, json):
         rule_builder = self.components.rule_builder
         text_area_elem = rule_builder.source.wait_for_visible()
diff --git a/lib/galaxy/selenium/navigates_galaxy_mixin.py b/lib/galaxy/selenium/navigates_galaxy_mixin.py
new file mode 100644
index 000000000000..ffa005e3412a
--- /dev/null
+++ b/lib/galaxy/selenium/navigates_galaxy_mixin.py
@@ -0,0 +1,15 @@
+"""Parent class for mixins that are meant to extend NavigatesGalaxy.
+
+This provides some level of type checking support despite being a bit hacky.
+"""
+
+from typing import TYPE_CHECKING
+
+from .context import GalaxySeleniumContext
+
+if TYPE_CHECKING:
+    NavigatesGalaxyMixin = GalaxySeleniumContext
+else:
+    NavigatesGalaxyMixin = object
+
+__all__ = ("NavigatesGalaxyMixin",)
diff --git a/lib/galaxy/selenium/scripts/dump_tour.py b/lib/galaxy/selenium/scripts/dump_tour.py
index f1c34d6f4475..e47c1a43aa2f 100755
--- a/lib/galaxy/selenium/scripts/dump_tour.py
+++ b/lib/galaxy/selenium/scripts/dump_tour.py
@@ -36,7 +36,7 @@ def __init__(self, driver_wrapper, output):
 
     def handle_step(self, step, step_index: int):
         time.sleep(0.5)
-        self.driver_wrapper.save_screenshot(f"{self.output}/{step_index}.png")
+        self.driver_wrapper.screenshot(f"{self.output}/{step_index}.png")
         time.sleep(0.5)
 
 
diff --git a/lib/galaxy/selenium/scripts/generate_rule_builder_tutorial.py b/lib/galaxy/selenium/scripts/generate_rule_builder_tutorial.py
new file mode 100755
index 000000000000..09ca9a977b73
--- /dev/null
+++ b/lib/galaxy/selenium/scripts/generate_rule_builder_tutorial.py
@@ -0,0 +1,156 @@
+#!/usr/bin/env python
+"""Script to generate a tutorial for the Galaxy Rule Builder.
+
+This script demonstrates using the Story class to create user documentation
+outside of the test framework with composable, rerunnable sections.
+
+Usage:
+    # Generate full tutorial
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial
+
+    # Generate only specific sections
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial \
+        --only-sections "workbook_example_1,rules_example_1"
+
+    # Skip sections
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial \
+        --skip-sections "workbook_example_3,workbook_example_4"
+
+    # Regenerate one section and merge into existing
+    python generate_rule_builder_tutorial.py \
+        --galaxy_url http://localhost:8081 \
+        --story-output ./rules_tutorial_v2 \
+        --only-sections "workbook_example_1" \
+        --merge-into ./rules_tutorial/story.md \
+        --section-mode replace
+"""
+import argparse
+import sys
+from contextlib import contextmanager
+from typing import Optional
+
+from galaxy.selenium import cli
+
+DESCRIPTION = __doc__
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    args = _arg_parser().parse_args(argv)
+    if not args.story_title:
+        args.story_title = "Galaxy Rule Builder Tutorial"
+    if not args.story_description:
+        args.story_description = "Tutorial demonstrating automatic and manual usage of Galaxy's Rule Builder."
+    driver_wrapper = cli.DriverWrapper(args)
+
+    include_result = args.perform_uploads
+
+    try:
+        # Generate the tutorial
+        generate_rule_builder_tutorial(driver_wrapper, include_result=include_result)
+
+        # Finalize story if enabled
+        if driver_wrapper.story.enabled:
+            driver_wrapper.story.finalize()
+            print(f"Tutorial generated in: {driver_wrapper.story.output_directory}")
+    finally:
+        driver_wrapper.finish()
+
+
+def generate_rule_builder_tutorial(has_driver, include_result: bool = False) -> None:
+    """Generate a tutorial documenting the Galaxy Rule Builder features."""
+
+    has_driver.home()
+    has_driver.register()
+
+    has_driver.home()
+    has_driver.ensure_rules_activity_enabled()
+
+    with has_driver.section("Workbook Example 1", "workbook_example_1") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 1"):
+                has_driver.upload_example_1_full_wizard()
+                has_driver.home()
+                has_driver.upload_workbook_example_1(include_result=include_result)
+
+    with has_driver.section("Workbook Example 2", "workbook_example_2") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 2"):
+                has_driver.upload_workbook_example_2_prereq_pick_a_collection()
+                has_driver.home()
+                has_driver.upload_workbook_example_2(include_result=include_result)
+
+    with has_driver.section("Workbook Example 3", "workbook_example_3") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 3"):
+                has_driver.upload_workbook_example_3(include_result=include_result)
+
+    with has_driver.section("Workbook Example 4", "workbook_example_4") as section:
+        if section:
+            with example_history(has_driver, "Workbook Example 4"):
+                has_driver.upload_workbook_example_4(include_result=include_result)
+
+    with has_driver.section("Rules Example 1", "rules_example_1") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 1"):
+                has_driver.upload_rules_example_1(include_result=include_result)
+
+    with has_driver.section("Rules Example 2", "rules_example_2") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 2"):
+                has_driver.upload_rules_example_2(include_result=include_result)
+
+    with has_driver.section("Rules Example 3", "rules_example_3") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 3"):
+                has_driver.upload_rules_example_3(include_result=include_result)
+
+    with has_driver.section("Rules Example 4", "rules_example_4") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 4"):
+                has_driver.upload_rules_example_4(include_result=include_result)
+
+    with has_driver.section("Rules Example 5", "rules_example_5") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 5"):
+                has_driver.upload_rules_example_5(include_result=include_result)
+
+    with has_driver.section("Rules Example 6", "rules_example_6") as section:
+        if section:
+            with example_history(has_driver, "Rules Example 6"):
+                has_driver.upload_rules_example_6(include_result=include_result)
+
+
+@contextmanager
+def example_history(driver, title: str):
+    """Context manager to create an example history for the tutorial."""
+    try:
+        driver.home()
+        history = driver.history_panel_create_new_with_name(title)
+        yield history
+    finally:
+        # potentially delete history here?
+        pass
+
+
+def _arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=DESCRIPTION)
+    parser = cli.add_story_arguments(parser)
+    parser.add_argument(
+        "--perform-uploads",
+        action="store_true",
+        help="Actually perform uploads and include final screenshots in the tutorial.",
+    )
+    return parser
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lib/galaxy/selenium/smart_components.py b/lib/galaxy/selenium/smart_components.py
index 6392c39b2066..bd89e3f6f718 100644
--- a/lib/galaxy/selenium/smart_components.py
+++ b/lib/galaxy/selenium/smart_components.py
@@ -142,6 +142,11 @@ def wait_for_and_send_enter(self):
         # TODO: add to unit test
         self._has_driver.send_enter(self.wait_for_visible())
 
+    def wait_for_and_highlight(self, **kwds):
+        """Wait for element visible and return context manager to highlight it."""
+        element = self.wait_for_visible(**kwds)
+        return self._has_driver.highlight_element(element)
+
     def wait_for_and_clear_and_send_keys(self, *text):
         dom_element = self.wait_for_visible()
         dom_element.clear()
diff --git a/lib/galaxy/selenium/stories/__init__.py b/lib/galaxy/selenium/stories/__init__.py
new file mode 100644
index 000000000000..5e0ed0d3e021
--- /dev/null
+++ b/lib/galaxy/selenium/stories/__init__.py
@@ -0,0 +1,32 @@
+"""Story generation for visual test documentation.
+
+This package provides tools for generating narrative documentation with
+interleaved screenshots and markdown content. It can be used in tests,
+standalone scripts, and Jupyter notebooks.
+"""
+
+from .story import (
+    ElementMetadata,
+    ElementType,
+    NoopStory,
+    SectionMetadata,
+    SectionMetadataInput,
+    SectionMode,
+    SectionProxy,
+    Story,
+    StoryElement,
+    StoryProtocol,
+)
+
+__all__ = [
+    "Story",
+    "NoopStory",
+    "StoryProtocol",
+    "SectionProxy",
+    "SectionMetadata",
+    "SectionMetadataInput",
+    "SectionMode",
+    "ElementMetadata",
+    "ElementType",
+    "StoryElement",
+]
diff --git a/lib/galaxy/selenium/stories/data/__init__.py b/lib/galaxy/selenium/stories/data/__init__.py
new file mode 100644
index 000000000000..bfa1edd6b2ea
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/__init__.py
@@ -0,0 +1,39 @@
+"""Helper functions for accessing story example data files."""
+
+from pathlib import Path
+
+
+def get_data_directory() -> Path:
+    """Get the path to the stories data directory.
+
+    Returns:
+        Path to lib/galaxy/selenium/stories/data/examples/
+    """
+    return Path(__file__).parent / "examples"
+
+
+def get_example_path(filename: str) -> str:
+    """Get the absolute path to a story example file.
+
+    Args:
+        filename: Name of the example file (e.g., 'workbook_example_1.tsv')
+
+    Returns:
+        Absolute path to the example file
+
+    Example:
+        >>> path = get_example_path('workbook_example_1.tsv')
+        >>> # Use in tests: self.workbook_upload(path)
+    """
+    return str(get_data_directory() / filename)
+
+
+def get_document_fragment_path(filename: str) -> str:
+    return str(Path(__file__).parent / "fragments" / filename)
+
+
+__all__ = [
+    "get_data_directory",
+    "get_document_fragment_path",
+    "get_example_path",
+]
diff --git a/test-data/rules/PRJDA60709.tsv b/lib/galaxy/selenium/stories/data/examples/PRJDA60709.tsv
similarity index 100%
rename from test-data/rules/PRJDA60709.tsv
rename to lib/galaxy/selenium/stories/data/examples/PRJDA60709.tsv
diff --git a/test-data/rules/PRJDB3920.tsv b/lib/galaxy/selenium/stories/data/examples/PRJDB3920.tsv
similarity index 100%
rename from test-data/rules/PRJDB3920.tsv
rename to lib/galaxy/selenium/stories/data/examples/PRJDB3920.tsv
diff --git a/test-data/rules/PRJNA355367.tsv b/lib/galaxy/selenium/stories/data/examples/PRJNA355367.tsv
similarity index 100%
rename from test-data/rules/PRJNA355367.tsv
rename to lib/galaxy/selenium/stories/data/examples/PRJNA355367.tsv
diff --git a/lib/galaxy/selenium/stories/data/examples/__init__.py b/lib/galaxy/selenium/stories/data/examples/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/test-data/rules/uniprot.json b/lib/galaxy/selenium/stories/data/examples/uniprot.json
similarity index 100%
rename from test-data/rules/uniprot.json
rename to lib/galaxy/selenium/stories/data/examples/uniprot.json
diff --git a/test-data/rules/uniprot.tsv b/lib/galaxy/selenium/stories/data/examples/uniprot.tsv
similarity index 100%
rename from test-data/rules/uniprot.tsv
rename to lib/galaxy/selenium/stories/data/examples/uniprot.tsv
diff --git a/lib/galaxy/selenium/stories/data/examples/workbook_example_1.tsv b/lib/galaxy/selenium/stories/data/examples/workbook_example_1.tsv
new file mode 100644
index 000000000000..77e2d857ec8a
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/examples/workbook_example_1.tsv
@@ -0,0 +1,5 @@
+name	url	genome
+DRR000770	https://zenodo.org/records/3263975/files/DRR000770.fastqsanger.gz	dm6
+DRR000771	https://zenodo.org/records/3263975/files/DRR000771.fastqsanger.gz	dm6
+DRR000772	https://zenodo.org/records/3263975/files/DRR000772.fastqsanger.gz	dm6
+DRR000773	https://zenodo.org/records/3263975/files/DRR000773.fastqsanger.gz	dm6
diff --git a/lib/galaxy/selenium/stories/data/examples/workbook_example_2.tsv b/lib/galaxy/selenium/stories/data/examples/workbook_example_2.tsv
new file mode 100644
index 000000000000..af61d9f9c6a3
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/examples/workbook_example_2.tsv
@@ -0,0 +1,5 @@
+LIST IDENTIFIER	URI	TYPE
+SAMD00016379	https://zenodo.org/records/3263975/files/DRR000770.fastqsanger.gz	fastqsanger.gz
+SAMD00016383	https://zenodo.org/records/3263975/files/DRR000771.fastqsanger.gz	fastqsanger.gz
+SAMD00016380	https://zenodo.org/records/3263975/files/DRR000772.fastqsanger.gz	fastqsanger.gz
+SAMD00016378	https://zenodo.org/records/3263975/files/DRR000773.fastqsanger.gz	fastqsanger.gz
diff --git a/lib/galaxy/selenium/stories/data/examples/workbook_example_3.tsv b/lib/galaxy/selenium/stories/data/examples/workbook_example_3.tsv
new file mode 100644
index 000000000000..eed70e412b1c
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/examples/workbook_example_3.tsv
@@ -0,0 +1,4 @@
+list identifier	forward_url	reverse_url	genome
+DRX036147	https://zenodo.org/records/3263975/files/DRX036147_1.fastq.gz	https://zenodo.org/records/3263975/files/DRX036147_2.fastq.gz	dm6
+DRX036148	https://zenodo.org/records/3263975/files/DRX036148_1.fastq.gz	https://zenodo.org/records/3263975/files/DRX036148_2.fastq.gz	dm6
+DRX036149	https://zenodo.org/records/3263975/files/DRX036149_1.fastq.gz	https://zenodo.org/records/3263975/files/DRX036149_2.fastq.gz	dm6
\ No newline at end of file
diff --git a/lib/galaxy/selenium/stories/data/examples/workbook_example_4.tsv b/lib/galaxy/selenium/stories/data/examples/workbook_example_4.tsv
new file mode 100644
index 000000000000..b6ef7b71246c
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/examples/workbook_example_4.tsv
@@ -0,0 +1,7 @@
+"URI 1"	"URI 2"	"Outer List Identifier"	"Inner List Identifier"
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/006/SRR5680996/SRR5680996_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/006/SRR5680996/SRR5680996_2.fastq.gz	H3K4me3	rep1
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/007/SRR5680997/SRR5680997_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/007/SRR5680997/SRR5680997_2.fastq.gz	H3K4me27	rep2
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/007/SRR5681007/SRR5681007_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/007/SRR5681007/SRR5681007_2.fastq.gz	H3K4me27	rep1
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/006/SRR5681006/SRR5681006_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/006/SRR5681006/SRR5681006_2.fastq.gz	H3K4me3	rep2
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/008/SRR5680998/SRR5680998_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/008/SRR5680998/SRR5680998_2.fastq.gz	CTCF	rep1
+ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/008/SRR5681008/SRR5681008_1.fastq.gz	ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR568/008/SRR5681008/SRR5681008_2.fastq.gz	CTCF	rep2
diff --git a/lib/galaxy/selenium/stories/data/fragments/__init__.py b/lib/galaxy/selenium/stories/data/fragments/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/lib/galaxy/selenium/stories/data/fragments/workbook_column_mapping.md b/lib/galaxy/selenium/stories/data/fragments/workbook_column_mapping.md
new file mode 100644
index 000000000000..ba7527fe9a37
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/fragments/workbook_column_mapping.md
@@ -0,0 +1,59 @@
+## What Galaxy Learns from Column Headers
+
+Galaxy automatically recognizes column headers in your workbook and uses them to set up your datasets. The header recognition is **flexible and case-insensitive** - you can use various names for the same thing.
+
+This might seem overwhelming but for datasets only a URI/URL is really essential for uploading workbooks to Galaxy. For uploading collections,
+the collection element identifiers describing the collection structure is also required - but everything else remains optional. Hopefully the
+examples ahead make this clear - but this section exists as reference documentation for what is available and how it works.
+
+### How Header Parsing Works
+
+All of these headers mean the same thing to Galaxy:
+- "MD5 Sum", "MD5", "md5", "Hash MD5", "md5sum" → all recognized as MD5 checksum
+- "Genome Build", "DBKey", "genome", "build" → all recognized as genome reference
+- "URI", "URL", "uri 1 (forward)" → all recognized as data source URL
+
+Galaxy does this by ignoring differences in capitalization, whitespace, special characters like `( ) - _`, and the word "optional" when reading your column headers.
+
+### Recognized Column Headers
+
+| What It's For | Example Headers | Description |
+|----------------|-----------------|-------------|
+| **URL/URI** | `URI`, `URL`, `uri`, `URI 1 (Forward)`, `URI 2 (Reverse)` | Where to download your data from |
+| **Deferred URL** | `URL Deferred`, `Deferred URL` | URL that won't download until the data is actually used |
+| **Name** | `Name`, `name`, `NAME` | Dataset name shown in your history |
+| **Collection Name** | `Collection Name`, `List Name`, `listname` | Groups multiple datasets into a named collection |
+| **Genome/DBKey** | `Genome`, `DBKey`, `build`, `Genome Build` | Reference genome (e.g., hg19, mm10) |
+| **File Type** | `File Type`, `Type`, `Extension`, `file extension` | Data format (e.g., fastqsanger, bam, vcf) |
+| **Info** | `Info`, `info` | Descriptive text shown in history panel |
+| **Tag** | `Tag`, `tag` | Tags for organizing your data |
+| **Group Tag** | `Group Tag`, `grouptag` | Tags that carry over to outputs (useful for experiments) |
+| **Name Tag** | `Name Tag`, `nametag` | Hash tags based on dataset name |
+| **List Identifier** | `List Identifier`, `listidentifier` | Sample or replicate name for collections |
+| **Paired Identifier** | `Paired Identifier`, `pairedidentifier` | Which read in a pair (forward/reverse: 1/2, F/R) |
+| **MD5 Hash** | `MD5`, `MD5 Sum`, `Hash MD5`, `md5sum` | MD5 checksum to verify file wasn't corrupted |
+| **SHA-1 Hash** | `SHA1`, `SHA-1 Sum`, `Hash SHA-1`, `sha1sum` | SHA-1 checksum to verify file wasn't corrupted |
+| **SHA-256 Hash** | `SHA256`, `SHA-256 Sum`, `Hash SHA-256` | SHA-256 checksum to verify file wasn't corrupted |
+| **SHA-512 Hash** | `SHA512`, `SHA-512 Sum`, `Hash SHA-512` | SHA-512 checksum to verify file wasn't corrupted |
+
+## Example Workbook
+
+Here's a sample workbook showing flexible header naming:
+
+| URI | Name | MD5 Sum | Genome Build | File Type |
+|-----|------|---------|--------------|-----------|
+| http://example.com/sample1.fq.gz | Sample A | 5d41402abc4b2a76b9719d911017c592 | hg19 | fastqsanger.gz |
+| http://example.com/sample2.fq.gz | Sample B | 7d793037a0760186574b0282f2f435e7 | hg19 | fastqsanger.gz |
+
+This could equivalently be written as:
+
+| url | NAME | hash md5 | dbkey | extension |
+|-----|------|----------|-------|-----------|
+| http://example.com/sample1.fq.gz | Sample A | 5d41402abc4b2a76b9719d911017c592 | hg19 | fastqsanger.gz |
+| http://example.com/sample2.fq.gz | Sample B | 7d793037a0760186574b0282f2f435e7 | hg19 | fastqsanger.gz |
+
+Both versions are recognized identically by Galaxy.
+
+### Unrecognized Columns
+
+Columns that Galaxy doesn't recognize are simply ignored - they won't cause errors, but their data won't be used.
diff --git a/lib/galaxy/selenium/stories/data/upload.py b/lib/galaxy/selenium/stories/data/upload.py
new file mode 100644
index 000000000000..f3bdb18b33d7
--- /dev/null
+++ b/lib/galaxy/selenium/stories/data/upload.py
@@ -0,0 +1,955 @@
+from selenium.webdriver.common.by import By
+from selenium.webdriver.common.keys import Keys
+
+from galaxy.selenium.context import GalaxySeleniumContext
+from ..data import (
+    get_document_fragment_path,
+    get_example_path,
+)
+
+# Convenience constants for workbook examples
+WORKBOOK_EXAMPLE_1 = get_example_path("workbook_example_1.tsv")
+WORKBOOK_EXAMPLE_2 = get_example_path("workbook_example_2.tsv")
+WORKBOOK_EXAMPLE_3 = get_example_path("workbook_example_3.tsv")
+WORKBOOK_EXAMPLE_4 = get_example_path("workbook_example_4.tsv")
+
+RULES_EXAMPLE_2_SOURCE = get_example_path("PRJDA60709.tsv")
+RULES_EXAMPLE_3_SOURCE = get_example_path("PRJDB3920.tsv")
+RULES_UNIPROT_SOURCE = get_example_path("uniprot.tsv")
+RULES_UNIPROT_RULES = get_example_path("uniprot.json")
+RULES_EXAMPLE_6_SOURCE = get_example_path("PRJNA355367.tsv")
+
+# Screenshot captions (used multiple times)
+CAPTION_RULES_WIZARD = "The Rules-based Data Import wizard interface"
+CAPTION_COLLECTIONS_BUTTON = "The collections button highlighted to indicate collection mode is active"
+
+# Documentation strings (used multiple times)
+DOC_CLICK_RULES_ACTIVITY = """
+Click the "Rules-based Data Import" activity to begin data import.
+"""
+
+DOC_CREATE_COLLECTIONS = """
+For this example, we'll create a collection rather than individual datasets. Click the large 'collections' button to indicate that we want to build a collection. The button will remain highlighted to show that collection mode is active.
+"""
+
+
+class UploadStoriesMixin(GalaxySeleniumContext):
+    """Mixin describing upload user stories around the workbooks and rules."""
+
+    def upload_example_1_full_wizard(self):
+        """Importing datasets from a workbook with automatic column mapping using the full wizard.
+
+        Demonstrates that Galaxy can:
+        - Automatically infer column mappings from common header patterns
+        - Detect dataset name, URL, and genome (dbkey) columns
+        - Correctly map columns without manual rule builder configuration
+        """
+        self.home()
+        self.document(
+            """
+## Example 1: Uploading Simple Datasets with Automatic Metadata Detection (the wizard)
+
+In this first example, we'll upload a set of FASTQ sequencing files from a spreadsheet. Galaxy's auto-detection feature will automatically recognize the column headers and map them to the appropriate metadata fields without any manual configuration.
+
+This is the easiest way to upload multiple datasets when your spreadsheet has clear, recognizable column names.
+"""
+        )
+        self.document(DOC_CLICK_RULES_ACTIVITY)
+        self.click_rules_activity()
+        self.screenshot("workbook_example_1_full_landing", CAPTION_RULES_WIZARD)
+        rule_builder = self.components.rule_builder
+        rule_builder.wizard_next.wait_for_and_click()
+        from_workbook = rule_builder.data_import_source_from(source="workbook")
+        self.document(
+            """Select 'External Workbook' as the import source. This will let you download an annotated Excel workbook that can be filled and uploaded."""
+        )
+        from_workbook.wait_for_and_click()
+        with from_workbook.wait_for_and_highlight():
+            self.screenshot("workbook_import_1_full_select_from_workbook")
+        rule_builder.wizard_next.wait_for_and_click()
+        download_link = rule_builder.workbook_download_link
+        with download_link.wait_for_and_highlight():
+            self.document("""This button lets you download an example workbook and fill it out.""")
+            self.screenshot("workbook_import_1_full_download_workbook")
+        download_link.wait_for_and_click()
+        upload_link = rule_builder.workbook_upload_link
+        with upload_link.wait_for_and_highlight():
+            self.document(
+                """When you're ready to upload your completed workbook, click the upload link in Step 3 of this wizard page."""
+            )
+            self.screenshot("workbook_import_1_full_upload_workbook", "The upload link is highlighted here.")
+        self.document_file(WORKBOOK_EXAMPLE_1, "Example workbook with dataset name, URL, and genome columns")
+        self.workbook_upload(WORKBOOK_EXAMPLE_1)
+        self.document(
+            """After uploading, the wizard will jump the last step automatically. You will be presented with how the tabular data was parsed into metadata by Galaxy."""
+        )
+        self.document_embed(get_document_fragment_path("workbook_column_mapping.md"))
+
+    def upload_workbook_example_1(self, include_result: bool = False):
+        """Importing datasets from a workbook with automatic column mapping (the shortcut)."""
+        self.home()
+        self.document(
+            """
+## Example 1: Uploading Simple Datasets with Automatic Metadata Detection (shortcut)
+
+Here we redo Example 1 but using the upload shortcut instead of the full wizard. This is a quicker way to get started when you just want to upload data without going through all the wizard steps.
+"""
+        )
+        self.document(DOC_CLICK_RULES_ACTIVITY)
+        self.click_rules_activity()
+        self.screenshot("workbook_example_1_shortcut_landing", CAPTION_RULES_WIZARD)
+
+        self.document(
+            "When we already have a completed workbook, we can use the upload shortcut to get started quickly and jump to the end of the wizard. You can either click the upload shortcut button and pick a spreadsheet/tabular file to upload or simply drag-and-drop the file onto the button."
+        )
+        with self.components.rule_builder.workbook_upload_button.wait_for_and_highlight():
+            self.screenshot(
+                "workbook_example_1_shortcut_upload_button", "The workbook upload shortcut button is highlighted here."
+            )
+
+        self.workbook_upload(WORKBOOK_EXAMPLE_1)
+
+        self.document(
+            """
+Just like using the full wizard. Galaxy has selected pulled out all the metadata correctly from this spreadsheet.
+"""
+        )
+        self.screenshot(
+            "workbook_example_1_mapped",
+            "The rule builder showing automatically detected column mappings for name, URL, and genome",
+        )
+        if include_result:
+            rule_builder = self.components.rule_builder
+            rule_builder.wizard_import.wait_for_and_click()
+            self.history_panel_wait_for_hid_ok(4)
+            # In next iteration - wait on the "uploading" message to disappear.
+            self.sleep_for(self.wait_types.UX_RENDER)
+            self.screenshot("workbook_example_1_complete", "Final datasets created and available in the history.")
+
+    def upload_workbook_example_2_prereq_pick_a_collection(self):
+        self.home()
+        self.click_rules_activity()
+        self.document(
+            """
+## Collection Examples
+
+When uploading individual datasets - Galaxy is able to assume row of the workbook is a single datasets and expect
+a single URL column for each dataset. As a result there is only a single example workbook template to download from
+Galaxy and start filling out.
+
+For collection uploads - there is more variety in workbook templates that can be downloaded from Galaxy
+depending on the type of collection you want to create. If you select to pick a collection on this first
+page of the wizard and then select "External Workbook" again - you will be presented with additional options
+to pick the type of collection you want to create.
+"""
+        )
+        rule_builder = self.components.rule_builder
+        rule_builder.create_collections.wait_for_and_click()
+        rule_builder.wizard_next.wait_for_and_click()
+        from_workbook = rule_builder.data_import_source_from(source="workbook")
+        from_workbook.wait_for_and_click()
+        rule_builder.wizard_next.wait_for_and_click()
+
+        self.screenshot(
+            "workbook_example_2_prereq_pick_collection_type",
+            "Picking collection type before downloading workbook template",
+        )
+        rule_builder.wizard_next.wait_for_and_click()
+        self.screenshot(
+            "workbook_example_2_prereq_upload_download_card",
+            "The process of downloading, filling out, and re-uploading the workbook is the same for collections from here though.",
+        )
+        self.document(
+            """Like with datasets though, any workbook with column names that are
+deducible by Galaxy will work for collections as well and these workbooks can be
+uploaded directly with the upload shortcut button from the first page of the wizard
+(as long as you've selected 'Collection' mode first). The rest of these examples will
+use that shortcut method to upload the workbooks describing collections.
+"""
+        )
+
+    def upload_workbook_example_2(self, include_result: bool = False):
+        """Importing a simple list collection from a workbook.
+
+        Demonstrates that Galaxy can:
+        - Detect collection mode when user clicks "collections" button
+        - Automatically infer list identifiers and file types
+        - Map URL columns for collection elements
+        """
+        self.home()
+        self.document(
+            """
+## Example 2: Creating a Simple List Collection
+
+Building on the previous example, we'll now create a **list collection** - a way to group related datasets together. Collections are useful when you want to run the same analysis on multiple samples at once.
+
+The key difference here is that our spreadsheet includes a **LIST IDENTIFIER** column, which tells Galaxy how to name each element in the collection.
+"""
+        )
+        self.document(DOC_CLICK_RULES_ACTIVITY)
+        self.click_rules_activity()
+        self.screenshot("workbook_example_2_landing", CAPTION_RULES_WIZARD)
+
+        self.document(DOC_CREATE_COLLECTIONS)
+        self.components.rule_builder.create_collections.wait_for_and_click()
+        self.screenshot("workbook_example_2_create_collections", CAPTION_COLLECTIONS_BUTTON)
+
+        self.document_file(
+            WORKBOOK_EXAMPLE_2,
+            "Example workbook with list identifier, URL, and file type columns",
+        )
+        self.workbook_upload(WORKBOOK_EXAMPLE_2)
+        self.rule_builder_set_collection_name("Example 2 - List")
+        self.document(
+            """
+Galaxy has recognized the column structure for a list collection:
+- The **LIST IDENTIFIER** column is detected as the collection element identifiers
+- The **URI** column (another common name for URLs) is mapped to the download locations
+- The **TYPE** column specifies the file type (datatype) for each dataset
+
+Even though these column names are different from Example 1 (URI instead of url, TYPE instead of format), Galaxy's auto-detection is flexible enough to recognize these alternative naming patterns. This means your spreadsheets don't need to follow one rigid format.
+"""
+        )
+        self.screenshot(
+            "workbook_example_2_mapped",
+            "The rule builder showing automatically detected list identifier, URI, and type column mappings",
+        )
+        if include_result:
+            self.rule_builder_import()
+            self.history_panel_wait_for_hid_ok(1)
+            # In next iteration - wait on the "uploading" message to disappear.
+            self.sleep_for(self.wait_types.UX_RENDER)
+            self.screenshot("workbook_example_2_complete", "Final collection created and available in the history.")
+
+    def upload_workbook_example_3(self, include_result: bool = False):
+        """Importing a list of pairs collection with automatic pairing.
+
+        This test validates that Galaxy can:
+        - Detect paired data from two URL columns per row
+        - Automatically split and pair forward/reverse elements
+        - Add paired_identifier column for the rule builder
+        - Map list identifiers and genome information
+        """
+        self.home()
+        self.document(
+            """
+## Example 3: Paired-End Sequencing Data
+
+Many sequencing experiments produce **paired-end reads** - two files per sample (forward and reverse reads). Galaxy can automatically detect this structure when your spreadsheet has two URL columns per row.
+
+This example demonstrates how Galaxy splits the paired data and creates a **list of pairs collection** - the appropriate structure for paired-end sequencing data.
+"""
+        )
+        self.document(DOC_CLICK_RULES_ACTIVITY)
+        self.click_rules_activity()
+        self.screenshot("workbook_example_3_landing", CAPTION_RULES_WIZARD)
+
+        self.document(DOC_CREATE_COLLECTIONS)
+        self.components.rule_builder.create_collections.wait_for_and_click()
+        self.screenshot("workbook_example_3_create_collections", CAPTION_COLLECTIONS_BUTTON)
+
+        self.document_file(
+            WORKBOOK_EXAMPLE_3,
+            "Example workbook with paired URLs (forward/reverse reads) and genome information",
+        )
+        self.workbook_upload(WORKBOOK_EXAMPLE_3)
+        self.rule_builder_set_collection_name("Example 3 - A List of Pairs")
+
+        self.document(
+            """
+Galaxy has automatically detected and processed the paired data structure:
+- The **forward_url** and **reverse_url** columns are recognized as paired data (two URLs per sample)
+- Galaxy automatically **split the data** - notice that each row in the spreadsheet becomes two rows in the rule builder
+- A new **paired identifier** column (column 4) has been added automatically, marking which reads are "forward" and "reverse"
+- The **list identifier** column defines the sample names
+- The **genome** column provides the reference build for each sample
+
+This automatic splitting and pairing is one of the most powerful features of the rule-based uploader - it handles the complexity of paired data without requiring manual rule configuration.
+"""
+        )
+        self.screenshot(
+            "workbook_example_3_mapped",
+            "The rule builder showing automatic paired data detection - notice the data has been split with forward/reverse identifiers added",
+        )
+        if include_result:
+            self.rule_builder_import()
+            self.history_panel_wait_for_hid_ok(1)
+            # In next iteration - wait on the "uploading" message to disappear.
+            self.sleep_for(self.wait_types.UX_RENDER)
+            self.screenshot("workbook_example_3_complete", "Final collection created and available in the history.")
+
+    def upload_workbook_example_4(self, include_result: bool = False):
+        """Importing nested list structures with paired data
+
+        Demonstrates that Galaxy can:
+        - Handle complex nested list structures
+        - Detect and split paired data (two URLs per row)
+        - Infer multiple list identifier levels
+        - Build correct nested collection hierarchy
+
+        Note: The outer list identifier is always the first one that appears.
+        Column order matters for list nesting.
+        """
+        self.home()
+        self.document(
+            """
+## Example 4: Nested Collections with Paired Data
+
+For complex experiments, you might need **nested collections** - collections within collections. A common example is organizing paired-end data by experimental condition (e.g., different ChIP-seq targets) with technical replicates.
+
+This example shows how Galaxy automatically builds nested structures when your spreadsheet has multiple identifier columns. **The key concept**: column order determines the nesting hierarchy.
+"""
+        )
+        self.document(DOC_CLICK_RULES_ACTIVITY)
+        self.click_rules_activity()
+        self.screenshot("workbook_example_4_landing", CAPTION_RULES_WIZARD)
+
+        self.document(DOC_CREATE_COLLECTIONS)
+        self.components.rule_builder.create_collections.wait_for_and_click()
+        self.screenshot("workbook_example_4_create_collections", CAPTION_COLLECTIONS_BUTTON)
+
+        self.document_file(
+            WORKBOOK_EXAMPLE_4,
+            "Example workbook with paired URLs and multiple list identifier columns",
+        )
+        self.workbook_upload(WORKBOOK_EXAMPLE_4)
+        self.rule_builder_set_collection_name("Example 4 - Nested Collections")
+
+        self.document(
+            """
+Galaxy has detected a complex nested structure from the spreadsheet:
+- The **URI 1** and **URI 2** columns are recognized as paired data and automatically split
+- The **Outer List Identifier** and **Inner List Identifier** columns create a nested list structure
+- The result is a **list of lists of pairs** collection - perfect for organizing paired-end data by experimental groups
+
+**Important**: Column order determines the nesting hierarchy. The **third column** (labeled "Outer List Identifier") becomes the outer level, and the **fourth column** (labeled "Inner List Identifier") becomes the inner level. This is based purely on column position, not the column names.
+
+If we had swapped the order of these columns in the spreadsheet (putting "Inner List Identifier" in column 3), that column would actually become the outer level - the labels in the headers don't affect the structure, only the column order matters.
+
+This example demonstrates the most advanced capability of auto-detection, handling complex hierarchical data structures that are common in large sequencing studies.
+"""
+        )
+        self.screenshot(
+            "workbook_example_4_mapped",
+            "The rule builder showing automatic nested structure detection from multiple list identifier columns and paired URL columns",
+        )
+        # This is 12 multi-gigabyte datasets - don't both ever actually running the upload in
+        # this example.
+
+    def upload_rules_example_1(self, include_result: bool = False):
+        """Uploading datasets with manual rules - basic filtering and column mapping.
+
+        Demonstrates manual rule building to:
+        - Filter header rows from tabular data
+        - Map columns to dataset names and URLs
+        - Set file types explicitly
+        """
+        self.home()
+        self.document(
+            """
+## Uploading Datasets with Rules
+
+This example demonstrates the fundamental workflow of the rule-based uploader when working with tabular metadata from external sources like the [European Nucleotide Archive (ENA)](https://www.ebi.ac.uk/ena).
+
+We'll take a table containing study metadata with multiple columns and transform it into Galaxy datasets by:
+1. **Filtering out header rows** that don't contain downloadable data
+2. **Mapping columns** to tell Galaxy which column contains the dataset name and which contains the download URL
+3. **Setting the file type** so Galaxy knows how to handle the data
+
+This workflow is common when you've downloaded metadata from a sequence repository or generated it from your own LIMS system.
+"""
+        )
+        self.upload_rule_start()
+        self.sleep_for(self.wait_types.UX_RENDER)
+        self.screenshot("rules_example_1_1_rules_landing", "The rule-based upload dialog")
+        self.components.upload.rule_source_content.wait_for_and_send_keys(
+            """study_accession sample_accession    experiment_accession    fastq_ftp
+PRJDA60709  SAMD00016379    DRX000475   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000770/DRR000770.fastq.gz
+PRJDA60709  SAMD00016383    DRX000476   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000771/DRR000771.fastq.gz
+PRJDA60709  SAMD00016380    DRX000477   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000772/DRR000772.fastq.gz
+PRJDA60709  SAMD00016378    DRX000478   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000773/DRR000773.fastq.gz
+PRJDA60709  SAMD00016381    DRX000479   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000774/DRR000774.fastq.gz
+PRJDA60709  SAMD00016382    DRX000480   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000775/DRR000775.fastq.gz"""
+        )
+        self.wait_for_upload_modal()
+        self.screenshot("rules_example_1_2_paste", "Tabular data pasted into the upload dialog")
+        self.document(
+            """
+After pasting the tabular data, we click **Build** to open the rule builder interface. This opens a spreadsheet-like view where we can see our data and define rules to transform it.
+"""
+        )
+        self.upload_rule_build()
+        rule_builder = self.components.rule_builder
+        rule_builder._.wait_for_and_click()
+        self.screenshot("rules_example_1_3_initial_rules", "The rule builder showing the initial tabular data")
+        self.document(
+            """
+### Filtering the Header Row
+
+Our first task is to remove the header row (the first row containing column names) since it doesn't represent actual data to download. We'll use a **Filter** rule to remove it.
+
+Galaxy's rule builder provides various filter options - in this case, we'll filter out the first N rows (where N=1).
+"""
+        )
+        rule_builder.menu_button_filter.wait_for_and_click()
+        self.screenshot("rule_builder_filters", "The Filter menu showing available filtering options")
+        rule_builder.menu_item_rule_type(rule_type="add-filter-count").wait_for_and_click()
+        filter_editor = rule_builder.rule_editor(rule_type="add-filter-count")
+        filter_editor_element = filter_editor.wait_for_visible()
+        filter_input = filter_editor_element.find_element(By.CSS_SELECTOR, "input[type='number']")
+        filter_input.clear()
+        filter_input.send_keys("1")
+        self.screenshot("rules_example_1_4_filter_header", "Configuring the filter to remove the first row")
+        self.document(
+            """
+After applying the filter, the header row is removed and we're left with only the data rows. Now we need to tell Galaxy how to interpret each column.
+"""
+        )
+        rule_builder.rule_editor_ok.wait_for_and_click()
+        self.document(
+            """
+### Defining Column Mappings
+
+Next, we define **column definitions** to tell Galaxy:
+- Which column contains the **URL** (where to download files from)
+- Which column contains the **Name** (what to call each dataset in the history)
+
+In this example:
+- Column D (fastq_ftp) contains the download URLs
+- Column C (experiment_accession) will be used as the dataset names
+"""
+        )
+        self.rule_builder_set_mapping("url", "D")
+        self.rule_builder_set_mapping("name", "C", screenshot_name="rules_example_1_5_mapping_edit")
+        self.screenshot("rules_example_1_6_mapping_set", "Column mappings set for URL and Name")
+        self.document(
+            """
+Finally, we specify the **file type** (datatype extension) so Galaxy knows these are compressed FASTQ files. This determines how Galaxy will process and display the data.
+"""
+        )
+        self.rule_builder_set_extension("fastqsanger.gz")
+        self.screenshot("rules_example_1_7_extension_set", "File type set to fastqsanger.gz - ready to upload")
+        if include_result:
+            rule_builder.main_button_ok.wait_for_and_click()
+            self.history_panel_wait_for_hid_ok(6)
+            self.screenshot(
+                "rules_example_1_6_download_complete", "Final datasets created and available in the history."
+            )
+
+    def upload_rules_example_2(self, include_result: bool = False):
+        """Creating a simple list collection from a history dataset.
+
+        Demonstrates:
+        - Using metadata from an existing history dataset as input
+        - Creating collections instead of individual datasets
+        - Defining list identifiers for collection elements
+        """
+        self.document(
+            """
+## Creating a Simple Dataset List Collection
+
+Building on the previous example, we'll now create a **list collection** instead of individual datasets. Collections are powerful organizational structures in Galaxy that allow you to:
+- Group related datasets together
+- Run tools on all elements at once (mapping over collections)
+- Maintain sample identifiers throughout your analysis
+
+This example also demonstrates loading metadata from an **existing history dataset** rather than pasting it directly. This is useful when you've:
+- Downloaded metadata from an external source as a file
+- Generated sample lists using Galaxy tools
+- Performed filtering or manipulation on your metadata
+"""
+        )
+        self.perform_upload(RULES_EXAMPLE_2_SOURCE)
+        self.history_panel_wait_for_hid_ok(1)
+        self.upload_rule_start()
+        self.upload_rule_set_data_type("Collections")
+        self.upload_rule_dataset_dialog()
+        self.upload_rule_set_dataset(1)
+        self.screenshot(
+            "rules_example_2_1_inputs", "Rule builder configured to create collections from a history dataset"
+        )
+        self.document(
+            """
+The key difference from Example 1 is that we've selected:
+- **Upload data as**: Collections (instead of individual datasets)
+- **Load tabular data from**: a History Dataset (instead of pasted text)
+
+This tells Galaxy we want to build a collection structure from our metadata.
+"""
+        )
+        self.upload_rule_build()
+        rule_builder = self.components.rule_builder
+        rule_builder._.wait_for_and_click()
+        self.screenshot("rules_example_2_2_initial_rules", "Initial view of the rule builder with metadata loaded")
+        self.document(
+            """
+### Collection-Specific Mappings
+
+When creating collections, we use **List Identifier** instead of **Name** for our dataset labels. List identifiers serve as the element names within the collection and are preserved when you map tools over the collection.
+
+We'll apply the same transformations as before:
+1. Filter the header row
+2. Map column D to URL (download location)
+3. Map column C to **List Identifier** (collection element name)
+4. Set the file type to fastqsanger.gz
+"""
+        )
+        # Filter header.
+        self.rule_builder_filter_count(1)
+        self.rule_builder_set_mapping("url", "D")
+        self.rule_builder_set_mapping("list-identifiers", "C")
+        self.rule_builder_set_extension("fastqsanger.gz")
+        self.screenshot("rules_example_2_3_rules", "Rules configured with list identifier mapping")
+        self.document(
+            """
+Finally, we give the collection itself a name - this is the name that will appear in your history panel. Using the study accession (PRJDA60709) makes it easy to track which experiment this data came from.
+"""
+        )
+        self.rule_builder_set_collection_name("PRJDA60709")
+        self.screenshot("rules_example_2_4_name", "Collection named and ready to upload")
+        if include_result:
+            rule_builder.main_button_ok.wait_for_and_click()
+            self.history_panel_wait_for_hid_ok(2)
+            self.screenshot(
+                "rules_example_2_5_download_complete", "Final collection created and available in the history."
+            )
+
+    def upload_rules_example_3(self, include_result: bool = False):
+        """Creating a list of pairs collection with regular expressions.
+
+        Demonstrates advanced techniques:
+        - Using regular expressions to extract data from columns
+        - Splitting columns to create multiple rows per sample
+        - Creating paired-end collection structures
+        - Building proper paired identifiers
+        """
+        self.document(
+            """
+## Creating a List of Dataset Pairs
+
+Many sequencing experiments produce **paired-end reads** - two files per sample (forward and reverse). This example shows how to handle metadata where both URLs are in a single column, separated by a semicolon.
+
+This is a more advanced workflow that demonstrates the power of the rule builder for data transformation. We'll need to:
+1. **Split** the semicolon-separated URLs into separate columns
+2. **Duplicate each row** so one row becomes two (one for forward, one for reverse)
+3. **Extract** the pair indicator (1 or 2) from the filenames using regular expressions
+4. **Map** the appropriate columns to create a list:paired collection structure
+
+This type of transformation is common when working with data from repositories like ENA or SRA where paired files are often listed together.
+"""
+        )
+        self.perform_upload(RULES_EXAMPLE_3_SOURCE)
+        self.history_panel_wait_for_hid_ok(1)
+        self.upload_rule_start()
+        self.upload_rule_set_data_type("Collections")
+        self.upload_rule_dataset_dialog()
+        self.upload_rule_set_dataset(1)
+        self.wait_for_upload_modal()
+        self.screenshot("rules_example_3_1_inputs", "Loading paired-end data from a history dataset")
+        self.upload_rule_build()
+        rule_builder = self.components.rule_builder
+        rule_builder._.wait_for_and_click()
+        self.screenshot("rules_example_3_2_initial_rules", "Initial data showing semicolon-separated URLs in column D")
+        self.document(
+            """
+### Initial Setup
+
+First, we'll do our standard setup: filter the header and set the list identifier mapping. Notice that column D contains two URLs separated by a semicolon - we'll need to handle this specially.
+"""
+        )
+        # Filter header.
+        self.rule_builder_filter_count(1)
+        self.rule_builder_set_mapping("list-identifiers", "C")
+        self.rule_builder_set_extension("fastqsanger.gz")
+        self.screenshot("rules_example_3_3_old_rules", "Basic mappings set, but column D still has two URLs")
+        self.document(
+            """
+### Splitting URLs with Regular Expressions
+
+Column D contains two URLs like `url1;url2`. We'll use a **regular expression** to split this into two separate columns:
+- Pattern: `(.*);(.*)`
+  - `(.*)` = capture any characters (first URL)
+  - `;` = match the semicolon separator
+  - `(.*)` = capture any characters (second URL)
+- This creates two new columns (D and E) from the original column D
+"""
+        )
+        self.rule_builder_add_regex_groups("D", 2, r"(.*);(.*)", screenshot_name="rules_example_3_4_regex")
+        self.screenshot(
+            "rules_example_3_6_with_regexes", "Column D split into two columns with forward and reverse URLs"
+        )
+        self.document(
+            """
+Now we have two URL columns, but they're still in the same row. We need one row per file.
+"""
+        )
+        # Remove A also?
+        self.rule_builder_remove_columns(["D"], screenshot_name="rules_example_3_7_removed_column")
+        self.document(
+            """
+### Creating Rows for Each Pair Member
+
+We'll use **Split Columns** to convert each row into two rows:
+- Odd rows will keep column D (forward reads)
+- Even rows will keep column E (reverse reads)
+
+This effectively doubles our row count, with each original sample now represented by two rows.
+"""
+        )
+        self.rule_builder_split_columns(["D"], ["E"], screenshot_name="rules_example_3_8_split_columns")
+        self.screenshot(
+            "rules_example_3_9_columns_are_split", "Each sample is now two rows - one for each read direction"
+        )
+        self.document(
+            r"""
+### Extracting the Pair Indicator
+
+Now we need to tell Galaxy which rows are forward reads and which are reverse. The filenames contain `_1.fastq.gz` or `_2.fastq.gz`, so we'll extract that digit using another regular expression:
+- Pattern: `.*_(\d).fastq.gz`
+  - `.*_` = match everything up to the underscore
+  - `(\d)` = capture one digit (this becomes our pair indicator: 1 or 2)
+  - `.fastq.gz` = match the file extension
+"""
+        )
+        self.rule_builder_add_regex_groups(
+            "D", 1, r".*_(\d).fastq.gz", screenshot_name="rules_example_3_10_regex_paired"
+        )
+        self.screenshot("rules_example_3_11_has_paired_id", "New column showing 1 or 2 to indicate forward/reverse")
+        self.document(
+            """
+For clarity, we'll swap the columns so the pair indicator appears before the URL column. Then we set our final column definitions:
+- Column D: **Paired identifier** (1 for forward, 2 for reverse)
+- Column E: **URL** (download location)
+"""
+        )
+        self.rule_builder_swap_columns("D", "E", screenshot_name="rules_example_3_12_swap_columns")
+        self.screenshot("rules_example_3_13_swapped_columns", "Columns reordered for clarity")
+        self.rule_builder_set_mapping("paired-identifier", "D")
+        self.rule_builder_set_mapping("url", "E")
+        self.rule_builder_set_collection_name("PRJDB3920")
+        self.screenshot("rules_example_3_14_paired_identifier_set", "Paired collection configured and ready to upload")
+
+    def upload_rules_example_4(self, include_result: bool = False):
+        """Building URLs from accession numbers.
+
+        Demonstrates advanced URL construction:
+        - Dynamically building download URLs from accession IDs
+        - Using regex replacement to construct URLs
+        - Sorting data for better organization
+        - Viewing the JSON rule definitions
+        """
+        self.document(
+            """
+## Building URLs from Accession Information
+
+In previous examples, our metadata already contained complete download URLs. But often you'll have **accession numbers** or **identifiers** without the full URLs. This example shows how to construct URLs programmatically from identifiers.
+
+### Scenario: UniProt Protein Data
+
+We have a table of UniProt accession IDs for proteins from a specific organism. UniProt provides FASTA files at predictable URLs:
+- Pattern: `https://www.uniprot.org/uniprot/{accession}.fasta`
+- Example: `https://www.uniprot.org/uniprot/E7C0H6.fasta`
+
+We'll use the rule builder to:
+1. Clean up unnecessary columns
+2. **Build complete URLs** using regex replacement
+3. Sort the data alphabetically for better organization
+4. Map the accession IDs as list identifiers
+"""
+        )
+        self.setup_uniprot_example()
+        self.wait_for_upload_modal()
+        self.screenshot("rules_example_4_1_inputs", "UniProt metadata loaded with accession IDs")
+        self.upload_rule_build()
+        rule_builder = self.components.rule_builder
+        rule_builder._.wait_for_and_click()
+        self.screenshot("rules_example_4_2_initial_rules", "Initial UniProt data with many columns")
+        self.document(
+            """
+### Cleaning and Organizing the Data
+
+First, we'll clean up our data by:
+1. Filtering the header row
+2. Removing unnecessary columns (keeping only accession ID and protein names)
+3. Mapping the protein names to the **Info** field (this will appear as tooltip text in the history)
+4. Sorting by accession ID for easier browsing
+"""
+        )
+        self.rule_builder_filter_count(1)
+        self.rule_builder_remove_columns(["B", "C", "E", "F", "G"])
+        self.rule_builder_set_mapping("info", "B")
+        self.screenshot("rules_example_4_3_basic_rules", "Cleaned data with Info mapping set")
+        self.rule_builder_sort("A", screenshot_name="rules_example_4_4_sort")
+
+        self.document(
+            """
+### Building URLs with Regex Replacement
+
+Now for the key step: building the download URLs. We'll use **regex replacement** to transform each accession ID into a complete URL.
+
+- **Pattern**: `.*` (match the entire accession ID)
+- **Replacement**: `http://www.uniprot.org/uniprot/\\0.fasta`
+  - `\\0` is replaced by the matched text (the accession ID)
+  - This constructs the full URL for each protein's FASTA file
+
+This technique works for any repository with predictable URL patterns.
+"""
+        )
+        self.rule_builder_add_regex_replacement(
+            "A", ".*", "http://www.uniprot.org/uniprot/\\0.fasta", screenshot_name="rules_example_4_5_url"
+        )
+        self.screenshot("rules_example_4_6_url_built", "New column C showing the constructed URLs")
+        self.document(
+            """
+### Final Column Mappings
+
+With URLs built, we can now set our final mappings:
+- Column A: **List Identifier** (the accession ID)
+- Column C: **URL** (the constructed download URL)
+- File type: **fasta**
+- Collection name: **UP000052092** (the proteome ID)
+"""
+        )
+        self.rule_builder_set_mapping("list-identifiers", "A")
+        self.rule_builder_set_mapping("url", "C")
+        self.rule_builder_set_extension("fasta")
+        self.rule_builder_set_collection_name("UP000052092")
+        self.screenshot("rules_example_4_7_mapping_extension_and_name", "Complete configuration ready to upload")
+
+        self.document(
+            """
+### Viewing Rule Definitions as JSON
+
+The rule builder stores all your transformations as JSON. This is useful for:
+- **Reproducibility**: Save and share your exact transformation steps
+- **Reuse**: Apply the same rules to new datasets
+- **Documentation**: Understanding exactly what transformations were applied
+
+Click the wrench icon to view the JSON representation of these rules.
+"""
+        )
+        rule_builder.view_source.wait_for_and_click()
+
+        self.screenshot("rules_example_4_8_source", "JSON representation of the rule transformations")
+
+        rule_builder.main_button_ok.wait_for_and_click()
+        rule_builder.view_source.wait_for_visible()
+
+    def upload_rules_example_5(self, include_result: bool = False):
+        """Building matched collections from the same metadata.
+
+        Demonstrates:
+        - Creating multiple collections simultaneously
+        - Using column splitting to duplicate rows for different file types
+        - Reading collection names and datatypes from metadata columns
+        - Reusing rules from previous examples (via JSON)
+        """
+        self.document(
+            """
+## Building Matched Collections
+
+Sometimes you need to download multiple file types for the same set of samples - for example, both FASTA sequences and GFF3 annotations for the same proteins. This example shows how to create **matched collections** with corresponding list identifiers from a single metadata table.
+
+We'll build two collections:
+1. **FASTA files** - protein sequences
+2. **GFF3 files** - gene annotations
+
+Both collections will have the same accession IDs as list identifiers, making it easy to process them together in workflows.
+
+The key technique: we'll add columns for BOTH file types, then use **Split Columns** to create two rows per accession - one for FASTA, one for GFF3.
+"""
+        )
+        self.setup_uniprot_example()
+        self.wait_for_upload_modal()
+        self.screenshot("rules_example_5_1_inputs", "Starting with the same UniProt metadata as Example 4")
+        self.upload_rule_build()
+
+        rule_builder = self.components.rule_builder
+        rule_builder.view_source.wait_for_and_click()
+
+        self.document(
+            """
+### Reusing Rules via JSON
+
+Rather than manually recreating the rules from Example 4, we can import the JSON directly. This demonstrates how to reuse transformation logic across datasets.
+"""
+        )
+        with open(RULES_UNIPROT_RULES) as f:
+            content = f.read()
+        self.rule_builder_enter_source_text(content)
+        self.screenshot("rules_example_5_2_source", "Importing rules JSON from Example 4")
+        rule_builder.main_button_ok.wait_for_and_click()
+        rule_builder.view_source.wait_for_visible()
+        self.screenshot("rules_example_5_3_initial_rules", "Rules from Example 4 applied - now we'll extend them")
+        self.document(
+            """
+### Adding Columns for Both File Types
+
+Now we'll add columns to describe both FASTA and GFF3 downloads:
+1. Add fixed value "fasta" (datatype for FASTA collection)
+2. Add fixed value "UP000052092 FASTA" (collection name)
+3. Build GFF3 URLs using regex replacement
+4. Add fixed value "gff3" (datatype for GFF3 collection)
+5. Add fixed value "UP000052092 GFF3" (collection name)
+
+This creates a wide table where each row has information for both file types.
+"""
+        )
+        self.rule_builder_add_value("fasta", screenshot_name="rules_example_5_4_fasta")
+        self.rule_builder_add_value("UP000052092 FASTA")
+        self.rule_builder_add_regex_replacement(
+            "A", ".*", "http://www.uniprot.org/uniprot/\\0.gff", screenshot_name="rules_example_5_5_url"
+        )
+        self.rule_builder_add_value("gff3")
+        self.rule_builder_add_value("UP000052092 GFF3")
+        self.scroll_to_end_of_table()
+        self.screenshot("rules_example_5_6_presplit", "Wide table with both FASTA and GFF3 information per row")
+        self.document(
+            """
+### Splitting into Separate Collection Rows
+
+Now we use **Split Columns** to create two rows per accession:
+- Odd rows get columns C, D, E (FASTA URL, "fasta" type, "UP000052092 FASTA" name)
+- Even rows get columns F, G, H (GFF3 URL, "gff3" type, "UP000052092 GFF3" name)
+
+This converts our wide table into a long table where each row represents one file to download.
+"""
+        )
+        self.rule_builder_split_columns(
+            ["C", "D", "E"], ["F", "G", "H"], screenshot_name="rules_example_5_7_split_columns"
+        )
+        self.screenshot("rules_example_5_8_split", "Data split - now each accession has two rows (FASTA and GFF3)")
+        self.document(
+            """
+### Reading Collection Properties from Metadata
+
+Finally, we set column definitions that read values FROM the metadata:
+- Column D: **Type** (file-type read from metadata: "fasta" or "gff3")
+- Column E: **Collection Name** (read from metadata: "UP000052092 FASTA" or "UP000052092 GFF3")
+
+This creates two separate collections with matched identifiers.
+"""
+        )
+        self.rule_builder_set_mapping("file-type", "D")
+        self.rule_builder_set_mapping("collection-name", "E")
+        self.screenshot("rules_example_5_9_mapping", "Mappings configured to create two matched collections")
+
+    def upload_rules_example_6(self, include_result: bool = False):
+        """Building nested list collections.
+
+        Demonstrates:
+        - Creating nested collection structures (list of lists)
+        - Using multiple list identifier columns
+        - Extracting grouping information with regex
+        - Organizing data by experimental conditions and samples
+        """
+        self.document(
+            """
+## Building Nested Lists
+
+For complex experimental designs, you may want **nested collections** - lists within lists. For example:
+- Outer level: experimental conditions (treated, untreated, different antibodies, etc.)
+- Inner level: individual samples or replicates
+
+This example uses SRA data where samples are organized by library type (e.g., "wtPA14", "con1", "str1", "gen1"). The library names include numbers (con1, con2, etc.) that we need to strip out to group samples by type.
+
+### Key Concept: Multiple List Identifiers
+
+When you assign **two columns** as list identifiers:
+- The **first column** becomes the outer (top-level) identifier
+- The **second column** becomes the inner (nested) identifier
+- Result: a **list:list** collection structure
+"""
+        )
+        self.home()
+        self.perform_upload(RULES_EXAMPLE_6_SOURCE)
+        self.history_panel_wait_for_hid_ok(1)
+        self.upload_rule_start()
+        self.upload_rule_set_data_type("Collections")
+        self.upload_rule_dataset_dialog()
+        self.upload_rule_set_dataset(1)
+
+        self.wait_for_upload_modal()
+        self.screenshot("rules_example_6_1_paste", "SRA metadata with library names like 'wtPA14', 'con1', 'str2'")
+        self.upload_rule_build()
+
+        rule_builder = self.components.rule_builder
+        rule_builder._.wait_for_and_click()
+
+        self.screenshot("rules_example_6_2_rules_landing", "Initial table view - note column J contains URLs")
+        self.document(
+            """
+### Basic Setup
+
+First, the standard operations:
+1. Filter the header row
+2. Map column J (download_path) to URL
+3. Set file type to sra
+"""
+        )
+        self.rule_builder_filter_count(1)
+
+        self.rule_builder_set_mapping("url", "J")
+        self.rule_builder_set_extension("sra")
+        self.scroll_to_end_of_table()
+        self.screenshot("rules_example_6_3_end_of_table", "Scrolled to show library names in column L")
+        self.document(
+            r"""
+### Extracting Group Names with Regex
+
+Column L contains library names like "wtPA14", "con1", "con2", "str1", "gen5". We want to group by the **text prefix** (con, str, gen) but the numbers make each name unique.
+
+We'll use regex to extract just the prefix:
+- Pattern: `([^\d]+)\d+`
+  - `[^\d]+` = one or more non-digit characters (captures "con", "str", "gen")
+  - `\d+` = one or more digits (matches but doesn't capture the numbers)
+- This creates a new column with just the group names
+"""
+        )
+        self.rule_builder_add_regex_groups("L", 1, r"([^\d]+)\d+", screenshot_name="rules_example_6_4_regex")
+        self.document(
+            """
+### Setting Multiple List Identifiers
+
+Now we assign **two columns** as list identifiers:
+1. Column M (the extracted group: "con", "str", "gen") - becomes the **outer** identifier
+2. Column A (the run accession: SRR numbers) - becomes the **inner** identifier
+
+This creates a nested structure where samples are organized by type, with individual runs nested inside each type.
+"""
+        )
+        self.rule_builder_set_mapping(
+            "list-identifiers", ["M", "A"], screenshot_name="rules_example_6_5_multiple_identifiers_edit"
+        )
+        self.scroll_to_end_of_table()
+        self.screenshot("rules_example_6_6_multiple_identifiers", "Two list identifier columns configured")
+        self.document(
+            """
+Name the collection and you're ready to create a nested list:list structure, perfect for running tools that need to process samples grouped by experimental condition.
+"""
+        )
+        self.rule_builder_set_collection_name("PRJNA355367")
+        self.screenshot("rules_example_6_7_named", "Nested collection configured and ready to upload")
+
+    def setup_uniprot_example(self):
+        self.perform_upload(RULES_UNIPROT_SOURCE)
+        self.history_panel_wait_for_hid_ok(1)
+        self.upload_rule_start()
+        self.upload_rule_set_data_type("Collections")
+        self.upload_rule_dataset_dialog()
+        self.upload_rule_set_dataset(1)
+
+    def scroll_to_end_of_table(self):
+        if self.backend_type == "selenium":
+            rule_builder = self.components.rule_builder
+            table_elem = rule_builder.table.wait_for_visible()
+            # handsontable
+            # first_cell = table_elem.find_elements(By.CSS_SELECTOR, "td")[0]
+            # aggrid
+            first_cell = table_elem.find_elements(By.CSS_SELECTOR, ".ag-cell")[0]
+            action_chains = self.action_chains()
+            action_chains.move_to_element(first_cell)
+            action_chains.click(first_cell)
+            for _ in range(15):
+                action_chains.send_keys(Keys.ARROW_RIGHT)
+            action_chains.perform()
diff --git a/lib/galaxy/selenium/stories/story.py b/lib/galaxy/selenium/stories/story.py
new file mode 100644
index 000000000000..fb01a10f9bdb
--- /dev/null
+++ b/lib/galaxy/selenium/stories/story.py
@@ -0,0 +1,622 @@
+"""General-purpose story builder for collecting screenshots and documentation.
+
+This module provides the Story class for creating narrative documentation with
+interleaved screenshots and markdown content. It's independent of any test
+framework and can be used in tests, Jupyter notebooks, or standalone scripts.
+"""
+
+import os
+import re
+import zipfile
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    Any,
+    Literal,
+    Optional,
+    TypedDict,
+)
+
+from galaxy.util.markdown import (
+    to_html,
+    to_pdf_raw,
+    weasyprint_available,
+)
+
+# Type for story elements: (type, content, metadata)
+StoryElement = tuple[str, str, dict[str, Any]]
+
+# Type aliases for stronger typing
+ElementType = Literal['documentation', 'screenshot']
+SectionMode = Literal['replace', 'append', 'standalone']
+
+
+class SectionMetadata(TypedDict):
+    """Metadata for a story section."""
+
+    title: str
+    anchor: str
+    level: int
+    skip: bool
+    start_index: Optional[int]
+
+
+class SectionMetadataInput(TypedDict):
+    """Input metadata when creating a section (before enrichment)."""
+
+    title: str
+    anchor: str
+
+
+class ElementMetadata(TypedDict, total=False):
+    """Metadata for story elements."""
+
+    caption: str
+    section_start: str
+
+
+class StoryProtocol(ABC):
+    """Protocol for story implementations (real or noop)."""
+
+    @property
+    @abstractmethod
+    def enabled(self) -> bool:
+        """Whether story generation is enabled."""
+
+    @property
+    @abstractmethod
+    def output_directory(self) -> str:
+        """Output directory for story artifacts."""
+
+    @property
+    @abstractmethod
+    def screenshot_counter(self) -> int:
+        """Current screenshot counter."""
+
+    @screenshot_counter.setter
+    @abstractmethod
+    def screenshot_counter(self, value: int):
+        """Set screenshot counter."""
+
+    @abstractmethod
+    def add_screenshot(self, screenshot_path: str, caption: str):
+        """Add a screenshot to the story."""
+
+    @abstractmethod
+    def add_documentation(self, markdown_content: str):
+        """Add markdown documentation to the story."""
+
+    @abstractmethod
+    def reset(self):
+        """Reset story state."""
+
+    @abstractmethod
+    def finalize(self):
+        """Generate final story artifacts."""
+
+    @abstractmethod
+    def _begin_section(self, meta: SectionMetadataInput) -> None:
+        """Start tracking a new section."""
+
+    @abstractmethod
+    def _end_section(self) -> None:
+        """Finish tracking current section."""
+
+
+class Story(StoryProtocol):
+    """General-purpose story builder for collecting screenshots and documentation.
+
+    This class is independent of any test framework and can be used in various
+    contexts (tests, Jupyter notebooks for tutorials, user documentation, etc.).
+    """
+
+    def __init__(
+        self,
+        title: str,
+        description: str,
+        output_directory: str,
+        only_sections: set[str] | None = None,
+        skip_sections: set[str] | None = None,
+        merge_target: str | None = None,
+        section_mode: SectionMode = 'standalone',
+    ):
+        """Initialize a new story.
+
+        Args:
+            title: Story title (used as H1 heading)
+            description: Story description (first paragraph after title)
+            output_directory: Directory where story artifacts will be saved
+            only_sections: Optional set of section anchors to include (exclude all others)
+            skip_sections: Optional set of section anchors to skip
+            merge_target: Path to existing markdown to merge sections into
+            section_mode: How to handle sections: 'replace', 'append', or 'standalone'
+        """
+        self.title = title
+        self.description = description
+        self._output_directory = output_directory
+        self.elements: list[StoryElement] = []  # List of (type, content, metadata) tuples
+        self._screenshot_counter = 0
+
+        # Section tracking
+        self.section_stack: list[SectionMetadata] = []
+        self.section_elements: dict[str, list[StoryElement]] = {}
+        self.only_sections: set[str] | None = only_sections
+        self.skip_sections: set[str] | None = skip_sections
+        self.merge_target: str | None = merge_target
+        self.section_mode: SectionMode = section_mode
+        self._filtering_active: bool = False
+
+    @property
+    def enabled(self) -> bool:
+        """Story generation is enabled for Story instances."""
+        return True
+
+    @property
+    def output_directory(self) -> str:
+        """Output directory for story artifacts."""
+        return self._output_directory
+
+    @property
+    def screenshot_counter(self) -> int:
+        """Current screenshot counter."""
+        return self._screenshot_counter
+
+    @screenshot_counter.setter
+    def screenshot_counter(self, value: int):
+        """Set screenshot counter."""
+        self._screenshot_counter = value
+
+    def add_screenshot(self, screenshot_path: str, caption: str):
+        """Add a screenshot to the story.
+
+        Args:
+            screenshot_path: Absolute path to screenshot file
+            caption: Caption for the screenshot (used as heading and alt text)
+        """
+        if self._filtering_active:
+            return  # Skip if in filtered-out section
+        element_meta: ElementMetadata = {"caption": caption}
+        self.elements.append(("screenshot", screenshot_path, element_meta))
+
+    def add_documentation(self, markdown_content: str):
+        """Add markdown documentation to the story.
+
+        Args:
+            markdown_content: Markdown-formatted content to append
+        """
+        if self._filtering_active:
+            return  # Skip if in filtered-out section
+        self.elements.append(("documentation", markdown_content, {}))
+
+    def _begin_section(self, meta: SectionMetadataInput) -> None:
+        """Start tracking a new section with filtering support."""
+        anchor = meta['anchor']
+
+        # Determine if this section should be included
+        should_skip = False
+        if self.only_sections and anchor not in self.only_sections:
+            should_skip = True
+        if self.skip_sections and anchor in self.skip_sections:
+            should_skip = True
+
+        # Calculate level: 2 (H2) + current depth
+        level = 2 + len(self.section_stack)
+
+        # Create enriched metadata
+        enriched: SectionMetadata = {
+            'title': meta['title'],
+            'anchor': anchor,
+            'level': level,
+            'skip': should_skip,
+            'start_index': None if should_skip else len(self.elements),
+        }
+
+        if should_skip:
+            self._filtering_active = True
+        else:
+            # Add section header
+            heading = f"{'#' * level} {enriched['title']}"
+            anchor_html = f'<a id="{anchor}"></a>'
+            element_meta: ElementMetadata = {'section_start': anchor}
+            self.elements.append(('documentation', f'{anchor_html}\n{heading}\n', element_meta))
+
+        self.section_stack.append(enriched)
+
+    def _end_section(self) -> None:
+        """Finish tracking current section with filtering support."""
+        if not self.section_stack:
+            return
+
+        meta = self.section_stack.pop()
+
+        if meta['skip']:
+            # Update filtering state based on remaining stack
+            self._filtering_active = len(self.section_stack) > 0 and any(s['skip'] for s in self.section_stack)
+            return
+
+        # Store section elements
+        anchor = meta['anchor']
+        start = meta['start_index']
+
+        if start is None:
+            return
+
+        end = len(self.elements)
+        self.section_elements[anchor] = self.elements[start:end].copy()
+
+        # Update filtering state based on remaining stack
+        self._filtering_active = len(self.section_stack) > 0 and any(s['skip'] for s in self.section_stack)
+
+    def reset(self):
+        """Reset story state for test retry.
+
+        Clears all collected screenshots and documentation, resets counters.
+        Used when a test is retried after failure to avoid accumulating content
+        from failed attempts.
+        """
+        self.elements = []
+        self._screenshot_counter = 0
+        self.section_stack = []
+        self.section_elements = {}
+        self._filtering_active = False
+
+    def finalize(self):
+        """Generate final story artifacts (markdown, HTML, PDF, zip).
+
+        Creates:
+        - story.md: Markdown source with embedded screenshots
+        - story.html: Self-contained HTML with embedded images
+        - story.pdf: PDF version (if weasyprint available)
+        - {output_directory}.zip: Zip archive of all artifacts
+
+        If merge_target is set, merges sections into existing markdown before generation.
+        """
+        # Merge sections into existing document if requested
+        if self.merge_target and os.path.exists(self.merge_target):
+            self._merge_sections(self.merge_target)
+
+        # 1. Generate markdown file
+        markdown_content = self._generate_markdown()
+        markdown_path = os.path.join(self.output_directory, "story.md")
+        with open(markdown_path, "w") as f:
+            f.write(markdown_content)
+
+        # 2. Generate HTML file
+        html_content = self._generate_html(markdown_content)
+        html_path = os.path.join(self.output_directory, "story.html")
+        with open(html_path, "w") as f:
+            f.write(html_content)
+
+        # 3. Generate PDF file
+        pdf_path = os.path.join(self.output_directory, "story.pdf")
+        self._generate_pdf(markdown_content, pdf_path)
+
+        # 4. Create zip archive
+        zip_path = os.path.join(
+            os.path.dirname(self.output_directory), f"{os.path.basename(self.output_directory)}.zip"
+        )
+        self._create_zip(zip_path)
+
+    def _generate_markdown(self) -> str:
+        """Generate markdown content for the story."""
+        lines = []
+
+        # Title
+        lines.append(f"# {self.title}\n")
+
+        # Description as first paragraph
+        if self.description:
+            lines.append(self.description.strip())
+            lines.append("\n")
+
+        # Interleave screenshots and documentation
+        for element_type, content, metadata in self.elements:
+            if element_type == "screenshot":
+                screenshot_path = content
+                caption = metadata.get("caption", "")
+                # Use relative path for markdown
+                rel_path = os.path.basename(screenshot_path)
+                lines.append(f"## {caption}\n")
+                lines.append(f"![{caption}]({rel_path})\n")
+            elif element_type == "documentation":
+                lines.append(content)
+                lines.append("\n")
+
+        return "\n".join(lines)
+
+    def _generate_html(self, markdown_content: str) -> str:
+        """Generate HTML from markdown."""
+        html_body = to_html(markdown_content)
+
+        # Wrap in basic HTML structure with styling
+        html_template = f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>{self.title}</title>
+    <style>
+        body {{
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 20px;
+            line-height: 1.6;
+        }}
+        img {{
+            max-width: 100%;
+            height: auto;
+            border: 1px solid #ddd;
+            border-radius: 4px;
+            margin: 10px 0;
+        }}
+        h1 {{
+            color: #333;
+            border-bottom: 2px solid #007bff;
+            padding-bottom: 10px;
+        }}
+        h2 {{
+            color: #555;
+            margin-top: 30px;
+        }}
+    </style>
+</head>
+<body>
+{html_body}
+</body>
+</html>"""
+
+        return html_template
+
+    def _generate_pdf(self, markdown_content: str, output_path: str):
+        """Generate PDF from markdown using weasyprint.
+
+        Degrades gracefully if weasyprint is not available.
+        """
+        try:
+            if not weasyprint_available():
+                print("Warning: weasyprint not available, skipping PDF generation")
+                return
+
+            pdf_bytes = to_pdf_raw(markdown_content, directory=self.output_directory)
+            with open(output_path, "wb") as f:
+                f.write(pdf_bytes)
+        except Exception as e:
+            print(f"Warning: Failed to generate PDF: {e}")
+            # Non-fatal - we still have markdown and HTML
+
+    def _extract_sections_from_markdown(self, markdown_path: str) -> dict[str, list[str]]:
+        """Parse existing markdown and extract sections by anchor.
+
+        Returns a dict mapping anchor -> list of lines for that section.
+        Also includes a special '__preamble__' key for content before first section.
+        """
+        with open(markdown_path) as f:
+            content = f.read()
+
+        sections: dict[str, list[str]] = {}
+        current_anchor: str | None = None
+        current_lines: list[str] = []
+        preamble_lines: list[str] = []
+
+        for line in content.split('\n'):
+            # Look for anchor tags: <a id="anchor_name"></a>
+            if '<a id="' in line:
+                # Save previous section if any
+                if current_anchor:
+                    sections[current_anchor] = current_lines
+                elif current_lines and not any(sections.values()):
+                    # This is preamble content (before first section)
+                    preamble_lines = current_lines
+
+                # Extract anchor from line
+                match = re.search(r'<a id="([^"]+)">', line)
+                current_anchor = match.group(1) if match else None
+                current_lines = [line]
+            elif current_anchor:
+                current_lines.append(line)
+            else:
+                # Before any section
+                preamble_lines.append(line)
+
+        # Save last section
+        if current_anchor and current_lines:
+            sections[current_anchor] = current_lines
+
+        # Save preamble if we have it
+        if preamble_lines:
+            sections['__preamble__'] = preamble_lines
+
+        return sections
+
+    def _elements_to_markdown(self, elements: list[StoryElement]) -> str:
+        """Convert elements list to markdown string."""
+        parts: list[str] = []
+        for element_type, content, metadata in elements:
+            if element_type == 'documentation':
+                parts.append(content)
+            elif element_type == 'screenshot':
+                caption = metadata.get('caption', '')
+                parts.append(f"## {caption}\n\n![{caption}]({os.path.basename(content)})\n")
+        return '\n'.join(parts)
+
+    def _merge_sections(self, target_path: str) -> None:
+        """Merge generated sections into existing document.
+
+        Updates self.elements with merged content based on section_mode:
+        - 'replace': Replace matching sections in existing doc
+        - 'append': Append new sections to end
+        - 'standalone': No merging (default behavior)
+        """
+        if self.section_mode == 'standalone':
+            return  # No merging needed
+
+        # Extract sections from existing document
+        existing_sections = self._extract_sections_from_markdown(target_path)
+
+        if self.section_mode == 'replace':
+            # Replace matching sections, preserve order from existing doc
+            merged_elements: list[StoryElement] = []
+
+            # Start with preamble if it exists
+            if '__preamble__' in existing_sections:
+                preamble_text = '\n'.join(existing_sections['__preamble__'])
+                if preamble_text.strip():
+                    merged_elements.append(('documentation', preamble_text, {}))
+
+            # Track which new sections we've used
+            used_anchors: set[str] = set()
+
+            # Iterate through existing sections in order
+            for anchor in existing_sections:
+                if anchor == '__preamble__':
+                    continue
+
+                if anchor in self.section_elements:
+                    # Use new version of this section
+                    merged_elements.extend(self.section_elements[anchor])
+                    used_anchors.add(anchor)
+                else:
+                    # Keep existing section
+                    section_text = '\n'.join(existing_sections[anchor])
+                    merged_elements.append(('documentation', section_text, {}))
+
+            # Add any new sections that weren't in the original
+            for anchor, elements in self.section_elements.items():
+                if anchor not in used_anchors:
+                    merged_elements.extend(elements)
+
+            self.elements = merged_elements
+
+        elif self.section_mode == 'append':
+            # Keep all existing sections, append new ones that don't exist
+            merged_elements = []
+
+            # Start with preamble
+            if '__preamble__' in existing_sections:
+                preamble_text = '\n'.join(existing_sections['__preamble__'])
+                if preamble_text.strip():
+                    merged_elements.append(('documentation', preamble_text, {}))
+
+            # Add all existing sections
+            for anchor in existing_sections:
+                if anchor == '__preamble__':
+                    continue
+                section_text = '\n'.join(existing_sections[anchor])
+                merged_elements.append(('documentation', section_text, {}))
+
+            # Append new sections that don't exist
+            for anchor, elements in self.section_elements.items():
+                if anchor not in existing_sections:
+                    merged_elements.extend(elements)
+
+            self.elements = merged_elements
+
+    def _create_zip(self, zip_path: str) -> None:
+        """Create zip archive of story directory."""
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zipf:
+            # Walk the output directory
+            for root, _dirs, files in os.walk(self.output_directory):
+                for file in files:
+                    file_path = os.path.join(root, file)
+                    # Add to zip with relative path
+                    arcname = os.path.relpath(file_path, self.output_directory)
+                    zipf.write(file_path, arcname)
+
+
+class SectionProxy:
+    """Context manager that tracks story sections.
+
+    Evaluates to False when the section should be skipped (filtered out),
+    allowing code to conditionally execute expensive operations:
+
+        with driver.section("Example", "example") as section:
+            if section:
+                # This only runs if section is not filtered
+                expensive_operation()
+    """
+
+    def __init__(self, driver_or_context: Any, title: str, anchor: str):
+        self._driver = driver_or_context
+        self._meta: SectionMetadataInput = {
+            'title': title,
+            'anchor': anchor,
+        }
+        self.should_skip: bool = False
+
+    def __enter__(self) -> 'SectionProxy':
+        # Access story via driver/context
+        story = getattr(self._driver, 'story', None)
+        if story and story.enabled:
+            story._begin_section(self._meta)
+            # Check if this section is being filtered out
+            if story.section_stack:
+                self.should_skip = story.section_stack[-1]['skip']
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
+        story = getattr(self._driver, 'story', None)
+        if story and story.enabled:
+            story._end_section()
+        return False  # Don't suppress exceptions
+
+    def __bool__(self) -> bool:
+        """Return False if section should be skipped, True otherwise."""
+        return not self.should_skip
+
+
+class NoopStory(StoryProtocol):
+    """No-op story implementation for when story generation is disabled.
+
+    Implements the StoryProtocol interface but does nothing. Used as a null
+    object to avoid conditional checks throughout the codebase.
+    """
+
+    def __init__(self):
+        """Initialize noop story."""
+        self._screenshot_counter = 0
+
+    @property
+    def enabled(self) -> bool:
+        """Story generation is disabled for NoopStory instances."""
+        return False
+
+    @property
+    def output_directory(self) -> str:
+        """Return empty string for noop story."""
+        return ""
+
+    @property
+    def screenshot_counter(self) -> int:
+        """Return counter (unused but required by protocol)."""
+        return self._screenshot_counter
+
+    @screenshot_counter.setter
+    def screenshot_counter(self, value: int):
+        """Set counter (no-op but required by protocol)."""
+        self._screenshot_counter = value
+
+    def add_screenshot(self, screenshot_path: str, caption: str):
+        """No-op: screenshot not added to story."""
+        pass
+
+    def add_documentation(self, markdown_content: str):
+        """No-op: documentation not added to story."""
+        pass
+
+    def reset(self):
+        """No-op: nothing to reset."""
+        pass
+
+    def finalize(self):
+        """No-op: no artifacts to generate."""
+        pass
+
+    def _begin_section(self, meta: SectionMetadataInput) -> None:
+        """No-op: section not tracked."""
+        pass
+
+    def _end_section(self) -> None:
+        """No-op: section not tracked."""
+        pass
diff --git a/lib/galaxy/util/markdown.py b/lib/galaxy/util/markdown.py
index fa142df66776..50f0e9530f99 100644
--- a/lib/galaxy/util/markdown.py
+++ b/lib/galaxy/util/markdown.py
@@ -1,4 +1,27 @@
-"""Common markdown formatting helpers for per-datatype rendering."""
+"""Common markdown formatting helpers for per-datatype rendering and conversion."""
+
+import os
+import shutil
+import tempfile
+from typing import (
+    List,
+    Optional,
+)
+
+from galaxy.util.resources import resource_string
+from galaxy.util.sanitize_html import sanitize_html
+
+# Optional markdown import
+try:
+    import markdown
+except ImportError:
+    markdown = None  # type: ignore[assignment,unused-ignore]
+
+# Optional weasyprint import
+try:
+    import weasyprint
+except ImportError:
+    weasyprint = None  # type: ignore[assignment,unused-ignore]
 
 
 def literal_via_fence(content):
@@ -11,3 +34,82 @@ def indicate_data_truncated():
 
 def pre_formatted_contents(markdown):
     return f"<pre>{markdown}</pre>"
+
+
+def markdown_available() -> bool:
+    """Check if markdown library is available."""
+    return markdown is not None
+
+
+def weasyprint_available() -> bool:
+    """Check if weasyprint library is available."""
+    return weasyprint is not None
+
+
+def to_html(basic_markdown: str) -> str:
+    """Convert markdown to HTML.
+
+    Args:
+        basic_markdown: Markdown content to convert
+
+    Returns:
+        HTML string
+
+    Raises:
+        ImportError: If markdown library is not available
+    """
+    if not markdown_available():
+        raise ImportError(
+            "markdown library is required for HTML conversion. Install with: pip install 'galaxy-util[markdown-convert]'"
+        )
+
+    # Allow data: urls so we can embed images.
+    html = sanitize_html(markdown.markdown(basic_markdown, extensions=["tables"]), allow_data_urls=True)
+    return html
+
+
+def to_pdf_raw(basic_markdown: str, css_paths: Optional[List[str]] = None, directory=None) -> bytes:
+    """Convert markdown to PDF bytes.
+
+    Args:
+        basic_markdown: Markdown content to convert
+        css_paths: Optional list of CSS file paths to apply to the PDF
+
+    Returns:
+        PDF as bytes
+
+    Raises:
+        ImportError: If markdown or weasyprint libraries are not available
+    """
+    if not markdown_available():
+        raise ImportError(
+            "markdown library is required for PDF conversion. Install with: pip install 'galaxy-util[markdown-convert]'"
+        )
+
+    if not weasyprint_available():
+        raise ImportError(
+            "weasyprint library is required for PDF conversion. Install with: pip install 'galaxy-util[markdown-convert]'"
+        )
+
+    css_paths = css_paths or []
+    as_html = to_html(basic_markdown)
+    directory_is_temp = False
+    if directory is None:
+        directory = tempfile.mkdtemp("gxmarkdown")
+        directory_is_temp = True
+    index = os.path.join(directory, "index.html")
+    try:
+        output_file = open(index, "w", encoding="utf-8", errors="xmlcharrefreplace")
+        output_file.write(as_html)
+        output_file.close()
+        html = weasyprint.HTML(filename=index)
+        stylesheets = [weasyprint.CSS(string=resource_string(__name__, "markdown_export_base.css"))]
+        for css_path in css_paths:
+            with open(css_path) as f:
+                css_content = f.read()
+            css = weasyprint.CSS(string=css_content)
+            stylesheets.append(css)
+        return html.write_pdf(stylesheets=stylesheets)
+    finally:
+        if directory_is_temp:
+            shutil.rmtree(directory)
diff --git a/lib/galaxy/managers/markdown_export_base.css b/lib/galaxy/util/markdown_export_base.css
similarity index 100%
rename from lib/galaxy/managers/markdown_export_base.css
rename to lib/galaxy/util/markdown_export_base.css
diff --git a/lib/galaxy_test/selenium/.claude/README.md b/lib/galaxy_test/selenium/.claude/README.md
new file mode 100644
index 000000000000..39783982c7d2
--- /dev/null
+++ b/lib/galaxy_test/selenium/.claude/README.md
@@ -0,0 +1,200 @@
+# Claude Code Configuration for Galaxy Selenium Tests
+
+This directory contains Claude Code configuration and slash commands for working with Galaxy's Selenium test suite.
+
+## CLAUDE.md
+
+The `CLAUDE.md` file in the parent directory (`../CLAUDE.md`) provides comprehensive documentation about Galaxy Selenium testing conventions. It includes:
+
+- Test structure and base classes
+- Common patterns (login, navigation, data upload)
+- Decorator usage (`@selenium_test`, `@managed_history`, `@requires_admin`)
+- Component system access
+- Helper methods and wait types
+- Accessibility testing guidelines
+- Complete test templates for different scenarios
+
+**Purpose**: This file serves as context for Claude Code when writing or modifying Selenium tests, ensuring consistency with Galaxy's testing conventions.
+
+## Slash Commands
+
+### Direct Test Creation
+
+#### `/new-selenium-test`
+
+Bootstrap a new Selenium test file from scratch.
+
+**Usage:**
+```
+/new-selenium-test <feature description>
+```
+
+**Examples:**
+```
+/new-selenium-test workflow import with accessibility testing
+/new-selenium-test admin user management features
+/new-selenium-test dataset metadata editing with managed history
+```
+
+**What it does:**
+- Creates a new test file with proper structure
+- Includes appropriate imports and decorators
+- Follows Galaxy naming conventions
+- Uses correct template based on requirements
+- Asks clarifying questions if needed
+
+#### `/add-selenium-test`
+
+Add new test methods to an existing Selenium test file.
+
+**Usage:**
+```
+/add-selenium-test <description and target file>
+```
+
+**Examples:**
+```
+/add-selenium-test Add a test for tag filtering to test_history_panel.py
+/add-selenium-test Add admin test for user deletion to test_admin_app.py
+/add-selenium-test Add dataset copy test with managed history to test_dataset_edit.py
+```
+
+**What it does:**
+- Reads existing file to match style
+- Adds properly structured test methods
+- Updates imports if necessary
+- Maintains consistency with existing code
+
+### Interactive Jupyter Workflow
+
+For complex tests or when you need to explore the DOM interactively, use the Jupyter notebook workflow:
+
+#### `/setup-selenium-test-notebook`
+
+Create a Jupyter notebook for interactively prototyping a Selenium test.
+
+**Usage:**
+```
+/setup-selenium-test-notebook <feature description OR GitHub PR>
+```
+
+**Examples (text mode):**
+```
+/setup-selenium-test-notebook dataset metadata editing
+/setup-selenium-test-notebook workflow import from URL
+/setup-selenium-test-notebook admin user quota management
+```
+
+**Examples (GitHub PR mode):**
+```
+/setup-selenium-test-notebook https://github.com/galaxyproject/galaxy/pull/12345
+/setup-selenium-test-notebook #12345
+/setup-selenium-test-notebook 12345
+```
+
+**What it does:**
+- Fetches PR context (if PR mode): description, screenshots, author
+- Launches research subagent to find similar existing tests
+- Creates a prototype notebook in `jupyter/` directory
+- Includes PR context, example code, and starter code
+- Prints complete setup instructions
+
+**Workflow:**
+1. Run `/setup-selenium-test-notebook <feature>` to create notebook
+2. Follow printed instructions to start Jupyter
+3. Prototype test interactively with screenshots and documentation
+4. Use `screenshot("name", caption="...")` to add captioned screenshots
+5. Use `document("markdown")` to add narrative documentation
+6. Run `/extract-selenium-test` when done to convert to test file
+
+#### `/extract-selenium-test`
+
+Extract test code from a Jupyter notebook and convert to a proper test file.
+
+**Usage:**
+```
+/extract-selenium-test <notebook path or description>
+```
+
+**Examples:**
+```
+/extract-selenium-test from jupyter/test_prototype_dataset_metadata.ipynb
+/extract-selenium-test jupyter/test_prototype_workflow_import.ipynb as test_workflow_import
+/extract-selenium-test notebook test_prototype_admin_users.ipynb
+```
+
+**What it does:**
+- Reads notebook cells (skipping initialization)
+- Transforms `gx_selenium_context` to `self`
+- Detects required decorators and attributes
+- Creates properly structured Pytest test file for the Selenium test suite
+- Groups related cells into test methods
+
+## Getting Started
+
+### Quick Start (Direct Creation)
+
+For straightforward tests with known requirements:
+
+1. **Read `../CLAUDE.md`** to understand Galaxy Selenium testing conventions
+2. **Use `/new-selenium-test <description>`** to create a new test file
+3. **Use `/add-selenium-test <description>`** to extend an existing test file
+4. **Run** with `pytest lib/galaxy_test/selenium/test_<your_file>.py`
+
+### Interactive Development (Jupyter Workflow)
+
+For complex tests or DOM exploration:
+
+1. **Create notebook**: `/setup-selenium-test-notebook <description>`
+2. **Start Galaxy & Jupyter** following the printed instructions
+3. **Prototype interactively** in the notebook with live screenshots
+4. **Add documentation** using `screenshot(caption="...")` and `document("markdown")`
+5. **Extract to test**: `/extract-selenium-test <notebook_path>`
+6. **Run** with `pytest lib/galaxy_test/selenium/test_<your_file>.py`
+
+## Test Stories
+
+Test stories provide visual narrative documentation of test execution, automatically generating markdown, HTML, and PDF artifacts with interleaved screenshots and documentation.
+
+### Enabling Test Stories
+
+Set the `GALAXY_TEST_STORIES_DIRECTORY` environment variable:
+
+```bash
+export GALAXY_TEST_STORIES_DIRECTORY=/path/to/stories
+pytest lib/galaxy_test/selenium/test_your_feature.py
+```
+
+### Generated Artifacts
+
+For each test, a timestamped directory is created containing:
+- `story.md` - Markdown source with embedded screenshots
+- `story.html` - Self-contained HTML with embedded images
+- `story.pdf` - PDF version (if weasyprint available)
+- `{test_name}.zip` - Zip archive of all artifacts
+
+### Building Stories in Tests
+
+Use `screenshot()` with captions and `document()` to create rich test documentation:
+
+```python
+@selenium_test
+def test_workflow_import(self):
+    self.document("## Testing TRS Import\n\nThis test validates workflow import from TRS.")
+    
+    self.navigate_to_workflows()
+    self.screenshot("workflow_list", caption="Initial workflow listing")
+    
+    self.document("Import workflow from TRS endpoint...")
+    self.import_workflow_from_trs("https://...")
+    self.screenshot("after_import", caption="Workflow appears in listing after import")
+```
+
+## Tips
+
+- **Be specific** in command descriptions (mention admin access, managed history, etc.)
+- **Use Jupyter workflow** when you need to explore the DOM or iterate quickly
+- **Use direct creation** when you know exactly what needs to be tested
+- Commands will **ask clarifying questions** if your request is ambiguous
+- **Review generated code** to ensure it meets your specific needs
+- **Reference existing tests** in the parent directory for patterns and examples
diff --git a/lib/galaxy_test/selenium/.claude/commands/add-selenium-test.md b/lib/galaxy_test/selenium/.claude/commands/add-selenium-test.md
new file mode 100644
index 000000000000..137137c684e4
--- /dev/null
+++ b/lib/galaxy_test/selenium/.claude/commands/add-selenium-test.md
@@ -0,0 +1,91 @@
+---
+description: Add a new test method to an existing Galaxy Selenium test file
+---
+
+The user input can be provided directly or as a command argument - you **MUST** consider it before proceeding.
+
+User input:
+
+$ARGUMENTS
+
+## Context
+
+You are adding a new test method to an existing Selenium test file in the Galaxy test suite. Read the CLAUDE.md file in this directory for complete context on Galaxy Selenium testing conventions.
+
+## Task
+
+Add one or more new test methods to an existing test file based on the user's description. The user should specify:
+- Which test file to modify (e.g., `test_history_panel.py`)
+- What scenario(s) to test
+- Any special requirements (managed history, admin access, etc.)
+
+## Requirements
+
+1. **Read CLAUDE.md** in the current directory for full context
+
+2. **Read the target test file** to understand:
+   - Existing class structure and attributes
+   - Import statements already present
+   - Coding style and patterns used
+   - Helper methods defined in the class
+
+3. **Match the existing style**:
+   - Use same patterns as other methods in the class
+   - Follow same naming conventions
+   - Maintain consistent indentation and spacing
+   - Add similar docstrings
+
+4. **Add necessary imports** if new decorators/modules are needed:
+   - `managed_history` if using `@managed_history`
+   - `requires_admin` if using `@requires_admin`
+   - Any other decorators from `galaxy.selenium.navigates_galaxy`
+
+5. **Use appropriate decorators**:
+   - Always use `@selenium_test`
+   - Add `@managed_history` if the test needs predictable HIDs
+   - Add `@requires_admin` if testing admin features
+   - Add `@edit_details` or other navigation decorators as needed
+
+6. **Follow test structure**:
+   - Clear, descriptive method name: `test_<specific_scenario>`
+   - Docstring explaining what is being tested
+   - Proper setup and navigation
+   - Clear assertions
+   - Screenshots if helpful (use `self.screenshot("description")`)
+
+7. **Respect class attributes**:
+   - If class has `ensure_registered = True`, user is already logged in
+   - If class has `run_as_admin = True`, tests run as admin
+   - Use these to simplify test setup
+
+## Output
+
+1. **Confirm the target**:
+   - Which file will be modified
+   - What test method(s) will be added
+
+2. **Add the test method(s)** to the appropriate class
+
+3. **Update imports** if needed
+
+4. **Explain what was added**:
+   - What the new test does
+   - Why certain decorators were used
+   - How it fits with existing tests
+   - How to run just this new test
+
+## Example Usage
+
+```
+/add-test Add a test for tag filtering to test_history_panel.py
+/add-test Add admin test for user deletion to test_admin_app.py
+/add-test Add dataset copy test with managed history to test_dataset_edit.py
+```
+
+## Notes
+
+- Always read the existing file first to match its style
+- Don't duplicate existing test scenarios
+- Keep tests independent and focused
+- Consider edge cases and error conditions
+- Add accessibility tests where appropriate
diff --git a/lib/galaxy_test/selenium/.claude/commands/extract-selenium-test.md b/lib/galaxy_test/selenium/.claude/commands/extract-selenium-test.md
new file mode 100644
index 000000000000..b48ca94abe51
--- /dev/null
+++ b/lib/galaxy_test/selenium/.claude/commands/extract-selenium-test.md
@@ -0,0 +1,118 @@
+---
+description: Extract test code from a Jupyter notebook and convert it to a proper Selenium test file
+---
+
+The user input can be provided directly or as a command argument - you **MUST** consider it before proceeding.
+
+User input:
+
+$ARGUMENTS
+
+## Context
+
+After prototyping a Selenium test interactively in a Jupyter notebook, this command extracts the test code and converts it into a proper test file following Galaxy's Selenium testing conventions.
+
+## Task
+
+Extract test cells from a Jupyter notebook and create a properly structured Selenium test file.
+
+## Requirements
+
+1. **Read the target notebook** specified by the user (e.g., `jupyter/test_prototype_<name>.ipynb`)
+
+2. **Read CLAUDE.md** for full context on Galaxy Selenium test conventions
+
+3. **Identify test cells** - Extract all cells after the initialization cell (cell 2):
+   - Skip the parameters cell (cell 0)
+   - Skip the initialization cell (cell 1)
+   - Extract cells 2+ which contain the test implementation
+
+4. **Transform notebook code to test code**:
+   - Replace `gx_selenium_context.` with `self.`
+   - Remove screenshot calls or keep them if desired for debugging
+   - Group related operations into logical test methods
+   - Add proper decorators (`@selenium_test`, `@managed_history`, etc.)
+   - Add docstrings to test methods
+
+5. **Determine test structure** from the notebook code:
+   - Does it need `ensure_registered = True`? (if it calls `register()` or `login()`)
+   - Does it need `run_as_admin = True`? (if it calls `admin_login()`)
+   - Does it need `@managed_history`? (if it works with datasets/HIDs)
+   - Does it need `@requires_admin`? (if testing admin features)
+
+6. **Create proper test file**:
+   - Add appropriate imports
+   - Create test class with correct name
+   - Add class attributes as needed
+   - Create test methods from notebook cells
+   - Group related cells into single test methods
+   - Split unrelated operations into separate test methods
+
+7. **Handle special cases**:
+   - If notebook uses `dataset_populator`, keep those patterns
+   - If notebook uses `current_history_id()`, consider `@managed_history`
+   - If notebook has multiple distinct scenarios, create multiple test methods
+   - Convert inline assertions to proper pytest assertions
+
+8. **File naming**: Ask user for feature name if not clear from notebook name
+
+## Output
+
+1. **Analyze the notebook** and report:
+   - Number of test cells found
+   - Key operations detected (login, upload, navigation, etc.)
+   - Recommended test structure (basic/managed history/admin)
+
+2. **Ask for confirmation** if structure is ambiguous:
+   - Should this be one test method or multiple?
+   - What should the test methods be named?
+   - Should screenshots be kept or removed?
+
+3. **Create the test file** at `test_<feature_name>.py` with:
+   - Proper imports
+   - Correctly structured test class
+   - Appropriate decorators and attributes
+   - Well-named test methods with docstrings
+   - Transformed code (gx_selenium_context → self)
+
+4. **Report completion**:
+   ```
+   ✓ Extracted test from notebook: jupyter/test_prototype_<name>.ipynb
+   ✓ Created test file: test_<feature_name>.py
+
+   Test structure:
+   - Class: Test<FeatureName>
+   - Attributes: [ensure_registered, run_as_admin, etc.]
+   - Methods: test_method_1, test_method_2, ...
+
+   To run the test:
+   pytest lib/galaxy_test/selenium/test_<feature_name>.py
+
+   Or run a specific test:
+   pytest lib/galaxy_test/selenium/test_<feature_name>.py::Test<FeatureName>::test_method_1
+   ```
+
+5. **Provide review guidance**:
+   - Suggest reviewing for proper wait/sleep patterns
+   - Recommend adding assertions if few were found
+   - Suggest accessibility testing if not present
+   - Note any hardcoded values that should be parameterized
+
+## Example Usage
+
+```
+/extract-test from jupyter/test_prototype_dataset_metadata.ipynb
+/extract-test jupyter/test_prototype_workflow_import.ipynb as test_workflow_import
+/extract-test notebook test_prototype_admin_users.ipynb
+```
+
+## Notes
+
+- Read CLAUDE.md for complete context on test conventions
+- The notebook's initialization cells (0-1) are never included in the test
+- Multiple notebook cells can be combined into a single test method if related
+- Distinct scenarios should become separate test methods
+- The command should intelligently detect patterns (admin, managed history, etc.)
+- Preserve the logic but adapt to test framework conventions
+- Remove debug-only code (print statements, excessive screenshots)
+- Keep test-relevant screenshots if they help document expected states
diff --git a/lib/galaxy_test/selenium/.claude/commands/new-selenium-test.md b/lib/galaxy_test/selenium/.claude/commands/new-selenium-test.md
new file mode 100644
index 000000000000..7bb9d6c3fa41
--- /dev/null
+++ b/lib/galaxy_test/selenium/.claude/commands/new-selenium-test.md
@@ -0,0 +1,105 @@
+---
+description: Bootstrap a new Galaxy Selenium test file with proper structure and conventions
+---
+
+The user input can be provided directly or as a command argument - you **MUST** consider it before proceeding.
+
+User input:
+
+$ARGUMENTS
+
+## Context
+
+You are creating a new Selenium test file for the Galaxy web application. Read the CLAUDE.md file in this directory for complete context on:
+- Test structure and conventions
+- Available decorators and their purposes
+- Common patterns and helper methods
+- Component system usage
+- Example templates
+
+## Task
+
+Create a new Selenium test file based on the user's description. The user may specify:
+- Feature name (e.g., "dataset permissions", "workflow import")
+- Test scenarios to include
+- Whether it needs admin access (`run_as_admin = True`)
+- Whether it needs managed history (`@managed_history`)
+- Accessibility testing requirements
+
+## Requirements
+
+1. **Read CLAUDE.md** in the current directory for full context on Galaxy Selenium testing conventions
+
+2. **Determine the appropriate template** based on requirements:
+   - Basic test (most common)
+   - Test with managed history (for predictable dataset HIDs)
+   - Admin test (requires `run_as_admin = True`)
+   - Combination of the above
+
+3. **Generate the test file** with:
+   - Proper imports from `.framework`
+   - Class name following `Test<FeatureName>` convention
+   - Appropriate class attributes (`ensure_registered`, `run_as_admin`)
+   - Well-named test methods using `test_<scenario>` pattern
+   - Proper decorators (`@selenium_test`, `@managed_history`, `@requires_admin`)
+   - Docstrings for each test method
+   - Common patterns from existing tests
+
+4. **File naming**: `test_<feature_name>.py` (lowercase with underscores)
+
+5. **Include common elements**:
+   - Navigation (`self.home()`)
+   - Component access via `self.components.*`
+   - Proper wait/sleep patterns
+   - Assertions (`self.assert_no_error_message()`, etc.)
+   - Accessibility tests where appropriate
+
+6. **For dataset/history tests**:
+   - Use `@managed_history` decorator
+   - Upload test data with `self.perform_upload(self.get_filename("1.txt"))`
+   - Wait for datasets with `self.history_panel_wait_for_hid_ok(hid)`
+   - Reference datasets by predictable HID (1, 2, 3...)
+
+7. **For admin tests**:
+   - Add `run_as_admin = True` class attribute
+   - Use `@requires_admin` decorator
+   - Include `self.admin_login()` and `self.admin_open()`
+   - Import from `galaxy_test.base.decorators import requires_admin`
+
+8. **Best practices**:
+   - Keep tests focused and independent
+   - Use descriptive test method names
+   - Add comments for complex interactions
+   - Follow existing code style in this directory
+   - Consider accessibility testing (`assert_no_axe_violations_with_impact_of_at_least`)
+
+## Output
+
+1. **Ask clarifying questions** if the user's request is ambiguous:
+   - Does this need admin access?
+   - Does this need managed history for dataset testing?
+   - What specific scenarios should be tested?
+   - Should accessibility testing be included?
+
+2. **Create the test file** at `/Users/jxc755/workspace/galaxy/lib/galaxy_test/selenium/test_<feature_name>.py`
+
+3. **Explain the structure**:
+   - Which template was used and why
+   - Key components and patterns included
+   - How to run the test
+   - Any additional setup needed
+
+## Example Usage
+
+```
+/new-test workflow import with accessibility testing
+/new-test admin user management features
+/new-test dataset metadata editing with managed history
+```
+
+## Notes
+
+- Reference CLAUDE.md for comprehensive examples and patterns
+- Look at similar existing tests in this directory for inspiration
+- Ensure all imports are correct and from the right modules
+- The test should be immediately runnable with pytest
diff --git a/lib/galaxy_test/selenium/.claude/commands/setup-selenium-test-notebook.md b/lib/galaxy_test/selenium/.claude/commands/setup-selenium-test-notebook.md
new file mode 100644
index 000000000000..c70ba743f916
--- /dev/null
+++ b/lib/galaxy_test/selenium/.claude/commands/setup-selenium-test-notebook.md
@@ -0,0 +1,202 @@
+---
+description: Create a Jupyter notebook for interactively prototyping a new Selenium test
+---
+
+The user input can be provided directly or as a command argument - you **MUST** consider it before proceeding.
+
+User input:
+
+$ARGUMENTS
+
+## Context
+
+Galaxy Selenium tests can be prototyped interactively in Jupyter notebooks. The notebook environment provides:
+- Full access to the Selenium test infrastructure
+- Screenshot capabilities with inline display and optional captions
+- Documentation capabilities via `document()` helper for adding markdown
+- Interactive DOM exploration
+- Rapid iteration without restarting Galaxy or re-running costly intermediate steps such as data upload.
+
+This command supports two modes:
+1. **Text description** - User provides a feature description
+2. **GitHub PR** - User provides a PR URL or number (fetches description and screenshots)
+
+## Task
+
+Create a new Jupyter notebook for prototyping a Selenium test. Input can be:
+- A text description of the feature
+- A GitHub PR URL (e.g., `https://github.com/galaxyproject/galaxy/pull/12345`)
+- A PR number (e.g., `#12345` or `12345`)
+
+## Requirements
+
+1. **Determine input mode**:
+   - If input contains GitHub URL or PR number (#), use PR mode
+   - Otherwise, use text description mode
+
+2. **PR Mode - Fetch PR information** (if applicable):
+   - Use `gh pr view <number> --json title,body,author` to get PR metadata
+   - Extract feature description from PR title and body
+   - Look for screenshots in PR body (markdown image syntax)
+   - If screenshots found, note their URLs for reference in notebook
+   - Use PR description as basis for feature understanding
+
+3. **Research similar tests** - Do a quick search in this directory only:
+   - Use Glob to find test files: `*.py` in current directory
+   - Use Grep to search for keywords related to the feature
+   - Read 1-2 most relevant test files
+   - Extract key patterns: component usage, helper methods, decorators
+   - Note which components are used (e.g., `self.components.history_panel.*`)
+   - Keep this step fast and focused
+
+4. **Create the notebook file** at `jupyter/test_prototype_<feature_name>.ipynb` with 4-5 cells:
+
+   **Cell 1** (tagged 'parameters'):
+   ```python
+   # Cell is tagged with 'parameters' so it can be parameterized with papermill,
+   # if config not overridden ./galaxy_selenium_context.yml can also be populated.
+   config = None
+   ```
+
+   **Cell 2** (initialization):
+   ```python
+   from galaxy_test.selenium.jupyter_context import init
+   gx_selenium_context = init(config)
+   ```
+
+   **Cell 3** (PR context - ONLY if PR mode):
+   ```python
+   # Testing PR #<number>: <PR title>
+   # Author: <author>
+   #
+   # Description:
+   # <PR body text>
+   #
+   # Screenshots in PR:
+   # - <screenshot URL 1>
+   # - <screenshot URL 2>
+   #
+   # You can compare your gx_selenium_context.screenshot() output with PR screenshots
+   ```
+
+   **Cell 4** (reference examples from similar tests):
+   ```python
+   # Similar test examples for reference:
+   #
+   # From test_<similar_file_1>.py:
+   # <relevant code snippets showing component usage>
+   #
+   # From test_<similar_file_2>.py:
+   # <more relevant code snippets>
+   #
+   # Components available:
+   # - self.components.<component_name>.<method>
+   # [List relevant components based on research]
+   ```
+
+   **Cell 5** (test prototype - add helpful starter code):
+   ```python
+   # Prototype your test here
+   # gx_selenium_context provides all the methods from SeleniumTestCase
+
+   # Example starter code based on feature description
+   ```
+
+5. **Add starter code** to the final cell based on the feature requirements:
+   - Login if needed: `gx_selenium_context.login()`
+   - Navigation: `gx_selenium_context.home()`
+   - Dataset creation if needed: `gx_selenium_context.dataset_populator.new_dataset(history_id)`
+   - Screenshots: `gx_selenium_context.screenshot("description", caption="Optional caption for story")`
+   - Documentation: `gx_selenium_context.document("# Markdown content\n\nExplain what this test does...")`
+   - Admin access if needed: `gx_selenium_context.admin_login()`
+   - Component access examples
+   - Comments suggesting what to implement
+
+6. **Check configuration** - Verify `jupyter/galaxy_selenium_context.yml` exists:
+   - If missing, inform user to copy from `galaxy_selenium_context.yml.sample`
+   - Explain they need to configure `login_email`, `login_password`, and optionally `admin_api_key`
+
+## Implementation Steps
+
+1. **Detect input mode and fetch PR if needed**:
+   - Check if input contains PR URL or number
+   - If PR mode: Use `gh pr view <number> --json title,body,author` to fetch PR data
+   - Extract feature description from PR content
+   - Parse PR body for screenshot URLs (markdown image syntax: `![...](url)`)
+
+2. **Search for similar tests** directly (no subagent):
+   - Use Grep to search for keywords in test files in current directory
+   - Example: search for "storage", "dashboard", "chart", etc. based on feature
+   - Identify 1-2 relevant files from grep results
+   - Read those files
+   - Extract key patterns: decorators used, components accessed, helper methods called
+   - Identify relevant code snippets (5-15 lines) showing component usage
+   - Keep this fast - just find the most obviously related tests
+
+3. **Create the notebook file** with:
+   - Standard initialization cells
+   - PR context cell (if PR mode)
+   - Similar test examples cell
+   - Starter code cell
+
+4. **Print setup instructions**:
+   ```
+   ✓ Created prototype notebook: jupyter/test_prototype_<feature_name>.ipynb
+   [If PR mode: ✓ Loaded context from PR #<number>: <title>]
+   [If PR mode: ✓ Found <N> screenshots in PR for reference]
+
+   To start prototyping:
+
+   1. Ensure Galaxy is running:
+      Terminal 1: GALAXY_SKIP_CLIENT_BUILD=1 GALAXY_RUN_WITH_TEST_TOOLS=1 sh run.sh
+      Terminal 2: make client-dev-server
+
+   2. Check configuration (first time only):
+      - Copy jupyter/galaxy_selenium_context.yml.sample to jupyter/galaxy_selenium_context.yml
+      - Edit it with your test user credentials and admin API key
+
+   3. Start Jupyter (from repo root):
+      . .venv/bin/activate
+      pip install jupyter  # first time only
+      make serve-selenium-notebooks
+
+   4. Open the notebook in Jupyter:
+      jupyter/test_prototype_<feature_name>.ipynb
+
+   5. Run cells interactively to prototype your test
+      - Screenshots will display inline
+      - Use screenshot("name", caption="...") to add captions for documentation
+      - Use document("markdown content") to add narrative documentation
+      - You can inspect the DOM, try different selectors
+      - Iterate quickly without restarting
+      - Components selectors defined in lib/galaxy/navigation/navigation.yml
+        will be dynamically reloaded in this mode.
+
+   6. When done, use /extract-test to convert to a test file
+   ```
+
+## Example Usage
+
+**Text description mode:**
+```
+/setup-selenium-test-notebook dataset metadata editing
+/setup-selenium-test-notebook workflow import from URL
+/setup-selenium-test-notebook admin user quota management
+```
+
+**GitHub PR mode:**
+```
+/setup-selenium-test-notebook https://github.com/galaxyproject/galaxy/pull/12345
+/setup-selenium-test-notebook #12345
+/setup-selenium-test-notebook 12345
+```
+
+## Notes
+
+- The notebook uses `JupyterTestContextImpl` which provides the "same" interface as `SeleniumTestCase`
+- All methods from `NavigatesGalaxy` are available on `gx_selenium_context`
+- Screenshots are displayed inline in Jupyter for immediate feedback
+- Use `screenshot("name", caption="...")` to add captions that appear in generated stories
+- Use `document("markdown")` to add narrative documentation between screenshots
+- Configuration is read from `jupyter/galaxy_selenium_context.yml` if present
+- After prototyping, use `/extract-test` to convert notebook cells into a proper test file
diff --git a/lib/galaxy_test/selenium/CLAUDE.md b/lib/galaxy_test/selenium/CLAUDE.md
new file mode 100644
index 000000000000..b5a75e7c2b1b
--- /dev/null
+++ b/lib/galaxy_test/selenium/CLAUDE.md
@@ -0,0 +1,323 @@
+# Galaxy Selenium Test Suite
+
+This directory contains Selenium-based end-to-end tests for the Galaxy web interface.
+
+## Test Structure
+
+All Selenium tests follow these conventions:
+
+### Base Class and Decorators
+
+```python
+from .framework import (
+    selenium_test,
+    SeleniumTestCase,
+)
+
+class TestYourFeature(SeleniumTestCase):
+    @selenium_test
+    def test_your_scenario(self):
+        # Test implementation
+```
+
+### Key Components
+
+- **Base class**: All test classes inherit from `SeleniumTestCase`
+- **Test decorator**: All test methods use the `@selenium_test` decorator
+- **Framework module**: `framework.py` provides the base testing infrastructure
+- **Component system**: Use `self.components` to access page object selectors
+
+## Common Patterns
+
+### User Registration and Login
+
+```python
+# Ensure user is registered before running tests
+class TestYourFeature(SeleniumTestCase):
+    ensure_registered = True  # Add this class attribute
+
+    # Or register manually in a test
+    @selenium_test
+    def test_with_login(self):
+        email = self._get_random_email()
+        self.register(email)
+        self.submit_login(email, assert_valid=True)
+```
+
+### Navigation
+
+```python
+self.home()  # Navigate to home page
+self.history_panel_wait_for_history_loaded()  # Wait for history to load
+```
+
+### Component Access
+
+```python
+# Access UI components via the component system
+self.components.masthead.login_masthead_button.wait_for_and_click()
+self.components.history_panel.name_edit_input.wait_for_visible()
+```
+
+### Accessibility Testing
+
+```python
+# Test for accessibility violations
+self.components.login.form.assert_no_axe_violations_with_impact_of_at_least("moderate")
+
+# With exceptions for specific rules
+VIOLATION_EXCEPTIONS = ["heading-order", "label"]
+self.components.history_panel._.assert_no_axe_violations_with_impact_of_at_least(
+    "moderate", VIOLATION_EXCEPTIONS
+)
+```
+
+### Data Upload
+
+```python
+# Upload test data
+self.perform_upload(self.get_filename("1.txt"))
+self.wait_for_history()
+
+# Wait for specific dataset
+self.history_panel_wait_for_hid_ok(1)
+```
+
+### Screenshots and Documentation
+
+```python
+# Take a screenshot (saved to screenshots directory)
+self.screenshot("workflow_editor")
+
+# Take a screenshot with caption (for test stories)
+self.screenshot("workflow_editor", caption="Workflow editor after loading")
+
+# Add markdown documentation to test story
+self.document("""
+## Testing Workflow Import
+
+This test validates that workflows can be imported from TRS endpoints.
+The following steps are performed:
+1. Navigate to workflow import page
+2. Enter TRS URL
+3. Verify workflow appears in listing
+""")
+```
+
+### Test Stories
+
+Test stories provide visual narrative documentation of test execution, automatically generating markdown, HTML, and PDF artifacts with interleaved screenshots and documentation.
+
+To enable test stories, set the `GALAXY_TEST_STORIES_DIRECTORY` environment variable:
+```bash
+export GALAXY_TEST_STORIES_DIRECTORY=/path/to/stories
+pytest lib/galaxy_test/selenium/test_your_feature.py
+```
+
+Stories are generated automatically for each test, creating timestamped directories with:
+- `story.md` - Markdown source with embedded screenshots
+- `story.html` - Self-contained HTML with embedded images  
+- `story.pdf` - PDF version (if weasyprint available)
+- `{test_name}.zip` - Zip archive of all artifacts
+
+Use `screenshot()` with captions and `document()` to build rich test documentation.
+
+### Assertions with Retry Logic
+
+```python
+from .framework import retry_assertion_during_transitions
+
+@retry_assertion_during_transitions
+def assert_something(self):
+    # Assertion that might fail during UI transitions
+    assert condition
+```
+
+### Fresh History with @managed_history
+
+Use the `@managed_history` decorator when you need a clean history for your test. This ensures predictable HIDs (History Item IDs) for uploaded datasets, starting from 1.
+
+```python
+from .framework import (
+    managed_history,
+    selenium_test,
+    SeleniumTestCase,
+)
+
+class TestHistoryFeature(SeleniumTestCase):
+    ensure_registered = True
+
+    @selenium_test
+    @managed_history
+    def test_with_fresh_history(self):
+        # Upload files with predictable HIDs
+        self.perform_upload(self.get_filename("1.txt"))
+        self.history_panel_wait_for_hid_ok(1)  # First upload is HID 1
+
+        self.perform_upload(self.get_filename("2.txt"))
+        self.history_panel_wait_for_hid_ok(2)  # Second upload is HID 2
+
+        # Now you can reliably reference datasets by HID
+        self.history_panel_click_item_title(hid=1, wait=True)
+```
+
+**Key benefits of @managed_history:**
+- Creates a fresh history before the test runs
+- HIDs start at 1 and increment predictably
+- No interference from previous test data
+- Makes tests more reliable and maintainable
+
+### Testing Admin Functionality
+
+For tests that require admin access, add `run_as_admin = True` as a class attribute and use the `@requires_admin` decorator:
+
+```python
+from galaxy_test.base.decorators import requires_admin
+from .framework import (
+    selenium_test,
+    SeleniumTestCase,
+)
+
+class TestAdminFeature(SeleniumTestCase):
+    run_as_admin = True  # This makes the test run with admin privileges
+
+    @selenium_test
+    @requires_admin
+    def test_admin_functionality(self):
+        self.admin_login()  # Login as admin user
+        self.admin_open()   # Navigate to admin panel
+
+        # Access admin components
+        admin_component = self.components.admin
+        admin_component.index.some_feature.wait_for_and_click()
+
+        # Test admin-specific functionality
+```
+
+**Admin test requirements:**
+- `run_as_admin = True` class attribute
+- `@requires_admin` decorator on test methods
+- Use `self.admin_login()` to authenticate as admin
+- Use `self.admin_open()` to navigate to admin panel
+
+## File Naming
+
+- Test files: `test_<feature_name>.py`
+- Test classes: `Test<FeatureName>`
+- Test methods: `test_<specific_scenario>`
+
+## Helper Methods Available
+
+Common methods from `SeleniumTestCase`:
+
+- `self.home()` - Navigate to home
+- `self.register(email, password=None)` - Register new user
+- `self.submit_login(email, password=None, assert_valid=True)` - Login
+- `self.logout_if_needed()` - Logout if logged in
+- `self.is_logged_in()` - Check login status
+- `self.assert_error_message()` - Assert error message displayed
+- `self.assert_no_error_message()` - Assert no error message
+- `self._get_random_email()` - Generate random test email
+- `self._get_random_name(prefix="")` - Generate random name
+- `self.sleep_for(wait_type)` - Sleep for specified wait type
+- `self.wait_for_history()` - Wait for history panel to load
+- `self.perform_upload(filepath)` - Upload a file
+- `self.history_panel_wait_for_hid_ok(hid)` - Wait for dataset to be OK
+- `self.screenshot(label, caption=None)` - Take screenshot, optionally add to story
+- `self.document(markdown_content)` - Add markdown documentation to test story
+
+## Wait Types
+
+```python
+self.sleep_for(self.wait_types.UX_RENDER)       # UI rendering delay
+self.sleep_for(self.wait_types.UX_TRANSITION)   # UI transition delay
+```
+
+## Test Data Files
+
+- Test data files are accessed via `self.get_filename("filename")`
+- Common test files include simple text files, tabular data, etc.
+
+## Example Test Templates
+
+### Basic Test Template
+
+```python
+from .framework import (
+    selenium_test,
+    SeleniumTestCase,
+)
+
+
+class TestNewFeature(SeleniumTestCase):
+    ensure_registered = True
+
+    @selenium_test
+    def test_basic_scenario(self):
+        """Test description goes here."""
+        self.home()
+        # Test implementation
+        self.assert_no_error_message()
+
+    @selenium_test
+    def test_accessibility(self):
+        """Test accessibility compliance."""
+        self.components.your_feature._.assert_no_axe_violations_with_impact_of_at_least("moderate")
+```
+
+### Template with Managed History
+
+```python
+from .framework import (
+    managed_history,
+    selenium_test,
+    SeleniumTestCase,
+)
+
+
+class TestDatasetFeature(SeleniumTestCase):
+    ensure_registered = True
+
+    @selenium_test
+    @managed_history
+    def test_with_datasets(self):
+        """Test with predictable dataset HIDs."""
+        # Upload test data
+        self.perform_upload(self.get_filename("1.txt"))
+        self.history_panel_wait_for_hid_ok(1)
+
+        # Interact with dataset by HID
+        self.history_panel_click_item_title(hid=1, wait=True)
+        # Further test logic...
+```
+
+### Admin Test Template
+
+```python
+from galaxy_test.base.decorators import requires_admin
+from .framework import (
+    selenium_test,
+    SeleniumTestCase,
+)
+
+
+class TestAdminFeature(SeleniumTestCase):
+    run_as_admin = True
+
+    @selenium_test
+    @requires_admin
+    def test_admin_panel(self):
+        """Test admin functionality."""
+        self.admin_login()
+        self.admin_open()
+
+        admin_component = self.components.admin
+        # Test admin-specific features...
+```
+
+## Additional Resources
+
+- `framework.py` - Base test framework and utilities
+- `conftest.py` - Pytest fixtures and configuration
+- `jupyter_context.py` - Jupyter notebook testing utilities
+- Page objects and navigation helpers are in `galaxy.selenium.navigates_galaxy`
diff --git a/lib/galaxy_test/selenium/framework.py b/lib/galaxy_test/selenium/framework.py
index b8399ed2ee24..c513c3c71122 100644
--- a/lib/galaxy_test/selenium/framework.py
+++ b/lib/galaxy_test/selenium/framework.py
@@ -14,7 +14,6 @@
     Any,
     cast,
     Optional,
-    TYPE_CHECKING,
 )
 
 import requests
@@ -36,9 +35,14 @@
 from galaxy.selenium.navigates_galaxy import (
     exception_seems_to_indicate_transition,
     galaxy_timeout_handler,
-    NavigatesGalaxy,
     retry_during_transitions,
 )
+from galaxy.selenium.navigates_galaxy_mixin import NavigatesGalaxyMixin
+from galaxy.selenium.stories import (
+    NoopStory,
+    Story,
+    StoryProtocol,
+)
 from galaxy.tool_util.verify.interactor import prepare_request_params
 from galaxy.util import (
     asbool,
@@ -137,6 +141,7 @@ def _load_config_file() -> None:
 TIMEOUT_MULTIPLIER = float(os.environ.get("GALAXY_TEST_TIMEOUT_MULTIPLIER", DEFAULT_TIMEOUT_MULTIPLIER))
 GALAXY_TEST_ERRORS_DIRECTORY = os.environ.get("GALAXY_TEST_ERRORS_DIRECTORY", DEFAULT_TEST_ERRORS_DIRECTORY)
 GALAXY_TEST_SCREENSHOTS_DIRECTORY = os.environ.get("GALAXY_TEST_SCREENSHOTS_DIRECTORY", None)
+GALAXY_TEST_STORIES_DIRECTORY = os.environ.get("GALAXY_TEST_STORIES_DIRECTORY", None)
 # Driver backend can be ["selenium", "playwright"]
 GALAXY_TEST_DRIVER_BACKEND = os.environ.get("GALAXY_TEST_DRIVER_BACKEND", "selenium")
 # Test browser can be ["CHROME", "FIREFOX"]
@@ -307,11 +312,43 @@ def try_symlink(file1, file2):
         pass
 
 
+def _create_story_directory(test_name: str) -> str:
+    """Create and return path to story directory for test.
+
+    Args:
+        test_name: Name of the test function
+
+    Returns:
+        Absolute path to created story directory
+    """
+    if GALAXY_TEST_STORIES_DIRECTORY is None:
+        raise ValueError("GALAXY_TEST_STORIES_DIRECTORY is not set")
+
+    test_stories_directory = os.path.abspath(GALAXY_TEST_STORIES_DIRECTORY)
+    if not os.path.exists(test_stories_directory):
+        os.makedirs(test_stories_directory)
+
+    timestamp = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
+    story_dir_name = f"{test_name}_{timestamp}"
+    story_dir = os.path.join(test_stories_directory, story_dir_name)
+    os.makedirs(story_dir)
+
+    return story_dir
+
+
 def selenium_test(f):
     test_name = f.__name__
+    test_docstring = f.__doc__
 
     @wraps(f)
     def func_wrapper(self, *args, **kwds):
+        # Initialize story (real or noop)
+        if GALAXY_TEST_STORIES_DIRECTORY:
+            story_dir = _create_story_directory(test_name)
+            self.story = Story(test_name, test_docstring or "", story_dir)
+        else:
+            self.story = NoopStory()
+
         retry_attempts = 0
         while True:
             if retry_attempts > 0:
@@ -319,6 +356,12 @@ def func_wrapper(self, *args, **kwds):
             try:
                 rval = f(self, *args, **kwds)
                 self.assert_baseline_accessibility()
+
+                # Finalize story on success
+                self.story.finalize()
+                if GALAXY_TEST_STORIES_DIRECTORY:
+                    try_symlink(story_dir, os.path.abspath(os.path.join(GALAXY_TEST_STORIES_DIRECTORY, "latest")))
+
                 return rval
             except unittest.SkipTest:
                 dump_test_information(self, test_name)
@@ -326,6 +369,11 @@ def func_wrapper(self, *args, **kwds):
                 raise
             except Exception:
                 dump_test_information(self, test_name)
+
+                # Still finalize story on failure (useful for debugging)
+                self.story.add_documentation("## Test Failed\n\nSee error directory for details.")
+                self.story.finalize()
+
                 if retry_attempts < GALAXY_TEST_SELENIUM_RETRIES:
                     retry_attempts += 1
                     print(
@@ -427,6 +475,8 @@ def _target_url_from_selenium(self):
     def setup_selenium(self):
         self.target_url_from_selenium = self._target_url_from_selenium()
         self.snapshots = []
+        # Initialize story as noop (decorator will override if stories enabled)
+        self.story: StoryProtocol = NoopStory()
         self.setup_driver_and_session()
         if self.run_as_admin and GALAXY_TEST_SELENIUM_ADMIN_USER_EMAIL == DEFAULT_ADMIN_USER:
             self._setup_interactor()
@@ -483,7 +533,50 @@ def write_screenshot_directory_file(self, label, content):
         with open(target, "w") as f:
             f.write(content)
 
+    def screenshot(self, label: str, caption: Optional[str] = None):
+        """Take a screenshot and save to both story and screenshots directories if configured.
+
+        Overrides parent implementation to support dual-saving when both
+        GALAXY_TEST_STORIES_DIRECTORY and GALAXY_TEST_SCREENSHOTS_DIRECTORY are set.
+
+        Args:
+            label: Base filename for screenshot
+            caption: Optional caption for the screenshot in the story
+        """
+        # Get primary target path
+        target = self._screenshot_path(label)
+        if target is None:
+            return
+
+        # Save to primary location
+        self.save_screenshot(target)
+
+        # If story is enabled AND screenshots directory is also configured, save there too
+        if self.story.enabled and GALAXY_TEST_SCREENSHOTS_DIRECTORY is not None:
+            screenshots_target = self._screenshots_directory_path(label)
+            if screenshots_target:
+                self.save_screenshot(screenshots_target)
+
+        # Add to story (noop if NoopStory)
+        self.story.add_screenshot(target, caption or label)
+
+        return target
+
     def _screenshot_path(self, label, extension=".png"):
+        """Generate screenshot path.
+
+        If story mode is enabled, saves to story directory with sequential numbering.
+        Otherwise uses the standard screenshots directory.
+        """
+        # If stories are enabled, save to story directory
+        if self.story.enabled:
+            target = os.path.join(
+                self.story.output_directory, f"{self.story.screenshot_counter:03d}_{label}{extension}"
+            )
+            self.story.screenshot_counter += 1
+            return target
+
+        # Otherwise use screenshots directory (existing behavior)
         if GALAXY_TEST_SCREENSHOTS_DIRECTORY is None:
             return
         if not os.path.exists(GALAXY_TEST_SCREENSHOTS_DIRECTORY):
@@ -497,7 +590,25 @@ def _screenshot_path(self, label, extension=".png"):
 
         return target
 
+    def _screenshots_directory_path(self, label, extension=".png"):
+        """Generate path for screenshots directory (not story).
+
+        Helper method for saving screenshots to the screenshots directory
+        when story mode is also enabled.
+        """
+        if GALAXY_TEST_SCREENSHOTS_DIRECTORY is None:
+            return None
+        if not os.path.exists(GALAXY_TEST_SCREENSHOTS_DIRECTORY):
+            os.makedirs(GALAXY_TEST_SCREENSHOTS_DIRECTORY)
+        target = os.path.join(GALAXY_TEST_SCREENSHOTS_DIRECTORY, label + extension)
+        copy = 1
+        while os.path.exists(target):
+            target = os.path.join(GALAXY_TEST_SCREENSHOTS_DIRECTORY, f"{label}-{copy}{extension}")
+            copy += 1
+        return target
+
     def reset_driver_and_session(self):
+        self.story.reset()
         self.tear_down_driver()
         self.target_url_from_selenium = self._target_url_from_selenium()
         self.setup_driver_and_session()
@@ -654,12 +765,6 @@ def setup_shared_state(self):
         """Override this to setup shared data for tests that gets initialized only once."""
 
 
-if TYPE_CHECKING:
-    NavigatesGalaxyMixin = NavigatesGalaxy
-else:
-    NavigatesGalaxyMixin = object
-
-
 class UsesLibraryAssertions(NavigatesGalaxyMixin):
     @retry_assertion_during_transitions
     def assert_num_displayed_items_is(self, n):
diff --git a/lib/galaxy_test/selenium/jupyter/__init__.py b/lib/galaxy_test/selenium/jupyter/__init__.py
index b4cf2c4669af..2271b529a04e 100644
--- a/lib/galaxy_test/selenium/jupyter/__init__.py
+++ b/lib/galaxy_test/selenium/jupyter/__init__.py
@@ -101,7 +101,7 @@
 ::
 
     $ GALAXY_SKIP_CLIENT_BUILD=1 GALAXY_RUN_WITH_TEST_TOOLS=1 sh run.sh
-    $ make client-watch
+    $ make client-dev-server
 
 Copy ``lib/galaxy_test/selenium/jupyter/galaxy_selenium.yml.sample`` to
 ``lib/galaxy_test/selenium/jupyter/galaxy_selenium.yml`` and specify a
diff --git a/lib/galaxy_test/selenium/test_uploads.py b/lib/galaxy_test/selenium/test_uploads.py
index 67fb8ad84c86..f398d87daa1e 100644
--- a/lib/galaxy_test/selenium/test_uploads.py
+++ b/lib/galaxy_test/selenium/test_uploads.py
@@ -1,9 +1,10 @@
-import os
-
 import pytest
 from selenium.webdriver.common.by import By
-from selenium.webdriver.common.keys import Keys
 
+from galaxy.selenium.stories.data.upload import (
+    RULES_EXAMPLE_6_SOURCE,
+    UploadStoriesMixin,
+)
 from .framework import (
     selenium_only,
     selenium_test,
@@ -12,7 +13,7 @@
 )
 
 
-class TestUploads(SeleniumTestCase, UsesHistoryItemAssertions):
+class TestUploads(SeleniumTestCase, UsesHistoryItemAssertions, UploadStoriesMixin):
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     def test_upload_file(self):
@@ -230,221 +231,42 @@ def test_upload_modal_retains_content(self):
     def test_rules_example_1_datasets(self):
         # Test case generated for:
         #   https://www.ebi.ac.uk/ena/data/view/PRJDA60709
-        self.home()
-        self.upload_rule_start()
-        self.sleep_for(self.wait_types.UX_RENDER)
-        self.screenshot("rules_example_1_1_rules_landing")
-        self.components.upload.rule_source_content.wait_for_and_send_keys(
-            """study_accession sample_accession    experiment_accession    fastq_ftp
-PRJDA60709  SAMD00016379    DRX000475   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000770/DRR000770.fastq.gz
-PRJDA60709  SAMD00016383    DRX000476   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000771/DRR000771.fastq.gz
-PRJDA60709  SAMD00016380    DRX000477   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000772/DRR000772.fastq.gz
-PRJDA60709  SAMD00016378    DRX000478   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000773/DRR000773.fastq.gz
-PRJDA60709  SAMD00016381    DRX000479   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000774/DRR000774.fastq.gz
-PRJDA60709  SAMD00016382    DRX000480   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000775/DRR000775.fastq.gz"""
-        )
-        self._wait_for_upload_modal()
-        self.screenshot("rules_example_1_2_paste")
-        self.upload_rule_build()
-        rule_builder = self.components.rule_builder
-        rule_builder._.wait_for_and_click()
-        self.screenshot("rules_example_1_3_initial_rules")
-        rule_builder.menu_button_filter.wait_for_and_click()
-        self.screenshot("rule_builder_filters")
-        rule_builder.menu_item_rule_type(rule_type="add-filter-count").wait_for_and_click()
-        filter_editor = rule_builder.rule_editor(rule_type="add-filter-count")
-        filter_editor_element = filter_editor.wait_for_visible()
-        filter_input = filter_editor_element.find_element(By.CSS_SELECTOR, "input[type='number']")
-        filter_input.clear()
-        filter_input.send_keys("1")
-        self.screenshot("rules_example_1_4_filter_header")
-        rule_builder.rule_editor_ok.wait_for_and_click()
-        self.rule_builder_set_mapping("url", "D")
-        self.rule_builder_set_mapping("name", "C", screenshot_name="rules_example_1_5_mapping_edit")
-        self.screenshot("rules_example_1_6_mapping_set")
-        self.rule_builder_set_extension("fastqsanger.gz")
-        self.screenshot("rules_example_1_7_extension_set")
-        # rule_builder.main_button_ok.wait_for_and_click()
-        # self.history_panel_wait_for_hid_ok(6)
-        # self.screenshot("rules_example_1_6_download_complete")
+        self.upload_rules_example_1()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     @pytest.mark.gtn_screenshot
     @pytest.mark.local
     def test_rules_example_2_list(self):
-        self.perform_upload(self.get_filename("rules/PRJDA60709.tsv"))
-        self.history_panel_wait_for_hid_ok(1)
-        self.upload_rule_start()
-        self.upload_rule_set_data_type("Collections")
-        self.upload_rule_dataset_dialog()
-        self.upload_rule_set_dataset(1)
-        self.screenshot("rules_example_2_1_inputs")
-        self.upload_rule_build()
-        rule_builder = self.components.rule_builder
-        rule_builder._.wait_for_and_click()
-        self.screenshot("rules_example_2_2_initial_rules")
-        # Filter header.
-        self.rule_builder_filter_count(1)
-        self.rule_builder_set_mapping("url", "D")
-        self.rule_builder_set_mapping("list-identifiers", "C")
-        self.rule_builder_set_extension("fastqsanger.gz")
-        self.screenshot("rules_example_2_3_rules")
-        self.rule_builder_set_collection_name("PRJDA60709")
-        self.screenshot("rules_example_2_4_name")
-        # rule_builder.main_buton_ok.wait_for_and_click()
-        # self.history_panel_wait_for_hid_ok(2)
-        # self.screenshot("rules_example_2_5_download_complete")
+        self.upload_rules_example_2()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     @pytest.mark.gtn_screenshot
     @pytest.mark.local
     def test_rules_example_3_list_pairs(self):
-        self.perform_upload(self.get_filename("rules/PRJDB3920.tsv"))
-        self.history_panel_wait_for_hid_ok(1)
-        self.upload_rule_start()
-        self.upload_rule_set_data_type("Collections")
-        self.upload_rule_dataset_dialog()
-        self.upload_rule_set_dataset(1)
-        self._wait_for_upload_modal()
-        self.screenshot("rules_example_3_1_inputs")
-        self.upload_rule_build()
-        rule_builder = self.components.rule_builder
-        rule_builder._.wait_for_and_click()
-        self.screenshot("rules_example_3_2_initial_rules")
-        # Filter header.
-        self.rule_builder_filter_count(1)
-        self.rule_builder_set_mapping("list-identifiers", "C")
-        self.rule_builder_set_extension("fastqsanger.gz")
-        self.screenshot("rules_example_3_3_old_rules")
-        self.rule_builder_add_regex_groups("D", 2, r"(.*);(.*)", screenshot_name="rules_example_3_4_regex")
-        self.screenshot("rules_example_3_6_with_regexes")
-        # Remove A also?
-        self.rule_builder_remove_columns(["D"], screenshot_name="rules_example_3_7_removed_column")
-        self.rule_builder_split_columns(["D"], ["E"], screenshot_name="rules_example_3_8_split_columns")
-        self.screenshot("rules_example_3_9_columns_are_split")
-        self.rule_builder_add_regex_groups(
-            "D", 1, r".*_(\d).fastq.gz", screenshot_name="rules_example_3_10_regex_paired"
-        )
-        self.screenshot("rules_example_3_11_has_paired_id")
-        self.rule_builder_swap_columns("D", "E", screenshot_name="rules_example_3_12_swap_columns")
-        self.screenshot("rules_example_3_13_swapped_columns")
-        self.rule_builder_set_mapping("paired-identifier", "D")
-        self.rule_builder_set_mapping("url", "E")
-        self.rule_builder_set_collection_name("PRJDB3920")
-        self.screenshot("rules_example_3_14_paired_identifier_set")
+        self.upload_rules_example_3()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     @pytest.mark.gtn_screenshot
     @pytest.mark.local
     def test_rules_example_4_accessions(self):
-        # http://www.uniprot.org/uniprot/?query=proteome:UP000052092+AND+proteomecomponent:%22Genome%22
-        self._setup_uniprot_example()
-        self._wait_for_upload_modal()
-        self.screenshot("rules_example_4_1_inputs")
-        self.upload_rule_build()
-        rule_builder = self.components.rule_builder
-        rule_builder._.wait_for_and_click()
-        self.screenshot("rules_example_4_2_initial_rules")
-        self.rule_builder_filter_count(1)
-        self.rule_builder_remove_columns(["B", "C", "E", "F", "G"])
-        self.rule_builder_set_mapping("info", "B")
-        self.screenshot("rules_example_4_3_basic_rules")
-        self.rule_builder_sort("A", screenshot_name="rules_example_4_4_sort")
-
-        self.rule_builder_add_regex_replacement(
-            "A", ".*", "http://www.uniprot.org/uniprot/\\0.fasta", screenshot_name="rules_example_4_5_url"
-        )
-        self.screenshot("rules_example_4_6_url_built")
-        self.rule_builder_set_mapping("list-identifiers", "A")
-        self.rule_builder_set_mapping("url", "C")
-        self.rule_builder_set_extension("fasta")
-        self.rule_builder_set_collection_name("UP000052092")
-        self.screenshot("rules_example_4_7_mapping_extension_and_name")
-
-        rule_builder.view_source.wait_for_and_click()
-        text_area_elem = rule_builder.source.wait_for_visible()
-
-        self.screenshot("rules_example_4_8_source")
-        self.write_screenshot_directory_file("rules_example_4_8_text", text_area_elem.get_attribute("value"))
-
-        rule_builder.main_button_ok.wait_for_and_click()
-        rule_builder.view_source.wait_for_visible()
+        self.upload_rules_example_4()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     @pytest.mark.gtn_screenshot
     @pytest.mark.local
     def test_rules_example_5_matching_collections(self):
-        self._setup_uniprot_example()
-        self._wait_for_upload_modal()
-        self.screenshot("rules_example_5_1_inputs")
-        self.upload_rule_build()
-
-        rule_builder = self.components.rule_builder
-        rule_builder.view_source.wait_for_and_click()
-
-        content = self._read_rules_test_data_file("uniprot.json")
-        self.rule_builder_enter_source_text(content)
-        self.screenshot("rules_example_5_2_source")
-        rule_builder.main_button_ok.wait_for_and_click()
-        rule_builder.view_source.wait_for_visible()
-        self.screenshot("rules_example_5_3_initial_rules")
-        self.rule_builder_add_value("fasta", screenshot_name="rules_example_5_4_fasta")
-        self.rule_builder_add_value("UP000052092 FASTA")
-        self.rule_builder_add_regex_replacement(
-            "A", ".*", "http://www.uniprot.org/uniprot/\\0.gff", screenshot_name="rules_example_5_5_url"
-        )
-        self.rule_builder_add_value("gff3")
-        self.rule_builder_add_value("UP000052092 GFF3")
-        self._scroll_to_end_of_table()
-        self.screenshot("rules_example_5_6_presplit")
-        self.rule_builder_split_columns(
-            ["C", "D", "E"], ["F", "G", "H"], screenshot_name="rules_example_5_7_split_columns"
-        )
-        self.screenshot("rules_example_5_8_split")
-        self.rule_builder_set_mapping("file-type", "D")
-        self.rule_builder_set_mapping("collection-name", "E")
-        self.screenshot("rules_example_5_9_mapping")
+        self.upload_rules_example_5()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
     @pytest.mark.gtn_screenshot
     @pytest.mark.local
     def test_rules_example_6_nested_lists(self):
-        self.home()
-        self.perform_upload(self.get_filename("rules/PRJNA355367.tsv"))
-        self.history_panel_wait_for_hid_ok(1)
-        self.upload_rule_start()
-        self.upload_rule_set_data_type("Collections")
-        self.upload_rule_dataset_dialog()
-        self.upload_rule_set_dataset(1)
-
-        self._wait_for_upload_modal()
-        self.screenshot("rules_example_6_1_paste")
-        self.upload_rule_build()
-
-        rule_builder = self.components.rule_builder
-        rule_builder._.wait_for_and_click()
-
-        self.screenshot("rules_example_6_2_rules_landing")
-
-        self.rule_builder_filter_count(1)
-
-        self.rule_builder_set_mapping("url", "J")
-        self.rule_builder_set_extension("sra")
-        self._scroll_to_end_of_table()
-        self.screenshot("rules_example_6_3_end_of_table")
-        self.rule_builder_add_regex_groups("L", 1, r"([^\d]+)\d+", screenshot_name="rules_example_6_4_regex")
-        self.rule_builder_set_mapping(
-            "list-identifiers", ["M", "A"], screenshot_name="rules_example_6_5_multiple_identifiers_edit"
-        )
-        self._scroll_to_end_of_table()
-        self.screenshot("rules_example_6_6_multiple_identifiers")
-        self.rule_builder_set_collection_name("PRJNA355367")
-        self.screenshot("rules_example_6_7_named")
+        self.upload_rules_example_6()
 
     @selenium_only("Not yet migrated to support Playwright backend")
     @selenium_test
@@ -465,7 +287,7 @@ def test_rules_deferred_datasets(self):
 PRJDA60709  SAMD00016381    DRX000479   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000774/DRR000774.fastq.gz
 PRJDA60709  SAMD00016382    DRX000480   ftp.sra.ebi.ac.uk/vol1/fastq/DRR000/DRR000775/DRR000775.fastq.gz"""
         )
-        self._wait_for_upload_modal()
+        self.wait_for_upload_modal()
         self.screenshot("rules_deferred_datasets_2_paste")
         self.upload_rule_build()
         rule_builder = self.components.rule_builder
@@ -495,14 +317,14 @@ def test_rules_deferred_datasets(self):
     @pytest.mark.local
     def test_rules_deferred_list(self):
         self.home()
-        self.perform_upload(self.get_filename("rules/PRJNA355367.tsv"))
+        self.perform_upload(RULES_EXAMPLE_6_SOURCE)
         self.history_panel_wait_for_hid_ok(1)
         self.upload_rule_start()
         self.upload_rule_set_data_type("Collections")
         self.upload_rule_dataset_dialog()
         self.upload_rule_set_dataset(1)
 
-        self._wait_for_upload_modal()
+        self.wait_for_upload_modal()
         self.screenshot("rules_deferred_list_1_paste")
         self.upload_rule_build()
 
@@ -514,13 +336,13 @@ def test_rules_deferred_list(self):
 
         self.rule_builder_set_mapping("url-deferred", "J")
         self.rule_builder_set_extension("sra")
-        self._scroll_to_end_of_table()
+        self.scroll_to_end_of_table()
         self.screenshot("rules_deferred_list_3_end_of_table")
         self.rule_builder_add_regex_groups("L", 1, r"([^\d]+)\d+", screenshot_name="rules_deferred_list_4_regex")
         self.rule_builder_set_mapping(
             "list-identifiers", ["M", "A"], screenshot_name="rules_deferred_list_5_multiple_identifiers_edit"
         )
-        self._scroll_to_end_of_table()
+        self.scroll_to_end_of_table()
         self.screenshot("rules_deferred_list_6_multiple_identifiers")
         self.rule_builder_set_collection_name("PRJNA355367")
         self.screenshot("rules_deferred_list_7_named")
@@ -529,36 +351,6 @@ def test_rules_deferred_list(self):
         self.history_panel_wait_for_hid_state(hid, state="deferred", allowed_force_refreshes=1)
         self.screenshot("rules_deferred_list_7_download_complete")
 
-    def _read_rules_test_data_file(self, name):
-        with open(self.test_data_resolver.get_filename(os.path.join("rules", name))) as f:
-            return f.read()
-
-    def _wait_for_upload_modal(self):
-        self.components.upload.build_button.wait_for_visible()
-        self.components.upload.build_button.wait_for_clickable()
-
-    def _scroll_to_end_of_table(self):
-        rule_builder = self.components.rule_builder
-        table_elem = rule_builder.table.wait_for_visible()
-        # handsontable
-        # first_cell = table_elem.find_elements(By.CSS_SELECTOR, "td")[0]
-        # aggrid
-        first_cell = table_elem.find_elements(By.CSS_SELECTOR, ".ag-cell")[0]
-        action_chains = self.action_chains()
-        action_chains.move_to_element(first_cell)
-        action_chains.click(first_cell)
-        for _ in range(15):
-            action_chains.send_keys(Keys.ARROW_RIGHT)
-        action_chains.perform()
-
-    def _setup_uniprot_example(self):
-        self.perform_upload(self.get_filename("rules/uniprot.tsv"))
-        self.history_panel_wait_for_hid_ok(1)
-        self.upload_rule_start()
-        self.upload_rule_set_data_type("Collections")
-        self.upload_rule_dataset_dialog()
-        self.upload_rule_set_dataset(1)
-
     # @selenium_test
     # def test_rules_example_5_matching_collections(self):
     #    self.rule_builder_add_value("Protein FASTA")
diff --git a/lib/galaxy_test/selenium/test_workbook_import.py b/lib/galaxy_test/selenium/test_workbook_import.py
new file mode 100644
index 000000000000..7c5f42cc16ba
--- /dev/null
+++ b/lib/galaxy_test/selenium/test_workbook_import.py
@@ -0,0 +1,149 @@
+from galaxy.selenium.stories.data.upload import UploadStoriesMixin
+from .framework import (
+    selenium_test,
+    SeleniumTestCase,
+)
+
+DOC_ENABLE_RULES_ACTIVITY = """
+If the "Rules-based Data Import" activity is not available in the activity side bar. Click the "... More" activity settings button and enable the option for "Rules-based Data Import".
+"""
+
+
+class TestWorkbookImport(SeleniumTestCase, UploadStoriesMixin):
+    """Test suite for workbook-based dataset and collection import."""
+
+    ensure_registered = True
+
+    def setup_rules_import(self) -> None:
+        """Set up the test environment for rules-based data import.
+
+        Navigates to home and ensures the rules activity is enabled.
+        """
+        self.home()
+        self.document(DOC_ENABLE_RULES_ACTIVITY)
+        self.ensure_rules_activity_enabled()
+
+    def _assert_rules_have_mapping(self, rule_json: dict) -> list:
+        """Assert that rule JSON contains a mapping and return it.
+
+        Args:
+            rule_json: The rule JSON from rule_builder_show_and_get_source_as_json()
+
+        Returns:
+            The mapping list from the rule JSON
+        """
+        assert "mapping" in rule_json
+        return rule_json["mapping"]
+
+    def _assert_maps_to_one_column_of_type(
+        self, mapping: list, index: int, expected_type: str, expected_column: int
+    ) -> None:
+        """Assert a mapping entry maps to exactly one column of the expected type.
+
+        Args:
+            mapping: The mapping list from rule JSON
+            index: Index of the mapping entry to check
+            expected_type: Expected mapping type (e.g., "name", "url", "dbkey")
+            expected_column: Expected column index (0-based)
+        """
+        assert mapping[index]["type"] == expected_type
+        assert len(mapping[index]["columns"]) == 1
+        assert mapping[index]["columns"][0] == expected_column
+
+    @selenium_test
+    def test_dataset_import_from_workbook(self):
+        """Test importing datasets from a workbook with automatic column mapping.
+
+        This test validates that Galaxy can:
+        - Automatically infer column mappings from common header patterns
+        - Detect dataset name, URL, and genome (dbkey) columns
+        - Correctly map columns without manual rule builder configuration
+        """
+        self.setup_rules_import()
+        self.upload_workbook_example_1()
+        self._verify_example_1()
+
+    def _verify_example_1(self):
+        rule_json = self.rule_builder_show_and_get_source_as_json()
+        mapping = self._assert_rules_have_mapping(rule_json)
+
+        self._assert_maps_to_one_column_of_type(mapping, 0, "name", 0)
+        self._assert_maps_to_one_column_of_type(mapping, 1, "url", 1)
+        self._assert_maps_to_one_column_of_type(mapping, 2, "dbkey", 2)
+
+    @selenium_test
+    def test_dataset_import_from_workbook_full_wizard(self):
+        """Same test as above but using the wizard instead of upload shortcut."""
+        self.setup_rules_import()
+        self.upload_example_1_full_wizard()
+        self._verify_example_1()
+
+    @selenium_test
+    def test_collection_type_selection_for_import(self):
+        self.setup_rules_import()
+        self.upload_workbook_example_2_prereq_pick_a_collection()
+
+    @selenium_test
+    def test_simple_list_collection_import(self):
+        """Test importing a simple list collection from a workbook.
+
+        This test validates that Galaxy can:
+        - Detect collection mode when user clicks "collections" button
+        - Automatically infer list identifiers and file types
+        - Map URL columns for collection elements
+        """
+        self.setup_rules_import()
+        self.upload_workbook_example_2()
+
+        # Verify the rule builder mapping
+        rule_json = self.rule_builder_show_and_get_source_as_json()
+        mapping = self._assert_rules_have_mapping(rule_json)
+
+        self._assert_maps_to_one_column_of_type(mapping, 0, "list_identifiers", 0)
+        self._assert_maps_to_one_column_of_type(mapping, 1, "url", 1)
+        self._assert_maps_to_one_column_of_type(mapping, 2, "file_type", 2)
+
+    @selenium_test
+    def test_list_of_pairs_collection_import(self):
+        """Test importing a list of pairs collection with automatic pairing.
+
+        This test validates that Galaxy can:
+        - Detect paired data from two URL columns per row
+        - Automatically split and pair forward/reverse elements
+        - Add paired_identifier column for the rule builder
+        - Map list identifiers and genome information
+        """
+        self.setup_rules_import()
+        self.upload_workbook_example_3()
+
+        # Verify the rule builder mapping
+        rule_json = self.rule_builder_show_and_get_source_as_json()
+        mapping = self._assert_rules_have_mapping(rule_json)
+
+        self._assert_maps_to_one_column_of_type(mapping, 0, "list_identifiers", 0)
+        self._assert_maps_to_one_column_of_type(mapping, 1, "url", 1)
+        self._assert_maps_to_one_column_of_type(mapping, 2, "dbkey", 2)
+        self._assert_maps_to_one_column_of_type(mapping, 3, "paired_identifier", 3)
+
+    @selenium_test
+    def test_nested_list_of_pairs_import(self):
+        """Test importing nested list structures with paired data.
+
+        This test validates that Galaxy can:
+        - Handle complex nested list structures
+        - Detect and split paired data (two URLs per row)
+        - Infer multiple list identifier levels
+        - Build correct nested collection hierarchy
+
+        Note: The outer list identifier is always the first one that appears.
+        Column order matters for list nesting.
+        """
+        self.setup_rules_import()
+        self.upload_workbook_example_4()
+
+        # Verify the rule builder mapping
+        rule_json = self.rule_builder_show_and_get_source_as_json()
+        mapping = self._assert_rules_have_mapping(rule_json)
+
+        self._assert_maps_to_one_column_of_type(mapping, 0, "url", 0)
+        self._assert_maps_to_one_column_of_type(mapping, 2, "paired_identifier", 3)
diff --git a/packages/util/setup.cfg b/packages/util/setup.cfg
index 0c1c79c19167..8a16731f76c5 100644
--- a/packages/util/setup.cfg
+++ b/packages/util/setup.cfg
@@ -52,6 +52,9 @@ image-util =
     pillow
 jstree =
     dictobj
+markdown-convert =
+    Markdown
+    weasyprint
 template =
     CT3>=3.3.3
     fissix;python_version>='3.13'
@@ -59,7 +62,7 @@ template =
 config-template =
     Jinja2
     pydantic
-test = 
+test =
     pytest
     pytest-httpserver
     responses
diff --git a/test/integration_selenium/test_trs_import.py b/test/integration_selenium/test_trs_import.py
index d6031a805377..d5ad2713a696 100644
--- a/test/integration_selenium/test_trs_import.py
+++ b/test/integration_selenium/test_trs_import.py
@@ -1,6 +1,9 @@
 import os
 
-from .framework import SeleniumIntegrationTestCase
+from .framework import (
+    selenium_test,
+    SeleniumIntegrationTestCase,
+)
 
 TRS_API_URL_DOCKSTORE = "https://dockstore.org/api"
 TRS_API_URL_WORKFLOWHUB = "https://workflowhub.eu"
@@ -53,10 +56,12 @@ def assert_workflow_imported(self, name):
         self.workflow_index_search_for(f'"{name}"')
         assert len(self.workflow_card_elements()) == 1, f"workflow ${name} not imported"
 
+    @selenium_test
     def test_import_workflow_by_url_dockstore(self):
         import_url = f"workflows/trs_import?trs_server=dockstore.org&trs_version={TRS_VERSION_DOCKSTORE}&trs_id=%23{TRS_ID_DOCKSTORE}"
         self._import_workflow_by_url(import_url)
 
+    @selenium_test
     def test_import_workflow_by_url_workflowhub(self):
         import_url = f"workflows/trs_import?trs_server=workflowhub&trs_version={TRS_VERSION_WORKFLOWHUB}&trs_id={TRS_ID_WORKFLOWHUB}"
         self._import_workflow_by_url(import_url)
@@ -67,6 +72,7 @@ def _import_workflow_by_url(self, import_url):
         self.components.workflows.workflow_cards.wait_for_visible()
         self.assert_workflow_imported(WORKFLOW_NAME)
 
+    @selenium_test
     def test_import_by_search_dockstore(self):
         self.go_to_trs_search()
         self.components.trs_search.search.wait_for_and_send_keys("This is the documentation for the workflow.")
@@ -78,6 +84,7 @@ def test_import_by_search_dockstore(self):
         self.workflow_index_open()
         self.assert_workflow_imported("Test Workflow")
 
+    @selenium_test
     def test_import_by_organization_search_dockstore(self):
         self.go_to_trs_search()
         self.components.trs_search.search.wait_for_and_send_keys("organization: iwc-workflows")
@@ -89,6 +96,7 @@ def test_import_by_organization_search_dockstore(self):
         self.components.workflows.trs_icon.wait_for_visible()
         self.screenshot("workflow_imported_via_dockstore_search")
 
+    @selenium_test
     def test_import_by_search_workflowhub(self):
         self.go_to_trs_search()
         self.components.trs_search.select_server_button.wait_for_and_click()
@@ -100,22 +108,28 @@ def test_import_by_search_workflowhub(self):
         self.workflow_index_open()
         self.assert_workflow_imported(WORKFLOW_NAME)
 
+    @selenium_test
     def test_import_by_id_dockstore(self):
         self._import_by_id(f"#{TRS_ID_DOCKSTORE}", server="dockstore")
 
+    @selenium_test
     def test_import_by_id_workflowhub(self):
         self._import_by_id(TRS_ID_WORKFLOWHUB, server="workflowhub")
 
+    @selenium_test
     def test_import_by_trs_url_dockstore(self):
         self._import_by_trs_url(TRS_URL_DOCKSTORE)
 
+    @selenium_test
     def test_import_by_trs_url_workflowhub(self):
         self._import_by_trs_url(TRS_URL_WORKFLOWHUB)
 
+    @selenium_test
     def test_auto_import_by_trs_url_dockstore(self):
         import_url = f"workflows/trs_import?trs_url={TRS_URL_DOCKSTORE}"
         self._import_workflow_by_url(import_url)
 
+    @selenium_test
     def test_auto_import_by_trs_url_workflowhub(self):
         import_url = f"workflows/trs_import?trs_url={TRS_URL_WORKFLOWHUB}"
         self._import_workflow_by_url(import_url)
diff --git a/test/unit/app/managers/test_markdown_to_html.py b/test/unit/app/managers/test_markdown_to_html.py
index 59cbc58f93e5..2420df122f24 100644
--- a/test/unit/app/managers/test_markdown_to_html.py
+++ b/test/unit/app/managers/test_markdown_to_html.py
@@ -5,7 +5,7 @@
 dependencies.
 """
 
-from galaxy.managers.markdown_util import to_html
+from galaxy.util.markdown import to_html
 
 
 def test_basics():
diff --git a/test/unit/selenium/test_has_driver.py b/test/unit/selenium/test_has_driver.py
index f157797bc38f..f6938b79f5cd 100644
--- a/test/unit/selenium/test_has_driver.py
+++ b/test/unit/selenium/test_has_driver.py
@@ -1051,6 +1051,64 @@ def test_get_screenshot_as_png(self, has_driver_instance, base_url):
         # PNG magic bytes: 89 50 4E 47 0D 0A 1A 0A
         assert screenshot_bytes[:8] == b"\x89PNG\r\n\x1a\n"
 
+    def test_highlight_element_basic(self, has_driver_instance, base_url):
+        """Test highlighting an element with red border."""
+        has_driver_instance.navigate_to(f"{base_url}/basic.html")
+        element = has_driver_instance.find_element_by_id("test-div")
+
+        # Get border before highlighting
+        original_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+
+        # Highlight element
+        with has_driver_instance.highlight_element(element):
+            # Border should be red while in context
+            current_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+            assert "red" in current_border.lower()
+            assert "3px" in current_border or "3" in current_border
+
+        # Border should be restored after context exits
+        restored_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+        assert restored_border == original_border
+
+    def test_highlight_element_restores_on_exception(self, has_driver_instance, base_url):
+        """Test that border is restored even if exception occurs in context."""
+        has_driver_instance.navigate_to(f"{base_url}/basic.html")
+        element = has_driver_instance.find_element_by_id("test-div")
+
+        # Get border before highlighting
+        original_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+
+        # Highlight element and raise exception
+        try:
+            with has_driver_instance.highlight_element(element):
+                raise ValueError("Test exception")
+        except ValueError:
+            pass
+
+        # Border should still be restored
+        restored_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+        assert restored_border == original_border
+
+    def test_highlight_element_with_existing_border(self, has_driver_instance, base_url):
+        """Test highlighting element that already has a border."""
+        has_driver_instance.navigate_to(f"{base_url}/basic.html")
+        element = has_driver_instance.find_element_by_id("test-div")
+
+        # Set a blue border first
+        has_driver_instance.execute_script("arguments[0].style.border = '2px solid blue';", element)
+        original_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+
+        # Highlight element
+        with has_driver_instance.highlight_element(element):
+            # Border should be red
+            current_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+            assert "red" in current_border.lower()
+
+        # Border should be restored to blue
+        restored_border = has_driver_instance.execute_script("return arguments[0].style.border;", element)
+        assert restored_border == original_border
+        assert "blue" in restored_border.lower() or "2px" in restored_border
+
 
 class TestAccessibility:
     """Tests for axe_eval accessibility testing."""
diff --git a/test/unit/selenium/test_story_sections.py b/test/unit/selenium/test_story_sections.py
new file mode 100644
index 000000000000..440bdb9cadbf
--- /dev/null
+++ b/test/unit/selenium/test_story_sections.py
@@ -0,0 +1,569 @@
+"""Tests for composable story sections functionality."""
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from galaxy.selenium.stories.story import (
+    SectionMetadataInput,
+    SectionProxy,
+    Story,
+)
+
+
+@pytest.fixture
+def temp_story_dir():
+    """Create a temporary directory for story output."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        yield tmpdir
+
+
+class TestSectionTracking:
+    """Test basic section tracking functionality."""
+
+    def test_basic_section_tracking(self, temp_story_dir):
+        """Test creating and tracking a basic section."""
+        story = Story("Test", "Description", temp_story_dir)
+
+        meta: SectionMetadataInput = {"title": "Test Section", "anchor": "test_section"}
+        story._begin_section(meta)
+        story.add_documentation("Test content")
+        story._end_section()
+
+        # Check that section was tracked
+        assert "test_section" in story.section_elements
+        assert len(story.section_elements["test_section"]) > 0
+
+    def test_section_with_screenshots(self, temp_story_dir):
+        """Test section containing screenshots."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        # Create a dummy screenshot file
+        screenshot_path = Path(temp_story_dir) / "001_test.png"
+        screenshot_path.write_text("fake image")
+
+        meta: SectionMetadataInput = {"title": "Screenshots", "anchor": "screenshots"}
+        story._begin_section(meta)
+        story.add_screenshot(str(screenshot_path), "Test Screenshot")
+        story.add_documentation("Screenshot description")
+        story._end_section()
+
+        assert "screenshots" in story.section_elements
+        elements = story.section_elements["screenshots"]
+        # Should contain header, screenshot, and documentation
+        assert any(e[0] == "screenshot" for e in elements)
+        assert any(e[0] == "documentation" for e in elements)
+
+    def test_nested_sections(self, temp_story_dir):
+        """Test nested section hierarchy."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        meta_outer: SectionMetadataInput = {"title": "Outer", "anchor": "outer"}
+        meta_inner: SectionMetadataInput = {"title": "Inner", "anchor": "inner"}
+
+        story._begin_section(meta_outer)
+        story.add_documentation("Outer content")
+        story._begin_section(meta_inner)
+        story.add_documentation("Inner content")
+        story._end_section()
+        story._end_section()
+
+        # Both sections should be tracked
+        assert "outer" in story.section_elements
+        assert "inner" in story.section_elements
+
+
+class TestSectionFiltering:
+    """Test section filtering (only_sections, skip_sections)."""
+
+    def test_only_sections_filter(self, temp_story_dir):
+        """Test --only-sections flag filters correctly."""
+        story = Story(
+            "Test",
+            "Desc",
+            temp_story_dir,
+            only_sections={"included"},
+        )
+
+        # Add included section
+        meta1: SectionMetadataInput = {"title": "Included", "anchor": "included"}
+        story._begin_section(meta1)
+        story.add_documentation("Included content")
+        story._end_section()
+
+        # Add excluded section
+        meta2: SectionMetadataInput = {"title": "Excluded", "anchor": "excluded"}
+        story._begin_section(meta2)
+        story.add_documentation("Excluded content")
+        story._end_section()
+
+        # Only included should be in section_elements
+        assert "included" in story.section_elements
+        assert "excluded" not in story.section_elements
+
+    def test_skip_sections_filter(self, temp_story_dir):
+        """Test --skip-sections flag filters correctly."""
+        story = Story(
+            "Test",
+            "Desc",
+            temp_story_dir,
+            skip_sections={"skipped"},
+        )
+
+        # Add kept section
+        meta1: SectionMetadataInput = {"title": "Kept", "anchor": "kept"}
+        story._begin_section(meta1)
+        story.add_documentation("Kept content")
+        story._end_section()
+
+        # Add skipped section
+        meta2: SectionMetadataInput = {"title": "Skipped", "anchor": "skipped"}
+        story._begin_section(meta2)
+        story.add_documentation("Skipped content")
+        story._end_section()
+
+        # Only kept should be in section_elements
+        assert "kept" in story.section_elements
+        assert "skipped" not in story.section_elements
+
+    def test_only_and_skip_conflict(self, temp_story_dir):
+        """Test that skip takes precedence over only."""
+        story = Story(
+            "Test",
+            "Desc",
+            temp_story_dir,
+            only_sections={"section_a", "section_b"},
+            skip_sections={"section_b"},
+        )
+
+        # Add section_a (in only, not skipped)
+        meta_a: SectionMetadataInput = {"title": "A", "anchor": "section_a"}
+        story._begin_section(meta_a)
+        story.add_documentation("A")
+        story._end_section()
+
+        # Add section_b (in only but also skipped)
+        meta_b: SectionMetadataInput = {"title": "B", "anchor": "section_b"}
+        story._begin_section(meta_b)
+        story.add_documentation("B")
+        story._end_section()
+
+        # Add section_c (not in only)
+        meta_c: SectionMetadataInput = {"title": "C", "anchor": "section_c"}
+        story._begin_section(meta_c)
+        story.add_documentation("C")
+        story._end_section()
+
+        # Only section_a should be included
+        assert "section_a" in story.section_elements
+        assert "section_b" not in story.section_elements  # Skipped takes precedence
+        assert "section_c" not in story.section_elements  # Not in only
+
+
+class TestSectionHeadingLevels:
+    """Test that section heading levels auto-increment with nesting."""
+
+    def test_top_level_heading(self, temp_story_dir):
+        """Test that top-level sections are H2."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        meta: SectionMetadataInput = {"title": "Top Level", "anchor": "top"}
+        story._begin_section(meta)
+        story._end_section()
+
+        # Check that section was added with H2 heading
+        elements = story.elements
+        assert any("## Top Level" in e[1] for e in elements if e[0] == "documentation")
+
+    def test_nested_heading_levels(self, temp_story_dir):
+        """Test that nested sections increment heading levels."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        meta_outer: SectionMetadataInput = {"title": "Outer", "anchor": "outer"}
+        meta_inner: SectionMetadataInput = {"title": "Inner", "anchor": "inner"}
+
+        story._begin_section(meta_outer)
+        # Inner section starts while outer is active
+        story._begin_section(meta_inner)
+        story._end_section()
+        story._end_section()
+
+        # Check heading levels in elements
+        elements_text = "\n".join(e[1] for e in story.elements if e[0] == "documentation")
+        assert "## Outer" in elements_text
+        assert "### Inner" in elements_text
+
+
+class TestSectionProxy:
+    """Test SectionProxy context manager."""
+
+    def test_section_proxy_context_manager(self, temp_story_dir):
+        """Test using SectionProxy as context manager."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        class FakeDriver:
+            def __init__(self, story_obj):
+                self.story = story_obj
+
+        driver = FakeDriver(story)
+
+        # Use section proxy as context manager
+        with SectionProxy(driver, "Test Section", "test") as section:
+            if section:
+                story.add_documentation("Content in section")
+
+        # Section should be tracked
+        assert "test" in story.section_elements
+
+    def test_section_proxy_truthiness_when_included(self, temp_story_dir):
+        """Test that section proxy is truthy when not filtered."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        class FakeDriver:
+            def __init__(self, story_obj):
+                self.story = story_obj
+
+        driver = FakeDriver(story)
+
+        # Section should be truthy (not filtered)
+        with SectionProxy(driver, "Test Section", "test") as section:
+            assert section  # Should be truthy
+            assert not section.should_skip
+
+    def test_section_proxy_truthiness_when_filtered(self, temp_story_dir):
+        """Test that section proxy is falsy when filtered out."""
+        story = Story("Test", "Desc", temp_story_dir, only_sections={"other"})
+
+        class FakeDriver:
+            def __init__(self, story_obj):
+                self.story = story_obj
+
+        driver = FakeDriver(story)
+
+        # Section should be falsy (filtered out)
+        executed = False
+        with SectionProxy(driver, "Test Section", "test") as section:
+            assert not section  # Should be falsy
+            assert section.should_skip
+            if section:
+                executed = True
+
+        # Code inside the if should not have run
+        assert not executed
+
+
+class TestReset:
+    """Test resetting story state."""
+
+    def test_reset_clears_sections(self, temp_story_dir):
+        """Test that reset() clears section tracking."""
+        story = Story("Test", "Desc", temp_story_dir)
+
+        meta: SectionMetadataInput = {"title": "Test", "anchor": "test"}
+        story._begin_section(meta)
+        story.add_documentation("Content")
+        story._end_section()
+
+        assert "test" in story.section_elements
+
+        # Reset
+        story.reset()
+
+        assert len(story.section_elements) == 0
+        assert len(story.section_stack) == 0
+        assert not story._filtering_active
+
+
+class TestMarkdownMerging:
+    """Test markdown section extraction and merging."""
+
+    def test_extract_sections_from_markdown(self, temp_story_dir):
+        """Test extracting sections from existing markdown."""
+        # Create a markdown file with sections
+        md_path = Path(temp_story_dir) / "existing.md"
+        md_content = """# Title
+
+This is preamble content before any sections.
+
+<a id="section1"></a>
+## Section 1
+
+Content for section 1.
+
+<a id="section2"></a>
+## Section 2
+
+Content for section 2.
+"""
+        md_path.write_text(md_content)
+
+        story = Story("Test", "Desc", temp_story_dir)
+        sections = story._extract_sections_from_markdown(str(md_path))
+
+        # Should have preamble and 2 sections
+        assert "__preamble__" in sections
+        assert "section1" in sections
+        assert "section2" in sections
+
+        # Check preamble content
+        preamble = "\n".join(sections["__preamble__"])
+        assert "Title" in preamble
+        assert "preamble content" in preamble
+
+        # Check section content
+        section1 = "\n".join(sections["section1"])
+        assert 'id="section1"' in section1
+        assert "Section 1" in section1
+        assert "Content for section 1" in section1
+
+    def test_merge_sections_replace_mode(self, temp_story_dir):
+        """Test replacing sections in existing markdown."""
+        # Create existing markdown
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_content = """# Tutorial
+
+<a id="intro"></a>
+## Introduction
+
+Old intro content.
+
+<a id="section1"></a>
+## Section 1
+
+Old section 1 content.
+
+<a id="section2"></a>
+## Section 2
+
+Old section 2 content.
+"""
+        existing_path.write_text(existing_content)
+
+        # Create story with replace mode
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "Tutorial",
+            "",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="replace",
+        )
+
+        # Add updated section1
+        meta: SectionMetadataInput = {"title": "Section 1 Updated", "anchor": "section1"}
+        story._begin_section(meta)
+        story.add_documentation("New section 1 content!")
+        story._end_section()
+
+        # Merge sections
+        story._merge_sections(str(existing_path))
+
+        # Check that elements were updated
+        markdown = story._generate_markdown()
+
+        # Should have intro (preserved), updated section1, and section2 (preserved)
+        assert "Old intro content" in markdown
+        assert "New section 1 content" in markdown
+        assert "Old section 2 content" in markdown
+        assert "Old section 1 content" not in markdown  # Replaced
+
+    def test_merge_sections_append_mode(self, temp_story_dir):
+        """Test appending new sections to existing markdown."""
+        # Create existing markdown
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_content = """# Tutorial
+
+<a id="section1"></a>
+## Section 1
+
+Existing section 1 content.
+"""
+        existing_path.write_text(existing_content)
+
+        # Create story with append mode
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "Tutorial",
+            "",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="append",
+        )
+
+        # Add new section (doesn't exist in original)
+        meta1: SectionMetadataInput = {"title": "Section 2", "anchor": "section2"}
+        story._begin_section(meta1)
+        story.add_documentation("New section 2 content.")
+        story._end_section()
+
+        # Try to add existing section (should be ignored in append mode)
+        meta2: SectionMetadataInput = {"title": "Section 1 Updated", "anchor": "section1"}
+        story._begin_section(meta2)
+        story.add_documentation("This should be ignored in append mode.")
+        story._end_section()
+
+        # Merge sections
+        story._merge_sections(str(existing_path))
+
+        markdown = story._generate_markdown()
+
+        # Should have existing section1 (not updated) and new section2
+        assert "Existing section 1 content" in markdown
+        assert "New section 2 content" in markdown
+        assert "This should be ignored" not in markdown  # Not appended (already exists)
+
+    def test_merge_sections_standalone_mode(self, temp_story_dir):
+        """Test that standalone mode doesn't merge."""
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_path.write_text("# Old Content")
+
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "New Tutorial",
+            "New description",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="standalone",  # Default
+        )
+
+        # Add section
+        meta: SectionMetadataInput = {"title": "New Section", "anchor": "new"}
+        story._begin_section(meta)
+        story.add_documentation("New content.")
+        story._end_section()
+
+        # Merge should do nothing in standalone mode
+        story._merge_sections(str(existing_path))
+
+        markdown = story._generate_markdown()
+
+        # Should have new content, not old
+        assert "New Tutorial" in markdown
+        assert "New content" in markdown
+        assert "Old Content" not in markdown
+
+    def test_finalize_with_merge(self, temp_story_dir):
+        """Test that finalize() calls merge when merge_target is set."""
+        # Create existing markdown
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_content = """# Tutorial
+
+<a id="section1"></a>
+## Section 1
+
+Old content.
+"""
+        existing_path.write_text(existing_content)
+
+        # Create story with replace mode
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "Tutorial",
+            "",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="replace",
+        )
+
+        # Add updated section
+        meta: SectionMetadataInput = {"title": "Section 1", "anchor": "section1"}
+        story._begin_section(meta)
+        story.add_documentation("Updated content!")
+        story._end_section()
+
+        # Test merge by calling _merge_sections directly (avoids HTML/PDF generation)
+        story._merge_sections(str(existing_path))
+
+        # Check merged content
+        markdown = story._generate_markdown()
+        assert "Updated content" in markdown
+        assert "Old content" not in markdown
+
+    def test_merge_preserves_section_order(self, temp_story_dir):
+        """Test that replace mode preserves original section order."""
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_content = """# Tutorial
+
+<a id="first"></a>
+## First
+
+First section.
+
+<a id="second"></a>
+## Second
+
+Second section.
+
+<a id="third"></a>
+## Third
+
+Third section.
+"""
+        existing_path.write_text(existing_content)
+
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "Tutorial",
+            "",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="replace",
+        )
+
+        # Update second section only
+        meta: SectionMetadataInput = {"title": "Second Updated", "anchor": "second"}
+        story._begin_section(meta)
+        story.add_documentation("Updated second section.")
+        story._end_section()
+
+        story._merge_sections(str(existing_path))
+        markdown = story._generate_markdown()
+
+        # Check order is preserved: first, second (updated), third
+        first_pos = markdown.find("First section")
+        second_pos = markdown.find("Updated second section")
+        third_pos = markdown.find("Third section")
+
+        assert first_pos < second_pos < third_pos
+
+    def test_merge_adds_new_sections_at_end(self, temp_story_dir):
+        """Test that new sections are added at the end in replace mode."""
+        existing_path = Path(temp_story_dir) / "existing.md"
+        existing_content = """# Tutorial
+
+<a id="existing"></a>
+## Existing Section
+
+Existing content.
+"""
+        existing_path.write_text(existing_content)
+
+        output_dir = Path(temp_story_dir) / "output"
+        output_dir.mkdir()
+        story = Story(
+            "Tutorial",
+            "",
+            str(output_dir),
+            merge_target=str(existing_path),
+            section_mode="replace",
+        )
+
+        # Add new section that doesn't exist
+        meta: SectionMetadataInput = {"title": "New Section", "anchor": "new"}
+        story._begin_section(meta)
+        story.add_documentation("New content at end.")
+        story._end_section()
+
+        story._merge_sections(str(existing_path))
+        markdown = story._generate_markdown()
+
+        # New section should come after existing
+        existing_pos = markdown.find("Existing content")
+        new_pos = markdown.find("New content at end")
+
+        assert existing_pos < new_pos