From ceb4adae91db258280f2246068eab880331c08cf Mon Sep 17 00:00:00 2001
From: dvozenil <vozenilekd@gmail.com>
Date: Wed, 18 Mar 2026 15:46:08 +0100
Subject: [PATCH 1/5] added CQA-related skills, added CLAUDE.md

---
 .claude/skills/cqa-reviewer/SKILL.md          | 198 ++++++++++++++++++
 .claude/skills/doc-structure-checker/SKILL.md |  83 ++++++++
 ...dular documentation templates checklist.md |  51 +++++
 .../references/TEMPLATE_ASSEMBLY.adoc         |  79 +++++++
 .../references/TEMPLATE_CONCEPT.adoc          |  52 +++++
 .../references/TEMPLATE_PROCEDURE.adoc        |  86 ++++++++
 .../references/TEMPLATE_REFERENCE.adoc        |  57 +++++
 .../skills/short-description-expert/SKILL.md  | 159 ++++++++++++++
 CLAUDE.md                                     | 184 ++++++++++++++++
 9 files changed, 949 insertions(+)
 create mode 100644 .claude/skills/cqa-reviewer/SKILL.md
 create mode 100644 .claude/skills/doc-structure-checker/SKILL.md
 create mode 100644 .claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md
 create mode 100644 .claude/skills/doc-structure-checker/references/TEMPLATE_ASSEMBLY.adoc
 create mode 100644 .claude/skills/doc-structure-checker/references/TEMPLATE_CONCEPT.adoc
 create mode 100644 .claude/skills/doc-structure-checker/references/TEMPLATE_PROCEDURE.adoc
 create mode 100644 .claude/skills/doc-structure-checker/references/TEMPLATE_REFERENCE.adoc
 create mode 100644 .claude/skills/short-description-expert/SKILL.md
 create mode 100644 CLAUDE.md

