fix(security): fix markdown linting issues in documentation

- Wrap bare URLs in markdown link syntax
- Add language specifiers to code blocks (bash for commands)
- Convert bold emphasis to proper markdown headings
- Fix list formatting and indentation
- Correct grammar: 'grades is' -> 'grades are'

Addresses code review nitpick comments for security plugin docs.

Author: rafaelvzago

plugins/security/README.md

@@ -8,7 +8,7 @@ The Security plugin provides automated vulnerability grade assessment for contai
 
 **Key capabilities:**
 - **Container vulnerability grading** using Red Hat Pyxis API
-- **Multi-architecture support** (amd64, arm64, ppc64le, s390x)
+- - **Multi-architecture support** (amd64, arm64, ppc64le, s390x)
 - **Release-based tracking** for OSSM and other Red Hat products
 - **Automated reporting** with grade-focused summaries
 - **Corporate environment compatibility** with Kerberos authentication
@@ -91,7 +91,7 @@ Summary: 2 repositories | Grades: 1×B, 1×C
 ### Prerequisites
 
 1. **Container Grade Reporter Tool**
-   - Clone from: https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter
+   - Clone from: [container-grade-reporter](https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter)
    - Requires Red Hat internal network access
 
 2. **Kerberos Authentication**
@@ -106,7 +106,7 @@ Summary: 2 repositories | Grades: 1×B, 1×C
 
 ### Setup
 
-**Step 1: Install Security Plugin**
+#### Step 1: Install Security Plugin
 
 ```bash
 # Add ai-helpers marketplace
@@ -116,22 +116,22 @@ Summary: 2 repositories | Grades: 1×B, 1×C
 /plugin install security@ai-helpers
 ```
 
-**Step 2: Clone Container Grade Reporter**
+#### Step 2: Clone Container Grade Reporter
 
 ```bash
 # Clone to your preferred location
 cd ~/Code
 git clone https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter.git
 ```
 
-**Step 3: Configure Tool Path**
+#### Step 3: Configure Tool Path
 
 ```bash
 # Set the tool location
 /security:set-image-grade-tool-path ~/Code/container-grade-reporter
 ```
 
-**Step 4: Verify Keytab**
+#### Step 4: Verify Keytab
 
 Ensure your keytab file is available:
 ```bash
@@ -302,12 +302,14 @@ The vulnerability grading system uses Red Hat's A-F scale:
 The plugin displays architecture information for each container image:
 
 **Grouped architectures** (when all have same grade/version):
+
 ```
 openshift-service-mesh/istio-cni-rhel9
   1.26 → Grade: B ✅ | v1.26.5 | amd64,arm64,ppc64le,s390x | End: 2025-08-22
 ```
 
 **Separate architectures** (when grades/versions differ):
+
 ```
 openshift-service-mesh/example-repo
   2.6 → Grade: B ✅ | v2.6.5 | amd64 | End: 2025-08-20
@@ -328,6 +330,7 @@ Error: Container Grade Reporter not found
 ```
 
 **Solutions:**
+
 1. Clone the repository: `git clone https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter.git`
 2. Configure path: `/security:set-image-grade-tool-path /path/to/container-grade-reporter`
 3. Or clone into workspace: `./container-grade-reporter/`
@@ -339,6 +342,7 @@ Error: Kerberos authentication failed
 ```
 
 **Solutions:**
+
 1. Verify keytab exists: `ls ~/ossm-report-sa.keytab`
 2. Check keytab is base64 encoded
 3. Test manual authentication: `kinit -kt ~/keytab your-principal@IPA.REDHAT.COM`
@@ -351,6 +355,7 @@ Error: Cannot connect to pyxis.engineering.redhat.com
 ```
 
 **Solutions:**
+
 1. Connect to Red Hat VPN
 2. Verify network access: `curl -k https://pyxis.engineering.redhat.com/v1/`
 3. Check proxy configuration
@@ -362,6 +367,7 @@ Error: Invalid YAML configuration file
 ```
 
 **Solutions:**
+
 1. Validate YAML syntax: `python -c "import yaml; yaml.safe_load(open('config.yaml'))"`
 2. Check indentation (use spaces, not tabs)
 3. Verify structure matches releases/components format
@@ -373,6 +379,7 @@ Error: Python 3.12 not found
 ```
 
 **Solutions:**
+
 1. Install Python 3.12: `sudo dnf install python3.12`
 2. Or use available Python 3.x (Makefile will fallback automatically)
 
@@ -465,10 +472,10 @@ Potential enhancements:
 
 ## Support
 
