Roadmap/TIME_TRACKING.md-14-14 (1)

14-14: Use headings instead of bold text for section labels

Markdownlint flags several bold lines used as headings (e.g., Line 14, Line 36, Line 54, Line 71, Line 88, Line 107, Line 124, Line 141, Line 158, Line 175, Line 194, Line 211). Converting them to proper heading levels will clear MD036.

✏️ Example fix (apply similarly to other lines)

-**Deliverables**:
+#### Deliverables

Also applies to: 36-36, 54-54, 71-71, 88-88, 107-107, 124-124, 141-141, 158-158, 175-175, 194-194, 211-211

packages/system/proxmox-csi/charts/proxmox-cloud-controller-manager/Chart.yaml-1-24 (1)

1-24: Remove manual Chart.yaml version bump and apply as patch instead

This vendored chart violates the chart vendoring policy. The Makefile's update target shows charts are downloaded fresh from upstream and modifications are applied via patches (currently only namespace.patch). However, the Chart.yaml version has been manually bumped to 0.3.0, while the upstream is at 0.2.11.

If you need a custom chart version locally, create a Chart.yaml patch file in patches/ instead of directly editing the vendored file. Alternatively, if this version bump should not be local, revert it to match the upstream version.

packages/system/capi-providers/docs/talos-proxmox-setup.md-141-142 (1)

141-142: Replace placeholder repository URLs

Lines 141 and 203 contain your-org placeholders that prevent copy-paste functionality. Update these to point to the actual CozyStack repository:

✏️ Suggested fixes