diff --git a/.claude/skills/cqa-reviewer/SKILL.md b/.claude/skills/cqa-reviewer/SKILL.md
new file mode 100644
index 00000000000..dcb3c1a8521
--- /dev/null
+++ b/.claude/skills/cqa-reviewer/SKILL.md
@@ -0,0 +1,198 @@
+---
+name: cqa-reviewer
+description: Reviews changes made by other CQA skills, compares before/after Vale results, and flags over-corrections or missed issues.
+---
+
+# CQA Reviewer
+
+I am the final quality gate in the CQA workflow. I can operate in two modes:
+
+- **Audit Mode** (standalone): Reads `master.adoc`, maps all included files, and reviews every existing abstract across all modules for quality — without requiring any prior skill run or git changes.
+- **Review Mode** (post-skill): Reviews changes made by other skills (short-description-expert, doc-structure-checker), compares before/after Vale results, and flags over-corrections or missed issues.
+
+---
+
+## Audit Mode
+
+Use this mode to proactively review abstract quality across an entire guide, including files where `[role="_abstract"]` is already present and Vale passes without errors.
+
+### AM-1. Setup
+
+The user provides a path to `master.adoc`. Recursively map all `include::` files exactly as `short-description-expert` does:
+
+1. Open `master.adoc` and follow every `include::` directive.
+2. Recursively open referenced files to find nested includes.
+3. Resolve relative paths from each file's directory.
+4. Build the complete file list.
+
+**Exclude from review** (same rules as `short-description-expert`):
+- Assembly files: `assembly_*.adoc` — abstracts live in their first included concept module, not in the assembly itself
+- Attribute files: `attributes*.adoc`, `_title-attributes.adoc`
+- Snippet files: `snip_*.adoc`
+- Non-content includes: `header.adoc`, `ribbons.adoc`
+
+Only review module files: `con_*.adoc`, `proc_*.adoc`, `ref_*.adoc`.
+
+### AM-2. Per-File Review
+
+For each module file:
+
+1. Read the file.
+2. Locate the `[role="_abstract"]` paragraph (the paragraph immediately following that tag).
+3. Classify the result:
+
+**MISSING** — no `[role="_abstract"]` tag exists at all.
+
+**PRESENT — evaluate against all criteria:**
+- Follows What+Why formula ("You can [action] to [benefit]", "To [goal], configure [feature]", etc.)
+- 1-2 sentences, 50–300 characters, ≤50 words
+- First paragraph after the title, not buried further down
+- No self-referential language ("This section explains...", "The following...", "This document...")
+- Does not end with a colon
+- Uses AsciiDoc attributes (`{Project}`, `{SmartProxy}`, etc.) rather than hard-coded product names
+- Does not simply restate the title word-for-word
+- Active voice, present tense
+
+### AM-3. Output Format
+
+```
+=== CQA Abstract Audit Report ===
+
+Guide: [path to master.adoc]
+Modules reviewed: N
+Assemblies skipped: N (by design)
+
+MISSING abstract [role="_abstract"] tag:
+- path/to/file.adoc — title: "..."
+
+APPROVED (abstract present and meets all criteria):
+- path/to/file.adoc
+
+CONCERNS (present but has issues):
+- path/to/file.adoc
+  - Issue: [describe the specific problem]
+  - Current text: "[quote the abstract]"
+  - Suggestion: [rewrite or targeted fix]
+
+SUMMARY:
+- Missing: N files
+- Approved: N files
+- Concerns: N files
+
+Recommendation: [PASS / PASS WITH NOTES / NEEDS FIXES]
+```
+
+---
+
+## Review Mode
+
+Use this mode after `short-description-expert` or `doc-structure-checker` has made changes, to verify the changes are correct and haven't introduced new problems.
+
+### RM-1. Prerequisites
+
+Before running, ensure:
+- `adoc-file-list.txt` exists (file manifest from the prior skill run)
+- `vale-output.txt` exists (pre-fix Vale results)
+- Other skills have completed their work
+- Changes are visible via `git diff`
+- `vale-output-post.txt` does not exist — remove it if it does
+
+Run Vale again to create post-fix results:
+```
+xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
+```
+
+### RM-2. Review Process
+
+#### RM-2.1 Compare Vale Results
+1. Parse `vale-output.txt` (before) and `vale-output-post.txt` (after).
+2. Identify:
+   - **Resolved issues**: Errors in "before" that are gone in "after"
+   - **New issues**: Errors in "after" that weren't in "before"
+   - **Unchanged issues**: Errors present in both
+
+**Flag if:** New issues were introduced by the fixes.
+
+#### RM-2.2 Review Changed Files
+For each file with changes (via `git diff --name-only`):
+
+1. Read the diff to understand what changed.
+2. **Verify short descriptions:**
+   - Follow What+Why formula
+   - Are 1-2 sentences, between 50-300 characters, maximum ~50 words
+   - Don't repeat the title verbatim
+   - No self-referential language ("This document describes...", "This section explains...", "The following examples...", "The examples below...")
+   - Use AsciiDoc attributes, not hard-coded product names
+   - Do not end with a colon
+3. **Verify structural changes:**
+   - Assembly includes are properly ordered
+   - No content was accidentally deleted
+   - Prerequisites are correctly formatted
+4. **Check for over-corrections:**
+   - Content rewritten that was already acceptable
+   - Style changes beyond the scope of the fix
+   - Added content that wasn't requested
+
+#### RM-2.3 Consistency Check
+Across all changed files:
+- Terminology is consistent (same product names, feature names)
+- Short description style is consistent
+- No conflicting information introduced
+
+### RM-3. What NOT to Do
+
+- Do NOT make changes directly. Flag issues only.
+- Do NOT request endless revision cycles. One review pass is sufficient.
+- Do NOT flag minor stylistic preferences. Focus on errors and quality issues.
+- Do NOT re-review unchanged files.
+
+### RM-4. Output Format
+
+```
+=== CQA Review Report ===
+
+Vale Comparison:
+- Issues resolved: X
+- New issues introduced: Y
+- Unchanged issues: Z
+
+Files Reviewed: N
+
+APPROVED (no issues):
+- path/to/file.adoc
+
+CONCERNS (minor, acceptable):
+- path/to/file.adoc: Short description is 302 characters (limit 300) - minor, can accept
+
+ISSUES (needs attention):
+- path/to/file.adoc:
+  - Problem: Short description uses "This section explains..."
+  - Suggestion: Rewrite to start with action or benefit
+
+- path/to/assembly.adoc:
+  - Problem: New Vale error introduced (line 45: RedHat.Spelling)
+  - Suggestion: Check spelling of product name
+
+SUMMARY:
+- Total files: N
+- Approved: X
+- Minor concerns: Y
+- Issues to address: Z
+
+Recommendation: [PASS / PASS WITH NOTES / NEEDS FIXES]
+```
+
+### RM-5. Recommendation Criteria
+
+- **PASS**: No issues, all changes look good
+- **PASS WITH NOTES**: Minor concerns only, acceptable to proceed
+- **NEEDS FIXES**: Issues found that should be addressed before committing
+
+### RM-6. After Review
+
+If issues are found:
+1. Report them clearly with file paths and line numbers
+2. Suggest specific fixes
+3. User decides whether to run fix skills again or manually adjust
+
+Do NOT automatically trigger another round of fixes. Human decides next steps.
diff --git a/.claude/skills/doc-structure-checker/SKILL.md b/.claude/skills/doc-structure-checker/SKILL.md
new file mode 100644
index 00000000000..d74a93987ca
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: doc-structure-checker
+description: Validates and fixes AsciiDoc structural issues including assembly format, module templates, prerequisites, and nesting depth.
+---
+
+# Document Structure Checker
+
+I validate and fix structural issues in modular AsciiDoc documentation.
+
+## References
+
+Before starting, read these files in `references/`:
+- `Modular documentation templates checklist.md` - **Primary reference** for validation rules
+- `TEMPLATE_ASSEMBLY.adoc` - Canonical assembly structure
+- `TEMPLATE_CONCEPT.adoc` - Canonical concept module structure
+- `TEMPLATE_PROCEDURE.adoc` - Canonical procedure module structure
+- `TEMPLATE_REFERENCE.adoc` - Canonical reference module structure
+
+## 1. File Preparation
+
+The user provides a path to `master.adoc`.
+
+**If `adoc-file-list.txt` exists:** Use it. Skip to Section 3.
+
+**If missing:** Create the manifest:
+1. Open `master.adoc` and identify all `include::` files recursively
+2. Create `adoc-file-list.txt` with discovered file paths, one per line
+
+## 2. Files to Exclude
+
+Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snippet_*.adoc`, files in `common/` directory.
+
+## 3. Execution Workflow
+
+1. **Read** the reference files in `references/` to understand the rules
+2. **Read** `adoc-file-list.txt` to get the file manifest
+3. **Categorize** each file as assembly or module by checking for `:_mod-docs-content-type:`
+4. **Validate** each file against the checklist rules
+5. **Fix** issues with clear solutions (see below)
+6. **Flag** issues needing human decision (see below)
+7. **Summarize** changes made and issues flagged
+
+## 4. What to Fix vs Flag
+
+**Fix automatically:**
+- Prerequisites using ordered lists → convert to unordered
+- Multi-step procedures using bullets → convert to ordered list
+- Single-step procedures using numbered list → convert to bullet
+- Missing blank lines between include statements
+- Supplementary content under steps missing `+` connector
+
+**Flag for human review:**
+- Missing `[role="_abstract"]` → instruct user to run `short-description-expert`
+- Missing `:_mod-docs-content-type:` declaration
+- Nesting depth exceeding 3 levels
+- Concept/reference modules containing imperative statements
+- Procedure modules with multiple `.Procedure` blocks
+- Block titles not in the allowed list
+
+## 5. RHEL 10 Conventions
+
+- NO module type prefixes in filenames (no `con_`, `proc_`, `ref_`)
+- NO context prefixes in IDs
+- Determine module type by `:_mod-docs-content-type:`, not filename
+
+## 6. Output Format
+
+```
+=== Structure Check Summary ===
+
+Files checked: X
+Issues fixed: Y
+Issues flagged for review: Z
+
+FIXED:
+- path/to/file.adoc: [description of fix]
+
+FLAGGED (needs human review):
+- path/to/file.adoc: [issue description]
+
+NO ISSUES:
+- path/to/file.adoc
+```
diff --git a/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md b/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md
new file mode 100644
index 00000000000..5c4a7d04538
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md	
@@ -0,0 +1,51 @@
+**Modular documentation templates checklist**
+
+**All modules and assemblies:**
+
+* Has :\_mod-docs-content-type: \<TYPE\>, where  \<TYPE\> is ASSEMBLY, CONCEPT, REFERENCE, or PROCEDURE.  
+* Has a topic ID in the following format:  
+  \[id="\<file-name\>\_{context}"\]  
+  	For OCP: \[\_{context}"\] does not belong in Assemblies.  
+    
+* Has one and only one level 0 (=) title (H1) title  
+* Has a short introduction  
+* Has a blank line between the level 0 (=)  title and the short introduction  
+* For any images, has alternative text descriptions enclosed in quotation marks ("")  
+* Admonitions do not include titles.
+
+**Nested assembly files:**
+
+* Contains the following conditional statement at the top of the document:  
+  ifdef::context\[:parent-context: {context}\]  
+* Contains the following conditional statement at the bottom of the document:  
+  ifdef::parent-context\[:context: {parent-context}\]  
+  ifndef::parent-context\[:\!context:\]  
+* Has the context variable declared and defined (:context: some-assembly).
+
+**All assembly files:**
+
+* Has a blank line between each include statement.  
+* Does not contain a level 2 (===) section title (H3) or lower.   
+* Does not include block titles.
+
+**Concept or reference module:**
+
+* Does not contain an instruction (imperative statement).  
+* Does not contain a level 2 (===) section title (H3) or lower..  
+* Does not contain block titles, except .Additional references or .Next steps. Note that .Next steps will not be mapped to \<related-links\>, .Additional resources will.
+
+**Procedure module:**
+
+* Includes the .Procedure block title followed by one ordered or unordered list.  
+* Includes only one .Procedure block title and list.  
+* Does not contain embellishments of .Procedure, for example .Procedure for installing X.  
+* Does not contain content following the last step of the procedure except the optional sections in the order listed:  
+  \* Prerequisites or Prerequisite  
+  \* Procedure  
+  \* Verification, Results, or Result  
+  \* Troubleshooting, Troubleshooting steps, or Troubleshooting step  
+  \* Next steps or Next step  
+  \* Additional resources  
+    
+* Does not contain any other block titles. 
+
diff --git a/.claude/skills/doc-structure-checker/references/TEMPLATE_ASSEMBLY.adoc b/.claude/skills/doc-structure-checker/references/TEMPLATE_ASSEMBLY.adoc
new file mode 100644
index 00000000000..e817ad483a7
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/references/TEMPLATE_ASSEMBLY.adoc
@@ -0,0 +1,79 @@
+////
+Retains the context of the parent assembly if this assembly is nested within another assembly.
+For more information about nesting assemblies, see: https://redhat-documentation.github.io/modular-docs/#nesting-assemblies
+See also the complementary step on the last line of this file.
+////
+
+ifdef::context[:parent-context: {context}]
+
+
+////
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
+////
+:_mod-docs-content-type: ASSEMBLY
+
+////
+ Base the file name and the ID on the assembly title. For example:
+* file name: assembly-my-user-story.adoc
+* ID: [id="assembly-my-user-story_{context}"]
+* Title: = My user story
+
+ID is a unique identifier that can be used to reference this assembly. Avoid changing it after the module has been published to ensure existing links are not broken. Include {context} in the ID so the assembly can be reused.
+
+Be sure to include a line break between the title and the :context: variable and the :context: variable and the assembly introduction.
+If the assembly covers a task, start the title with a verb in the gerund form, such as Creating or Configuring.
+////
+[id="assembly-my-user-story_{context}"]
+= My user story
+////
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+////
+
+:context: assembly-keyword
+
+[role="_abstract"]
+This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on.
+
+== Prerequisites
+
+* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+* You can also link to other modules or assemblies the user must follow before starting this assembly.
+* Delete the section title and bullets if the assembly has no prerequisites.
+* X is installed. For information about installing X, see <link>.
+* You can log in to X with administrator privileges.
+
+////
+The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
+
+[leveloffset=+1] ensures that when a module title is a level 1 heading (= Title), the heading will be interpreted as a level-2 heading (== Title) in the assembly. Use [leveloffset=+2] and [leveloffset=+3] to nest modules in an assembly.
+
+ Add a blank line after each 'include::' statement.
+////
+
+include::TEMPLATE_CONCEPT_concept-explanation.adoc[leveloffset=+1]
+
+include::TEMPLATE_PROCEDURE_doing-one-procedure.adoc[leveloffset=+2]
+
+include::TEMPLATE_REFERENCE_reference-material.adoc[leveloffset=+2]
+
+== Next steps
+
+* This section is optional.
+* Provide information about the next steps the user might want to take.
+* This section can include text and links.
+
+// If the last module included in your assembly contains an Additional resources section as well, check the appearance of the rendered assembly. If the two Additional resources sections might be confusing for a reader, consider consolidating their content and removing one of them.
+
+[role="_additional-resources"]
+== Additional resources
+////
+Optional. Delete if not used.
+Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
+////
+* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
+* xref:some-module_{context}[]
+
+// Restore the context to what it was before this assembly.
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]
diff --git a/.claude/skills/doc-structure-checker/references/TEMPLATE_CONCEPT.adoc b/.claude/skills/doc-structure-checker/references/TEMPLATE_CONCEPT.adoc
new file mode 100644
index 00000000000..ea22c0accba
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/references/TEMPLATE_CONCEPT.adoc
@@ -0,0 +1,52 @@
+////
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
+////
+
+:_mod-docs-content-type: CONCEPT
+
+////
+Base the file name and the ID on the module title. For example:
+* file name: con_my-concept-module-a.adoc
+* ID: [id="my-concept-module-a_{context}"]
+* Title: = My concept module A
+
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
+////
+
+[id="my-concept-module-a_{context}"]
+= My concept module A
+////
+In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly. Do not start the title of concept modules with a verb or gerund. See also _Wording of headings_ in _IBM Style_.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module.
+
+The contents of a concept module give the user descriptions and explanations needed to understand and use a product.
+
+* Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
+* Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
+* Avoid including action items. Action items belong in procedure modules. However, in some cases a concept or reference can include suggested actions when those actions are simple, are highly dependent on the context of the module, and have no place in any procedure module. In such cases, ensure that the heading of the concept or reference remains a noun phrase and not a gerund.
+
+
+////
+Do not include third-level headings (===).
+Include titles and alternative text descriptions for images and enclose the descriptions in straight quotation marks (""). Alternative text should provide a textual, complete description of the image as a full sentence.
+Images should never be the sole means of conveying information and should only supplement the text.
+Avoid screenshots or other images that might quickly go out of date and that create a maintenance burden on documentation. Provide text equivalents for every diagram, image, or other non-text element. Avoid using images of text instead of actual text.
+////
+//.Image title
+//image::image-file.png["A textual representation of the essential information conveyed by the image."]
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
+////
+* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
+* xref:some-module_{context}[]
diff --git a/.claude/skills/doc-structure-checker/references/TEMPLATE_PROCEDURE.adoc b/.claude/skills/doc-structure-checker/references/TEMPLATE_PROCEDURE.adoc
new file mode 100644
index 00000000000..fe3e5dcf01c
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/references/TEMPLATE_PROCEDURE.adoc
@@ -0,0 +1,86 @@
+////
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
+////
+
+:_mod-docs-content-type: PROCEDURE
+
+////
+Base the file name and the ID on the module title. For example:
+* file name: proc_doing-procedure-a.adoc
+* ID: [id="doing-procedure-a_{context}"]
+* Title: = Doing procedure A
+
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
+////
+
+[id="doing-procedure-a_{context}"]
+= Doing procedure A
+////
+Start the title of a procedure module with a gerund, such as Creating, Installing, or Deploying.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module. The introduction should include what the module will help the user do and why it will be beneficial to the user. Include key words that relate to the module to maximize search engine optimization.
+
+.Prerequisites
+* A bulleted list of conditions that must be satisfied before the user starts the steps in this module.
+* Prerequisites can be full sentences or sentence fragments; however, prerequisite list items must be parallel.
+* Do not use imperative statements in the Prerequisites section.
+
+.Procedure
+. Make each step an instruction.
+. Include one imperative sentence for each step, for example:
+.. Do this thing and then select *Next*.
+.. Do this other thing, and this other thing, and then select *Next*.
+. Use an unnumbered bullet (*) if the procedure includes only one step.
++
+NOTE: You can add text, tables, code examples, images, and other items to a step. However, these items must be connected to the step with a plus sign (+). Any items under the .Procedure heading and before one of the following approved headings that are not connected to the last step with a plus sign cannot be converted to DITA.
+
+////
+Only the following block titles can be reliably mapped to DITA:
+
+* Prerequisites or Prerequisite
+* Procedure
+* Verification, Results, or Result
+* Troubleshooting, Troubleshooting steps, or Troubleshooting step
+* Next steps or Next step
+* Additional resources
+
+With the exception of Additional resources, these titles are only allowed in a procedure module. You can use each title exactly once and cannot use two different variants of the same title in the same module.
+
+Additionally, you can use block titles for figures, tables, and example blocks.
+////
+
+.Verification
+Delete this section if it does not apply to your module. Provide the user with verification methods for the procedure, such as expected output or commands that confirm success or failure.
+
+* Provide an example of expected command output or a pop-up window that the user receives when the procedure is successful.
+* List actions for the user to complete, such as entering a command, to determine the success or failure of the procedure.
+* Make each step an instruction.
+* Use an unnumbered bullet (*) if the verification includes only one step.
+
+.Troubleshooting
+Delete this section if it does not apply to your module. Provide the user with troubleshooting steps.
+
+* Make each step an instruction.
+* Use an unnumbered bullet (*) if the troubleshooting includes only one step.
+
+.Next steps
+* Delete this section if it does not apply to your module.
+* Provide a bulleted list of links that contain instructions that might be useful to the user after they complete this procedure.
+* Use an unnumbered bullet (*) if the list includes only one step.
+
+NOTE: Do not use *Next steps* to provide a second list of instructions.
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
+////
+* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
+* xref:some-module_{context}[]
diff --git a/.claude/skills/doc-structure-checker/references/TEMPLATE_REFERENCE.adoc b/.claude/skills/doc-structure-checker/references/TEMPLATE_REFERENCE.adoc
new file mode 100644
index 00000000000..b1f6885caef
--- /dev/null
+++ b/.claude/skills/doc-structure-checker/references/TEMPLATE_REFERENCE.adoc
@@ -0,0 +1,57 @@
+////
+Metadata attribute that will help enable correct parsing and conversion to the appropriate DITA topic type.
+////
+:_mod-docs-content-type: REFERENCE
+
+////
+Base the file name and the ID on the module title. For example:
+* file name: ref_my-reference-a.adoc
+* ID: [id="my-reference-a_{context}"]
+* Title: = My reference A
+
+ ID is a unique identifier that can be used to reference this module. Avoid changing it after the module has been published to ensure existing links are not broken.
+
+The `context` attribute enables module reuse. Every module ID includes {context}, which ensures that the module has a unique ID so you can include it multiple times in the same guide.
+
+Be sure to include a line break between the title and the module introduction.
+////
+
+[id="reference-material_{context}"]
+= Reference material
+////
+In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.
+on.
+////
+
+[role="_abstract"]
+Write a short introductory paragraph that provides an overview of the module.
+
+A reference module provides data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want.
+
+AsciiDoc markup to consider for reference data:
+
+.Unordered list
+* For more details on writing reference modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+* Use a consistent system for file names, IDs, and titles.
+For tips, see _File names and anchors_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+
+.Labeled list
+Term 1:: Definition
+Term 2:: Definition
+
+.Table
+[options="header"]
+|====
+|Column 1|Column 2|Column 3
+|Row 1, column 1|Row 1, column 2|Row 1, column 3
+|Row 2, column 1|Row 2, column 2|Row 2, column 3
+|====
+
+[role="_additional-resources"]
+.Additional resources
+////
+Optional. Delete if not used.
+Provide a bulleted list of links and display text relevant to the assembly. These links can include `link:` and `xref:` macros. Do not include additional text.
+////
+* link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]
+* xref:some-module_{context}[]
diff --git a/.claude/skills/short-description-expert/SKILL.md b/.claude/skills/short-description-expert/SKILL.md
new file mode 100644
index 00000000000..4b927f883f5
--- /dev/null
+++ b/.claude/skills/short-description-expert/SKILL.md
@@ -0,0 +1,159 @@
+---
+name: short-description-expert
+description: Recursively maps AsciiDoc includes from master.adoc, audits every module's short description for content quality, and rewrites abstracts that don't meet the "What and Why" formula. Processes files in batches of 50 with progress tracking.
+---
+
+# Short Description Expert
+
+I am a specialist in managing documentation pipelines and writing DITA/AsciiDoc short descriptions. I map document structures, evaluate existing abstracts for quality, and ensure all abstracts provide immediate user value.
+
+## 1. File Preparation Workflow
+The user provides a path to `master.adoc`. Check if artifacts already exist:
+
+**If `_short-desc-progress.md` exists:** A previous run was interrupted or is in progress. Read it to determine:
+- Which files have already been processed
+- Which files remain
+- Any skipped files and reasons
+
+Resume from where the previous run left off. Skip to Section 8 (Execution Workflow).
+
+**If `adoc-file-list.txt` AND `vale-output.txt` both exist (but no progress file):** Use them. Skip to Section 8 (Execution Workflow).
+
+**If either is missing:** Create fresh artifacts:
+1.  **Recursive Mapping**: Open `master.adoc` and identify all `include::` files. Recursively open those files to find nested includes. Resolve relative paths correctly.
+2.  **Manifest Creation**: Create `adoc-file-list.txt` containing only the discovered file paths, one per line, no additional text.
+3.  **Linting**: Run `xargs vale --output line < adoc-file-list.txt > vale-output.txt`.
+
+## 2. Files to Exclude from Abstract Auditing
+The following file types do not require abstracts — skip them entirely:
+- Assembly files: `assembly_*.adoc` — in this repository, assemblies do not carry their own abstract. The introduction and short description live in the first included concept module.
+- Attribute files: `attributes*.adoc`, `_title-attributes.adoc`
+- Snippet files: `snip_*.adoc`
+- Non-content includes: `header.adoc`, `ribbons.adoc`
+
+Focus abstract auditing exclusively on module files (`con_*.adoc`, `proc_*.adoc`, `ref_*.adoc`).
+
+## 3. Short Description Content Formula
+Every short description must follow this customer-centric pattern:
+- **What**: State the action or feature clearly.
+- **Why**: State the business value, benefit, or goal.
+- **Patterns**:
+  - "You can [action] to [benefit]"
+  - "To [goal], configure [feature]"
+  - "[Action] [what] to [why]"
+
+## 4. Structural Constraints
+- **Paragraphs**: Exactly one single paragraph.
+- **Length**: 1-2 simple sentences; between 50-300 characters, maximum ~50 words.
+- **Placement**: This must be the very first paragraph of the topic, immediately after the title.
+- **No Admonitions**: Never place a Note, Warning, or Important box before the short description.
+- **Doesn't end with a colon**: Must be a self-contained paragraph, not introduce a list.
+
+## 5. Style & Tone
+- **Voice**: Active Voice, present tense. No "allows you to" or "This section covers...".
+- **Product Names**: Use AsciiDoc attributes (`{Project}`, `{SmartProxy}`, etc.) — never hard-code product names.
+- **No Repetition**: Do not simply repeat the title; build upon it.
+- **No Self-Referential Language**: Avoid phrases like:
+  - "This document describes..."
+  - "This section explains..."
+  - "The following examples..."
+  - "The examples below..."
+  - Any variation that references the document structure itself
+
+## 6. Examples of Preferred Rewrites
+
+| Title | Preferred Short Description |
+| :--- | :--- |
+| Creating a group and adding a system | Group many systems together in the Edge Management application to manage them more easily. For example, you can more easily mitigate vulnerabilities and update systems that are alike. |
+| Browsing hosts in Satellite Web UI | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
+| Cloning Hosts | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
+| Editing System Purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |
+
+## 7. Batch Processing and Progress Tracking
+
+When the file list contains more than 50 files requiring fixes, process in batches:
+
+### Batch Size
+- **Default batch size**: 50 files
+- Process one batch at a time, then pause for user confirmation before continuing
+
+### Progress File: `_short-desc-progress.md`
+Create this file when starting work on a large file list (>50 files). Update it after each batch.
+
+**Format:**
+```markdown
+# Short Description Progress
+
+- **Last updated**: YYYY-MM-DD HH:MM
+- **Total files needing fixes**: [number]
+- **Processed**: [number] files
+- **Remaining**: [number] files
+- **Skipped**: [number] files (see list below)
+
+## Completed Batches
+- Batch 1: [number] files - YYYY-MM-DD
+- Batch 2: [number] files - YYYY-MM-DD
+
+## Skipped Files
+List files that were skipped and why (e.g., assembly file, attribute file):
+- `path/to/file.adoc` - Reason
+
+## Remaining Files
+List of files still needing processing:
+- `path/to/file1.adoc`
+- `path/to/file2.adoc`
+
+## Notes
+Any user requests or special instructions (e.g., "User requested batches of 50")
+```
+
+### Cleanup
+Delete `_short-desc-progress.md` only when all files have been processed and the user confirms completion.
+
+## 8. Execution Workflow
+
+1.  **Check for Progress File**: If `_short-desc-progress.md` exists, read it and resume from the remaining files list. Otherwise, start fresh.
+
+2.  **Audit All Module Files**: For each module file in `adoc-file-list.txt` (excluding file types in Section 2), read the file and classify it into one of three categories:
+
+    - **MISSING** — no `[role="_abstract"]` tag exists anywhere in the file.
+    - **NEEDS REWRITE** — `[role="_abstract"]` tag is present, but the paragraph immediately following it fails one or more criteria from Sections 3–5. Common failure patterns:
+      - Self-referential language ("This section describes...", "The following...")
+      - Passive voice or "allows you to" constructions
+      - Simply restates the title word-for-word
+      - Ends with a colon
+      - Under 50 or over 300 characters
+      - Hard-coded product names instead of AsciiDoc attributes
+      - Missing the Why — describes only what without benefit or goal
+    - **APPROVED** — `[role="_abstract"]` tag is present and the content meets all criteria from Sections 3–5.
+
+    Use `vale-output.txt` as a supplementary signal (DITA ShortDescription errors confirm a file needs attention), but do NOT rely on Vale alone. Files may pass Vale and still have poor-quality abstracts that require rewriting.
+
+3.  **Determine Batch**: Count MISSING + NEEDS REWRITE files. If more than 50:
+    - Create `_short-desc-progress.md` if it doesn't exist
+    - Select the first 50 unprocessed files for this batch
+
+4.  **Fix Each File**:
+    - **MISSING**: Draft a 2-sentence short description using the What+Why formula. Add `[role="_abstract"]` immediately above the new paragraph, placed as the first paragraph after the title.
+    - **NEEDS REWRITE**: Read the existing abstract carefully. Rewrite only the abstract paragraph content. Keep the existing `[role="_abstract"]` tag in place — do not move or duplicate it. Do not alter any other content in the file.
+    - **APPROVED**: Skip. Do not touch the file.
+
+5.  **Clean & Verify**: After writing each file, confirm:
+    - No self-referential phrasing
+    - Word count is under 50
+    - `[role="_abstract"]` appears exactly once, immediately before the abstract paragraph
+    - Abstract is the first paragraph after the title (no admonitions, blank lines with content, or other paragraphs before it)
+
+6.  **Update Progress**: After completing a batch:
+    - Update `_short-desc-progress.md` with completed count and remaining files
+    - Provide a summary to the user:
+      - Files fixed in this batch (distinguish MISSING vs NEEDS REWRITE)
+      - Files skipped and why
+      - Remaining file count
+    - Ask user: "Continue with next batch of 50 files?"
+
+7.  **Final Verification**: When all batches complete:
+    - Run `xargs vale --output line < adoc-file-list.txt > vale-output-post.txt`
+    - Verify no ShortDescription errors remain on module files
+    - Report fixes and any remaining errors of different types
+    - Delete `_short-desc-progress.md` after user confirms completion
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..206fdd7ea55
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,184 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a documentation repository for the Foreman project and its downstream products (Katello, Satellite, orcharhino). Documentation is written in AsciiDoc and follows the [modular documentation framework](https://redhat-documentation.github.io/modular-docs/).
+
+## Build Commands
+
+### Prerequisites (macOS)
+
+```bash
+brew install ruby make
+echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
+# Then restart terminal and install gems:
+make prep
+```
+
+### Building guides
+
+```bash
+# Build a single guide (run from a doc-*/ subdirectory)
+make BUILD=foreman-el
+
+# Build all guides (run from guides/)
+make html
+
+# Build all guides for a specific target
+make BUILD=katello  # options: foreman-el (default), foreman-deb, katello, satellite, orcharhino
+
+# Open built guide in browser (from a doc-*/ subdirectory)
+make browser
+
+# Parallel build (recommended)
+make -j9
+
+# Clean build artifacts
+make clean
+```
+
+### Full site (root Makefile)
+
+```bash
+make serve         # builds everything and serves at http://localhost:5000
+make html          # builds all guide variants
+make web           # builds the static landing site
+PORT=5008 make serve  # use a custom port
+```
+
+### Container build (alternative)
+
+```bash
+podman build --tag foreman_documentation .
+rm -rf guides/build && podman run --rm -v $(pwd):/foreman-documentation foreman_documentation make html
+```
+
+### Vale linting
+
+Vale linting runs automatically in CI on PRs. To run locally:
+
+```bash
+vale guides/common/modules/your-file.adoc
+vale --config=.vale-dita.ini guides/common/modules/your-file.adoc
+```
+
+The Vale config at `.vale.ini` uses the `RedHat`, `AsciiDoc`, and `foreman-documentation` style packages.
+
+### Link checking
+
+```bash
+# Run from guides/ after building HTML
+make linkchecker
+```
+
+## Repository Structure
+
+```
+guides/
+  common/            # Shared content included by all guides
+    assembly_*.adoc  # Assemblies (user stories that include modules)
+    modules/         # Individual content modules
+      con_*.adoc     # Concept modules (what/why)
+      proc_*.adoc    # Procedure modules (how-to steps)
+      ref_*.adoc     # Reference modules (tables, lists)
+      snip_*.adoc    # Snippets (reusable admonitions, no ID)
+    attributes.adoc           # Version numbers, includes other attribute files
+    attributes-base.adoc      # Base attributes for all builds
+    attributes-foreman-el.adoc
+    attributes-foreman-deb.adoc
+    attributes-katello.adoc
+    attributes-satellite.adoc
+    attributes-orcharhino.adoc
+    attributes-titles.adoc
+  doc-*/             # Individual guides, each with:
+    master.adoc      # Top-level file for the guide
+    common -> ../common  (symlink)
+    images/
+    images/common -> ../common/images  (symlink)
+    Makefile         # includes ../common/Makefile
+  build/             # Generated HTML output (gitignored)
+web/                 # Static landing page (nanoc site)
+.vale/
+  styles/
+    foreman-documentation/  # Custom Vale rules
+    config/vocabularies/Foreman/  # accept.txt, reject.txt
+.vale.ini            # Vale configuration for AsciiDoc
+.vale-dita.ini       # Vale configuration for DITA structure checks
+```
+
+## Content Architecture
+
+### Multi-target builds
+
+The same source files build documentation for multiple products. **Never use product names directly** — always use AsciiDoc attributes:
+
+- `{Project}` — product name (Foreman, Satellite, orcharhino)
+- `{ProjectServer}`, `{SmartProxy}`, `{ProjectWebUI}` — component names
+- `{ProjectVersion}`, `{KatelloVersion}` — version numbers
+
+Build targets: `foreman-el`, `foreman-deb`, `foremanctl-katello`, `foremanctl-orcharhino`, `foremanctl-satellite`, `katello`, `satellite`, `orcharhino`
+
+### Conditional content
+
+```asciidoc
+ifdef::katello[]
+Content only for Katello builds.
+endif::[]
+
+ifndef::satellite[]
+Content for all builds except Satellite.
+endif::[]
+
+// Logic OR:
+ifdef::katello,satellite[]
+Content for Katello or Satellite builds.
+endif::[]
+```
+
+### Using attributes in code blocks
+
+```asciidoc
+[options="nowrap" subs="+quotes,attributes"]
+----
+# command {AttributeName}
+----
+```
+
+### Module file structure
+
+Each module file starts with a content-type attribute on line 1:
+
+```asciidoc
+:_mod-docs-content-type: CONCEPT
+[id="my-topic_{context}"]
+= My topic title
+```
+
+Snippets (`snip_`) must not contain an ID.
+
+## Cursor Commands (`.cursor/commands/`)
+
+These commands describe common refactoring patterns:
+
+- **`abstract.md`** — review/write short descriptions (50–300 chars, user-centric, no self-referential language)
+- **`refactor-adoc.md`** — rename a file, update its ID, title, and all `include::` references across the repo
+- **`split-web-ui-cli.md`** — split a procedure into separate web UI (`proc_*-by-using-web-ui.adoc`) and CLI (`proc_*-by-using-cli.adoc`) files
+
+## Writing Conventions
+
+- One sentence per line in source files.
+- Use underscores for variable user input: `hammer org create --name "_My_Organization_"`
+- No trailing whitespace.
+- UTF-8 encoding.
+- IDs use lowercase kebab-case: `[id="my-topic_{context}"]`
+- Surround variable parts of IDs with `_{context}` (appended by the include mechanism).
+- Web UI and CLI procedures for the same task are split into separate files named `proc_*-by-using-web-ui.adoc` and `proc_*-by-using-cli.adoc`.
+
+## Branching Model
+
+- `master` = nightly (current development)
+- `X.Y` branches = stable releases (e.g., `3.18`)
+- Versions are set in `guides/common/attributes.adoc` (`ProjectVersion`, `KatelloVersion`)
+- PR descriptions include a cherry-pick list indicating which versions the change applies to

From a3e423d44cca756e2d7b0b72330b88f69487b480 Mon Sep 17 00:00:00 2001
From: dvozenil <56678357+dvozenil@users.noreply.github.com>
Date: Fri, 27 Mar 2026 14:00:02 +0100
Subject: [PATCH 2/5] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Lena Ansorgová <zuansorg@redhat.com>
Co-authored-by: Aneta Šteflová Petrová <apetrova@redhat.com>
---
 .claude/skills/cqa-reviewer/SKILL.md          | 30 ++++++++--------
 .claude/skills/doc-structure-checker/SKILL.md | 20 ++++-------
 ...dular documentation templates checklist.md | 15 ++++----
 .../skills/short-description-expert/SKILL.md  | 36 +++++++++----------
 4 files changed, 47 insertions(+), 54 deletions(-)

diff --git a/.claude/skills/cqa-reviewer/SKILL.md b/.claude/skills/cqa-reviewer/SKILL.md
index dcb3c1a8521..f5d8055ffa5 100644
--- a/.claude/skills/cqa-reviewer/SKILL.md
+++ b/.claude/skills/cqa-reviewer/SKILL.md
@@ -3,29 +3,29 @@ name: cqa-reviewer
 description: Reviews changes made by other CQA skills, compares before/after Vale results, and flags over-corrections or missed issues.
 ---
 
-# CQA Reviewer
+# CQA reviewer
 
-I am the final quality gate in the CQA workflow. I can operate in two modes:
+I am the final quality gate in the Content Quality Assessment (CQA) workflow. I can operate in two modes:
 
 - **Audit Mode** (standalone): Reads `master.adoc`, maps all included files, and reviews every existing abstract across all modules for quality — without requiring any prior skill run or git changes.
 - **Review Mode** (post-skill): Reviews changes made by other skills (short-description-expert, doc-structure-checker), compares before/after Vale results, and flags over-corrections or missed issues.
 
 ---
 
-## Audit Mode
+## Audit mode
 
 Use this mode to proactively review abstract quality across an entire guide, including files where `[role="_abstract"]` is already present and Vale passes without errors.
 
 ### AM-1. Setup
 
-The user provides a path to `master.adoc`. Recursively map all `include::` files exactly as `short-description-expert` does:
+The user provides a path to `master.adoc`. Recursively map all `include::` files:
 
 1. Open `master.adoc` and follow every `include::` directive.
 2. Recursively open referenced files to find nested includes.
 3. Resolve relative paths from each file's directory.
 4. Build the complete file list.
 
-**Exclude from review** (same rules as `short-description-expert`):
+**Exclude from review**:
 - Assembly files: `assembly_*.adoc` — abstracts live in their first included concept module, not in the assembly itself
 - Attribute files: `attributes*.adoc`, `_title-attributes.adoc`
 - Snippet files: `snip_*.adoc`
@@ -33,7 +33,7 @@ The user provides a path to `master.adoc`. Recursively map all `include::` files
 
 Only review module files: `con_*.adoc`, `proc_*.adoc`, `ref_*.adoc`.
 
-### AM-2. Per-File Review
+### AM-2. Per-file review
 
 For each module file:
 
@@ -53,7 +53,7 @@ For each module file:
 - Does not simply restate the title word-for-word
 - Active voice, present tense
 
-### AM-3. Output Format
+### AM-3. Output format
 
 ```
 === CQA Abstract Audit Report ===
