Sync agents and skills from help-content-tools

.github/skills/finalize-draft-pr/SKILL.md

@@ -315,7 +315,11 @@ Generate URLs only for reviewable content files:
 
 **Limit:** If more than 10 files changed, include only the top 10 most significant files to avoid overwhelming the comment.
 
-#### Step 3c — Handle edge cases
+#### Step 3c — Create preview link labels
+
+For each preview URL, use the title displayed on the rendered page as the link label. Do not use the file name, file path, topic ID, or page ID. Follow the label rules in `references/alphahelp-url-construction.md`, including resolving DITA variables in `<title>` elements.
+
+#### Step 3d — Handle edge cases
 
 **Snippets only:**
 - If only snippets changed, note: "Updated shared snippets (no direct preview URL)"
@@ -374,9 +378,9 @@ Use `mcp_github_create_pull_request` with:
 
 Preview on alphahelp (after build completes):
 
-- [{file1-display-name}]({alphahelp-url-1})
-- [{file2-display-name}]({alphahelp-url-2})
-- [{file3-display-name}]({alphahelp-url-3})
+- [{page1-title}]({alphahelp-url-1})
+- [{page2-title}]({alphahelp-url-2})
+- [{page3-title}]({alphahelp-url-3})
 
 ### Changes
 
@@ -479,9 +483,9 @@ Use `mcp_jira_addCommentToJiraIssue` with:
 Pull request: [PR #{pr_number}]({pr_url})
 
 Preview on alphahelp:
-* [{file1}]({url1})
-* [{file2}]({url2})
-* [{file3}]({url3})
+* [{page1-title}]({url1})
+* [{page2-title}]({url2})
+* [{page3-title}]({url3})
 ```
 
 **That's it.** Just PR link + alphahelp URLs. No extra formatting, no build notes, no automation disclaimer.

.github/skills/finalize-draft-pr/references/alphahelp-url-construction.md

@@ -114,7 +114,7 @@ https://alphahelp.qliktech.com/rc/en-US/{site-segment}/{transformed-path}
 - **Path**: `Content/AnalyticsMigrationTool/...` (no transformation)
 - **Final URL**:
   ```
-  https://alphahelp.qliktech.com/rc/en-US/migration-DOC-2686-unified-tagging-tests-ld/Content/AnalyticsMigrationTool/Qlik-Analytics-Migration-Tool-Overview.htm
+  https://alphahelp.qliktech.com/rc/en-US/migration-DOC-2686-unified-tagging-tests-rc/Content/AnalyticsMigrationTool/Qlik-Analytics-Migration-Tool-Overview.htm
   ```
 
 #### Example 2: Qlik Cloud Services (QCS)
@@ -161,13 +161,30 @@ Example: `cloud-DOC-4764-DE-1-6-persistence-storage`
 
 ### Step 2: Extract mapid from DITAMAP
 
-**Simple Rule:** The mapid is always the ditamap filename without the `.ditamap` extension.
+Use the value of the map's mapid element: `<othermeta name="mapid" content="..."/>`.
 
 Examples:
 - `installation-guide.ditamap` → mapid: `installation-guide`
 - `debug-jobs.ditamap` → mapid: `debug-jobs`
 - `dynamic-engine-configuration-guide.ditamap` → mapid: `dynamic-engine-configuration-guide`
 
+#### Operating-system build flavors
+
+The build appends an operating-system flavor to these map IDs:
+
+- `installation-guide`
+- `hybrid-installation-guide`
+- `remote-engine-user-guide`
+
+A URL that uses one of these base map IDs without a flavor is invalid.
+
+- Append `-linux` by default. The Linux build contains the most content.
+- If all relevant changes are specific to Windows, append `-windows`.
+- If all relevant changes are specific to macOS, append `-mac`.
+- If the changes apply to multiple operating systems, provide one Linux preview link. Do not provide all flavor variants.
+
+Determine whether a change is operating-system-specific from the changed content's profiling attributes and surrounding topic references. When this cannot be determined, use the Linux flavor and flag the assumption for review.
+
 #### Finding Which DITAMAP References Your Topic
 
 Ditamaps are always located in these specific directories:
@@ -211,7 +228,7 @@ Example DITA file:
 </concept>
 ```
 
-The `pageid` is `configure-docker-registry`.
+The `pageid` is `r2026-05-studio-new-features`.
 
 ### Step 4: Assemble Final URL
 
@@ -226,7 +243,7 @@ https://alphahelp.qliktech.com/talend/en-US/{mapid}/{branch-name}/{pageid}
 - **Branch**: `cloud-DOC-4764-DE-1-6-persistence-storage`
 - **File**: `en/engines/configure-docker-registry-task.dita`
 - **DITAMAP**: `dynamic-engine-configuration-guide.ditamap` (mapid: `dynamic-engine-configuration-guide`)
-- **DITA file id**: `configure-docker-registry`
+- **DITA pageid**: `configure-docker-registry`
 - **Final URL**:
   ```
   https://alphahelp.qliktech.com/talend/en-US/dynamic-engine-configuration-guide/cloud-DOC-4764-DE-1-6-persistence-storage/configure-docker-registry
@@ -236,6 +253,21 @@ https://alphahelp.qliktech.com/talend/en-US/{mapid}/{branch-name}/{pageid}
 
 ## Edge Cases and Special Handling
 
+### Preview link labels
+
+Use the page title as the link label in PR descriptions and Jira comments. Do not use the file name, file path, topic ID, or page ID as the label.
+
+- For DITA, resolve the topic's `<title>`, including referenced variables, so the label matches the rendered page title.
+- For Flare, use the title displayed as the page heading.
+- Preserve the title's capitalization and product names.
+- If the title cannot be resolved, flag the label for manual review instead of substituting a file path.
+
+Example:
+
+```markdown
+- [Installing and configuring MongoDB](https://alphahelp.qliktech.com/talend/en-US/installation-guide-linux/cloud-DOC-1234-example/installing-and-configuring-mongodb)
+```
+
 ### Multiple Files Changed
 
 Generate a URL for each changed htm or dita file.
@@ -314,6 +346,8 @@ After generating URLs:
 3. **Incorrect product code mapping** (e.g., using `qcs` instead of `cloud-services`)
 4. **Posting URLs before build completes** (URLs won't work until Jenkins finishes)
 5. **For DITA**: Confusing filename with pageid (pageid comes from `pageid` attribute, not filename)
+6. **Using `installation-guide`, `hybrid-installation-guide`, or `remote-engine-user-guide` without a build flavor** (append `-linux` by default)
+7. **Using a file path or ID as the link label** (use the rendered page title)
 
 ---
 

.github/skills/finalize-draft-pr/references/comment-templates.md

@@ -15,9 +15,9 @@ Use this template when posting comments to GitHub pull requests with `mcp_github
 
 Preview the updated documentation on alphahelp (after build completes):
 
-- [{file1-display-name}]({alphahelp-url-1})
-- [{file2-display-name}]({alphahelp-url-2})
-- [{file3-display-name}]({alphahelp-url-3})
+- [{page1-title}]({alphahelp-url-1})
+- [{page2-title}]({alphahelp-url-2})
+- [{page3-title}]({alphahelp-url-3})
 
 ### Changes Summary
 
@@ -40,20 +40,18 @@ _This comment was posted automatically by the documentation automation system._
 
 | Variable | Description | Example |
 |---|---|---|
-| `{file1-display-name}` | Relative path from `Content/` (Flare) or feature folder (DITA) | `Sense_Hub/Introduction/creating-analytics.htm` |
+| `{page1-title}` | Title displayed on the rendered page | `Creating analytics and visualizing data` |
 | `{alphahelp-url-1}` | Full alphahelp URL for the file | `https://alphahelp.qliktech.com/rc/en-US/...` |
 | `{brief-summary-from-plan-or-commit-message}` | 1-3 sentence summary of changes | "Added documentation for new Azure Blob Storage connector configuration options including authentication methods and connection string parameters." |
 
-### File Display Name Format
+### Preview Link Label Format
 
-Keep display names concise and readable:
-- Use relative paths that make sense to reviewers
-- Omit `Content/` prefix for clarity
-- Keep folder context when helpful
-- Examples:
-  - `Connectors/Azure/Configuration.htm`
-  - `engines/configure-docker-registry.dita`
-  - `Introduction/creating-analytics.htm`
+Use the title displayed on the rendered page as each link label. Do not use a file name, path, topic ID, or page ID.
+
+- For DITA, resolve the topic's `<title>`, including referenced variables.
+- For Flare, use the title displayed as the page heading.
+- Preserve the title's capitalization and product names.
+- If the title cannot be resolved, flag it for manual review.
 
 ---