-- **Issues**: https://github.com/openshift-eng/ai-helpers/issues
+- **Issues**: [openshift-eng/ai-helpers/issues](https://github.com/openshift-eng/ai-helpers/issues)
 - **Documentation**: ai-helpers repository README and AGENTS.md
 - **Authentication**: Contact Red Hat IT for keytab and API access
-- **Tool Repository**: https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter
+- **Tool Repository**: [container-grade-reporter](https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter)
 
 ## License
 

plugins/security/commands/image-grades.md

@@ -67,13 +67,13 @@ The command uses the container-grade-reporter tool which must be installed and c
    ```
 
    **With `--email` (send email report):**
-   
+
    Without grade filter:
    ```bash
    cd <tool-path>
    make email CONFIG=<absolute-config-path>
    ```
-   
+
    With grade filter:
    ```bash
    cd <tool-path>
@@ -286,48 +286,48 @@ HTML report saved: /tmp/security-image-grades-20251110-154523/vulnerability_repo
 ## Examples
 
 1. **Generate report for OSSM releases**:
-   ```
+   ```bash
    /security:image-grades ~/ossm-releases.yaml
    ```
 
 2. **Generate report with specific configuration**:
-   ```
+   ```bash
    /security:image-grades ./configs/ossm-3.1.yaml
    ```
 
 3. **Generate report after setting tool path**:
-   ```
+   ```bash
    /security:set-image-grade-tool-path ~/Code/container-grade-reporter
    /security:image-grades ./my-releases.yaml
    ```
 
 4. **Filter by specific grade**:
-   ```
+   ```bash
    /security:image-grades ~/releases.yaml --grade b
    ```
 
 5. **Filter by multiple grades**:
-   ```
+   ```bash
    /security:image-grades ~/releases.yaml --grade c,d,f
    ```
 
 6. **Check for critical vulnerabilities only**:
-   ```
+   ```bash
    /security:image-grades ./configs/ossm-3.1.yaml --grade d,f
    ```
 
 7. **Send email report**:
-   ```
+   ```bash
    /security:image-grades ~/releases.yaml --email
    ```
 
 8. **Send filtered email report**:
-   ```
+   ```bash
    /security:image-grades ~/releases.yaml --grade c,d,f --email
    ```
 
 9. **Email only critical vulnerabilities to team**:
-   ```
+   ```bash
    /security:image-grades ./configs/ossm-3.1.yaml --grade d,f --email
    ```
 
@@ -340,7 +340,7 @@ HTML report saved: /tmp/security-image-grades-20251110-154523/vulnerability_repo
 
 - **$2**: Grade filter (optional)
   - Required: No
-  - Format: `--grade <grades>` where grades is a comma-separated list
+  - Format: `--grade <grades>` where grades are a comma-separated list
   - Valid grades: A, B, C, D, F (case-insensitive)
   - Examples: `--grade b`, `--grade c,d,f`, `--grade D,F`
   - When specified, only images with matching grades are displayed in simplified format

plugins/security/commands/set-image-grade-tool-path.md

@@ -75,17 +75,17 @@ Next steps:
 ## Examples
 
 1. **Configure tool path**:
-   ```
+   ```bash
    /security:set-image-grade-tool-path ~/Code/container-grade-reporter
    ```
 
 2. **Configure with absolute path**:
-   ```
+   ```bash
    /security:set-image-grade-tool-path /home/user/projects/container-grade-reporter
    ```
 
 3. **Configure workspace-relative path**:
-   ```
+   ```bash
    /security:set-image-grade-tool-path ./container-grade-reporter
    ```
 

plugins/security/skills/container-grade-reporter/SKILL.md

@@ -85,7 +85,7 @@ This saves the configuration to `~/.config/ai-helpers/security-config.json`:
 }
 ```
 
-**Alternative: Workspace-relative installation**
+### Alternative: Workspace-relative installation
 
 If you don't use `/security:set-image-grade-tool-path`, the `/security:image-grades` command will search:
 1. `./container-grade-reporter/` (current directory)
@@ -169,7 +169,7 @@ releases:
 /security:image-grades ~/my-config.yaml --grade d,f --email
 ```
 
-**Manual execution using Makefile:**
+### Manual execution using Makefile
 
 ```bash
 cd ~/Code/container-grade-reporter
@@ -306,7 +306,7 @@ print(f"Summary: {len(data)} repositories | Grades: {grade_summary}")
 
 ### Common Issues and Solutions
 
-**1. Authentication Failure**
+### 1. Authentication Failure
 
 ```
 Error: Kerberos authentication failed
@@ -319,7 +319,7 @@ Error: Kerberos authentication failed
 - Test manual kinit: `kinit -kt ~/keytab.keytab principal@IPA.REDHAT.COM`
 - Contact Red Hat IT for keytab issues
 
-**2. Network Connectivity**
+### 2. Network Connectivity
 
 ```
 Error: Cannot connect to pyxis.engineering.redhat.com
@@ -330,7 +330,7 @@ Error: Cannot connect to pyxis.engineering.redhat.com
 - Check network access: `curl -k https://pyxis.engineering.redhat.com/v1/`
 - Verify no proxy issues blocking API access
 
-**3. Python Version Issues**
+### 3. Python Version Issues
 
 ```
 Error: Python 3.12 not found
@@ -341,7 +341,7 @@ Error: Python 3.12 not found
 - Or let Makefile use available Python 3.x (it will fallback automatically)
 - Check Python version: `python3 --version`
 
-**4. Missing Dependencies**
+### 4. Missing Dependencies
 
 ```
 Error: ModuleNotFoundError: No module named 'yaml'
@@ -351,7 +351,7 @@ Error: ModuleNotFoundError: No module named 'yaml'
 - Let Makefile handle installation: `make install`
 - Or manual install: `pip install -r requirements.txt`
 
-**5. Invalid YAML Configuration**
+### 5. Invalid YAML Configuration
 
 ```
 Error: Invalid YAML syntax
@@ -362,7 +362,7 @@ Error: Invalid YAML syntax
 - Check indentation (use spaces, not tabs)
 - Verify structure matches releases/components format
 
-**6. Repository Not Found**
+### 6. Repository Not Found
 
 ```
 Warning: Repository not found: path/to/repo
@@ -475,9 +475,9 @@ make dry-run-email  # Generates HTML without sending
 
 ## References
 
-- **Repository**: https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter
-- **Pyxis API**: https://pyxis.engineering.redhat.com/v1/
-- **Red Hat Registry**: https://registry.access.redhat.com
+- **Repository**: [container-grade-reporter](https://gitlab.cee.redhat.com/istio/servicemesh-qe/container-grade-reporter)
+- **Pyxis API**: [https://pyxis.engineering.redhat.com/v1/](https://pyxis.engineering.redhat.com/v1/)
+- **Red Hat Registry**: [https://registry.access.redhat.com](https://registry.access.redhat.com)
 - **Red Hat IT Support**: For keytab and authentication issues
 
 ## Notes