@@ -102,9 +102,9 @@ Run Vale again to create post-fix results:
 xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
 ```
 
-### RM-2. Review Process
+### RM-2. Review process
 
-#### RM-2.1 Compare Vale Results
+#### RM-2.1 Compare Vale results
 1. Parse `vale-output.txt` (before) and `vale-output-post.txt` (after).
 2. Identify:
    - **Resolved issues**: Errors in "before" that are gone in "after"
@@ -113,7 +113,7 @@ xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
 
 **Flag if:** New issues were introduced by the fixes.
 
-#### RM-2.2 Review Changed Files
+#### RM-2.2 Review changed files
 For each file with changes (via `git diff --name-only`):
 
 1. Read the diff to understand what changed.
@@ -133,20 +133,20 @@ For each file with changes (via `git diff --name-only`):
    - Style changes beyond the scope of the fix
    - Added content that wasn't requested
 
-#### RM-2.3 Consistency Check
+#### RM-2.3 Consistency check
 Across all changed files:
 - Terminology is consistent (same product names, feature names)
 - Short description style is consistent
 - No conflicting information introduced
 
-### RM-3. What NOT to Do
+### RM-3. What NOT to do
 
 - Do NOT make changes directly. Flag issues only.
 - Do NOT request endless revision cycles. One review pass is sufficient.
 - Do NOT flag minor stylistic preferences. Focus on errors and quality issues.
 - Do NOT re-review unchanged files.
 
-### RM-4. Output Format
+### RM-4. Output format
 
 ```
 === CQA Review Report ===