- git clone https://github.com/your-org/cozystack.git
+ git clone https://github.com/cozystack/cozystack.git
@@
-- [CozyStack Documentation](https://github.com/your-org/cozystack/docs)
+- [CozyStack Documentation](https://github.com/cozystack/cozystack/tree/main/docs)

packages/system/proxmox-csi/Makefile-1-4 (1)

1-4: Add .PHONY: update for explicit target declaration

The update target should be declared as phony. While the parent makefile app-helm.mk attempts to declare it, using .PHONY: update locally makes the intent explicit and uses correct Make syntax.

Proposed fix

 include ../../hack/app-helm.mk
+.PHONY: update

Roadmap/TESTING_RESULTS.md-65-66 (1)

65-66: Avoid “latest stable” wording in a dated test report.

Use “tested with Proxmox VE 9.0.10” to avoid future staleness.

✏️ Suggested wording

-**Result**: ✅ Proxmox VE 9.0.10 (latest stable, excellent compatibility)
+**Result**: ✅ Tested with Proxmox VE 9.0.10
...
-- **Proxmox VE 9.0.10** - Latest stable version
+- **Proxmox VE 9.0.10** - Tested version

Also applies to: 252-253

Roadmap/TESTING_RESULTS.md-103-109 (1)

103-109: Add language identifiers to fenced blocks (markdownlint MD040).

Several code fences don’t specify a language. Please add a language tag (e.g., text, yaml, bash) to keep markdownlint happy.

Also applies to: 148-153, 161-166, 169-174, 207-212, 296-302, 305-312, 314-324

Roadmap/COZYSTACK_UPGRADE_PLAN.md-216-229 (1)

216-229: kubectl apply -f Chart.yaml/values.yaml will fail.

Those files aren’t Kubernetes manifests. Use Helm directly or helm template + kubectl apply.

✅ Suggested fix

-# Apply updates
-kubectl apply -f Chart.yaml
-kubectl apply -f values.yaml
-
-# Or use Helm
-helm upgrade cozystack-platform . \
+# Use Helm
+helm upgrade cozystack-platform . \
   --namespace cozy-system \
   --values values.yaml \
   --wait --timeout=15m

packages/system/proxmox-csi/charts/proxmox-cloud-controller-manager/README.md.gotmpl-43-49 (1)

43-49: Fix example URL typo and CCM token name.

The example URL uses exmple.com (typo) and the token suffix csi in a CCM doc. Consider example.com and a CCM token suffix for clarity.

✏️ Suggested example fix

-    - url: https://cluster-api-1.exmple.com:8006/api2/json
+    - url: https://cluster-api-1.example.com:8006/api2/json
       insecure: false
-      token_id: "kubernetes@pve!csi"
+      token_id: "kubernetes@pve!ccm"
       token_secret: "key"

packages/system/proxmox-csi/charts/proxmox-cloud-controller-manager/ci/values.yaml-22-30 (1)

22-30: Use reserved example domains and explicit placeholder tokens.

exmple.com is a typo and can resolve to a real domain. Also, token_secret: "secret" can be misread as a real secret. Use example.com/.invalid and clear placeholders.

✏️ Suggested placeholders

-    - url: https://cluster-api-1.exmple.com:8006/api2/json
+    - url: https://cluster-api-1.example.com:8006/api2/json
       insecure: false
-      token_id: "user!token-id"
-      token_secret: "secret"
+      token_id: "<TOKEN_ID>"
+      token_secret: "<TOKEN_SECRET>"
       region: cluster-1

packages/system/proxmox-csi-node/Chart.yaml-1-2 (1)

1-2: Missing apiVersion field required for Helm 3.

While the naming convention is correct, the chart is missing the apiVersion field which is required for Helm 3 charts.

Suggested fix

+apiVersion: v2
 name: cozy-proxmox-csi-node
 version: 0.1.0
+description: Proxmox CSI Node Plugin

packages/system/proxmox-csi/Chart.yaml-1-2 (1)

1-2: Chart.yaml appears incomplete with placeholder values.

The chart uses a generic name app instead of a descriptive name like cozy-proxmox-csi, and is missing required fields for Helm 3:

• apiVersion (required, should be v2 for Helm 3)
• description (recommended)

Compare with the sibling chart proxmox-csi-node which uses cozy-proxmox-csi-node.

Suggested fix

+apiVersion: v2
-name: app
-version: 0.0.0
+name: cozy-proxmox-csi
+version: 0.1.0
+description: Proxmox CSI Plugin for Kubernetes

Based on learnings: "Use Helm Chart umbrella pattern with vendored upstream charts in charts/ directory" for packages/system/**.

packages/system/capi-providers/scripts/debug-proxmox-cluster.sh-63-70 (1)

63-70: Namespace mismatch when fetching machine logs.

The function retrieves machines from all namespaces (-A) but then attempts to fetch logs only from the default namespace. This will miss logs for machines deployed in other namespaces.

Proposed fix to preserve namespace context

 check_machine_logs() {
     debug_log "Checking machine logs..."
-    for machine in $(kubectl get machines -A -o jsonpath='{.items[*].metadata.name}'); do
+    kubectl get machines -A -o jsonpath='{range .items[*]}{.metadata.namespace}{" "}{.metadata.name}{"\n"}{end}' | while read -r ns machine; do
+        [ -z "$machine" ] && continue
         echo "=== Logs for machine $machine ==="
-        kubectl logs -n default -l cluster.x-k8s.io/machine-name=$machine --tail=100
+        kubectl logs -n "$ns" -l cluster.x-k8s.io/machine-name="$machine" --tail=100 2>/dev/null || echo "No logs found"
     done
 }

packages/system/proxmox-csi/charts/proxmox-cloud-controller-manager/README.md-47-47 (1)

47-47: Typo: "exmple.com" should be "example.com".

📝 Proposed fix

-    - url: https://cluster-api-1.exmple.com:8006/api2/json
+    - url: https://cluster-api-1.example.com:8006/api2/json

packages/system/capi-providers-proxmox/README.md-207-209 (1)

207-209: Update placeholder URLs to actual repository links.

The GitHub Issues URL contains a placeholder your-org that should be updated to the actual organization.

📝 Proposed fix

 ## Support
 
 - **Documentation**: https://docs.cozystack.io
-- **GitHub Issues**: https://github.com/your-org/cozystack/issues
+- **GitHub Issues**: https://github.com/cozystack/cozystack/issues
 - **Community**: https://community.cozystack.io

.github/workflows/ci.yml-41-45 (1)

41-45: Fix typo in step name.

"Build usig make" should be "Build using make".

Proposed fix

       - uses: actions/checkout@v3
-      - name: Build usig make
+      - name: Build using make
         run: |
           make

packages/system/capi-providers/docs/kube-ovn-cilium-setup.md-62-89 (1)

62-89: Remove duplicate keys in Kube-OVN ConfigMap example.

Lines 76-89 duplicate the keys from lines 62-75. In YAML, duplicate keys cause the second value to silently override the first. This appears to be a copy-paste error that will confuse users following the guide.

Proposed fix - remove duplicate lines 76-89

   default_vpc_subnet_pool_nat_outgoing: "true"
   default_vpc_subnet_pool_gateway_type: "distributed"
-  default_vpc_subnet_pool_allow_live_migration: "true"
-  default_vpc_subnet_pool_vlan_id: "0"
-  default_vpc_subnet_pool_vlan_range: "1,4095"
-  default_vpc_subnet_pool_u2o_interconnection: "false"
-  default_vpc_subnet_pool_logical_gateway: "false"
-  default_vpc_subnet_pool_gateway_check: "true"
-  default_vpc_subnet_pool_dns: "10.16.0.1"
-  default_vpc_subnet_pool_interface: "eth0"
-  default_vpc_subnet_pool_mtu: "1500"
-  default_vpc_subnet_pool_mac_address: ""
-  default_vpc_subnet_pool_dhcp_options: ""
-  default_vpc_subnet_pool_private: "false"
-  default_vpc_subnet_pool_nat_outgoing: "true"
-  default_vpc_subnet_pool_gateway_type: "distributed"

.github/workflows/lint.yml-27-31 (1)

27-31: Duplicate GITHUB_TOKEN environment variable.

GITHUB_TOKEN is defined twice in the env block (lines 27 and 31). The second definition is redundant and shadows the first. Remove the duplicate to avoid confusion.

Proposed fix

         env:
           # To report GitHub Actions status checks
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VALIDATE_ALL_CODEBASE: false  # Lint only changed files
           VALIDATE_TERRAFORM: false     # Disable Terraform linting (remove if you need it)
           DEFAULT_BRANCH: main          # Set your default branch
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           # Enable only the linters you need for your project
           VALIDATE_JAVASCRIPT_ES: true

packages/system/capi-providers/docs/kube-ovn-cilium-setup.md-162-177 (1)

162-177: Remove triplicate keys in Cilium ConfigMap example.

enable-hubble-metrics and hubble-metrics appear three times each (lines 162-165, 167-171, 173-177). Only the last occurrence takes effect. Remove the duplicates to avoid misleading users.

Proposed fix - keep only the first occurrence

   # Enable Hubble metrics server
   enable-hubble-metrics: "true"

   # List of metrics to enable
   hubble-metrics: "dns,drop,tcp,flow,port-distribution,icmp,http"
-
-  # Enable Hubble metrics server
-  enable-hubble-metrics: "true"
-
-  # List of metrics to enable
-  hubble-metrics: "dns,drop,tcp,flow,port-distribution,icmp,http"
-
-  # Enable Hubble metrics server
-  enable-hubble-metrics: "true"
-
-  # List of metrics to enable
-  hubble-metrics: "dns,drop,tcp,flow,port-distribution,icmp,http"

Roadmap/FINAL_TESTING_REPORT.md-26-31 (1)

26-31: Replace the bare URL with a Markdown link.

Line 27 trips MD034; wrap the URL in a link or angle brackets.

💡 Suggested fix

-1. ✅ API Connectivity - Accessible at https://10.0.0.1:8006
+1. ✅ API Connectivity - Accessible at <https://10.0.0.1:8006>

Roadmap/PROXMOX_INTEGRATION_RUNBOOK.md-598-602 (1)

598-602: Format the email as a mailto link (MD034).

Line 601 is treated as a bare URL.

💡 Suggested fix

-- **Email**: support@cozystack.io
+- **Email**: [support@cozystack.io](mailto:support@cozystack.io)

Roadmap/README.md-223-227 (1)

223-227: Convert the email to a mailto link (MD034).

Line 226 is flagged as a bare URL.

💡 Suggested fix

-- **Email**: support@cozystack.io
+- **Email**: [support@cozystack.io](mailto:support@cozystack.io)

Roadmap/FINAL_TESTING_REPORT.md-94-101 (1)

94-101: Add a language to fenced code blocks (MD040).

Line 94 starts a fenced block without a language. Please add a language tag and mirror this across the other fenced blocks in this document.

💡 Suggested fix (apply similarly to other blocks)

-```
+```text
 Host: 10.0.0.1
 Port: 8006
 Node Name: mgr
 Version: Proxmox VE 9.0.10
 OS: Debian GNU/Linux 13 (trixie)
 Kernel: 6.14.11-2-pve

</details>

</blockquote></details>
<details>
<summary>Roadmap/SPRINT_TIMELINE.md-13-16 (1)</summary><blockquote>

`13-16`: **Use headings instead of bold text for section titles.**

Line 14 triggers MD036. Consider promoting these “Phase …” lines to headings and apply the same change throughout the file.  
<details>
<summary>💡 Suggested fix</summary>

```diff
-**Phase 1.1: Current Infrastructure Analysis**
+#### Phase 1.1: Current Infrastructure Analysis

Roadmap/NEXCAGE_INTEGRATION.md-12-12 (1)

12-12: Wrap bare URLs in Markdown links (MD034).

✏️ Proposed fix

-**GitHub**: https://github.com/CageForge/nexcage
+**GitHub**: [https://github.com/CageForge/nexcage](https://github.com/CageForge/nexcage)
@@
-- **NexCage GitHub**: https://github.com/CageForge/nexcage
-- **LXC Documentation**: https://linuxcontainers.org/lxc/
-- **Proxmox LXC**: https://pve.proxmox.com/wiki/Linux_Container
-- **OCI Runtime Spec**: https://github.com/opencontainers/runtime-spec
-- **Kubernetes CRI**: https://kubernetes.io/docs/concepts/architecture/cri/
+- **NexCage GitHub**: [https://github.com/CageForge/nexcage](https://github.com/CageForge/nexcage)
+- **LXC Documentation**: [https://linuxcontainers.org/lxc/](https://linuxcontainers.org/lxc/)
+- **Proxmox LXC**: [https://pve.proxmox.com/wiki/Linux_Container](https://pve.proxmox.com/wiki/Linux_Container)
+- **OCI Runtime Spec**: [https://github.com/opencontainers/runtime-spec](https://github.com/opencontainers/runtime-spec)
+- **Kubernetes CRI**: [https://kubernetes.io/docs/concepts/architecture/cri/](https://kubernetes.io/docs/concepts/architecture/cri/)

Also applies to: 687-691

Roadmap/SESSION_SUMMARY.md-246-251 (1)

246-251: Add language identifiers to fenced blocks (MD040).

✏️ Proposed fix

-```
+```text
 Start (0%) → Planning (25%) → Recovery (50%) → Testing (75%) → Validation (85%) → Fixes (→100%)
                                                                       ▲
                                                                    YOU ARE HERE

...
- +text
Roadmap/
├── COMPLETE_ROADMAP.md ← Full roadmap
├── CURRENT_STATE_AND_FIXES.md ← What to do next
├── RECOVERY_SUCCESS.md ← How we fixed cluster
└── PROJECT_SUMMARY.md ← Executive summary
@@
tests/proxmox-integration/
├── run-integrity-checks.sh ← Run this to validate
├── integrity_checker.py ← Detailed checks
└── INTEGRITY_CHECKS.md ← Documentation

Also applies to: 351-362

Roadmap/EXTENDED_INTEGRATION_PLAN.md-297-300 (1)

297-300: Wrap the bare URL in a Markdown link (MD034).

✏️ Proposed fix

-**Project**: https://github.com/lxc/incus  
+**Project**: [https://github.com/lxc/incus](https://github.com/lxc/incus)  

Roadmap/SESSION_SUMMARY.md-380-381 (1)

380-381: Convert bare URLs to Markdown links (MD034).

✏️ Proposed fix

-- **PR**: https://github.com/cozystack/cozystack/pull/107
-- **Issue**: https://github.com/cozystack/cozystack/issues/69
+- **PR**: [https://github.com/cozystack/cozystack/pull/107](https://github.com/cozystack/cozystack/pull/107)
+- **Issue**: [https://github.com/cozystack/cozystack/issues/69](https://github.com/cozystack/cozystack/issues/69)

Roadmap/NEXCAGE_INTEGRATION.md-458-465 (1)

458-465: Add a language tag to the output snippet (MD040).

✏️ Proposed fix

-```
+```text
 systemctl status nexcage
 ● nexcage.service - failed to start

</details>

</blockquote></details>
<details>
<summary>Roadmap/WORK_COMPLETE_SUMMARY.md-308-313 (1)</summary><blockquote>

`308-313`: **Remove the stray trailing quote.**

It reads like an accidental character at the end of the doc.


<details>
<summary>✂️ Proposed fix</summary>

```diff
-**Status**: Excellent foundation for future work!
-
-The path forward is clear and well-documented! 🎉"
+**Status**: Excellent foundation for future work!
+
+The path forward is clear and well-documented! 🎉

Roadmap/NEXCAGE_INTEGRATION.md-31-70 (1)

31-70: Add a language tag to the ASCII diagram fence (MD040).

✏️ Proposed fix

-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                      Kubernetes Cluster                      │
 │                                                              │
@@
         │  │  LXC Containers     │   │
         │  │  /var/lib/lxc/      │   │
         │  └─────────────────────┘   │
         └─────────────────────────────┘

</details>

</blockquote></details>
<details>
<summary>Roadmap/PROXMOX_ARCHITECTURE.md-9-21 (1)</summary><blockquote>

`9-21`: **Add a language identifier to the architecture fences (MD040).**


<details>
<summary>✏️ Proposed fix</summary>

```diff
-```
+```text
 User → Kubernetes API → KubeVirt → QEMU/KVM (in pods) → Storage

@@
- +text
User → Kubernetes API → Cluster API → Proxmox API → Proxmox VMs
↓
Proxmox CSI → Proxmox Storage
↓
Proxmox CCM → Proxmox Networking

Roadmap/PROXMOX_ARCHITECTURE.md-231-333 (1)

231-333: Use proper headings instead of bold text (MD036).

✏️ Proposed fix

-**Method 1: Via Kubernetes App (Recommended)**
+#### Method 1: Via Kubernetes App (Recommended)

@@
-**Method 2: Direct ProxmoxMachine (Advanced)**
+#### Method 2: Direct ProxmoxMachine (Advanced)

@@
-**Option A: In LXC Containers** (Future, requires proxmox-lxcri)
+#### Option A: In LXC Containers (Future, requires proxmox-lxcri)

@@
-**Option B: In Proxmox VMs**
+#### Option B: In Proxmox VMs

@@
-**Option C: In Kubernetes Pods** (Default, current)
+#### Option C: In Kubernetes Pods (Default, current)

Roadmap/COMPLETE_ROADMAP.md-312-313 (1)

312-313: Timeline dates may need updating.

The "Revised Schedule" references "Sept 15-29, 2025" but the document is dated October 2025. Consider updating the timeline section to reflect current planning dates.

Roadmap/COMPLETE_ROADMAP.md-5-5 (1)

5-5: Date inconsistency between header and footer.

The header shows Last Updated: 2025-10-24 (line 5) while the footer shows Last Updated: 2025-10-13 23:30 (line 709). Please reconcile these dates.

🐛 Suggested fix

 **Last Updated**: 2025-10-24
 ...
-**Last Updated**: 2025-10-13 23:30
+**Last Updated**: 2025-10-24

Also applies to: 709-709

packages/system/capi-providers-proxmox/scripts/test-proxmox-cluster.sh-49-54 (1)

49-54: Pipeline with grep -q may not trigger set -e on failure.

When using set -e, a pipeline like kubectl get pods | grep -q may not cause the script to exit if grep fails (no match), because only the last command's exit status is checked by default. Consider using set -o pipefail or restructuring.

🐛 Proposed fix

 #!/bin/bash
 
 # Test script for Proxmox Cluster API integration
 
 set -e
+set -o pipefail

Or use a different pattern:

-    if kubectl get pods -n cozy-cluster-api | grep -q "cluster-api-operator"; then
+    if kubectl get pods -n cozy-cluster-api 2>/dev/null | grep -q "cluster-api-operator"; then

packages/system/capi-providers-proxmox/INTEGRATION.md-9-21 (1)

9-21: Add a language tag to the architecture diagram fence.
markdownlint flags this block (MD040). Use text for the ASCII diagram.

📝 Example fix

-```
+```text
┌─────────────────────────────────────────────────────────────────┐
│                    CozyStack CAPI Architecture                  │
├─────────────────────────────────────────────────────────────────┤
│  capi-operator                                                  │
│  ├── cozy-capi-providers-core (Core Provider)                  │
│  ├── cozy-capi-providers-bootstrap (Bootstrap Provider)        │
│  ├── cozy-capi-providers-cpprovider (Control Plane Provider)   │
│  └── cozy-capi-providers-infraprovider (Infrastructure Provider)│
│      ├── kubevirt (existing)                                   │
│      └── proxmox (new)                                         │
└─────────────────────────────────────────────────────────────────┘
-```
+```

Roadmap/ARCHITECTURE_FIX_SUMMARY.md-139-199 (1)

139-199: Add language identifiers to fenced code blocks.
markdownlint flags these fences (MD040). Please add text (or yaml where appropriate) to all unlabeled code blocks in this file.

📝 Example fix

-```
+```text
User Request
    ↓
Kubernetes API
    ↓
VirtualMachine CRD (apps.cozystack.io)
    ↓
HelmRelease
    ↓
Chart creates:
├── DataVolume (CDI)
├── PVC
├── VirtualMachine (kubevirt.io)
└── Service
    ↓
KubeVirt creates:
├── VirtualMachineInstance
└── virt-launcher Pod
    ↓
Pod runs QEMU/KVM
    ↓
VM runs inside pod
-```
+```

Roadmap/PROXMOX_VM_CREATION_GUIDE.md-19-26 (1)

19-26: Add language identifiers to the short fenced blocks.
markdownlint flags these fences (MD040). Use text for the flow snippets.

📝 Example fix

-```
+```text
User → kubectl apply → CAPI → capmox provider → Proxmox API → Proxmox VM
-```
+```
@@
-```
+```text
User → kubectl apply → KubeVirt → Pod → QEMU → VM  ❌
-```
+```

packages/system/capi-providers/docs/talos-proxmox-setup.md (1)

15-18: Pin Talos and CozyStack versions for reproducibility

Lines 17 and 135 use latest for version tags, which causes this guide to drift as upstream projects release new versions. Pin specific versions to ensure reproducibility and reduce maintenance burden when re-validating.

✏️ Suggested update

 1. Download the latest Talos Linux image for Proxmox:
 ```bash
+TALOS_VERSION=vX.Y.Z
-curl -LO https://github.com/siderolabs/talos/releases/latest/download/metal-amd64.raw.xz
+curl -LO https://github.com/siderolabs/talos/releases/download/${TALOS_VERSION}/metal-amd64.raw.xz

```diff
-export COZYSTACK_VERSION=latest
+export COZYSTACK_VERSION=vA.B.C

packages/system/proxmox-csi/charts/proxmox-cloud-controller-manager/ci/values.yaml (1)

1-4: Pin the CCM image for deterministic CI runs.

tag: edge plus pullPolicy: Always makes CI nondeterministic and can introduce flakiness. Prefer a fixed tag or digest for CI reproducibility.

✅ Example (pin to a version)

 image:
   repository: ghcr.io/sergelogvinov/proxmox-cloud-controller-manager
-  pullPolicy: Always
-  tag: edge
+  pullPolicy: IfNotPresent
+  tag: vX.Y.Z

Roadmap/PROXMOX_TESTING_PLAN.md (1)

373-375: Potential stale metadata.

The "Last Updated" date (2025-09-10) predates other documents in this PR (dated 2025-10-24). Consider updating to reflect the current state if this document has been modified recently.

Suggested update

-**Last Updated**: 2025-09-10  
+**Last Updated**: 2025-10-24  

Roadmap/UPGRADE_CRITICAL_FINDINGS.md (1)

24-34: Add language specifier to fenced code blocks.

Several fenced code blocks are missing language specifiers, which affects syntax highlighting and rendering. The static analysis flagged lines 24, 38, 68, 93, and 330.

Example fix for this block

-```
+```text
 Base Version: v0.28.0

Apply similar fixes to other unlabeled code blocks (lines 38, 68, 93, 330) using appropriate language identifiers (text, bash, or the relevant language).

Roadmap/UPGRADE_HEALTH_CHECK_REPORT.md (1)

24-30: Add language specifiers to fenced code blocks.

Similar to other documents in this PR, several code blocks lack language specifiers (lines 24, 44, 86, 108, 136, 159, 168, 180). Use text for output blocks or appropriate language identifiers.

Example fix

-```
+```text
 NAME           STATUS   ROLES           AGE    VERSION

Roadmap/UPGRADE_STATUS_FINAL.md (1)

54-57: Add language specifiers to code blocks for consistency.

Multiple code blocks in this document lack language identifiers. Consider using text for output/error messages and bash for shell commands to improve rendering.

packages/system/capi-providers/scripts/create-proxmox-cluster.sh (3)

24-39: Quote variables to prevent word splitting.

Variables used in kubectl commands should be quoted to prevent word splitting issues if values contain spaces or special characters.

Suggested fix

 check_provider_logs() {
     debug_log "Checking provider logs..."
     for namespace in capi-system capi-kubeadm-bootstrap-system capi-kubeadm-control-plane-system capi-proxmox-system; do
         echo "=== Logs from $namespace ==="
-        kubectl logs -n $namespace -l control-plane=controller-manager --tail=100
+        kubectl logs -n "$namespace" -l control-plane=controller-manager --tail=100
     done
 }
 
 check_machine_logs() {
     debug_log "Checking machine logs..."
     kubectl get machines -A -o wide
-    for machine in $(kubectl get machines -A -o jsonpath='{.items[*].metadata.name}'); do
+    while IFS= read -r machine; do
+        [ -z "$machine" ] && continue
         echo "=== Logs for machine $machine ==="
-        kubectl logs -n default -l cluster.x-k8s.io/machine-name=$machine --tail=100
+        kubectl logs -n default -l "cluster.x-k8s.io/machine-name=$machine" --tail=100
-    done
+    done < <(kubectl get machines -A -o jsonpath='{.items[*].metadata.name}' | tr ' ' '\n')
 }

---

64-70: Relative path may cause issues.

The template path templates/proxmox-examples.yaml is relative, which requires the script to be executed from a specific directory. Consider using SCRIPT_DIR to make the path relative to the script location.

Suggested fix

+# Get script directory for relative paths
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 # Process the manifests with environment variables
 debug_log "Processing manifests..."
-envsubst < templates/proxmox-examples.yaml > "$TEMP_DIR/processed-manifests.yaml"
+envsubst < "$SCRIPT_DIR/templates/proxmox-examples.yaml" > "$TEMP_DIR/processed-manifests.yaml"

---

77-84: Consider making cluster name configurable.

The cluster name proxmox-cluster is hardcoded. Consider making it configurable via an environment variable for flexibility across different deployments.

Suggested fix

+# Optional: default cluster name if not set
+CLUSTER_NAME="${CLUSTER_NAME:-proxmox-cluster}"
+
 echo "Waiting for cluster to be ready..."
-kubectl wait --for=condition=ready cluster/proxmox-cluster --timeout=300s || {
+kubectl wait --for=condition=ready "cluster/${CLUSTER_NAME}" --timeout=300s || {

packages/system/capi-providers/scripts/debug-proxmox-cluster.sh (2)

1-1: Consider adding bash strict mode options.

For debugging scripts that interact with cluster resources, adding set -euo pipefail helps catch errors early and prevents issues with undefined variables or failed commands silently continuing.

Suggested improvement

 #!/bin/bash
+set -euo pipefail
 
 # Colors for output

---

72-78: Secret lookup may fail without explicit namespace.

The proxmox-credentials secret namespace is not specified, which will default to the current context namespace. Consider specifying the expected namespace explicitly.

Suggested improvement

 check_proxmox_connection() {
     debug_log "Checking Proxmox connection..."
-    kubectl get secret proxmox-credentials -o jsonpath='{.data.url}' | base64 -d
+    kubectl get secret proxmox-credentials -n capi-proxmox-system -o jsonpath='{.data.url}' | base64 -d 2>/dev/null || echo "Secret not found"
     echo -e "\nChecking Proxmox provider pods..."
     kubectl get pods -n capi-proxmox-system -o wide
 }

packages/system/proxmox-csi/README.md (1)

5-6: Convert bare URLs to proper Markdown links.

Static analysis flags bare URLs. Using proper Markdown link syntax improves rendering consistency across different Markdown parsers.

Suggested fix

-- GitHub: https://github.com/sergelogvinov/proxmox-csi-plugin
-- Telegram: https://t.me/ru_talos
+- GitHub: <https://github.com/sergelogvinov/proxmox-csi-plugin>
+- Telegram: <https://t.me/ru_talos>

packages/system/capi-providers/docs/proxmox-csi-setup.md (1)

91-92: Avoid using :latest tag in documentation examples.

Using :latest in documentation examples can lead to non-reproducible deployments and unexpected behavior when the image is updated. Consider specifying a concrete version tag.

Suggested fix

-        image: proxmox/csi-driver:latest
+        image: ghcr.io/sergelogvinov/proxmox-csi-node:v0.9.0

packages/system/capi-providers/README.md (1)

24-35: Consider documenting a dedicated namespace for credentials.

The example creates the secret in the default namespace, which is not recommended for production deployments. Consider specifying a dedicated namespace (e.g., capi-proxmox-system or cozy-cluster-api) for better security isolation.

📝 Suggested improvement

 apiVersion: v1
 kind: Secret
 metadata:
   name: proxmox-credentials
-  namespace: default
+  namespace: capi-proxmox-system
 type: Opaque
 stringData:
   username: your-proxmox-username

.github/workflows/lint.yml (1)

18-21: Update actions/checkout to v4.

actions/checkout@v3 is outdated and may cause compatibility issues with newer GitHub Actions runners. Update to v4 for better support and security patches.

Proposed fix

       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0

Roadmap/INTEGRATION_COMPLETE.md (1)

20-21: Wrap bare URL in angle brackets for Markdown compliance.

The API endpoint URL should be enclosed in angle brackets to comply with Markdown standards (MD034).

Proposed fix

-   - API: https://10.0.0.40:6443
+   - API: <https://10.0.0.40:6443>

.github/workflows/ci.yml (2)

41-42: Update actions/checkout to v4.

actions/checkout@v3 is outdated. Update to v4 for better compatibility and security.

Proposed fix

-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4

---

34-40: Redundant REGISTRY override logic.

The conditional at line 36 checks GITHUB_ACTIONS, which is always "true" when running in GitHub Actions. This makes the else branch unreachable, and line 37 simply re-sets REGISTRY to the same value already defined at line 17. Consider removing this step or clarifying the intent if local execution support is needed.

Proposed fix - remove redundant step

-      - name: Set up Docker Registry
-        run: |
-          if [ "$GITHUB_ACTIONS" = "true" ]; then
-            echo "REGISTRY=ghcr.io/${{ github.repository_owner }}" >> $GITHUB_ENV
-          else
-            echo "REGISTRY=localhost:5000/cozystack_local" >> $GITHUB_ENV
-          fi
-
       - uses: actions/checkout@v4

If local execution support is intended, consider using a separate workflow or environment-specific inputs.

Roadmap/INITIAL_ASSESSMENT.md (1)

18-27: Add language specifiers to fenced code blocks.

The code blocks at lines 21-27 and 62-67 lack language identifiers. Adding text or bash improves readability and enables syntax highlighting in rendered Markdown.

Proposed fix for lines 21-27

 ### Node Status
-```
+```text
 NAME           STATUS   ROLES           AGE    VERSION
 mgr-cozy1      Ready    control-plane   208d   v1.32.3

Roadmap/PROXMOX_INTEGRATION_RUNBOOK.md (1)

98-106: Avoid embedding literal passwords in examples.

Line 99 (and other examples later) embeds a plaintext password; this encourages insecure copy‑paste. Consider using placeholders or environment variables and add a short note to source secrets from a manager.

💡 Suggested fix (apply similarly elsewhere)

-pveum user add k8s-api@pve --password 'secure-password'
+pveum user add k8s-api@pve --password "${PROXMOX_PASSWORD}"

Roadmap/FINAL_SESSION_REPORT.md (1)

171-179: Add language specifier to fenced code block.

The code block displaying integrity check results should have a language specifier for proper syntax highlighting.

📝 Suggested fix

-```
+```text
 Total Checks: 18
 Passed: 13 (72%)
 Failed: 2 (11%)
 Warnings: 3 (17%)
 Success Rate: 72%
 
 Status: ⚠️ DEGRADED (but functional)

</details>

</blockquote></details>
<details>
<summary>packages/system/capi-providers-proxmox/SUMMARY.md (1)</summary><blockquote>

`34-43`: **Add language specifier to fenced code blocks.**

The architecture diagram and file structure blocks should have a language specifier (e.g., `text`) for consistency with markdown linting rules.



<details>
<summary>📝 Suggested fix for architecture diagram (line 34)</summary>

```diff
-```
+```text
 CozyStack CAPI Architecture:
 ├── capi-operator
 ├── cozy-capi-providers-core
 ├── cozy-capi-providers-bootstrap  
 ├── cozy-capi-providers-cpprovider
 └── cozy-capi-providers-infraprovider
     ├── kubevirt (existing)
     └── proxmox (new) ← Added

</details>

<details>
<summary>📝 Suggested fix for file structure (line 92)</summary>

```diff
-```
+```text
 packages/system/capi-providers-proxmox/
 ├── Chart.yaml
 ...

</details>

</blockquote></details>
<details>
<summary>Roadmap/CURRENT_STATE_AND_FIXES.md (2)</summary><blockquote>

`90-117`: **Ensure placeholder token secrets are clearly marked.**

The example values file contains `<token-secret>` placeholders which is good. However, consider adding a clear warning comment to prevent accidental commits with real secrets.



<details>
<summary>📝 Suggested improvement</summary>

```diff
 # 3. Create values file
+# WARNING: Replace <token-secret> with actual token - never commit real secrets!
 cat > custom-values.yaml <<EOF
 proxmox-cloud-controller-manager:
   config:

---

347-355: Add language specifiers to fenced code blocks.

Several code blocks displaying status output lack language specifiers.

📝 Suggested fixes

Line 347:

-```
+```text
 Total Checks: 50

Line 468:

-```
+```text
 Integration Completion: 100%

Line 574:

-```text
 Current (85%) 
     ↓

Also applies to: 468-474, 574-592

Roadmap/VM_CREATION_TEST_RESULTS.md (2)

229-247: Add language specifiers to architecture diagram code blocks.

The architecture validation diagrams should have a text language specifier for consistency.

📝 Suggested fix

-```
+```text
 ✅ User → kubectl apply ProxmoxMachine
    ↓
 ✅ capmox controller detects resource

And similarly for line 244:

-```
+```text
 ❌ User → KubeVirt → Pod → QEMU → VM

---

254-272: Add language specifier to workflow diagram.

📝 Suggested fix

-```
+```text
 1. Create Cluster CRD
    ↓
 2. Create ProxmoxCluster (infrastructure)

Roadmap/UPGRADE_EXECUTION_LOG.md (1)

59-59: Consider generalizing local filesystem paths.

The path /home/moriarti/repo/cozystack/docs/changelogs/ is user-specific and may confuse others reading this document. Consider using a relative path or a placeholder like <repo-root>/docs/changelogs/.

Roadmap/CRITICAL_FIX_PROXMOX_BUNDLE.md (2)

114-134: Table formatting has structural issues.

The table contains rows with single cells used as section headers (lines 116, 122, 125, 127, 130), which breaks proper Markdown table structure. Consider using proper table rows with merged content or restructuring as separate subsection tables.

♻️ Suggested restructuring

Instead of inline section headers, split into separate tables:

-| Component | paas-full | paas-proxmox | Reason |
-|-----------|-----------|--------------|--------|
-| **VM Management** |
-| kubevirt-operator | ✅ | ❌ | Not needed with Proxmox |
+### VM Management
+
+| Component | paas-full | paas-proxmox | Reason |
+|-----------|-----------|--------------|--------|
+| kubevirt-operator | ✅ | ❌ | Not needed with Proxmox |

---

15-22: Add language specifiers to fenced code blocks.

The ASCII diagrams lack language specifiers. While these are diagrams rather than code, adding text or leaving them empty with triple backticks helps linters and renders consistently.

♻️ Example fix

-```
+```text
 User → K8s API → KubeVirt → Pod → QEMU/KVM → VM
-```
+```

packages/system/capi-providers-proxmox/scripts/test-proxmox-cluster.sh (2)

74-79: Relative path assumes specific working directory.

The path examples/proxmox-cluster.yaml is relative and assumes the script is executed from a specific directory. Consider using $SCRIPT_DIR to make the path relative to the script location.

♻️ Proposed fix

+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
 # Test cluster creation
 test_cluster_creation() {
     print_status "Testing cluster creation..."
     
     # Apply example cluster configuration
-    if kubectl apply -f examples/proxmox-cluster.yaml; then
+    if kubectl apply -f "${SCRIPT_DIR}/../examples/proxmox-cluster.yaml"; then
         print_status "Cluster configuration applied successfully."

---

128-129: Interactive read may block in CI/automated environments.

The read -p command will block indefinitely waiting for user input, which can cause issues in CI pipelines or automated testing. Consider adding a timeout or making this behavior conditional.

♻️ Proposed fix

-        read -p "Press Enter to cleanup test resources..."
+        if [[ -t 0 ]]; then
+            read -p "Press Enter to cleanup test resources..."
+        else
+            print_status "Non-interactive mode: waiting 30 seconds before cleanup..."
+            sleep 30
+        fi
         cleanup

Roadmap/FRESH_INSTALL_PLAN.md (1)

517-525: Consider documenting version verification for external downloads.

The Zig installation downloads from an external URL with a specific version. Consider adding a note about verifying checksums or using the official Zig package manager where available.

♻️ Example enhancement

 # Install Zig 0.15.1 (required for NexCage)
 cd /tmp
 wget https://ziglang.org/download/0.15.1/zig-linux-x86_64-0.15.1.tar.xz
+# Verify checksum (get from https://ziglang.org/download/)
+# echo "EXPECTED_SHA256  zig-linux-x86_64-0.15.1.tar.xz" | sha256sum -c -
 tar -xf zig-linux-x86_64-0.15.1.tar.xz

Roadmap/VM_CREATION_FINAL_REPORT.md (1)

19-25: Add language specifier to code block.

This code block showing VM list output would benefit from a language specifier for consistency.

♻️ Suggested fix

-```
+```text
 VMID 124: control-plane-template (stopped)
 VMID 201: ubuntu22-k8s-template (stopped)

Roadmap/COMPLETE_ROADMAP.md (1)

200-245: Add language specifier to ASCII diagram.

The architecture diagram code block would benefit from a text language specifier for consistent rendering.

Roadmap/SESSION_2025-10-24_SUMMARY.md (1)

112-115: Add language specifiers to fenced code blocks.

Several code blocks throughout this document lack language specifiers, which improves readability and enables syntax highlighting. Static analysis flagged blocks at lines 112, 143, 256, 265, 277, 288, and 417.

Example fix for this block:

-```
+```text
 /run/openvswitch/kube-ovn-daemon.sock: no such file or directory

packages/system/proxmox-csi-node/templates/deploy.yaml (1)

146-154: Using namespace as app label is unconventional.

The matchLabels and pod labels use {{ .Release.Namespace }} as the app value. Typically, this would be a descriptive app name (e.g., proxmox-csi-node) for better observability and to avoid conflicts if multiple releases exist.

♻️ Proposed fix

   selector:
     matchLabels:
-      app: {{ .Release.Namespace }}
+      app: proxmox-csi-node
   updateStrategy:
     type: RollingUpdate
   template:
     metadata:
       labels:
-        app: {{ .Release.Namespace }}
+        app: proxmox-csi-node