@@ -182,13 +182,13 @@ SUMMARY:
 Recommendation: [PASS / PASS WITH NOTES / NEEDS FIXES]
 ```
 
-### RM-5. Recommendation Criteria
+### RM-5. Recommendation criteria
 
 - **PASS**: No issues, all changes look good
 - **PASS WITH NOTES**: Minor concerns only, acceptable to proceed
 - **NEEDS FIXES**: Issues found that should be addressed before committing
 
-### RM-6. After Review
+### RM-6. After review
 
 If issues are found:
 1. Report them clearly with file paths and line numbers
diff --git a/.claude/skills/doc-structure-checker/SKILL.md b/.claude/skills/doc-structure-checker/SKILL.md
index d74a93987ca..39d3e843921 100644
--- a/.claude/skills/doc-structure-checker/SKILL.md
+++ b/.claude/skills/doc-structure-checker/SKILL.md
@@ -3,7 +3,7 @@ name: doc-structure-checker
 description: Validates and fixes AsciiDoc structural issues including assembly format, module templates, prerequisites, and nesting depth.
 ---
 
-# Document Structure Checker
+# Document structure checker
 
 I validate and fix structural issues in modular AsciiDoc documentation.
 
@@ -16,7 +16,7 @@ Before starting, read these files in `references/`:
 - `TEMPLATE_PROCEDURE.adoc` - Canonical procedure module structure
 - `TEMPLATE_REFERENCE.adoc` - Canonical reference module structure
 
-## 1. File Preparation
+## 1. File preparation
 
 The user provides a path to `master.adoc`.
 
@@ -26,11 +26,11 @@ The user provides a path to `master.adoc`.
 1. Open `master.adoc` and identify all `include::` files recursively
 2. Create `adoc-file-list.txt` with discovered file paths, one per line
 
-## 2. Files to Exclude
+## 2. Files to exclude
 
-Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snippet_*.adoc`, files in `common/` directory.
+Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snip_*.adoc`, files in `common/` directory.
 
-## 3. Execution Workflow
+## 3. Execution workflow
 
 1. **Read** the reference files in `references/` to understand the rules
 2. **Read** `adoc-file-list.txt` to get the file manifest
@@ -40,7 +40,7 @@ Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snippet_*.adoc`, files in
 6. **Flag** issues needing human decision (see below)
 7. **Summarize** changes made and issues flagged
 
-## 4. What to Fix vs Flag
+## 4. What to fix vs flag
 
 **Fix automatically:**
 - Prerequisites using ordered lists → convert to unordered
@@ -57,13 +57,7 @@ Skip: `_attributes*.adoc`, `_title-attributes.adoc`, `snippet_*.adoc`, files in
 - Procedure modules with multiple `.Procedure` blocks
 - Block titles not in the allowed list
 
-## 5. RHEL 10 Conventions
-
-- NO module type prefixes in filenames (no `con_`, `proc_`, `ref_`)
-- NO context prefixes in IDs
-- Determine module type by `:_mod-docs-content-type:`, not filename
-
-## 6. Output Format
+## 6. Output format
 
 ```
 === Structure Check Summary ===
diff --git a/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md b/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md
index 5c4a7d04538..17bc393765f 100644
--- a/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md	
+++ b/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md	
@@ -4,8 +4,9 @@
 
 * Has :\_mod-docs-content-type: \<TYPE\>, where  \<TYPE\> is ASSEMBLY, CONCEPT, REFERENCE, or PROCEDURE.  
 * Has a topic ID in the following format:  
-  \[id="\<file-name\>\_{context}"\]  
-  	For OCP: \[\_{context}"\] does not belong in Assemblies.  
+  \[id="\<file-name-with-underscores\>\_{context}"\]  
+  \[id="\<file-name-with-underscores\>\"\]  
+  Add "_{context}" only if it was part of the ID before. Do not add "_{context}" to IDs that did not already include it.
     
 * Has one and only one level 0 (=) title (H1) title  
 * Has a short introduction  
@@ -32,7 +33,7 @@
 
 * Does not contain an instruction (imperative statement).  
 * Does not contain a level 2 (===) section title (H3) or lower..  
-* Does not contain block titles, except .Additional references or .Next steps. Note that .Next steps will not be mapped to \<related-links\>, .Additional resources will.
+* Does not contain block titles, except .Additional references or .Next steps.
 
 **Procedure module:**
 
@@ -40,11 +41,9 @@
 * Includes only one .Procedure block title and list.  
 * Does not contain embellishments of .Procedure, for example .Procedure for installing X.  
 * Does not contain content following the last step of the procedure except the optional sections in the order listed:  
-  \* Prerequisites or Prerequisite  
-  \* Procedure  
-  \* Verification, Results, or Result  
-  \* Troubleshooting, Troubleshooting steps, or Troubleshooting step  
-  \* Next steps or Next step  
+  \* Verification
+  \* Troubleshooting
+  \* Next steps
   \* Additional resources  
     
 * Does not contain any other block titles. 
diff --git a/.claude/skills/short-description-expert/SKILL.md b/.claude/skills/short-description-expert/SKILL.md
index 4b927f883f5..88e1c67dbf5 100644
--- a/.claude/skills/short-description-expert/SKILL.md
+++ b/.claude/skills/short-description-expert/SKILL.md
@@ -3,11 +3,11 @@ name: short-description-expert
 description: Recursively maps AsciiDoc includes from master.adoc, audits every module's short description for content quality, and rewrites abstracts that don't meet the "What and Why" formula. Processes files in batches of 50 with progress tracking.
 ---
 
-# Short Description Expert
+# Short description expert
 
 I am a specialist in managing documentation pipelines and writing DITA/AsciiDoc short descriptions. I map document structures, evaluate existing abstracts for quality, and ensure all abstracts provide immediate user value.
 
-## 1. File Preparation Workflow
+## 1. File preparation workflow
 The user provides a path to `master.adoc`. Check if artifacts already exist:
 
 **If `_short-desc-progress.md` exists:** A previous run was interrupted or is in progress. Read it to determine:
@@ -24,7 +24,7 @@ Resume from where the previous run left off. Skip to Section 8 (Execution Workfl
 2.  **Manifest Creation**: Create `adoc-file-list.txt` containing only the discovered file paths, one per line, no additional text.
 3.  **Linting**: Run `xargs vale --output line < adoc-file-list.txt > vale-output.txt`.
 
-## 2. Files to Exclude from Abstract Auditing
+## 2. Files to exclude from abstract auditing
 The following file types do not require abstracts — skip them entirely:
 - Assembly files: `assembly_*.adoc` — in this repository, assemblies do not carry their own abstract. The introduction and short description live in the first included concept module.
 - Attribute files: `attributes*.adoc`, `_title-attributes.adoc`
@@ -33,7 +33,7 @@ The following file types do not require abstracts — skip them entirely:
 
 Focus abstract auditing exclusively on module files (`con_*.adoc`, `proc_*.adoc`, `ref_*.adoc`).
 
-## 3. Short Description Content Formula
+## 3. Short description content formula
 Every short description must follow this customer-centric pattern:
 - **What**: State the action or feature clearly.
 - **Why**: State the business value, benefit, or goal.
@@ -42,15 +42,15 @@ Every short description must follow this customer-centric pattern:
   - "To [goal], configure [feature]"
   - "[Action] [what] to [why]"
 
-## 4. Structural Constraints
+## 4. Structural constraints
 - **Paragraphs**: Exactly one single paragraph.
 - **Length**: 1-2 simple sentences; between 50-300 characters, maximum ~50 words.
 - **Placement**: This must be the very first paragraph of the topic, immediately after the title.
 - **No Admonitions**: Never place a Note, Warning, or Important box before the short description.
 - **Doesn't end with a colon**: Must be a self-contained paragraph, not introduce a list.
 
-## 5. Style & Tone
-- **Voice**: Active Voice, present tense. No "allows you to" or "This section covers...".
+## 5. Style and tone
+- **Voice**: Active voice, present tense. No "allows you to" or "This section covers...".
 - **Product Names**: Use AsciiDoc attributes (`{Project}`, `{SmartProxy}`, etc.) — never hard-code product names.
 - **No Repetition**: Do not simply repeat the title; build upon it.
 - **No Self-Referential Language**: Avoid phrases like:
@@ -60,29 +60,29 @@ Every short description must follow this customer-centric pattern:
   - "The examples below..."
   - Any variation that references the document structure itself
 
-## 6. Examples of Preferred Rewrites
+## 6. Examples of preferred rewrites
 
 | Title | Preferred Short Description |
 | :--- | :--- |
 | Creating a group and adding a system | Group many systems together in the Edge Management application to manage them more easily. For example, you can more easily mitigate vulnerabilities and update systems that are alike. |
 | Browsing hosts in Satellite Web UI | Find and categorize your hosts within {Project} to get a quick overview of your managed infrastructure. Browsing hosts helps you understand your environment and identify specific host types for targeted actions. |
-| Cloning Hosts | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
-| Editing System Purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |
+| Cloning hosts | Clone existing hosts in {Project} to quickly create new hosts with similar configurations. This streamlines deployment processes and improves consistency across your environment. |
+| Editing system purpose | Edit the system purpose attributes for your Red Hat Enterprise Linux hosts to help ensure they receive correct subscriptions and accurate reporting. This optimizes license compliance and management. |
 
-## 7. Batch Processing and Progress Tracking
+## 7. Batch processing and progress tracking
 
 When the file list contains more than 50 files requiring fixes, process in batches:
 
-### Batch Size
+### Batch size
 - **Default batch size**: 50 files
 - Process one batch at a time, then pause for user confirmation before continuing
 
-### Progress File: `_short-desc-progress.md`
+### Progress file: `_short-desc-progress.md`
 Create this file when starting work on a large file list (>50 files). Update it after each batch.
 
 **Format:**
 ```markdown
-# Short Description Progress
+# Short description progress
 
 - **Last updated**: YYYY-MM-DD HH:MM
 - **Total files needing fixes**: [number]
@@ -90,15 +90,15 @@ Create this file when starting work on a large file list (>50 files). Update it
 - **Remaining**: [number] files
 - **Skipped**: [number] files (see list below)
 
-## Completed Batches
+## Completed batches
 - Batch 1: [number] files - YYYY-MM-DD
 - Batch 2: [number] files - YYYY-MM-DD
 
-## Skipped Files
+## Skipped files
 List files that were skipped and why (e.g., assembly file, attribute file):
 - `path/to/file.adoc` - Reason
 
-## Remaining Files
+## Remaining files
 List of files still needing processing:
 - `path/to/file1.adoc`
 - `path/to/file2.adoc`
@@ -110,7 +110,7 @@ Any user requests or special instructions (e.g., "User requested batches of 50")
 ### Cleanup
 Delete `_short-desc-progress.md` only when all files have been processed and the user confirms completion.
 
-## 8. Execution Workflow
+## 8. Execution workflow
 
 1.  **Check for Progress File**: If `_short-desc-progress.md` exists, read it and resume from the remaining files list. Otherwise, start fresh.
 

From 84d40eaac86c446113f7da112a0217cb942bbfa3 Mon Sep 17 00:00:00 2001
From: dvozenil <vozenilekd@gmail.com>
Date: Fri, 27 Mar 2026 14:14:34 +0100
Subject: [PATCH 3/5] Address review feedback: rename checklist, drop nested
 assembly context lines

- Rename checklist file to use underscores instead of spaces
- Update reference in SKILL.md to match new filename
- Remove nested assembly parent-context lines (assembly reuse is rare in this repo)

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/doc-structure-checker/SKILL.md            | 2 +-
 ...t.md => modular_documentation_templates_checklist.md} | 9 ---------
 2 files changed, 1 insertion(+), 10 deletions(-)
 rename .claude/skills/doc-structure-checker/references/{Modular documentation templates checklist.md => modular_documentation_templates_checklist.md} (80%)

diff --git a/.claude/skills/doc-structure-checker/SKILL.md b/.claude/skills/doc-structure-checker/SKILL.md
index 39d3e843921..bc4797dc97e 100644
--- a/.claude/skills/doc-structure-checker/SKILL.md
+++ b/.claude/skills/doc-structure-checker/SKILL.md
@@ -10,7 +10,7 @@ I validate and fix structural issues in modular AsciiDoc documentation.
 ## References
 
 Before starting, read these files in `references/`:
-- `Modular documentation templates checklist.md` - **Primary reference** for validation rules
+- `modular_documentation_templates_checklist.md` - **Primary reference** for validation rules
 - `TEMPLATE_ASSEMBLY.adoc` - Canonical assembly structure
 - `TEMPLATE_CONCEPT.adoc` - Canonical concept module structure
 - `TEMPLATE_PROCEDURE.adoc` - Canonical procedure module structure
diff --git a/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md b/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
similarity index 80%
rename from .claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md
rename to .claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
index 17bc393765f..15d22f3d956 100644
--- a/.claude/skills/doc-structure-checker/references/Modular documentation templates checklist.md	
+++ b/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
@@ -14,15 +14,6 @@
 * For any images, has alternative text descriptions enclosed in quotation marks ("")  
 * Admonitions do not include titles.
 
-**Nested assembly files:**
-
-* Contains the following conditional statement at the top of the document:  
-  ifdef::context\[:parent-context: {context}\]  
-* Contains the following conditional statement at the bottom of the document:  
-  ifdef::parent-context\[:context: {parent-context}\]  
-  ifndef::parent-context\[:\!context:\]  
-* Has the context variable declared and defined (:context: some-assembly).
-
 **All assembly files:**
 
 * Has a blank line between each include statement.  

From 9e16cd1166397b472af5898ba5872e575f35fbaf Mon Sep 17 00:00:00 2001
From: dvozenil <vozenilekd@gmail.com>
Date: Mon, 30 Mar 2026 16:13:25 +0200
Subject: [PATCH 4/5] Remove CLAUDE.md from repository

CLAUDE.md is a local Claude Code configuration file and should not be
tracked in the repository. It is excluded via .git/info/exclude locally.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 184 ------------------------------------------------------
 1 file changed, 184 deletions(-)
 delete mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 206fdd7ea55..00000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Repository Overview
-
-This is a documentation repository for the Foreman project and its downstream products (Katello, Satellite, orcharhino). Documentation is written in AsciiDoc and follows the [modular documentation framework](https://redhat-documentation.github.io/modular-docs/).
-
-## Build Commands
-
-### Prerequisites (macOS)
-
-```bash
-brew install ruby make
-echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
-# Then restart terminal and install gems:
-make prep
-```
-
-### Building guides
-
-```bash
-# Build a single guide (run from a doc-*/ subdirectory)
-make BUILD=foreman-el
-
-# Build all guides (run from guides/)
-make html
-
-# Build all guides for a specific target
-make BUILD=katello  # options: foreman-el (default), foreman-deb, katello, satellite, orcharhino
-
-# Open built guide in browser (from a doc-*/ subdirectory)
-make browser
-
-# Parallel build (recommended)
-make -j9
-
-# Clean build artifacts
-make clean
-```
-
-### Full site (root Makefile)
-
-```bash
-make serve         # builds everything and serves at http://localhost:5000
-make html          # builds all guide variants
-make web           # builds the static landing site
-PORT=5008 make serve  # use a custom port
-```
-
-### Container build (alternative)
-
-```bash
-podman build --tag foreman_documentation .
-rm -rf guides/build && podman run --rm -v $(pwd):/foreman-documentation foreman_documentation make html
-```
-
-### Vale linting
-
-Vale linting runs automatically in CI on PRs. To run locally:
-
-```bash
-vale guides/common/modules/your-file.adoc
-vale --config=.vale-dita.ini guides/common/modules/your-file.adoc
-```
-
-The Vale config at `.vale.ini` uses the `RedHat`, `AsciiDoc`, and `foreman-documentation` style packages.
-
-### Link checking
-
-```bash
-# Run from guides/ after building HTML
-make linkchecker
-```
-
-## Repository Structure
-
-```
-guides/
-  common/            # Shared content included by all guides
-    assembly_*.adoc  # Assemblies (user stories that include modules)
-    modules/         # Individual content modules
-      con_*.adoc     # Concept modules (what/why)
-      proc_*.adoc    # Procedure modules (how-to steps)
-      ref_*.adoc     # Reference modules (tables, lists)
-      snip_*.adoc    # Snippets (reusable admonitions, no ID)
-    attributes.adoc           # Version numbers, includes other attribute files
-    attributes-base.adoc      # Base attributes for all builds
-    attributes-foreman-el.adoc
-    attributes-foreman-deb.adoc
-    attributes-katello.adoc
-    attributes-satellite.adoc
-    attributes-orcharhino.adoc
-    attributes-titles.adoc
-  doc-*/             # Individual guides, each with:
-    master.adoc      # Top-level file for the guide
-    common -> ../common  (symlink)
-    images/
-    images/common -> ../common/images  (symlink)
-    Makefile         # includes ../common/Makefile
-  build/             # Generated HTML output (gitignored)
-web/                 # Static landing page (nanoc site)
-.vale/
-  styles/
-    foreman-documentation/  # Custom Vale rules
-    config/vocabularies/Foreman/  # accept.txt, reject.txt
-.vale.ini            # Vale configuration for AsciiDoc
-.vale-dita.ini       # Vale configuration for DITA structure checks
-```
-
-## Content Architecture
-
-### Multi-target builds
-
-The same source files build documentation for multiple products. **Never use product names directly** — always use AsciiDoc attributes:
-
-- `{Project}` — product name (Foreman, Satellite, orcharhino)
-- `{ProjectServer}`, `{SmartProxy}`, `{ProjectWebUI}` — component names
-- `{ProjectVersion}`, `{KatelloVersion}` — version numbers
-
-Build targets: `foreman-el`, `foreman-deb`, `foremanctl-katello`, `foremanctl-orcharhino`, `foremanctl-satellite`, `katello`, `satellite`, `orcharhino`
-
-### Conditional content
-
-```asciidoc
-ifdef::katello[]
-Content only for Katello builds.
-endif::[]
-
-ifndef::satellite[]
-Content for all builds except Satellite.
-endif::[]
-
-// Logic OR:
-ifdef::katello,satellite[]
-Content for Katello or Satellite builds.
-endif::[]
-```
-
-### Using attributes in code blocks
-
-```asciidoc
-[options="nowrap" subs="+quotes,attributes"]
-----
-# command {AttributeName}
-----
-```
-
-### Module file structure
-
-Each module file starts with a content-type attribute on line 1:
-
-```asciidoc
-:_mod-docs-content-type: CONCEPT
-[id="my-topic_{context}"]
-= My topic title
-```
-
-Snippets (`snip_`) must not contain an ID.
-
-## Cursor Commands (`.cursor/commands/`)
-
-These commands describe common refactoring patterns:
-
-- **`abstract.md`** — review/write short descriptions (50–300 chars, user-centric, no self-referential language)
-- **`refactor-adoc.md`** — rename a file, update its ID, title, and all `include::` references across the repo
-- **`split-web-ui-cli.md`** — split a procedure into separate web UI (`proc_*-by-using-web-ui.adoc`) and CLI (`proc_*-by-using-cli.adoc`) files
-
-## Writing Conventions
-
-- One sentence per line in source files.
-- Use underscores for variable user input: `hammer org create --name "_My_Organization_"`
-- No trailing whitespace.
-- UTF-8 encoding.
-- IDs use lowercase kebab-case: `[id="my-topic_{context}"]`
-- Surround variable parts of IDs with `_{context}` (appended by the include mechanism).
-- Web UI and CLI procedures for the same task are split into separate files named `proc_*-by-using-web-ui.adoc` and `proc_*-by-using-cli.adoc`.
-
-## Branching Model
-
-- `master` = nightly (current development)
-- `X.Y` branches = stable releases (e.g., `3.18`)
-- Versions are set in `guides/common/attributes.adoc` (`ProjectVersion`, `KatelloVersion`)
-- PR descriptions include a cherry-pick list indicating which versions the change applies to

From e87970b038fdad4ca3e7e023837ef6f1c9e2f36e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lena=20Ansorgov=C3=A1?= <zuansorg@redhat.com>
Date: Tue, 7 Apr 2026 16:52:49 +0200
Subject: [PATCH 5/5] Apply formatting suggestions from review

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>
---
 .claude/skills/cqa-reviewer/SKILL.md                           | 3 +++
 .../references/modular_documentation_templates_checklist.md    | 3 +--
 .claude/skills/short-description-expert/SKILL.md               | 1 +
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/cqa-reviewer/SKILL.md b/.claude/skills/cqa-reviewer/SKILL.md
index f5d8055ffa5..c5b5e5a23ab 100644
--- a/.claude/skills/cqa-reviewer/SKILL.md
+++ b/.claude/skills/cqa-reviewer/SKILL.md
@@ -105,6 +105,7 @@ xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
 ### RM-2. Review process
 
 #### RM-2.1 Compare Vale results
+
 1. Parse `vale-output.txt` (before) and `vale-output-post.txt` (after).
 2. Identify:
    - **Resolved issues**: Errors in "before" that are gone in "after"
@@ -114,6 +115,7 @@ xargs vale --output line < adoc-file-list.txt > vale-output-post.txt
 **Flag if:** New issues were introduced by the fixes.
 
 #### RM-2.2 Review changed files
+
 For each file with changes (via `git diff --name-only`):
 
 1. Read the diff to understand what changed.
@@ -134,6 +136,7 @@ For each file with changes (via `git diff --name-only`):
    - Added content that wasn't requested
 
 #### RM-2.3 Consistency check
+
 Across all changed files:
 - Terminology is consistent (same product names, feature names)
 - Short description style is consistent
diff --git a/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md b/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
index 15d22f3d956..c17eb5687d8 100644
--- a/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
+++ b/.claude/skills/doc-structure-checker/references/modular_documentation_templates_checklist.md
@@ -10,7 +10,7 @@
     
 * Has one and only one level 0 (=) title (H1) title  
 * Has a short introduction  
-* Has a blank line between the level 0 (=)  title and the short introduction  
+* Has a blank line between the level 0 (=) title and the short introduction  
 * For any images, has alternative text descriptions enclosed in quotation marks ("")  
 * Admonitions do not include titles.
 
@@ -38,4 +38,3 @@
   \* Additional resources  
     
 * Does not contain any other block titles. 
-
diff --git a/.claude/skills/short-description-expert/SKILL.md b/.claude/skills/short-description-expert/SKILL.md
index 88e1c67dbf5..94bd4a66223 100644
--- a/.claude/skills/short-description-expert/SKILL.md
+++ b/.claude/skills/short-description-expert/SKILL.md
@@ -8,6 +8,7 @@ description: Recursively maps AsciiDoc includes from master.adoc, audits every m
 I am a specialist in managing documentation pipelines and writing DITA/AsciiDoc short descriptions. I map document structures, evaluate existing abstracts for quality, and ensure all abstracts provide immediate user value.
 
 ## 1. File preparation workflow
+
 The user provides a path to `master.adoc`. Check if artifacts already exist:
 
 **If `_short-desc-progress.md` exists:** A previous run was interrupted or is in progress. Read it to determine: