From 5ed196f8bff417c9997cbaaa2cd9ed83256b7adb Mon Sep 17 00:00:00 2001 From: rhartuv Date: Tue, 8 Sep 2026 11:33:54 +0300 Subject: [PATCH 1/2] chore: standardize skill documentation on references/ layout --- .../agentic-contribution-skill/SKILL.md | 48 ++--- .../{docs => references}/examples.md | 20 +- .../compass-manifest-maintenance/SKILL.md | 21 +- CONTRIBUTING.md | 1 + Makefile | 2 +- SKILL_DESIGN_PRINCIPLES.md | 11 +- ocp-admin/README.md | 54 ++--- ocp-admin/{docs => references}/SOURCES.md | 0 ocp-admin/skills/cluster-creator/SKILL.md | 58 ++--- .../docs/multi-cluster-auth.md | 1 - .../{docs => references}/INDEX.md | 0 .../{docs => references}/backup-restore.md | 0 .../certificate-management.md | 0 .../certificate-rotation.md | 0 .../credentials-management.md | 0 .../database-connection-management.md | 0 .../{docs => references}/day-2-operations.md | 0 .../{docs => references}/etcd-maintenance.md | 0 .../{docs => references}/examples.md | 0 .../{docs => references}/host-requirements.md | 0 .../{docs => references}/idp.md | 0 .../input-validation-guide.md | 0 .../references/multi-cluster-auth.md | 1 + .../{docs => references}/networking.md | 0 .../{docs => references}/platforms.md | 0 .../{docs => references}/providers.md | 0 .../pvc-capacity-planning.md | 0 .../{docs => references}/quick-reference.md | 0 .../{docs => references}/rbac.md | 0 .../security-checklist.md | 0 .../static-networking-guide.md | 2 +- .../{docs => references}/storage.md | 0 .../{docs => references}/troubleshooting.md | 0 ocp-admin/skills/cluster-inventory/SKILL.md | 8 +- .../skills/cluster-inventory/docs/INDEX.md | 1 - .../cluster-inventory/docs/backup-restore.md | 1 - .../docs/certificate-rotation.md | 1 - .../docs/credentials-management.md | 1 - .../docs/database-connection-management.md | 1 - .../docs/day-2-operations.md | 1 - .../docs/etcd-maintenance.md | 1 - .../skills/cluster-inventory/docs/examples.md | 1 - .../docs/host-requirements.md | 1 - .../skills/cluster-inventory/docs/idp.md | 1 - .../docs/input-validation-guide.md | 1 - .../docs/multi-cluster-auth.md | 1 - .../cluster-inventory/docs/networking.md | 1 - .../cluster-inventory/docs/platforms.md | 1 - .../cluster-inventory/docs/providers.md | 1 - .../docs/pvc-capacity-planning.md | 1 - .../cluster-inventory/docs/quick-reference.md | 1 - .../skills/cluster-inventory/docs/rbac.md | 1 - .../docs/security-checklist.md | 1 - .../docs/static-networking-guide.md | 1 - .../skills/cluster-inventory/docs/storage.md | 1 - .../cluster-inventory/docs/troubleshooting.md | 1 - .../cluster-inventory/references/INDEX.md | 1 + .../references/backup-restore.md | 1 + .../references/certificate-rotation.md | 1 + .../references/credentials-management.md | 1 + .../database-connection-management.md | 1 + .../references/day-2-operations.md | 1 + .../references/etcd-maintenance.md | 1 + .../cluster-inventory/references/examples.md | 1 + .../references/host-requirements.md | 1 + .../cluster-inventory/references/idp.md | 1 + .../references/input-validation-guide.md | 1 + .../references/multi-cluster-auth.md | 1 + .../references/networking.md | 1 + .../cluster-inventory/references/platforms.md | 1 + .../cluster-inventory/references/providers.md | 1 + .../references/pvc-capacity-planning.md | 1 + .../references/quick-reference.md | 1 + .../cluster-inventory/references/rbac.md | 1 + .../references/security-checklist.md | 1 + .../references/static-networking-guide.md | 1 + .../cluster-inventory/references/storage.md | 1 + .../references/troubleshooting.md | 1 + ocp-admin/skills/cluster-report/SKILL.md | 20 +- ocp-admin/skills/cluster-report/docs/INDEX.md | 1 - .../cluster-report/docs/backup-restore.md | 1 - .../docs/certificate-rotation.md | 1 - .../docs/credentials-management.md | 1 - .../docs/database-connection-management.md | 1 - .../cluster-report/docs/day-2-operations.md | 1 - .../cluster-report/docs/etcd-maintenance.md | 1 - .../skills/cluster-report/docs/examples.md | 1 - .../cluster-report/docs/host-requirements.md | 1 - ocp-admin/skills/cluster-report/docs/idp.md | 1 - .../docs/input-validation-guide.md | 1 - .../skills/cluster-report/docs/networking.md | 1 - .../skills/cluster-report/docs/platforms.md | 1 - .../skills/cluster-report/docs/providers.md | 1 - .../docs/pvc-capacity-planning.md | 1 - .../cluster-report/docs/quick-reference.md | 1 - ocp-admin/skills/cluster-report/docs/rbac.md | 1 - .../cluster-report/docs/security-checklist.md | 1 - .../docs/static-networking-guide.md | 1 - .../skills/cluster-report/docs/storage.md | 1 - .../cluster-report/docs/troubleshooting.md | 1 - .../skills/cluster-report/references/INDEX.md | 1 + .../references/backup-restore.md | 1 + .../references/certificate-rotation.md | 1 + .../references/credentials-management.md | 1 + .../database-connection-management.md | 1 + .../references/day-2-operations.md | 1 + .../references/etcd-maintenance.md | 1 + .../cluster-report/references/examples.md | 1 + .../references/host-requirements.md | 1 + .../skills/cluster-report/references/idp.md | 1 + .../references/input-validation-guide.md | 1 + .../multi-cluster-auth.md | 0 .../cluster-report/references/networking.md | 1 + .../cluster-report/references/platforms.md | 1 + .../cluster-report/references/providers.md | 1 + .../references/pvc-capacity-planning.md | 1 + .../references/quick-reference.md | 1 + .../skills/cluster-report/references/rbac.md | 1 + .../references/security-checklist.md | 1 + .../references/static-networking-guide.md | 1 + .../cluster-report/references/storage.md | 1 + .../references/troubleshooting.md | 1 + rh-ai-engineer/README.md | 4 +- .../skills/ai-observability/SKILL.md | 4 +- .../docs/references/known-model-profiles.md | 1 - .../docs/references/live-doc-lookup.md | 1 - .../docs/references/supported-runtimes.md | 1 - .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../references/supported-runtimes.md | 1 + .../skills/debug-inference/SKILL.md | 4 +- .../docs/references/known-model-profiles.md | 1 - .../docs/references/live-doc-lookup.md | 1 - .../docs/references/supported-runtimes.md | 1 - .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../references/supported-runtimes.md | 1 + .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- rh-ai-engineer/skills/model-deploy/SKILL.md | 14 +- .../docs/references/live-doc-lookup.md | 1 - .../docs/references/supported-runtimes.md | 1 - .../model-deploy/references/common-issues.md | 184 +++++++++++++++- .../examples/model-deploy.md | 0 .../references/known-model-profiles.md | 0 .../references/live-doc-lookup.md | 107 +++++++++- .../references/supported-runtimes.md | 1 + .../model-monitor/references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- rh-ai-engineer/skills/nim-setup/SKILL.md | 8 +- .../docs/references/supported-runtimes.md | 1 - .../nim-setup/references/common-issues.md | 184 +++++++++++++++- .../examples/nim-setup.md | 0 .../references/known-model-profiles.md | 1 + .../nim-setup/references/live-doc-lookup.md | 107 +++++++++- .../references/supported-runtimes.md | 1 + .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../skills/references/common-issues.md | 2 +- .../skills/serving-runtime-config/SKILL.md | 6 +- .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../references/supported-runtimes.md | 0 .../references/common-issues.md | 184 +++++++++++++++- .../references/known-model-profiles.md | 1 + .../references/live-doc-lookup.md | 107 +++++++++- .../docs/.ai-index/cross-reference-graph.json | 64 ------ .../docs/.ai-index/semantic-index.json | 101 --------- .../docs/.ai-index/task-to-docs-mapping.json | 73 ------- rh-automation/docs/INDEX.md | 46 ---- rh-automation/docs/SOURCES.md | 200 ------------------ .../skills/execution-risk-analyzer/SKILL.md | 6 +- .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../{docs => references}/aap/README.md | 0 .../aap/execution-governance.md | 2 +- .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/execution-summary/SKILL.md | 8 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/forensic-troubleshooter/SKILL.md | 10 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/governance-assessor/SKILL.md | 4 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../references/sample-full-assessment.md | 4 +- .../references/sample-scoped-assessment.md | 4 +- .../skills/governance-executor/SKILL.md | 4 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../governance-readiness-assessor/SKILL.md | 6 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../aap/governance-readiness.md | 2 +- .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/governed-job-launcher/SKILL.md | 6 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/host-fact-inspector/SKILL.md | 6 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 1 + .../skills/job-failure-analyzer/SKILL.md | 6 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/references/error-classification.md | 1 - .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../aap/job-troubleshooting.md | 6 +- .../references/error-classification.md | 1 + .../skills/resolution-advisor/SKILL.md | 10 +- .../docs/aap/execution-governance.md | 1 - .../docs/aap/governance-readiness.md | 1 - .../docs/aap/job-troubleshooting.md | 1 - .../{docs => }/references/README.md | 0 .../references/aap/execution-governance.md | 1 + .../references/aap/governance-readiness.md | 1 + .../references/aap/job-troubleshooting.md | 1 + .../references/error-classification.md | 12 +- rh-developer/.catalog/collection.json | 14 +- rh-developer/.catalog/collection.yaml | 14 +- .../skills/containerize-deploy/SKILL.md | 14 +- .../docs/builder-images.md | 1 - .../docs/debugging-patterns.md | 1 - .../docs/human-in-the-loop.md | 1 - .../docs/image-selection-criteria.md | 1 - .../containerize-deploy/docs/prerequisites.md | 1 - .../docs/python-s2i-entrypoints.md | 1 - .../docs/rhel-deployment.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/builder-images.md | 1 + .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../references/image-selection-criteria.md | 1 + .../references/prerequisites.md | 1 + .../references/python-s2i-entrypoints.md | 1 + .../references/rhel-deployment.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-build/SKILL.md | 12 +- .../skills/debug-build/docs/builder-images.md | 1 - .../debug-build/docs/human-in-the-loop.md | 1 - .../skills/debug-build/docs/prerequisites.md | 1 - .../docs/python-s2i-entrypoints.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../debug-build/references/builder-images.md | 1 + .../debugging-patterns.md | 0 .../references/human-in-the-loop.md | 1 + .../debug-build/references/prerequisites.md | 1 + .../references/python-s2i-entrypoints.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-container/SKILL.md | 10 +- .../docs/debugging-patterns.md | 1 - .../debug-container/docs/human-in-the-loop.md | 1 - .../debug-container/docs/prerequisites.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-network/SKILL.md | 8 +- .../debug-network/docs/debugging-patterns.md | 1 - .../debug-network/docs/human-in-the-loop.md | 1 - .../debug-network/docs/prerequisites.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../debug-network/references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-pipeline/SKILL.md | 8 +- .../debug-pipeline/docs/debugging-patterns.md | 1 - .../debug-pipeline/docs/human-in-the-loop.md | 1 - .../debug-pipeline/docs/prerequisites.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-pod/SKILL.md | 8 +- .../debug-pod/docs/debugging-patterns.md | 1 - .../debug-pod/docs/human-in-the-loop.md | 1 - .../skills/debug-pod/docs/prerequisites.md | 1 - .../debug-pod/docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../debug-pod/references/human-in-the-loop.md | 1 + .../debug-pod/references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-rbac/SKILL.md | 6 +- .../debug-rbac/docs/debugging-patterns.md | 1 - .../skills/debug-rbac/docs/prerequisites.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../debug-rbac/references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-rhel/SKILL.md | 12 +- .../debug-rhel/docs/debugging-patterns.md | 1 - .../debug-rhel/docs/human-in-the-loop.md | 1 - .../skills/debug-rhel/docs/prerequisites.md | 1 - .../skills/debug-rhel/docs/rhel-deployment.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../debug-rhel/references/prerequisites.md | 1 + .../debug-rhel/references/rhel-deployment.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/debug-scc/SKILL.md | 6 +- .../debug-scc/docs/debugging-patterns.md | 1 - .../skills/debug-scc/docs/prerequisites.md | 1 - .../debug-scc/docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../debug-scc/references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/deploy/SKILL.md | 6 +- .../skills/deploy/docs/debugging-patterns.md | 1 - .../skills/deploy/docs/human-in-the-loop.md | 1 - .../skills/deploy/docs/prerequisites.md | 1 - .../deploy/docs/selinux-troubleshooting.md | 1 - .../deploy/references/debugging-patterns.md | 1 + .../deploy/references/human-in-the-loop.md | 1 + .../skills/deploy/references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/detect-project/SKILL.md | 8 +- .../detect-project/docs/human-in-the-loop.md | 1 - .../detect-project/docs/prerequisites.md | 1 - .../{docs => references}/builder-images.md | 0 .../references/human-in-the-loop.md | 1 + .../references/prerequisites.md | 1 + .../python-s2i-entrypoints.md | 0 rh-developer/skills/helm-deploy/SKILL.md | 8 +- .../skills/helm-deploy/docs/builder-images.md | 1 - .../helm-deploy/docs/human-in-the-loop.md | 1 - .../docs/image-selection-criteria.md | 1 - .../skills/helm-deploy/docs/prerequisites.md | 1 - .../helm-deploy/references/builder-images.md | 1 + .../references/human-in-the-loop.md | 1 + .../references/image-selection-criteria.md | 1 + .../helm-deploy/references/prerequisites.md | 1 + rh-developer/skills/incident-triage/SKILL.md | 6 +- .../docs/debugging-patterns.md | 1 - .../incident-triage/docs/prerequisites.md | 1 - .../docs/selinux-troubleshooting.md | 1 - .../references/debugging-patterns.md | 1 + .../references/prerequisites.md | 1 + .../references/selinux-troubleshooting.md | 1 + rh-developer/skills/recommend-image/SKILL.md | 16 +- .../recommend-image/docs/builder-images.md | 1 - .../recommend-image/docs/human-in-the-loop.md | 1 - .../recommend-image/docs/prerequisites.md | 1 - .../references/builder-images.md | 1 + .../dynamic-validation.md | 0 .../references/human-in-the-loop.md | 1 + .../image-selection-criteria.md | 0 .../references/prerequisites.md | 1 + rh-developer/skills/rhel-deploy/SKILL.md | 16 +- .../rhel-deploy/docs/debugging-patterns.md | 1 - .../rhel-deploy/docs/human-in-the-loop.md | 1 - .../skills/rhel-deploy/docs/prerequisites.md | 1 - .../references/debugging-patterns.md | 1 + .../references/human-in-the-loop.md | 1 + .../rhel-deploy/references/prerequisites.md | 1 + .../{docs => references}/rhel-deployment.md | 0 .../selinux-troubleshooting.md | 0 rh-developer/skills/s2i-build/SKILL.md | 10 +- .../skills/s2i-build/docs/builder-images.md | 1 - .../s2i-build/docs/debugging-patterns.md | 1 - .../s2i-build/docs/human-in-the-loop.md | 1 - .../skills/s2i-build/docs/prerequisites.md | 1 - .../s2i-build/docs/python-s2i-entrypoints.md | 1 - .../s2i-build/docs/selinux-troubleshooting.md | 1 - .../s2i-build/references/builder-images.md | 1 + .../references/debugging-patterns.md | 1 + .../s2i-build/references/human-in-the-loop.md | 1 + .../s2i-build/references/prerequisites.md | 1 + .../references/python-s2i-entrypoints.md | 1 + .../references/selinux-troubleshooting.md | 1 + .../skills/validate-environment/SKILL.md | 8 +- .../{docs => references}/human-in-the-loop.md | 2 +- .../{docs => references}/prerequisites.md | 0 rh-sre/.catalog/collection.json | 14 +- rh-sre/.catalog/collection.yaml | 14 +- .../.ai-index/cross-reference-graph.json | 0 .../.ai-index/semantic-index.json | 0 .../.ai-index/task-to-docs-mapping.json | 0 rh-sre/{docs => references}/INDEX.md | 0 rh-sre/{docs => references}/SOURCES.md | 2 +- rh-sre/skills/cve-impact/SKILL.md | 28 +-- rh-sre/skills/cve-impact/docs/SOURCES.md | 1 - .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../cve-impact/docs/ansible/error-handling.md | 1 - .../cve-impact/docs/ansible/idempotency.md | 1 - .../docs/insights/fleet-management.md | 1 - .../cve-impact/docs/insights/insights-api.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../docs/references/skill-invocation.md | 1 - .../docs/rhel/package-management.md | 1 - .../cve-impact/docs/rhel/selinux-context.md | 1 - .../cve-impact/docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../references/05-error-handling.md | 2 +- .../{docs => }/references/README.md | 2 +- .../skills/cve-impact/references/SOURCES.md | 1 + .../references/ansible/aap-integration.md | 1 + .../ansible/cve-remediation-templates.md | 1 + .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../references/compliance-frameworks.md | 1 + .../cve-impact/references/cvss-scoring.md | 1 + .../references/flows/01-account-cves.md | 6 +- .../references/flows/02-system-all-cves.md | 8 +- .../flows/03-system-remediatable-cves.md | 8 +- .../references/insights/fleet-management.md | 1 + .../references/insights/insights-api.md | 1 + .../insights/vulnerability-logic.md | 1 + .../references/lightspeed-mcp-parameters.md | 0 .../lightspeed-mcp-tool-failures.md | 0 .../references/rhel/package-management.md | 1 + .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + .../cve-impact/references/skill-invocation.md | 1 + rh-sre/skills/cve-validation/SKILL.md | 16 +- .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../docs/ansible/error-handling.md | 1 - .../docs/ansible/idempotency.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/skill-invocation.md | 1 - .../docs/rhel/package-management.md | 1 - .../docs/rhel/selinux-context.md | 1 - .../docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../references/ansible/aap-integration.md | 1 + .../ansible/cve-remediation-templates.md | 1 + .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../references/compliance-frameworks.md | 1 + .../{docs => }/references/cvss-scoring.md | 4 +- .../insights/vulnerability-logic.md | 6 +- .../references/rhel/package-management.md | 1 + .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + .../references/skill-invocation.md | 1 + rh-sre/skills/execution-summary/SKILL.md | 6 +- rh-sre/skills/fleet-inventory/SKILL.md | 12 +- .../references/03-output-templates.md | 2 +- .../insights/fleet-management.md | 0 .../insights/insights-api.md | 4 +- rh-sre/skills/mcp-aap-validator/SKILL.md | 2 +- .../docs/ansible/aap-job-execution.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../docs/ansible/playbook-integration-aap.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../docs/rhel/package-management.md | 1 - .../ansible/aap-integration.md | 0 .../references/ansible/aap-job-execution.md | 1 + .../ansible/cve-remediation-templates.md | 1 + .../ansible/error-handling.md | 0 .../ansible/idempotency.md | 0 .../ansible/playbook-integration-aap.md | 1 + .../references/compliance-frameworks.md | 0 .../references/cvss-scoring.md | 1 + .../insights/vulnerability-logic.md | 1 + .../references/rhel/package-management.md | 1 + .../rhel/selinux-context.md | 0 .../rhel/systemd-services.md | 0 .../rhel/version-compatibility.md | 0 .../testing/aap-integration-test-guide.md | 0 .../skills/mcp-lightspeed-validator/SKILL.md | 2 +- .../mcp-lightspeed-validator/docs/SOURCES.md | 1 - .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../docs/ansible/error-handling.md | 1 - .../docs/ansible/idempotency.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../docs/rhel/package-management.md | 1 - .../docs/rhel/selinux-context.md | 1 - .../docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../references/SOURCES.md | 1 + .../references/ansible/aap-integration.md | 1 + .../ansible/cve-remediation-templates.md | 1 + .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../references/compliance-frameworks.md | 1 + .../references/cvss-scoring.md | 1 + .../{docs => references}/insights/README.md | 0 .../insights/vulnerability-logic.md | 1 + .../references/rhel/package-management.md | 1 + .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + rh-sre/skills/playbook-executor/SKILL.md | 4 +- .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../docs/ansible/error-handling.md | 1 - .../docs/ansible/idempotency.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../docs/rhel/package-management.md | 1 - .../docs/rhel/selinux-context.md | 1 - .../docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../references/ansible/aap-integration.md | 1 + .../ansible/aap-job-execution.md | 0 .../ansible/cve-remediation-templates.md | 1 + .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../ansible/playbook-integration-aap.md | 0 .../references/compliance-frameworks.md | 1 + .../references/cvss-scoring.md | 1 + .../insights/vulnerability-logic.md | 1 + .../references/rhel/package-management.md | 1 + .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + rh-sre/skills/playbook-generator/SKILL.md | 4 +- .../skills/playbook-generator/docs/SOURCES.md | 1 - .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/error-handling.md | 1 - .../docs/ansible/idempotency.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../docs/rhel/selinux-context.md | 1 - .../docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../playbook-generator/references/SOURCES.md | 1 + .../{docs => references}/ansible/README.md | 0 .../references/ansible/aap-integration.md | 1 + .../ansible/cve-remediation-templates.md | 2 +- .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../references/compliance-frameworks.md | 1 + .../references/cvss-scoring.md | 1 + .../insights/vulnerability-logic.md | 1 + .../{docs => references}/rhel/README.md | 0 .../rhel/package-management.md | 0 .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + rh-sre/skills/remediation/SKILL.md | 12 +- .../docs/ansible/aap-integration.md | 1 - .../docs/ansible/cve-remediation-templates.md | 1 - .../docs/ansible/error-handling.md | 1 - .../remediation/docs/ansible/idempotency.md | 1 - .../docs/insights/vulnerability-logic.md | 1 - .../docs/references/compliance-frameworks.md | 1 - .../docs/references/cvss-scoring.md | 1 - .../lightspeed-mcp-tool-failures.md | 1 - .../docs/rhel/package-management.md | 1 - .../remediation/docs/rhel/selinux-context.md | 1 - .../remediation/docs/rhel/systemd-services.md | 1 - .../docs/rhel/version-compatibility.md | 1 - .../references/ansible/aap-integration.md | 1 + .../ansible/cve-remediation-templates.md | 1 + .../references/ansible/error-handling.md | 1 + .../references/ansible/idempotency.md | 1 + .../references/compliance-frameworks.md | 1 + .../remediation/references/cvss-scoring.md | 1 + .../insights/vulnerability-logic.md | 1 + .../lightspeed-mcp-tool-failures.md | 1 + .../references/rhel/package-management.md | 1 + .../references/rhel/selinux-context.md | 1 + .../references/rhel/systemd-services.md | 1 + .../references/rhel/version-compatibility.md | 1 + .../{docs => }/references/skill-invocation.md | 0 rh-virt/README.md | 2 +- .../.ai-index/semantic-index.json | 0 rh-virt/skills/vm-clone/SKILL.md | 10 +- rh-virt/skills/vm-clone/docs/README.md | 1 - rh-virt/skills/vm-clone/docs/SOURCES.md | 1 - .../vm-clone/docs/troubleshooting/INDEX.md | 1 - .../docs/troubleshooting/lifecycle-errors.md | 1 - .../docs/troubleshooting/network-errors.md | 1 - .../docs/troubleshooting/runtime-errors.md | 1 - .../docs/troubleshooting/scheduling-errors.md | 1 - .../docs/troubleshooting/storage-errors.md | 1 - rh-virt/skills/vm-clone/references/README.md | 1 + rh-virt/skills/vm-clone/references/SOURCES.md | 1 + .../references/troubleshooting/INDEX.md | 1 + .../troubleshooting/lifecycle-errors.md | 1 + .../troubleshooting/network-errors.md | 1 + .../troubleshooting/runtime-errors.md | 1 + .../troubleshooting/scheduling-errors.md | 1 + .../troubleshooting/storage-errors.md | 1 + rh-virt/skills/vm-create/SKILL.md | 12 +- rh-virt/skills/vm-create/docs/README.md | 1 - rh-virt/skills/vm-create/docs/SOURCES.md | 1 - .../vm-create/docs/troubleshooting/INDEX.md | 1 - .../docs/troubleshooting/lifecycle-errors.md | 1 - .../docs/troubleshooting/scheduling-errors.md | 1 - .../docs/troubleshooting/storage-errors.md | 1 - rh-virt/skills/vm-create/references/README.md | 1 + .../skills/vm-create/references/SOURCES.md | 1 + .../references/troubleshooting/INDEX.md | 1 + .../troubleshooting/lifecycle-errors.md | 1 + .../troubleshooting/network-errors.md | 0 .../troubleshooting/runtime-errors.md | 2 +- .../troubleshooting/scheduling-errors.md | 1 + .../troubleshooting/storage-errors.md | 1 + rh-virt/skills/vm-delete/SKILL.md | 14 +- .../vm-delete/docs/troubleshooting/INDEX.md | 1 - .../docs/troubleshooting/lifecycle-errors.md | 1 - .../docs/troubleshooting/network-errors.md | 1 - .../docs/troubleshooting/runtime-errors.md | 1 - .../docs/troubleshooting/scheduling-errors.md | 1 - .../docs/troubleshooting/storage-errors.md | 1 - .../vm-delete/{docs => references}/README.md | 0 .../vm-delete/{docs => references}/SOURCES.md | 0 .../references/troubleshooting/INDEX.md | 1 + .../troubleshooting/lifecycle-errors.md | 1 + .../troubleshooting/network-errors.md | 1 + .../troubleshooting/runtime-errors.md | 1 + .../troubleshooting/scheduling-errors.md | 1 + .../troubleshooting/storage-errors.md | 1 + rh-virt/skills/vm-lifecycle-manager/SKILL.md | 8 +- .../vm-lifecycle-manager/docs/README.md | 1 - .../vm-lifecycle-manager/docs/SOURCES.md | 1 - .../docs/troubleshooting/INDEX.md | 1 - .../docs/troubleshooting/lifecycle-errors.md | 1 - .../docs/troubleshooting/network-errors.md | 1 - .../docs/troubleshooting/runtime-errors.md | 1 - .../docs/troubleshooting/scheduling-errors.md | 1 - .../docs/troubleshooting/storage-errors.md | 1 - .../vm-lifecycle-manager/references/README.md | 1 + .../references/SOURCES.md | 1 + .../references/troubleshooting/INDEX.md | 1 + .../troubleshooting/lifecycle-errors.md | 1 + .../troubleshooting/network-errors.md | 1 + .../troubleshooting/runtime-errors.md | 1 + .../troubleshooting/scheduling-errors.md | 1 + .../troubleshooting/storage-errors.md | 1 + .../vm-rebalance/REBALANCE_AUTOMATIC.md | 10 +- .../skills/vm-rebalance/REBALANCE_MANUAL.md | 26 +-- rh-virt/skills/vm-rebalance/SKILL.md | 32 +-- rh-virt/skills/vm-rebalance/docs/README.md | 1 - rh-virt/skills/vm-rebalance/docs/SOURCES.md | 1 - .../docs/troubleshooting/network-errors.md | 1 - .../docs/troubleshooting/runtime-errors.md | 1 - .../skills/vm-rebalance/references/README.md | 1 + .../skills/vm-rebalance/references/SOURCES.md | 1 + .../live-migration-best-practices.md | 2 +- .../troubleshooting/INDEX.md | 0 .../troubleshooting/lifecycle-errors.md | 0 .../troubleshooting/network-errors.md | 1 + .../troubleshooting/runtime-errors.md | 1 + .../troubleshooting/scheduling-errors.md | 0 .../troubleshooting/storage-errors.md | 0 scripts/validate_compass_manifests.py | 114 +++++++++- scripts/validate_docs_tree_links.py | 8 +- scripts/validate_skill_doc_links.py | 28 ++- 712 files changed, 4015 insertions(+), 1202 deletions(-) rename .claude/skills/agentic-contribution-skill/{docs => references}/examples.md (91%) rename ocp-admin/{docs => references}/SOURCES.md (100%) delete mode 120000 ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md rename ocp-admin/skills/cluster-creator/{docs => references}/INDEX.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/backup-restore.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/certificate-management.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/certificate-rotation.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/credentials-management.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/database-connection-management.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/day-2-operations.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/etcd-maintenance.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/examples.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/host-requirements.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/idp.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/input-validation-guide.md (100%) create mode 120000 ocp-admin/skills/cluster-creator/references/multi-cluster-auth.md rename ocp-admin/skills/cluster-creator/{docs => references}/networking.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/platforms.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/providers.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/pvc-capacity-planning.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/quick-reference.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/rbac.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/security-checklist.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/static-networking-guide.md (99%) rename ocp-admin/skills/cluster-creator/{docs => references}/storage.md (100%) rename ocp-admin/skills/cluster-creator/{docs => references}/troubleshooting.md (100%) delete mode 120000 ocp-admin/skills/cluster-inventory/docs/INDEX.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/backup-restore.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/credentials-management.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/database-connection-management.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/day-2-operations.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/examples.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/host-requirements.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/idp.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/networking.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/platforms.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/providers.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/quick-reference.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/rbac.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/security-checklist.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/storage.md delete mode 120000 ocp-admin/skills/cluster-inventory/docs/troubleshooting.md create mode 120000 ocp-admin/skills/cluster-inventory/references/INDEX.md create mode 120000 ocp-admin/skills/cluster-inventory/references/backup-restore.md create mode 120000 ocp-admin/skills/cluster-inventory/references/certificate-rotation.md create mode 120000 ocp-admin/skills/cluster-inventory/references/credentials-management.md create mode 120000 ocp-admin/skills/cluster-inventory/references/database-connection-management.md create mode 120000 ocp-admin/skills/cluster-inventory/references/day-2-operations.md create mode 120000 ocp-admin/skills/cluster-inventory/references/etcd-maintenance.md create mode 120000 ocp-admin/skills/cluster-inventory/references/examples.md create mode 120000 ocp-admin/skills/cluster-inventory/references/host-requirements.md create mode 120000 ocp-admin/skills/cluster-inventory/references/idp.md create mode 120000 ocp-admin/skills/cluster-inventory/references/input-validation-guide.md create mode 120000 ocp-admin/skills/cluster-inventory/references/multi-cluster-auth.md create mode 120000 ocp-admin/skills/cluster-inventory/references/networking.md create mode 120000 ocp-admin/skills/cluster-inventory/references/platforms.md create mode 120000 ocp-admin/skills/cluster-inventory/references/providers.md create mode 120000 ocp-admin/skills/cluster-inventory/references/pvc-capacity-planning.md create mode 120000 ocp-admin/skills/cluster-inventory/references/quick-reference.md create mode 120000 ocp-admin/skills/cluster-inventory/references/rbac.md create mode 120000 ocp-admin/skills/cluster-inventory/references/security-checklist.md create mode 120000 ocp-admin/skills/cluster-inventory/references/static-networking-guide.md create mode 120000 ocp-admin/skills/cluster-inventory/references/storage.md create mode 120000 ocp-admin/skills/cluster-inventory/references/troubleshooting.md delete mode 120000 ocp-admin/skills/cluster-report/docs/INDEX.md delete mode 120000 ocp-admin/skills/cluster-report/docs/backup-restore.md delete mode 120000 ocp-admin/skills/cluster-report/docs/certificate-rotation.md delete mode 120000 ocp-admin/skills/cluster-report/docs/credentials-management.md delete mode 120000 ocp-admin/skills/cluster-report/docs/database-connection-management.md delete mode 120000 ocp-admin/skills/cluster-report/docs/day-2-operations.md delete mode 120000 ocp-admin/skills/cluster-report/docs/etcd-maintenance.md delete mode 120000 ocp-admin/skills/cluster-report/docs/examples.md delete mode 120000 ocp-admin/skills/cluster-report/docs/host-requirements.md delete mode 120000 ocp-admin/skills/cluster-report/docs/idp.md delete mode 120000 ocp-admin/skills/cluster-report/docs/input-validation-guide.md delete mode 120000 ocp-admin/skills/cluster-report/docs/networking.md delete mode 120000 ocp-admin/skills/cluster-report/docs/platforms.md delete mode 120000 ocp-admin/skills/cluster-report/docs/providers.md delete mode 120000 ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md delete mode 120000 ocp-admin/skills/cluster-report/docs/quick-reference.md delete mode 120000 ocp-admin/skills/cluster-report/docs/rbac.md delete mode 120000 ocp-admin/skills/cluster-report/docs/security-checklist.md delete mode 120000 ocp-admin/skills/cluster-report/docs/static-networking-guide.md delete mode 120000 ocp-admin/skills/cluster-report/docs/storage.md delete mode 120000 ocp-admin/skills/cluster-report/docs/troubleshooting.md create mode 120000 ocp-admin/skills/cluster-report/references/INDEX.md create mode 120000 ocp-admin/skills/cluster-report/references/backup-restore.md create mode 120000 ocp-admin/skills/cluster-report/references/certificate-rotation.md create mode 120000 ocp-admin/skills/cluster-report/references/credentials-management.md create mode 120000 ocp-admin/skills/cluster-report/references/database-connection-management.md create mode 120000 ocp-admin/skills/cluster-report/references/day-2-operations.md create mode 120000 ocp-admin/skills/cluster-report/references/etcd-maintenance.md create mode 120000 ocp-admin/skills/cluster-report/references/examples.md create mode 120000 ocp-admin/skills/cluster-report/references/host-requirements.md create mode 120000 ocp-admin/skills/cluster-report/references/idp.md create mode 120000 ocp-admin/skills/cluster-report/references/input-validation-guide.md rename ocp-admin/skills/cluster-report/{docs => references}/multi-cluster-auth.md (100%) create mode 120000 ocp-admin/skills/cluster-report/references/networking.md create mode 120000 ocp-admin/skills/cluster-report/references/platforms.md create mode 120000 ocp-admin/skills/cluster-report/references/providers.md create mode 120000 ocp-admin/skills/cluster-report/references/pvc-capacity-planning.md create mode 120000 ocp-admin/skills/cluster-report/references/quick-reference.md create mode 120000 ocp-admin/skills/cluster-report/references/rbac.md create mode 120000 ocp-admin/skills/cluster-report/references/security-checklist.md create mode 120000 ocp-admin/skills/cluster-report/references/static-networking-guide.md create mode 120000 ocp-admin/skills/cluster-report/references/storage.md create mode 120000 ocp-admin/skills/cluster-report/references/troubleshooting.md delete mode 120000 rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md delete mode 120000 rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md delete mode 120000 rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/ai-observability/references/common-issues.md create mode 120000 rh-ai-engineer/skills/ai-observability/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md create mode 120000 rh-ai-engineer/skills/ai-observability/references/supported-runtimes.md delete mode 120000 rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md delete mode 120000 rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md delete mode 120000 rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/debug-inference/references/common-issues.md create mode 120000 rh-ai-engineer/skills/debug-inference/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md create mode 120000 rh-ai-engineer/skills/debug-inference/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/ds-project-setup/references/common-issues.md create mode 120000 rh-ai-engineer/skills/ds-project-setup/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md mode change 120000 => 100644 rh-ai-engineer/skills/guardrails-config/references/common-issues.md create mode 120000 rh-ai-engineer/skills/guardrails-config/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md delete mode 120000 rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md delete mode 120000 rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/model-deploy/references/common-issues.md rename rh-ai-engineer/skills/model-deploy/{docs => references}/examples/model-deploy.md (100%) rename rh-ai-engineer/skills/model-deploy/{docs => }/references/known-model-profiles.md (100%) mode change 120000 => 100644 rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md create mode 120000 rh-ai-engineer/skills/model-deploy/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/model-monitor/references/common-issues.md create mode 120000 rh-ai-engineer/skills/model-monitor/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md mode change 120000 => 100644 rh-ai-engineer/skills/model-registry/references/common-issues.md create mode 120000 rh-ai-engineer/skills/model-registry/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md delete mode 120000 rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/nim-setup/references/common-issues.md rename rh-ai-engineer/skills/nim-setup/{docs => references}/examples/nim-setup.md (100%) create mode 120000 rh-ai-engineer/skills/nim-setup/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md create mode 120000 rh-ai-engineer/skills/nim-setup/references/supported-runtimes.md mode change 120000 => 100644 rh-ai-engineer/skills/pipeline-manage/references/common-issues.md create mode 120000 rh-ai-engineer/skills/pipeline-manage/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md mode change 120000 => 100644 rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md create mode 120000 rh-ai-engineer/skills/serving-runtime-config/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md rename rh-ai-engineer/skills/serving-runtime-config/{docs => }/references/supported-runtimes.md (100%) mode change 120000 => 100644 rh-ai-engineer/skills/workbench-manage/references/common-issues.md create mode 120000 rh-ai-engineer/skills/workbench-manage/references/known-model-profiles.md mode change 120000 => 100644 rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md delete mode 100644 rh-automation/docs/.ai-index/cross-reference-graph.json delete mode 100644 rh-automation/docs/.ai-index/semantic-index.json delete mode 100644 rh-automation/docs/.ai-index/task-to-docs-mapping.json delete mode 100644 rh-automation/docs/INDEX.md delete mode 100644 rh-automation/docs/SOURCES.md delete mode 120000 rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md rename rh-automation/skills/execution-risk-analyzer/{docs => references}/aap/README.md (100%) rename rh-automation/skills/execution-risk-analyzer/{docs => references}/aap/execution-governance.md (99%) create mode 120000 rh-automation/skills/execution-risk-analyzer/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/execution-risk-analyzer/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/execution-risk-analyzer/references/error-classification.md delete mode 120000 rh-automation/skills/execution-summary/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/execution-summary/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/execution-summary/docs/references/error-classification.md create mode 120000 rh-automation/skills/execution-summary/references/aap/execution-governance.md create mode 120000 rh-automation/skills/execution-summary/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/execution-summary/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/execution-summary/references/error-classification.md delete mode 120000 rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md create mode 120000 rh-automation/skills/forensic-troubleshooter/references/aap/execution-governance.md create mode 120000 rh-automation/skills/forensic-troubleshooter/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/forensic-troubleshooter/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/forensic-troubleshooter/references/error-classification.md delete mode 120000 rh-automation/skills/governance-assessor/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/governance-assessor/docs/references/error-classification.md create mode 120000 rh-automation/skills/governance-assessor/references/aap/execution-governance.md create mode 120000 rh-automation/skills/governance-assessor/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/governance-assessor/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/governance-assessor/references/error-classification.md delete mode 120000 rh-automation/skills/governance-executor/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/governance-executor/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/governance-executor/docs/references/error-classification.md create mode 120000 rh-automation/skills/governance-executor/references/aap/execution-governance.md create mode 120000 rh-automation/skills/governance-executor/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/governance-executor/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/governance-executor/references/error-classification.md delete mode 120000 rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md create mode 120000 rh-automation/skills/governance-readiness-assessor/references/aap/execution-governance.md rename rh-automation/skills/governance-readiness-assessor/{docs => references}/aap/governance-readiness.md (99%) create mode 120000 rh-automation/skills/governance-readiness-assessor/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/governance-readiness-assessor/references/error-classification.md delete mode 120000 rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/governed-job-launcher/docs/references/error-classification.md create mode 120000 rh-automation/skills/governed-job-launcher/references/aap/execution-governance.md create mode 120000 rh-automation/skills/governed-job-launcher/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/governed-job-launcher/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/governed-job-launcher/references/error-classification.md delete mode 120000 rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md delete mode 120000 rh-automation/skills/host-fact-inspector/docs/references/error-classification.md create mode 120000 rh-automation/skills/host-fact-inspector/references/aap/execution-governance.md create mode 120000 rh-automation/skills/host-fact-inspector/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/host-fact-inspector/references/aap/job-troubleshooting.md create mode 120000 rh-automation/skills/host-fact-inspector/references/error-classification.md delete mode 120000 rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md create mode 120000 rh-automation/skills/job-failure-analyzer/references/aap/execution-governance.md create mode 120000 rh-automation/skills/job-failure-analyzer/references/aap/governance-readiness.md rename rh-automation/skills/job-failure-analyzer/{docs => references}/aap/job-troubleshooting.md (98%) create mode 120000 rh-automation/skills/job-failure-analyzer/references/error-classification.md delete mode 120000 rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md delete mode 120000 rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md delete mode 120000 rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md rename rh-automation/skills/resolution-advisor/{docs => }/references/README.md (100%) create mode 120000 rh-automation/skills/resolution-advisor/references/aap/execution-governance.md create mode 120000 rh-automation/skills/resolution-advisor/references/aap/governance-readiness.md create mode 120000 rh-automation/skills/resolution-advisor/references/aap/job-troubleshooting.md rename rh-automation/skills/resolution-advisor/{docs => }/references/error-classification.md (95%) delete mode 120000 rh-developer/skills/containerize-deploy/docs/builder-images.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/prerequisites.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/rhel-deployment.md delete mode 120000 rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/containerize-deploy/references/builder-images.md create mode 120000 rh-developer/skills/containerize-deploy/references/debugging-patterns.md create mode 120000 rh-developer/skills/containerize-deploy/references/human-in-the-loop.md create mode 120000 rh-developer/skills/containerize-deploy/references/image-selection-criteria.md create mode 120000 rh-developer/skills/containerize-deploy/references/prerequisites.md create mode 120000 rh-developer/skills/containerize-deploy/references/python-s2i-entrypoints.md create mode 120000 rh-developer/skills/containerize-deploy/references/rhel-deployment.md create mode 120000 rh-developer/skills/containerize-deploy/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-build/docs/builder-images.md delete mode 120000 rh-developer/skills/debug-build/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-build/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md delete mode 120000 rh-developer/skills/debug-build/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-build/references/builder-images.md rename rh-developer/skills/debug-build/{docs => references}/debugging-patterns.md (100%) create mode 120000 rh-developer/skills/debug-build/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-build/references/prerequisites.md create mode 120000 rh-developer/skills/debug-build/references/python-s2i-entrypoints.md create mode 120000 rh-developer/skills/debug-build/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-container/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-container/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-container/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-container/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-container/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-container/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-container/references/prerequisites.md create mode 120000 rh-developer/skills/debug-container/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-network/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-network/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-network/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-network/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-network/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-network/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-network/references/prerequisites.md create mode 120000 rh-developer/skills/debug-network/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-pipeline/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-pipeline/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-pipeline/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-pipeline/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-pipeline/references/prerequisites.md create mode 120000 rh-developer/skills/debug-pipeline/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-pod/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-pod/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-pod/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-pod/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-pod/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-pod/references/prerequisites.md create mode 120000 rh-developer/skills/debug-pod/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-rbac/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-rbac/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-rbac/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-rbac/references/prerequisites.md create mode 120000 rh-developer/skills/debug-rbac/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-rhel/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-rhel/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/debug-rhel/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-rhel/docs/rhel-deployment.md delete mode 120000 rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-rhel/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-rhel/references/human-in-the-loop.md create mode 120000 rh-developer/skills/debug-rhel/references/prerequisites.md create mode 120000 rh-developer/skills/debug-rhel/references/rhel-deployment.md create mode 120000 rh-developer/skills/debug-rhel/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/debug-scc/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/debug-scc/docs/prerequisites.md delete mode 120000 rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/debug-scc/references/debugging-patterns.md create mode 120000 rh-developer/skills/debug-scc/references/prerequisites.md create mode 120000 rh-developer/skills/debug-scc/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/deploy/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/deploy/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/deploy/docs/prerequisites.md delete mode 120000 rh-developer/skills/deploy/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/deploy/references/debugging-patterns.md create mode 120000 rh-developer/skills/deploy/references/human-in-the-loop.md create mode 120000 rh-developer/skills/deploy/references/prerequisites.md create mode 120000 rh-developer/skills/deploy/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/detect-project/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/detect-project/docs/prerequisites.md rename rh-developer/skills/detect-project/{docs => references}/builder-images.md (100%) create mode 120000 rh-developer/skills/detect-project/references/human-in-the-loop.md create mode 120000 rh-developer/skills/detect-project/references/prerequisites.md rename rh-developer/skills/detect-project/{docs => references}/python-s2i-entrypoints.md (100%) delete mode 120000 rh-developer/skills/helm-deploy/docs/builder-images.md delete mode 120000 rh-developer/skills/helm-deploy/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/helm-deploy/docs/image-selection-criteria.md delete mode 120000 rh-developer/skills/helm-deploy/docs/prerequisites.md create mode 120000 rh-developer/skills/helm-deploy/references/builder-images.md create mode 120000 rh-developer/skills/helm-deploy/references/human-in-the-loop.md create mode 120000 rh-developer/skills/helm-deploy/references/image-selection-criteria.md create mode 120000 rh-developer/skills/helm-deploy/references/prerequisites.md delete mode 120000 rh-developer/skills/incident-triage/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/incident-triage/docs/prerequisites.md delete mode 120000 rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/incident-triage/references/debugging-patterns.md create mode 120000 rh-developer/skills/incident-triage/references/prerequisites.md create mode 120000 rh-developer/skills/incident-triage/references/selinux-troubleshooting.md delete mode 120000 rh-developer/skills/recommend-image/docs/builder-images.md delete mode 120000 rh-developer/skills/recommend-image/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/recommend-image/docs/prerequisites.md create mode 120000 rh-developer/skills/recommend-image/references/builder-images.md rename rh-developer/skills/recommend-image/{docs => references}/dynamic-validation.md (100%) create mode 120000 rh-developer/skills/recommend-image/references/human-in-the-loop.md rename rh-developer/skills/recommend-image/{docs => references}/image-selection-criteria.md (100%) create mode 120000 rh-developer/skills/recommend-image/references/prerequisites.md delete mode 120000 rh-developer/skills/rhel-deploy/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/rhel-deploy/docs/prerequisites.md create mode 120000 rh-developer/skills/rhel-deploy/references/debugging-patterns.md create mode 120000 rh-developer/skills/rhel-deploy/references/human-in-the-loop.md create mode 120000 rh-developer/skills/rhel-deploy/references/prerequisites.md rename rh-developer/skills/rhel-deploy/{docs => references}/rhel-deployment.md (100%) rename rh-developer/skills/rhel-deploy/{docs => references}/selinux-troubleshooting.md (100%) delete mode 120000 rh-developer/skills/s2i-build/docs/builder-images.md delete mode 120000 rh-developer/skills/s2i-build/docs/debugging-patterns.md delete mode 120000 rh-developer/skills/s2i-build/docs/human-in-the-loop.md delete mode 120000 rh-developer/skills/s2i-build/docs/prerequisites.md delete mode 120000 rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md delete mode 120000 rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md create mode 120000 rh-developer/skills/s2i-build/references/builder-images.md create mode 120000 rh-developer/skills/s2i-build/references/debugging-patterns.md create mode 120000 rh-developer/skills/s2i-build/references/human-in-the-loop.md create mode 120000 rh-developer/skills/s2i-build/references/prerequisites.md create mode 120000 rh-developer/skills/s2i-build/references/python-s2i-entrypoints.md create mode 120000 rh-developer/skills/s2i-build/references/selinux-troubleshooting.md rename rh-developer/skills/validate-environment/{docs => references}/human-in-the-loop.md (97%) rename rh-developer/skills/validate-environment/{docs => references}/prerequisites.md (100%) rename rh-sre/{docs => references}/.ai-index/cross-reference-graph.json (100%) rename rh-sre/{docs => references}/.ai-index/semantic-index.json (100%) rename rh-sre/{docs => references}/.ai-index/task-to-docs-mapping.json (100%) rename rh-sre/{docs => references}/INDEX.md (100%) rename rh-sre/{docs => references}/SOURCES.md (99%) delete mode 120000 rh-sre/skills/cve-impact/docs/SOURCES.md delete mode 120000 rh-sre/skills/cve-impact/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/cve-impact/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/cve-impact/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/cve-impact/docs/insights/fleet-management.md delete mode 120000 rh-sre/skills/cve-impact/docs/insights/insights-api.md delete mode 120000 rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/cve-impact/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/cve-impact/docs/references/skill-invocation.md delete mode 120000 rh-sre/skills/cve-impact/docs/rhel/package-management.md delete mode 120000 rh-sre/skills/cve-impact/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/cve-impact/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md rename rh-sre/skills/cve-impact/{docs => }/references/README.md (96%) create mode 120000 rh-sre/skills/cve-impact/references/SOURCES.md create mode 120000 rh-sre/skills/cve-impact/references/ansible/aap-integration.md create mode 120000 rh-sre/skills/cve-impact/references/ansible/cve-remediation-templates.md create mode 120000 rh-sre/skills/cve-impact/references/ansible/error-handling.md create mode 120000 rh-sre/skills/cve-impact/references/ansible/idempotency.md create mode 120000 rh-sre/skills/cve-impact/references/compliance-frameworks.md create mode 120000 rh-sre/skills/cve-impact/references/cvss-scoring.md create mode 120000 rh-sre/skills/cve-impact/references/insights/fleet-management.md create mode 120000 rh-sre/skills/cve-impact/references/insights/insights-api.md create mode 120000 rh-sre/skills/cve-impact/references/insights/vulnerability-logic.md rename rh-sre/skills/cve-impact/{docs => }/references/lightspeed-mcp-parameters.md (100%) rename rh-sre/skills/cve-impact/{docs => }/references/lightspeed-mcp-tool-failures.md (100%) create mode 120000 rh-sre/skills/cve-impact/references/rhel/package-management.md create mode 120000 rh-sre/skills/cve-impact/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/cve-impact/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/cve-impact/references/rhel/version-compatibility.md create mode 120000 rh-sre/skills/cve-impact/references/skill-invocation.md delete mode 120000 rh-sre/skills/cve-validation/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/cve-validation/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/cve-validation/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/cve-validation/docs/references/skill-invocation.md delete mode 120000 rh-sre/skills/cve-validation/docs/rhel/package-management.md delete mode 120000 rh-sre/skills/cve-validation/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/cve-validation/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md create mode 120000 rh-sre/skills/cve-validation/references/ansible/aap-integration.md create mode 120000 rh-sre/skills/cve-validation/references/ansible/cve-remediation-templates.md create mode 120000 rh-sre/skills/cve-validation/references/ansible/error-handling.md create mode 120000 rh-sre/skills/cve-validation/references/ansible/idempotency.md create mode 120000 rh-sre/skills/cve-validation/references/compliance-frameworks.md rename rh-sre/skills/cve-validation/{docs => }/references/cvss-scoring.md (98%) rename rh-sre/skills/cve-validation/{docs => references}/insights/vulnerability-logic.md (98%) create mode 120000 rh-sre/skills/cve-validation/references/rhel/package-management.md create mode 120000 rh-sre/skills/cve-validation/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/cve-validation/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/cve-validation/references/rhel/version-compatibility.md create mode 120000 rh-sre/skills/cve-validation/references/skill-invocation.md rename rh-sre/skills/fleet-inventory/{docs => references}/insights/fleet-management.md (100%) rename rh-sre/skills/fleet-inventory/{docs => references}/insights/insights-api.md (92%) delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md rename rh-sre/skills/mcp-aap-validator/{docs => references}/ansible/aap-integration.md (100%) create mode 120000 rh-sre/skills/mcp-aap-validator/references/ansible/aap-job-execution.md create mode 120000 rh-sre/skills/mcp-aap-validator/references/ansible/cve-remediation-templates.md rename rh-sre/skills/mcp-aap-validator/{docs => references}/ansible/error-handling.md (100%) rename rh-sre/skills/mcp-aap-validator/{docs => references}/ansible/idempotency.md (100%) create mode 120000 rh-sre/skills/mcp-aap-validator/references/ansible/playbook-integration-aap.md rename rh-sre/skills/mcp-aap-validator/{docs => }/references/compliance-frameworks.md (100%) create mode 120000 rh-sre/skills/mcp-aap-validator/references/cvss-scoring.md create mode 120000 rh-sre/skills/mcp-aap-validator/references/insights/vulnerability-logic.md create mode 120000 rh-sre/skills/mcp-aap-validator/references/rhel/package-management.md rename rh-sre/skills/mcp-aap-validator/{docs => references}/rhel/selinux-context.md (100%) rename rh-sre/skills/mcp-aap-validator/{docs => references}/rhel/systemd-services.md (100%) rename rh-sre/skills/mcp-aap-validator/{docs => references}/rhel/version-compatibility.md (100%) rename rh-sre/skills/mcp-aap-validator/{docs => references}/testing/aap-integration-test-guide.md (100%) delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/SOURCES.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/ansible/aap-integration.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/ansible/cve-remediation-templates.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/ansible/error-handling.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/ansible/idempotency.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/compliance-frameworks.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/cvss-scoring.md rename rh-sre/skills/mcp-lightspeed-validator/{docs => references}/insights/README.md (100%) create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/insights/vulnerability-logic.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/rhel/package-management.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/mcp-lightspeed-validator/references/rhel/version-compatibility.md delete mode 120000 rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/playbook-executor/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/playbook-executor/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/playbook-executor/docs/rhel/package-management.md delete mode 120000 rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md create mode 120000 rh-sre/skills/playbook-executor/references/ansible/aap-integration.md rename rh-sre/skills/playbook-executor/{docs => references}/ansible/aap-job-execution.md (100%) create mode 120000 rh-sre/skills/playbook-executor/references/ansible/cve-remediation-templates.md create mode 120000 rh-sre/skills/playbook-executor/references/ansible/error-handling.md create mode 120000 rh-sre/skills/playbook-executor/references/ansible/idempotency.md rename rh-sre/skills/playbook-executor/{docs => references}/ansible/playbook-integration-aap.md (100%) create mode 120000 rh-sre/skills/playbook-executor/references/compliance-frameworks.md create mode 120000 rh-sre/skills/playbook-executor/references/cvss-scoring.md create mode 120000 rh-sre/skills/playbook-executor/references/insights/vulnerability-logic.md create mode 120000 rh-sre/skills/playbook-executor/references/rhel/package-management.md create mode 120000 rh-sre/skills/playbook-executor/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/playbook-executor/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/playbook-executor/references/rhel/version-compatibility.md delete mode 120000 rh-sre/skills/playbook-generator/docs/SOURCES.md delete mode 120000 rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/playbook-generator/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/playbook-generator/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md create mode 120000 rh-sre/skills/playbook-generator/references/SOURCES.md rename rh-sre/skills/playbook-generator/{docs => references}/ansible/README.md (100%) create mode 120000 rh-sre/skills/playbook-generator/references/ansible/aap-integration.md rename rh-sre/skills/playbook-generator/{docs => references}/ansible/cve-remediation-templates.md (99%) create mode 120000 rh-sre/skills/playbook-generator/references/ansible/error-handling.md create mode 120000 rh-sre/skills/playbook-generator/references/ansible/idempotency.md create mode 120000 rh-sre/skills/playbook-generator/references/compliance-frameworks.md create mode 120000 rh-sre/skills/playbook-generator/references/cvss-scoring.md create mode 120000 rh-sre/skills/playbook-generator/references/insights/vulnerability-logic.md rename rh-sre/skills/playbook-generator/{docs => references}/rhel/README.md (100%) rename rh-sre/skills/playbook-generator/{docs => references}/rhel/package-management.md (100%) create mode 120000 rh-sre/skills/playbook-generator/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/playbook-generator/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/playbook-generator/references/rhel/version-compatibility.md delete mode 120000 rh-sre/skills/remediation/docs/ansible/aap-integration.md delete mode 120000 rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md delete mode 120000 rh-sre/skills/remediation/docs/ansible/error-handling.md delete mode 120000 rh-sre/skills/remediation/docs/ansible/idempotency.md delete mode 120000 rh-sre/skills/remediation/docs/insights/vulnerability-logic.md delete mode 120000 rh-sre/skills/remediation/docs/references/compliance-frameworks.md delete mode 120000 rh-sre/skills/remediation/docs/references/cvss-scoring.md delete mode 120000 rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md delete mode 120000 rh-sre/skills/remediation/docs/rhel/package-management.md delete mode 120000 rh-sre/skills/remediation/docs/rhel/selinux-context.md delete mode 120000 rh-sre/skills/remediation/docs/rhel/systemd-services.md delete mode 120000 rh-sre/skills/remediation/docs/rhel/version-compatibility.md create mode 120000 rh-sre/skills/remediation/references/ansible/aap-integration.md create mode 120000 rh-sre/skills/remediation/references/ansible/cve-remediation-templates.md create mode 120000 rh-sre/skills/remediation/references/ansible/error-handling.md create mode 120000 rh-sre/skills/remediation/references/ansible/idempotency.md create mode 120000 rh-sre/skills/remediation/references/compliance-frameworks.md create mode 120000 rh-sre/skills/remediation/references/cvss-scoring.md create mode 120000 rh-sre/skills/remediation/references/insights/vulnerability-logic.md create mode 120000 rh-sre/skills/remediation/references/lightspeed-mcp-tool-failures.md create mode 120000 rh-sre/skills/remediation/references/rhel/package-management.md create mode 120000 rh-sre/skills/remediation/references/rhel/selinux-context.md create mode 120000 rh-sre/skills/remediation/references/rhel/systemd-services.md create mode 120000 rh-sre/skills/remediation/references/rhel/version-compatibility.md rename rh-sre/skills/remediation/{docs => }/references/skill-invocation.md (100%) rename rh-virt/{docs => references}/troubleshooting/.ai-index/semantic-index.json (100%) delete mode 120000 rh-virt/skills/vm-clone/docs/README.md delete mode 120000 rh-virt/skills/vm-clone/docs/SOURCES.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md delete mode 120000 rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md create mode 120000 rh-virt/skills/vm-clone/references/README.md create mode 120000 rh-virt/skills/vm-clone/references/SOURCES.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/INDEX.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/lifecycle-errors.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/network-errors.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/runtime-errors.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/scheduling-errors.md create mode 120000 rh-virt/skills/vm-clone/references/troubleshooting/storage-errors.md delete mode 120000 rh-virt/skills/vm-create/docs/README.md delete mode 120000 rh-virt/skills/vm-create/docs/SOURCES.md delete mode 120000 rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md delete mode 120000 rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md delete mode 120000 rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md delete mode 120000 rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md create mode 120000 rh-virt/skills/vm-create/references/README.md create mode 120000 rh-virt/skills/vm-create/references/SOURCES.md create mode 120000 rh-virt/skills/vm-create/references/troubleshooting/INDEX.md create mode 120000 rh-virt/skills/vm-create/references/troubleshooting/lifecycle-errors.md rename rh-virt/skills/vm-create/{docs => references}/troubleshooting/network-errors.md (100%) rename rh-virt/skills/vm-create/{docs => references}/troubleshooting/runtime-errors.md (99%) create mode 120000 rh-virt/skills/vm-create/references/troubleshooting/scheduling-errors.md create mode 120000 rh-virt/skills/vm-create/references/troubleshooting/storage-errors.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md delete mode 120000 rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md rename rh-virt/skills/vm-delete/{docs => references}/README.md (100%) rename rh-virt/skills/vm-delete/{docs => references}/SOURCES.md (100%) create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/INDEX.md create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/lifecycle-errors.md create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/network-errors.md create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/runtime-errors.md create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/scheduling-errors.md create mode 120000 rh-virt/skills/vm-delete/references/troubleshooting/storage-errors.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/README.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md delete mode 120000 rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/README.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/SOURCES.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/INDEX.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/lifecycle-errors.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/network-errors.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/runtime-errors.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/scheduling-errors.md create mode 120000 rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/storage-errors.md delete mode 120000 rh-virt/skills/vm-rebalance/docs/README.md delete mode 120000 rh-virt/skills/vm-rebalance/docs/SOURCES.md delete mode 120000 rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md delete mode 120000 rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md create mode 120000 rh-virt/skills/vm-rebalance/references/README.md create mode 120000 rh-virt/skills/vm-rebalance/references/SOURCES.md rename rh-virt/skills/vm-rebalance/{docs => references}/troubleshooting/INDEX.md (100%) rename rh-virt/skills/vm-rebalance/{docs => references}/troubleshooting/lifecycle-errors.md (100%) create mode 120000 rh-virt/skills/vm-rebalance/references/troubleshooting/network-errors.md create mode 120000 rh-virt/skills/vm-rebalance/references/troubleshooting/runtime-errors.md rename rh-virt/skills/vm-rebalance/{docs => references}/troubleshooting/scheduling-errors.md (100%) rename rh-virt/skills/vm-rebalance/{docs => references}/troubleshooting/storage-errors.md (100%) diff --git a/.claude/skills/agentic-contribution-skill/SKILL.md b/.claude/skills/agentic-contribution-skill/SKILL.md index 2de61c38..b16f938b 100644 --- a/.claude/skills/agentic-contribution-skill/SKILL.md +++ b/.claude/skills/agentic-contribution-skill/SKILL.md @@ -118,7 +118,7 @@ Ask concisely, validate before proceeding. Make additional questions if needed t 4. **Workflow**: "Steps with MCP tools?" (e.g., "1. Validate VM - resources_get") 5. **Common Issues**: "3+ issues: problem: cause: solution" 6. **Prerequisites**: "Special requirements? (env vars, permissions)" -7. **External Resources**: "Any external docs/links/KB articles referenced?" (will be saved to `docs/` folder) +7. **External Resources**: "Any external references/links/KB articles referenced?" (will be saved to `references/` folder) **Quality over Speed**: Focus on gathering complete, accurate information. Validation and iteration will ensure correctness - prioritize quality of final result over generation time. @@ -210,7 +210,7 @@ Show complete spec: **Workflow**: steps **Common Issues**: documented **MCP Tools**: tools (verified to exist) -**External Resources**: (will be saved to docs/) +**External Resources**: (will be saved to references/) **Human-in-the-Loop**: [If >10 steps or complex workflow]: @@ -229,26 +229,26 @@ Proceed with generation? (yes/no) ```bash mkdir -p /skills// # If external resources provided by user: -mkdir -p /skills//docs/ +mkdir -p /skills//references/ ``` **Generate files**: 1. **SKILL.md**: YAML frontmatter + mandatory sections (follow SKILL_DESIGN_PRINCIPLES.md template - already consulted in Phase 3) - Focus on complete, production-ready content - Include all relevant information from user and verified sources - - Keep main skill focused; detailed content can go to `docs/` if needed -2. **docs/ folder** (if applicable): - - `docs/workflow-details.md` - Extended workflow explanations if skill is concise - - `docs/common-issues.md` - Detailed troubleshooting with full KB article content - - `docs/examples.md` - Comprehensive usage examples - - `docs/external-resources.md` - Any external docs/links/KB articles mentioned by user + - Keep main skill focused; detailed content can go to `references/` if needed +2. **references/ folder** (if applicable): + - `references/workflow-details.md` - Extended workflow explanations if skill is concise + - `references/common-issues.md` - Detailed troubleshooting with full KB article content + - `references/examples.md` - Comprehensive usage examples + - `references/external-resources.md` - Any external references/links/KB articles mentioned by user 3. **Update /AGENTS.md**: Add intent routing entry 4. **Create /mcps.json**: If new MCP server needed (use `${ENV_VAR}` format) 5. **Compass manifests**: Run **compass-manifest-maintenance** (`.claude/skills/compass-manifest-maintenance/`) for registered packs — skill `catalog-info.yaml`, Location targets, bidirectional `dependsOn`/`dependencyOf` on plugin and MCP manifests 6. **Update marketplace/rh-agentic-collection.yml** in [agentic-catalog](https://github.com/RHEcosystemAppEng/agentic-catalog): If new pack (register pack for Lola installation) 7. **Create pack structure**: If new pack (README.md, AGENTS.md, skills/ directory) -Generate SKILL.md following the mandatory section template in SKILL_DESIGN_PRINCIPLES.md (already consulted in Phase 3). If SKILL.md becomes too long, move detailed content to `docs/` with references in main file. +Generate SKILL.md following the mandatory section template in SKILL_DESIGN_PRINCIPLES.md (already consulted in Phase 3). If SKILL.md becomes too long, move detailed content to `references/` with references in main file. ### Phase 5: Validation & Iteration @@ -267,7 +267,7 @@ uv run python scripts/validate_skills_tier2.py /skills//SKILL. **Report clearly**: - ✅ PASSED → Proceed to Phase 6 - ⚠️ WARNINGS → Review warnings with user - - Non-standard subdirectory (docs/) is acceptable if needed + - Non-standard subdirectory (references/) is acceptable if needed - Description buzzwords acceptable if accurate for critical skills - Ask: "Warnings acceptable? (yes/no)" - ❌ ERRORS → **Fix required**, iterate until validation passes @@ -275,10 +275,10 @@ uv run python scripts/validate_skills_tier2.py /skills//SKILL. **Iteration Protocol** (if validation fails): 1. **Analyze errors**: Identify specific issues (line count, missing sections, format problems) 2. **Determine fix strategy**: - - Line count exceeded → Move detailed content to `docs/` folder, keep main skill concise + - Line count exceeded → Move detailed content to `references/` folder, keep main skill concise - Missing sections → Add required sections per DP7 - Format issues → Correct frontmatter, section headers, or structure -3. **Apply fixes**: Edit SKILL.md and/or create docs/ files +3. **Apply fixes**: Edit SKILL.md and/or create references/ files 4. **Re-validate**: Run both Tier 1 and Tier 2 again 5. **Repeat until ✅ PASSED** @@ -358,23 +358,23 @@ curl -LsSf https://astral.sh/uv/install.sh | sh **Cause**: Skill content is comprehensive but exceeds agentskills.io 500-line limit -**Fix**: Iterate to move detailed content to `docs/` folder: -1. Create `/docs/` directory -2. Move detailed workflow explanations to `docs/workflow-details.md` -3. Move full troubleshooting KB articles to `docs/common-issues.md` -4. Move comprehensive examples to `docs/examples.md` -5. Keep main SKILL.md concise with references to docs/ +**Fix**: Iterate to move detailed content to `references/` folder: +1. Create `/references/` directory +2. Move detailed workflow explanations to `references/workflow-details.md` +3. Move full troubleshooting KB articles to `references/common-issues.md` +4. Move comprehensive examples to `references/examples.md` +5. Keep main SKILL.md concise with references to references/ 6. Re-run validation **Example**: ```markdown ## Common Issues -See [docs/common-issues.md](docs/common-issues.md) for detailed solutions. +See [references/common-issues.md](references/common-issues.md) for detailed solutions. ### Issue 1: Snapshot Fails Storage doesn't support snapshots. -**Solution**: Use snapshot-capable storage. [Details](docs/common-issues.md#issue-1) +**Solution**: Use snapshot-capable storage. [Details](references/common-issues.md#issue-1) ``` ## Dependencies @@ -443,7 +443,7 @@ See [Prerequisites](#prerequisites) section for required system tools (git, uv, ## Example Usage -**See [docs/examples.md](docs/examples.md) for comprehensive examples.** +**See [references/examples.md](references/examples.md) for comprehensive examples.** ### Quick Example: Creating VM Backup Skill @@ -461,8 +461,8 @@ Skill guides through: Result: Production-ready skill in rh-virt/skills/vm-backup-create/ ``` -**More examples**: [docs/examples.md](docs/examples.md) +**More examples**: [references/examples.md](references/examples.md) - Example 1: VM backup skill (complete create interaction) - Example 2: Non-representative name correction - Example 3: Importing an existing skill (analysis, adaptation, validation) -- Example 4: Large skill requiring docs/ folder with iteration +- Example 4: Large skill requiring references/ folder with iteration diff --git a/.claude/skills/agentic-contribution-skill/docs/examples.md b/.claude/skills/agentic-contribution-skill/references/examples.md similarity index 91% rename from .claude/skills/agentic-contribution-skill/docs/examples.md rename to .claude/skills/agentic-contribution-skill/references/examples.md index 4e8e78ab..fd0c76b8 100644 --- a/.claude/skills/agentic-contribution-skill/docs/examples.md +++ b/.claude/skills/agentic-contribution-skill/references/examples.md @@ -210,7 +210,7 @@ Ready to commit? (yes/no) [Git workflow with confirmations] ``` -## Example 4: Large Skill Requires docs/ Folder +## Example 4: Large Skill Requires references/ Folder ``` [After Phase 2 - Definition] @@ -236,14 +236,14 @@ Running validation... ❌ Tier 1: FAILED - Line count exceeds 500 (got 1533) -**Iteration 1**: Moving detailed content to docs/ folder... +**Iteration 1**: Moving detailed content to references/ folder... -Creating docs/: -✅ docs/workflow-details.md (extended step explanations) -✅ docs/common-issues.md (full KB articles with solutions) -✅ docs/examples.md (comprehensive success/rollback scenarios) +Creating references/: +✅ references/workflow-details.md (extended step explanations) +✅ references/common-issues.md (full KB articles with solutions) +✅ references/examples.md (comprehensive success/rollback scenarios) -Updating SKILL.md with references to docs/... +Updating SKILL.md with references to references/... Running validation again... @@ -254,9 +254,9 @@ Running validation again... **Files**: ✅ ocp-admin/skills/cluster-upgrade/SKILL.md (323 lines) -✅ ocp-admin/skills/cluster-upgrade/docs/workflow-details.md -✅ ocp-admin/skills/cluster-upgrade/docs/common-issues.md -✅ ocp-admin/skills/cluster-upgrade/docs/examples.md +✅ ocp-admin/skills/cluster-upgrade/references/workflow-details.md +✅ ocp-admin/skills/cluster-upgrade/references/common-issues.md +✅ ocp-admin/skills/cluster-upgrade/references/examples.md **Quality**: Production-ready, comprehensive, validation compliant diff --git a/.claude/skills/compass-manifest-maintenance/SKILL.md b/.claude/skills/compass-manifest-maintenance/SKILL.md index b200cf36..5028189f 100644 --- a/.claude/skills/compass-manifest-maintenance/SKILL.md +++ b/.claude/skills/compass-manifest-maintenance/SKILL.md @@ -96,6 +96,19 @@ test -f CLAUDE.md && echo "✓ repo root" || echo "✗ wrong directory" 7. **Reconcile plugin MCP deps** — plugin `dependsOn` = union of all `mcpserver:` refs across pack skill manifests. +8. **Verify skill documentation layout** ([agent-plugins.org](https://agent-plugins.org/specification) / agentskills.io): + - Skill-local documentation belongs in `skills//references/`, not `docs/`. + - **Allowed locations only:** pack-level `/references/` or skill-level `skills//references/`. **No** `references/references/` nesting inside a skill. + - **Scan** every `skills//` for a `docs/` directory. + - **If `docs/` exists:** + 1. Rename or merge into `references/` (merge file-by-file when both exist). + 2. If `docs/references/` existed, flatten into `skills//references/` (not `references/references/`). + 3. Update markdown links in `SKILL.md` and all files under the skill directory: `docs/...` → `references/...` (also `./docs/...` and relative `../docs/...` segments). + 4. **Delete** the `docs/` directory after migration — do not leave an empty or stale `docs/` folder. + 5. Update symlinks under `references/` that still target `docs/` paths to `references/`. + - Shared reference pools (e.g. `common-issues.md`, `live-doc-lookup.md`) symlinked into multiple skills must use link targets that resolve when opened through the symlink (same-directory or `references/...` paths from the symlink location). + - Run `uv run python scripts/validate_compass_manifests.py` to confirm (includes manifest roster, bidirectional refs, and references layout). + ### 2. Register a new pack in Compass 1. Create `/-plugin.yaml` from [assets/plugin-catalog-info.yaml](assets/plugin-catalog-info.yaml) with **`spec.lifecycle: development`** (default for new packs; confirm with user before raising maturity). @@ -106,7 +119,7 @@ test -f CLAUDE.md && echo "✓ repo root" || echo "✗ wrong directory" ### 3. Drift / compliance audit -Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-compass-manifests`). It enforces the same structural rules as this table: +Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-compass-manifests`). It enforces manifest roster, bidirectional refs, and skill references layout: | Check | Rule | |-------|------| @@ -117,6 +130,7 @@ Run `uv run python scripts/validate_compass_manifests.py` (or `make validate-com | Dangling refs | Every ref resolves to on-disk manifest or documented canonical MCP | | Forbidden | No `partOf`/`hasPart` on AiResource/MCPServer; no redundant `dependsOn: system:default/agentic-plugins` on plugins | | Namespace | Refs use `ai5-marketplace` except `mcpserver:redhat/*` and `default/agentic-plugins` | +| Skill docs layout | No `skills//docs/` (delete after migrate); no `references/references/` nesting; links use `references/...` or `./references/...`, not `docs/...` | Report violations with file path and fix per workflow §1. Do not weaken checks. @@ -131,6 +145,7 @@ Report violations with file path and fix per workflow §1. Do not weaken checks. - If skill on disk has no manifest → create from `assets/skill-catalog-info.yaml` and add Location target. - If inverse `dependencyOf` missing on plugin or MCP → update per [relationship-rules.md](references/relationship-rules.md). - If MCP ref cannot be resolved → grep pack manifests; do not invent new `mcpserver:` refs. +- If `skills//docs/` exists or markdown links use `docs/...` → rename/merge to `references/`, flatten any `references/references/`, update link paths, **delete** `docs/`, fix symlinks; re-run `validate_compass_manifests.py`. ## Self-review checklist @@ -141,6 +156,7 @@ Report violations with file path and fix per workflow §1. Do not weaken checks. - [ ] Pack Location lists every skill manifest path. - [ ] Plugin `dependencyOf` lists every skill in the pack. - [ ] No `partOf`/`hasPart` on custom kinds. +- [ ] Skill documentation uses `references/` only — no leftover `docs/` directory, no `references/references/` nesting; links use `references/...` or `./references/...`. ## Dependencies @@ -171,11 +187,12 @@ None — uses Read, Glob, Grep, Bash. - **Orchestration gaps** — `remediation`-style skills missing skill→skill edges or inverse `dependencyOf` on depended skills. - **Canonical vs owned** — Lightspeed and Security use `mcpserver:redhat/...`; do not register duplicates in `mcps/`. - **Unregistered packs** — `rh-developer`, `rh-ai-engineer`, `rh-automation` exist on disk but are not in root Location until explicitly added. +- **`docs/` vs `references/`** — agent-plugins.org expects `references/` for skill-local docs; rename/merge, flatten `references/references/`, update links, **delete** `docs/`, then run `make validate-compass-manifests`. ## Example usage ```bash -# CI structural validation (roster + bidirectional refs) +# CI structural validation (roster + bidirectional refs + references layout) uv run python scripts/validate_compass_manifests.py # or: make validate-compass-manifests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c43a592..67acc557 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,7 @@ Both tiers must pass before submitting a PR. - [ ] Tier 1 validation passed (agentskills.io spec) - [ ] Tier 2 validation passed (design principles) +- [ ] Compass manifests and references layout validated: `make validate-compass-manifests` - [ ] Skill doc links validated: `uv run python scripts/validate_skill_doc_links.py /skills//SKILL.md` - [ ] Skill doc tree links validated: `uv run python scripts/validate_docs_tree_links.py /skills//SKILL.md` - [ ] Pack AGENTS.md intent routing updated diff --git a/Makefile b/Makefile index 8927a78b..bb9696ee 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ help: @echo " validate-structure - Structure, links, compliance, MCP tools (no per-skill tier checks)" @echo " validate-collection-schema - Schema + roster + banners (subset of compliance)" @echo " validate-collection-compliance - Full .catalog compliance (includes collection.json drift)" - @echo " validate-compass-manifests - Compass catalog-info.yaml roster and bidirectional refs" + @echo " validate-compass-manifests - Compass manifests, roster, refs, and skill references/ layout" @echo " validate-skill-design - Validate all skills (use PACK=rh-sre for a specific pack)" @echo " validate-skill-design-changed - Validate only changed skills (staged + unstaged, for local dev)" @echo " validate-mcp-tools - Validate allowed-tools against live MCP servers (requires podman)" diff --git a/SKILL_DESIGN_PRINCIPLES.md b/SKILL_DESIGN_PRINCIPLES.md index c0f1a055..032de4dd 100644 --- a/SKILL_DESIGN_PRINCIPLES.md +++ b/SKILL_DESIGN_PRINCIPLES.md @@ -182,10 +182,13 @@ Every skill MUST include a **Dependencies** section listing: ``` **Skill-local docs rule (required):** -- Internal docs consumed by a skill must resolve under that skill directory using `docs/...` links. -- Do **not** use upward traversal links to pack-level docs such as `../docs/...`, `../../docs/...`, or `../../../docs/...`. -- Shared docs may be reused via symlinks under `skills//docs/...`. -- Pack-level `docs/INDEX.md` and `docs/SOURCES.md` may exist for repository navigation/source attribution, but skills must not depend on them at execution time. +- Internal docs consumed by a skill must resolve under that skill directory using `references/...` or `./references/...` links in `SKILL.md`. +- Do **not** use upward traversal links to pack-level docs such as `../references/...`, `../../references/...`, or `../../../references/...`. +- Shared docs may be reused via symlinks under `skills//references/...`. Link targets inside shared pool files must resolve when the file is opened through a skill symlink (use same-directory or `references/...` paths from the symlink location). +- After migrating `docs/` → `references/`, **delete** the `skills//docs/` directory — do not leave empty or stale folders. +- Do **not** nest `references/references/` inside a skill. If `docs/references/` existed, flatten files into `skills//references/`. +- Pack-level `/references/` or skill-level `skills//references/` are the only allowed reference locations. +- Pack-level `references/INDEX.md` and `references/SOURCES.md` may exist for repository navigation/source attribution, but skills must not depend on them at execution time. **Rationale**: Makes dependencies explicit for debugging and troubleshooting. diff --git a/ocp-admin/README.md b/ocp-admin/README.md index 8a97a400..746c48d1 100644 --- a/ocp-admin/README.md +++ b/ocp-admin/README.md @@ -277,15 +277,15 @@ Create OpenShift clusters using the Red Hat Assisted Installer with full workflo - `alter_static_network_config_nmstate_for_host` - Apply static networking to hosts **Documentation**: -- [Input Validation Guide](skills/cluster-creator/docs/input-validation-guide.md) - Parameter requirements -- [Providers](skills/cluster-creator/docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) -- [Platforms](skills/cluster-creator/docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD) -- [Networking](skills/cluster-creator/docs/networking.md) - Network configuration, VIPs, CIDR planning -- [Static Networking Guide](skills/cluster-creator/docs/static-networking-guide.md) - NMState configuration -- [Host Requirements](skills/cluster-creator/docs/host-requirements.md) - Hardware specifications -- [Examples](skills/cluster-creator/docs/examples.md) - 10 real-world configurations -- [Troubleshooting](skills/cluster-creator/docs/troubleshooting.md) - Common errors and solutions -- [INDEX.md](skills/cluster-creator/docs/INDEX.md) - Complete documentation navigation +- [Input Validation Guide](skills/cluster-creator/references/input-validation-guide.md) - Parameter requirements +- [Providers](skills/cluster-creator/references/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) +- [Platforms](skills/cluster-creator/references/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD) +- [Networking](skills/cluster-creator/references/networking.md) - Network configuration, VIPs, CIDR planning +- [Static Networking Guide](skills/cluster-creator/references/static-networking-guide.md) - NMState configuration +- [Host Requirements](skills/cluster-creator/references/host-requirements.md) - Hardware specifications +- [Examples](skills/cluster-creator/references/examples.md) - 10 real-world configurations +- [Troubleshooting](skills/cluster-creator/references/troubleshooting.md) - Common errors and solutions +- [INDEX.md](skills/cluster-creator/references/INDEX.md) - Complete documentation navigation ### 2. **cluster-inventory** - Cluster Discovery and Status @@ -466,7 +466,7 @@ export KUBECONFIG=/tmp/cluster-report-kubeconfig # In Claude Code: /cluster-report ``` -See [skills/cluster-report/docs/multi-cluster-auth.md](skills/cluster-report/docs/multi-cluster-auth.md) for the full setup guide, token rotation, and troubleshooting. +See [skills/cluster-report/references/multi-cluster-auth.md](skills/cluster-report/references/multi-cluster-auth.md) for the full setup guide, token rotation, and troubleshooting. --- @@ -680,26 +680,26 @@ Result: Real-time installation status without leaving Claude The pack includes 17 comprehensive reference documents covering all aspects of OpenShift administration: ### Installation & Planning -- [Input Validation Guide](skills/cluster-creator/docs/input-validation-guide.md) - Parameter validation rules -- [Providers](skills/cluster-creator/docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) -- [Platforms](skills/cluster-creator/docs/platforms.md) - OpenShift platform types (SNO, OCP, ROSA, ARO, OSD) -- [Host Requirements](skills/cluster-creator/docs/host-requirements.md) - Hardware specifications -- [Networking](skills/cluster-creator/docs/networking.md) - Network configuration, VIPs, CIDR planning, Egress IP, Multus, SR-IOV, Dual-Stack -- [Static Networking Guide](skills/cluster-creator/docs/static-networking-guide.md) - NMState configuration (Simple/Advanced/Manual modes) -- [Storage](skills/cluster-creator/docs/storage.md) - Storage options, CSI drivers, ODF -- [Examples](skills/cluster-creator/docs/examples.md) - 10 real-world cluster configurations +- [Input Validation Guide](skills/cluster-creator/references/input-validation-guide.md) - Parameter validation rules +- [Providers](skills/cluster-creator/references/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) +- [Platforms](skills/cluster-creator/references/platforms.md) - OpenShift platform types (SNO, OCP, ROSA, ARO, OSD) +- [Host Requirements](skills/cluster-creator/references/host-requirements.md) - Hardware specifications +- [Networking](skills/cluster-creator/references/networking.md) - Network configuration, VIPs, CIDR planning, Egress IP, Multus, SR-IOV, Dual-Stack +- [Static Networking Guide](skills/cluster-creator/references/static-networking-guide.md) - NMState configuration (Simple/Advanced/Manual modes) +- [Storage](skills/cluster-creator/references/storage.md) - Storage options, CSI drivers, ODF +- [Examples](skills/cluster-creator/references/examples.md) - 10 real-world cluster configurations ### Post-Installation -- [Credentials Management](skills/cluster-creator/docs/credentials-management.md) - Authentication, OAuth, RBAC, identity providers -- [Multi-Cluster Authentication](skills/cluster-report/docs/multi-cluster-auth.md) - Service account tokens, kubeconfig merging -- [Day-2 Operations](skills/cluster-creator/docs/day-2-operations.md) - Monitoring, logging, updates, scaling, maintenance -- [Certificate Management](skills/cluster-creator/docs/certificate-management.md) - Certificate lifecycle and rotation -- [Backup and Restore](skills/cluster-creator/docs/backup-restore.md) - etcd backup/restore procedures +- [Credentials Management](skills/cluster-creator/references/credentials-management.md) - Authentication, OAuth, RBAC, identity providers +- [Multi-Cluster Authentication](skills/cluster-report/references/multi-cluster-auth.md) - Service account tokens, kubeconfig merging +- [Day-2 Operations](skills/cluster-creator/references/day-2-operations.md) - Monitoring, logging, updates, scaling, maintenance +- [Certificate Management](skills/cluster-creator/references/certificate-management.md) - Certificate lifecycle and rotation +- [Backup and Restore](skills/cluster-creator/references/backup-restore.md) - etcd backup/restore procedures ### Reference & Troubleshooting -- [Quick Reference](skills/cluster-creator/docs/quick-reference.md) - Common `oc` commands and scenarios -- [Troubleshooting](skills/cluster-creator/docs/troubleshooting.md) - Common errors and resolutions -- [INDEX.md](skills/cluster-creator/docs/INDEX.md) - Complete documentation navigation +- [Quick Reference](skills/cluster-creator/references/quick-reference.md) - Common `oc` commands and scenarios +- [Troubleshooting](skills/cluster-creator/references/troubleshooting.md) - Common errors and resolutions +- [INDEX.md](skills/cluster-creator/references/INDEX.md) - Complete documentation navigation **All documentation**: - Derived from official Red Hat sources @@ -752,7 +752,7 @@ The pack includes 17 comprehensive reference documents covering all aspects of O 1. Check host requirements match cluster type (SNO vs HA) 2. Verify VIPs are in same subnet as nodes 3. Review cluster events: Use `cluster-inventory` skill -4. Check troubleshooting guide: [skills/cluster-creator/docs/troubleshooting.md](skills/cluster-creator/docs/troubleshooting.md) +4. Check troubleshooting guide: [skills/cluster-creator/references/troubleshooting.md](skills/cluster-creator/references/troubleshooting.md) 5. Verify network connectivity between hosts ### Skills Not Triggering diff --git a/ocp-admin/docs/SOURCES.md b/ocp-admin/references/SOURCES.md similarity index 100% rename from ocp-admin/docs/SOURCES.md rename to ocp-admin/references/SOURCES.md diff --git a/ocp-admin/skills/cluster-creator/SKILL.md b/ocp-admin/skills/cluster-creator/SKILL.md index cd923dc8..98e4cf17 100644 --- a/ocp-admin/skills/cluster-creator/SKILL.md +++ b/ocp-admin/skills/cluster-creator/SKILL.md @@ -126,7 +126,7 @@ TaskCreate(subject: "#12 Retrieve credentials", description: "Download kubeconfi **Prerequisites Check**: Execute verification from Prerequisites section. -**On Failure**: If prerequisites fail, consult [troubleshooting.md](docs/troubleshooting.md) for common setup issues, then stop and report error to user. +**On Failure**: If prerequisites fail, consult [troubleshooting.md](references/troubleshooting.md) for common setup issues, then stop and report error to user. --- @@ -142,11 +142,11 @@ Use AskUserQuestion to collect configuration: - **SNO**: Platform is automatically set to "none" (Red Hat API requirement) - DO NOT ask user - **HA**: Ask user to select: baremetal, vsphere, nutanix, or oci 3. **Version**: Call `list_versions`, show "Full Support" versions -4. **Cluster Name**: Ask "Cluster name? (or type your custom name directly)" - Suggest based on context (e.g., "prod-ocp", "edge-site-01", "dev-cluster") OR user types custom name. Validate: 1-54 chars, lowercase/numbers/hyphens, starts with letter ([validation](docs/input-validation-guide.md#cluster-name)) -5. **Base Domain**: Ask "Base domain? (e.g., example.com)" - User types domain directly. Validate: valid DNS format ([validation](docs/input-validation-guide.md#base-domain)) +4. **Cluster Name**: Ask "Cluster name? (or type your custom name directly)" - Suggest based on context (e.g., "prod-ocp", "edge-site-01", "dev-cluster") OR user types custom name. Validate: 1-54 chars, lowercase/numbers/hyphens, starts with letter ([validation](references/input-validation-guide.md#cluster-name)) +5. **Base Domain**: Ask "Base domain? (e.g., example.com)" - User types domain directly. Validate: valid DNS format ([validation](references/input-validation-guide.md#base-domain)) 6. **CPU Arch**: x86_64 (default), aarch64, ppc64le, s390x 7. **SSH Key**: Ask "How to provide?" Options: Generate new (recommended, save to cluster folder) | Existing file (path) | Paste | ⚠️ None (warn, require "PROCEED WITHOUT SSH" confirmation) -8. **Hardware**: Confirm servers meeting [host requirements](docs/host-requirements.md) are ready +8. **Hardware**: Confirm servers meeting [host requirements](references/host-requirements.md) are ready **Create folder**: `/tmp/{cluster_name}.{base_domain}/` (permissions 700), display location @@ -158,7 +158,7 @@ Use AskUserQuestion to collect configuration: Ask: "How to configure networking?" Options: 1) Default (auto CIDRs, DHCP, HA: ask VIPs) | 2) Custom CIDRs (ask each, validate) | 3) Static IPs (Simple/Advanced/Manual modes, use `generate_nmstate_yaml`) | 4) Describe requirements (AI infers from text like "192.168.1.0/24, 100 pods") -**Reference**: [Networking Guide](docs/networking.md) has detailed examples for all 4 options +**Reference**: [Networking Guide](references/networking.md) has detailed examples for all 4 options --- @@ -167,7 +167,7 @@ Ask: "How to configure networking?" Options: 1) Default (auto CIDRs, DHCP, HA: a Display summary: Cluster Name, Type (SNO/HA), Version, Platform, Architecture, Domain, VIPs (if applicable), Networking (DHCP/Static) -**Reference**: [Examples](docs/examples.md) +**Reference**: [Examples](references/examples.md) --- @@ -211,7 +211,7 @@ Ask: "Review configuration. Ready to create cluster definition?" - **Parameters**: `{cluster_id, nmstate_yaml, mac_address}` - **Verify**: Call `list_static_network_config` -**Reference**: [Providers](docs/providers.md), [Networking](docs/networking.md) +**Reference**: [Providers](references/providers.md), [Networking](references/networking.md) --- @@ -270,7 +270,7 @@ Display: "Waiting for you to boot hosts. When ready, say 'check for hosts'." **If insufficient**: Ask to wait/proceed/abort. -**Reference**: [Host Requirements](docs/host-requirements.md) +**Reference**: [Host Requirements](references/host-requirements.md) --- @@ -298,7 +298,7 @@ Display: "Waiting for you to boot hosts. When ready, say 'check for hosts'." **If validation fails**: 1. Display errors from cluster_info -2. Consult [troubleshooting.md](docs/troubleshooting.md) for cluster status meanings and validation error diagnosis +2. Consult [troubleshooting.md](references/troubleshooting.md) for cluster status meanings and validation error diagnosis 3. Offer options: fix/wait/abort --- @@ -338,7 +338,7 @@ Ask: "Start installation now?" **On Error**: 1. Display error message -2. Consult [troubleshooting.md](docs/troubleshooting.md) for error diagnosis +2. Consult [troubleshooting.md](references/troubleshooting.md) for error diagnosis 3. If error is new/undocumented, note it for future documentation 4. Offer retry/abort @@ -368,7 +368,7 @@ Background monitoring? (yes/no) **If manual**: Wait for "check status", then call `cluster_info`, display progress, repeat until "installed" or "error" **If installation fails**: -1. Consult [troubleshooting.md](docs/troubleshooting.md) for cluster lifecycle states and common installation errors +1. Consult [troubleshooting.md](references/troubleshooting.md) for cluster lifecycle states and common installation errors 2. Download logs (`cluster_logs_download_url`) for detailed diagnosis 3. Offer options: diagnose errors, cleanup and retry, or manual intervention 4. **Cleanup**: Failed cluster remains in Assisted Installer - use cluster_info to verify state before deleting or retrying with same cluster_id @@ -385,7 +385,7 @@ Display: "Installation Completed! Cluster: {cluster_name}, Status: installed, Ti ### Step 17: Retrieve Credentials **Document Consultation** (REQUIRED): -1. **Action**: Read [credentials-management.md](docs/credentials-management.md) +1. **Action**: Read [credentials-management.md](references/credentials-management.md) 2. **Output**: "I consulted credentials-management.md for credential download procedures." **Execute**: Follow download procedure to save kubeconfig and kubeadmin-password to `/tmp/{cluster_name}.{base_domain}/` (permissions 600) @@ -433,7 +433,7 @@ Congratulations! **If yes**: Ask destination (default: ~/.kube/clusters/), copy folder with `cp -r`, set permissions 700, display confirmation -**Reference**: [Credentials Management](docs/credentials-management.md) +**Reference**: [Credentials Management](references/credentials-management.md) --- @@ -455,27 +455,27 @@ All tools from `openshift-self-managed` MCP server: ### Reference Documentation **Configuration & Validation**: -- [Input Validation Guide](docs/input-validation-guide.md) - Parameter requirements -- [Networking](docs/networking.md) - Network configuration, VIPs, CIDR planning -- [Static Networking Guide](docs/static-networking-guide.md) - NMState configuration +- [Input Validation Guide](references/input-validation-guide.md) - Parameter requirements +- [Networking](references/networking.md) - Network configuration, VIPs, CIDR planning +- [Static Networking Guide](references/static-networking-guide.md) - NMState configuration **Platform & Infrastructure**: -- [Providers](docs/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) -- [Platforms](docs/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD) -- [Host Requirements](docs/host-requirements.md) - Hardware specs by cluster type +- [Providers](references/providers.md) - Infrastructure providers (baremetal, vsphere, oci, nutanix) +- [Platforms](references/platforms.md) - OpenShift types (SNO, OCP, ROSA, ARO, OSD) +- [Host Requirements](references/host-requirements.md) - Hardware specs by cluster type **Post-Installation**: -- [Credentials Management](docs/credentials-management.md) - Kubeconfig and authentication setup -- [Identity Providers](docs/idp.md) - HTPasswd, LDAP, OIDC, GitHub authentication -- [RBAC](docs/rbac.md) - Role-Based Access Control and Security Context Constraints -- [Certificate Rotation](docs/certificate-rotation.md) - Certificate management and renewal -- [Security Checklist](docs/security-checklist.md) - Post-installation security verification -- [Storage](docs/storage.md) - Storage options by provider -- [Examples](docs/examples.md) - Configuration examples -- [Troubleshooting](docs/troubleshooting.md) - Common errors and resolutions +- [Credentials Management](references/credentials-management.md) - Kubeconfig and authentication setup +- [Identity Providers](references/idp.md) - HTPasswd, LDAP, OIDC, GitHub authentication +- [RBAC](references/rbac.md) - Role-Based Access Control and Security Context Constraints +- [Certificate Rotation](references/certificate-rotation.md) - Certificate management and renewal +- [Security Checklist](references/security-checklist.md) - Post-installation security verification +- [Storage](references/storage.md) - Storage options by provider +- [Examples](references/examples.md) - Configuration examples +- [Troubleshooting](references/troubleshooting.md) - Common errors and resolutions **Complete Documentation Guide**: -- **[Documentation Index](docs/INDEX.md)** - Navigate all ocp-admin documentation (consult for topics not explicitly referenced above) +- **[Documentation Index](references/INDEX.md)** - Navigate all ocp-admin documentation (consult for topics not explicitly referenced above) --- @@ -497,4 +497,4 @@ This skill performs critical, irreversible operations requiring explicit user co **Result**: SNO deployed in ~45 min. All artifacts in `/tmp/edge-site-01.edge.local/`: kubeconfig, kubeadmin-password, SSH keys, discovery.iso, ISO URL, metadata -**More Examples**: See [examples.md](docs/examples.md) for HA, static networking, multi-cluster, and air-gapped configurations. +**More Examples**: See [examples.md](references/examples.md) for HA, static networking, multi-cluster, and air-gapped configurations. diff --git a/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md deleted file mode 120000 index c50a7889..00000000 --- a/ocp-admin/skills/cluster-creator/docs/multi-cluster-auth.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-report/docs/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-creator/docs/INDEX.md b/ocp-admin/skills/cluster-creator/references/INDEX.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/INDEX.md rename to ocp-admin/skills/cluster-creator/references/INDEX.md diff --git a/ocp-admin/skills/cluster-creator/docs/backup-restore.md b/ocp-admin/skills/cluster-creator/references/backup-restore.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/backup-restore.md rename to ocp-admin/skills/cluster-creator/references/backup-restore.md diff --git a/ocp-admin/skills/cluster-creator/docs/certificate-management.md b/ocp-admin/skills/cluster-creator/references/certificate-management.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/certificate-management.md rename to ocp-admin/skills/cluster-creator/references/certificate-management.md diff --git a/ocp-admin/skills/cluster-creator/docs/certificate-rotation.md b/ocp-admin/skills/cluster-creator/references/certificate-rotation.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/certificate-rotation.md rename to ocp-admin/skills/cluster-creator/references/certificate-rotation.md diff --git a/ocp-admin/skills/cluster-creator/docs/credentials-management.md b/ocp-admin/skills/cluster-creator/references/credentials-management.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/credentials-management.md rename to ocp-admin/skills/cluster-creator/references/credentials-management.md diff --git a/ocp-admin/skills/cluster-creator/docs/database-connection-management.md b/ocp-admin/skills/cluster-creator/references/database-connection-management.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/database-connection-management.md rename to ocp-admin/skills/cluster-creator/references/database-connection-management.md diff --git a/ocp-admin/skills/cluster-creator/docs/day-2-operations.md b/ocp-admin/skills/cluster-creator/references/day-2-operations.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/day-2-operations.md rename to ocp-admin/skills/cluster-creator/references/day-2-operations.md diff --git a/ocp-admin/skills/cluster-creator/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-creator/references/etcd-maintenance.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/etcd-maintenance.md rename to ocp-admin/skills/cluster-creator/references/etcd-maintenance.md diff --git a/ocp-admin/skills/cluster-creator/docs/examples.md b/ocp-admin/skills/cluster-creator/references/examples.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/examples.md rename to ocp-admin/skills/cluster-creator/references/examples.md diff --git a/ocp-admin/skills/cluster-creator/docs/host-requirements.md b/ocp-admin/skills/cluster-creator/references/host-requirements.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/host-requirements.md rename to ocp-admin/skills/cluster-creator/references/host-requirements.md diff --git a/ocp-admin/skills/cluster-creator/docs/idp.md b/ocp-admin/skills/cluster-creator/references/idp.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/idp.md rename to ocp-admin/skills/cluster-creator/references/idp.md diff --git a/ocp-admin/skills/cluster-creator/docs/input-validation-guide.md b/ocp-admin/skills/cluster-creator/references/input-validation-guide.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/input-validation-guide.md rename to ocp-admin/skills/cluster-creator/references/input-validation-guide.md diff --git a/ocp-admin/skills/cluster-creator/references/multi-cluster-auth.md b/ocp-admin/skills/cluster-creator/references/multi-cluster-auth.md new file mode 120000 index 00000000..979f44f0 --- /dev/null +++ b/ocp-admin/skills/cluster-creator/references/multi-cluster-auth.md @@ -0,0 +1 @@ +../../cluster-report/references/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-creator/docs/networking.md b/ocp-admin/skills/cluster-creator/references/networking.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/networking.md rename to ocp-admin/skills/cluster-creator/references/networking.md diff --git a/ocp-admin/skills/cluster-creator/docs/platforms.md b/ocp-admin/skills/cluster-creator/references/platforms.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/platforms.md rename to ocp-admin/skills/cluster-creator/references/platforms.md diff --git a/ocp-admin/skills/cluster-creator/docs/providers.md b/ocp-admin/skills/cluster-creator/references/providers.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/providers.md rename to ocp-admin/skills/cluster-creator/references/providers.md diff --git a/ocp-admin/skills/cluster-creator/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-creator/references/pvc-capacity-planning.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/pvc-capacity-planning.md rename to ocp-admin/skills/cluster-creator/references/pvc-capacity-planning.md diff --git a/ocp-admin/skills/cluster-creator/docs/quick-reference.md b/ocp-admin/skills/cluster-creator/references/quick-reference.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/quick-reference.md rename to ocp-admin/skills/cluster-creator/references/quick-reference.md diff --git a/ocp-admin/skills/cluster-creator/docs/rbac.md b/ocp-admin/skills/cluster-creator/references/rbac.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/rbac.md rename to ocp-admin/skills/cluster-creator/references/rbac.md diff --git a/ocp-admin/skills/cluster-creator/docs/security-checklist.md b/ocp-admin/skills/cluster-creator/references/security-checklist.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/security-checklist.md rename to ocp-admin/skills/cluster-creator/references/security-checklist.md diff --git a/ocp-admin/skills/cluster-creator/docs/static-networking-guide.md b/ocp-admin/skills/cluster-creator/references/static-networking-guide.md similarity index 99% rename from ocp-admin/skills/cluster-creator/docs/static-networking-guide.md rename to ocp-admin/skills/cluster-creator/references/static-networking-guide.md index c35ecd84..b4b1dd9a 100644 --- a/ocp-admin/skills/cluster-creator/docs/static-networking-guide.md +++ b/ocp-admin/skills/cluster-creator/references/static-networking-guide.md @@ -669,7 +669,7 @@ Host 1: - **RHEL Networking Guide**: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/configuring_and_managing_networking/ - **OpenShift Networking**: https://docs.openshift.com/container-platform/latest/networking/ - **IEEE 802.3ad (LACP)**: https://www.ieee802.org/3/hssg/public/apr07/frazier_01_0407.pdf -- **troubleshooting.md**: See `ocp-admin/docs/troubleshooting.md` for cluster-specific issues +- **troubleshooting.md**: See `ocp-admin/references/troubleshooting.md` for cluster-specific issues --- diff --git a/ocp-admin/skills/cluster-creator/docs/storage.md b/ocp-admin/skills/cluster-creator/references/storage.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/storage.md rename to ocp-admin/skills/cluster-creator/references/storage.md diff --git a/ocp-admin/skills/cluster-creator/docs/troubleshooting.md b/ocp-admin/skills/cluster-creator/references/troubleshooting.md similarity index 100% rename from ocp-admin/skills/cluster-creator/docs/troubleshooting.md rename to ocp-admin/skills/cluster-creator/references/troubleshooting.md diff --git a/ocp-admin/skills/cluster-inventory/SKILL.md b/ocp-admin/skills/cluster-inventory/SKILL.md index ad6ecb40..9fde3b5b 100644 --- a/ocp-admin/skills/cluster-inventory/SKILL.md +++ b/ocp-admin/skills/cluster-inventory/SKILL.md @@ -238,10 +238,10 @@ Execute when user requests events, troubleshoots errors, or needs installation l - Future: cluster-installer, cluster-deletion ### Reference Documentation -- [troubleshooting.md](docs/troubleshooting.md) - Cluster status and error diagnosis -- [PVC Capacity Planning](docs/pvc-capacity-planning.md) - Consult when cluster storage details show high PVC usage or approaching capacity -- [Database Connection Management](docs/database-connection-management.md) - Consult when cluster workloads include PostgreSQL with high connection usage -- **[Documentation Index](docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) +- [troubleshooting.md](references/troubleshooting.md) - Cluster status and error diagnosis +- [PVC Capacity Planning](references/pvc-capacity-planning.md) - Consult when cluster storage details show high PVC usage or approaching capacity +- [Database Connection Management](references/database-connection-management.md) - Consult when cluster workloads include PostgreSQL with high connection usage +- **[Documentation Index](references/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) ## Example Usage diff --git a/ocp-admin/skills/cluster-inventory/docs/INDEX.md b/ocp-admin/skills/cluster-inventory/docs/INDEX.md deleted file mode 120000 index dc8236cf..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/backup-restore.md b/ocp-admin/skills/cluster-inventory/docs/backup-restore.md deleted file mode 120000 index 69a2c4d7..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/backup-restore.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md b/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md deleted file mode 120000 index f24dab8f..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/certificate-rotation.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/credentials-management.md b/ocp-admin/skills/cluster-inventory/docs/credentials-management.md deleted file mode 120000 index 3a168f1e..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/credentials-management.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md b/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md deleted file mode 120000 index 5cd634fe..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/database-connection-management.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md b/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md deleted file mode 120000 index f81391c7..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/day-2-operations.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md deleted file mode 120000 index 0ac3e5a8..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/etcd-maintenance.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/examples.md b/ocp-admin/skills/cluster-inventory/docs/examples.md deleted file mode 120000 index ff790b2e..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/examples.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/host-requirements.md b/ocp-admin/skills/cluster-inventory/docs/host-requirements.md deleted file mode 120000 index 940ac361..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/host-requirements.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/idp.md b/ocp-admin/skills/cluster-inventory/docs/idp.md deleted file mode 120000 index 6ff039bc..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/idp.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md b/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md deleted file mode 120000 index 7fe632b8..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/input-validation-guide.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md deleted file mode 120000 index c50a7889..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/multi-cluster-auth.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-report/docs/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/networking.md b/ocp-admin/skills/cluster-inventory/docs/networking.md deleted file mode 120000 index 74cf579c..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/networking.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/platforms.md b/ocp-admin/skills/cluster-inventory/docs/platforms.md deleted file mode 120000 index 1705928b..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/platforms.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/providers.md b/ocp-admin/skills/cluster-inventory/docs/providers.md deleted file mode 120000 index a9736c66..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/providers.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md deleted file mode 120000 index fc0f73fc..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/pvc-capacity-planning.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/quick-reference.md b/ocp-admin/skills/cluster-inventory/docs/quick-reference.md deleted file mode 120000 index 19cf9f54..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/quick-reference.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/rbac.md b/ocp-admin/skills/cluster-inventory/docs/rbac.md deleted file mode 120000 index 19e4d531..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/rbac.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/security-checklist.md b/ocp-admin/skills/cluster-inventory/docs/security-checklist.md deleted file mode 120000 index 539e3143..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/security-checklist.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md b/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md deleted file mode 120000 index dff4db1b..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/static-networking-guide.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/storage.md b/ocp-admin/skills/cluster-inventory/docs/storage.md deleted file mode 120000 index f0d664da..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/storage.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md b/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md deleted file mode 120000 index 66df404a..00000000 --- a/ocp-admin/skills/cluster-inventory/docs/troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/troubleshooting.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/INDEX.md b/ocp-admin/skills/cluster-inventory/references/INDEX.md new file mode 120000 index 00000000..d582fa92 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/INDEX.md @@ -0,0 +1 @@ +../../cluster-creator/references/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/backup-restore.md b/ocp-admin/skills/cluster-inventory/references/backup-restore.md new file mode 120000 index 00000000..c627d992 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/backup-restore.md @@ -0,0 +1 @@ +../../cluster-creator/references/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/certificate-rotation.md b/ocp-admin/skills/cluster-inventory/references/certificate-rotation.md new file mode 120000 index 00000000..bd25a3cf --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/certificate-rotation.md @@ -0,0 +1 @@ +../../cluster-creator/references/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/credentials-management.md b/ocp-admin/skills/cluster-inventory/references/credentials-management.md new file mode 120000 index 00000000..52e9a700 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/credentials-management.md @@ -0,0 +1 @@ +../../cluster-creator/references/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/database-connection-management.md b/ocp-admin/skills/cluster-inventory/references/database-connection-management.md new file mode 120000 index 00000000..9a2c123b --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/database-connection-management.md @@ -0,0 +1 @@ +../../cluster-creator/references/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/day-2-operations.md b/ocp-admin/skills/cluster-inventory/references/day-2-operations.md new file mode 120000 index 00000000..dc14c9e0 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/day-2-operations.md @@ -0,0 +1 @@ +../../cluster-creator/references/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/etcd-maintenance.md b/ocp-admin/skills/cluster-inventory/references/etcd-maintenance.md new file mode 120000 index 00000000..fd707015 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/etcd-maintenance.md @@ -0,0 +1 @@ +../../cluster-creator/references/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/examples.md b/ocp-admin/skills/cluster-inventory/references/examples.md new file mode 120000 index 00000000..28a3e2b3 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/examples.md @@ -0,0 +1 @@ +../../cluster-creator/references/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/host-requirements.md b/ocp-admin/skills/cluster-inventory/references/host-requirements.md new file mode 120000 index 00000000..91fb23f5 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/host-requirements.md @@ -0,0 +1 @@ +../../cluster-creator/references/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/idp.md b/ocp-admin/skills/cluster-inventory/references/idp.md new file mode 120000 index 00000000..a8395abd --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/idp.md @@ -0,0 +1 @@ +../../cluster-creator/references/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/input-validation-guide.md b/ocp-admin/skills/cluster-inventory/references/input-validation-guide.md new file mode 120000 index 00000000..ebfabd0b --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/input-validation-guide.md @@ -0,0 +1 @@ +../../cluster-creator/references/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/multi-cluster-auth.md b/ocp-admin/skills/cluster-inventory/references/multi-cluster-auth.md new file mode 120000 index 00000000..979f44f0 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/multi-cluster-auth.md @@ -0,0 +1 @@ +../../cluster-report/references/multi-cluster-auth.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/networking.md b/ocp-admin/skills/cluster-inventory/references/networking.md new file mode 120000 index 00000000..660a296b --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/networking.md @@ -0,0 +1 @@ +../../cluster-creator/references/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/platforms.md b/ocp-admin/skills/cluster-inventory/references/platforms.md new file mode 120000 index 00000000..4cb1c7d8 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/platforms.md @@ -0,0 +1 @@ +../../cluster-creator/references/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/providers.md b/ocp-admin/skills/cluster-inventory/references/providers.md new file mode 120000 index 00000000..36adeed1 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/providers.md @@ -0,0 +1 @@ +../../cluster-creator/references/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/pvc-capacity-planning.md b/ocp-admin/skills/cluster-inventory/references/pvc-capacity-planning.md new file mode 120000 index 00000000..38621d65 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/pvc-capacity-planning.md @@ -0,0 +1 @@ +../../cluster-creator/references/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/quick-reference.md b/ocp-admin/skills/cluster-inventory/references/quick-reference.md new file mode 120000 index 00000000..1d1b2659 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/quick-reference.md @@ -0,0 +1 @@ +../../cluster-creator/references/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/rbac.md b/ocp-admin/skills/cluster-inventory/references/rbac.md new file mode 120000 index 00000000..9f1e9206 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/rbac.md @@ -0,0 +1 @@ +../../cluster-creator/references/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/security-checklist.md b/ocp-admin/skills/cluster-inventory/references/security-checklist.md new file mode 120000 index 00000000..d3ae4d2c --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/security-checklist.md @@ -0,0 +1 @@ +../../cluster-creator/references/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/static-networking-guide.md b/ocp-admin/skills/cluster-inventory/references/static-networking-guide.md new file mode 120000 index 00000000..bbced179 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/static-networking-guide.md @@ -0,0 +1 @@ +../../cluster-creator/references/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/storage.md b/ocp-admin/skills/cluster-inventory/references/storage.md new file mode 120000 index 00000000..9088a84f --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/storage.md @@ -0,0 +1 @@ +../../cluster-creator/references/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-inventory/references/troubleshooting.md b/ocp-admin/skills/cluster-inventory/references/troubleshooting.md new file mode 120000 index 00000000..3d3256d3 --- /dev/null +++ b/ocp-admin/skills/cluster-inventory/references/troubleshooting.md @@ -0,0 +1 @@ +../../cluster-creator/references/troubleshooting.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/SKILL.md b/ocp-admin/skills/cluster-report/SKILL.md index eae01917..6fb24415 100644 --- a/ocp-admin/skills/cluster-report/SKILL.md +++ b/ocp-admin/skills/cluster-report/SKILL.md @@ -60,7 +60,7 @@ This skill uses `openshift-administration` MCP server exclusively. This server p **Required Environment Variables**: `KUBECONFIG` — must contain at least one cluster context. Two or more recommended for comparison. -**Multi-Cluster Setup**: For large-scale deployments using service account tokens instead of interactive `oc login`, see [multi-cluster-auth.md](docs/multi-cluster-auth.md) and the [build-kubeconfig.py](scripts/build-kubeconfig.py) helper script. +**Multi-Cluster Setup**: For large-scale deployments using service account tokens instead of interactive `oc login`, see [multi-cluster-auth.md](references/multi-cluster-auth.md) and the [build-kubeconfig.py](scripts/build-kubeconfig.py) helper script. **Helper Scripts** (Python 3, stdlib only — auditable, do not reimplement): - [`assemble.py`](scripts/assemble.py) — resolves `$file` references into complete raw data JSON @@ -328,11 +328,11 @@ Render the structured JSON output as markdown using this template: ### Operational Alerts -⚠️ **etcd**: If any cluster reports etcd fragmentation ratio > 4.0 or DB size approaching quota, see [etcd-maintenance.md](docs/etcd-maintenance.md) for defragmentation procedure. +⚠️ **etcd**: If any cluster reports etcd fragmentation ratio > 4.0 or DB size approaching quota, see [etcd-maintenance.md](references/etcd-maintenance.md) for defragmentation procedure. -⚠️ **PVC Capacity**: If any PVC usage exceeds 80% or `predict_linear` forecasts capacity exhaustion within 24h, see [pvc-capacity-planning.md](docs/pvc-capacity-planning.md) for expansion workflow. +⚠️ **PVC Capacity**: If any PVC usage exceeds 80% or `predict_linear` forecasts capacity exhaustion within 24h, see [pvc-capacity-planning.md](references/pvc-capacity-planning.md) for expansion workflow. -⚠️ **Database Connections**: If PostgreSQL active connections exceed 80% of `max_connections`, see [database-connection-management.md](docs/database-connection-management.md) for saturation diagnosis and connection pooling. +⚠️ **Database Connections**: If PostgreSQL active connections exceed 80% of `max_connections`, see [database-connection-management.md](references/database-connection-management.md) for saturation diagnosis and connection pooling. ``` ### Step 5: Cleanup @@ -384,12 +384,12 @@ Would you like to: - `/cluster-inventory` - List and inspect individual clusters ### Reference Documentation -- [Credentials Management](docs/credentials-management.md) - KUBECONFIG setup and multi-cluster contexts -- [Multi-Cluster Auth](docs/multi-cluster-auth.md) - Service account token configuration for large deployments -- [etcd Maintenance](docs/etcd-maintenance.md) - Consult when etcd fragmentation ratio appears elevated in cluster metrics -- [PVC Capacity Planning](docs/pvc-capacity-planning.md) - Consult when PVC usage is high or approaching capacity -- [Database Connection Management](docs/database-connection-management.md) - Consult when PostgreSQL connection usage is high -- **[Documentation Index](docs/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) +- [Credentials Management](references/credentials-management.md) - KUBECONFIG setup and multi-cluster contexts +- [Multi-Cluster Auth](references/multi-cluster-auth.md) - Service account token configuration for large deployments +- [etcd Maintenance](references/etcd-maintenance.md) - Consult when etcd fragmentation ratio appears elevated in cluster metrics +- [PVC Capacity Planning](references/pvc-capacity-planning.md) - Consult when PVC usage is high or approaching capacity +- [Database Connection Management](references/database-connection-management.md) - Consult when PostgreSQL connection usage is high +- **[Documentation Index](references/INDEX.md)** - Complete guide to all ocp-admin documentation (consult for topics not explicitly referenced above) ## Error Handling diff --git a/ocp-admin/skills/cluster-report/docs/INDEX.md b/ocp-admin/skills/cluster-report/docs/INDEX.md deleted file mode 120000 index dc8236cf..00000000 --- a/ocp-admin/skills/cluster-report/docs/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/backup-restore.md b/ocp-admin/skills/cluster-report/docs/backup-restore.md deleted file mode 120000 index 69a2c4d7..00000000 --- a/ocp-admin/skills/cluster-report/docs/backup-restore.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/certificate-rotation.md b/ocp-admin/skills/cluster-report/docs/certificate-rotation.md deleted file mode 120000 index f24dab8f..00000000 --- a/ocp-admin/skills/cluster-report/docs/certificate-rotation.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/credentials-management.md b/ocp-admin/skills/cluster-report/docs/credentials-management.md deleted file mode 120000 index 3a168f1e..00000000 --- a/ocp-admin/skills/cluster-report/docs/credentials-management.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/database-connection-management.md b/ocp-admin/skills/cluster-report/docs/database-connection-management.md deleted file mode 120000 index 5cd634fe..00000000 --- a/ocp-admin/skills/cluster-report/docs/database-connection-management.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/day-2-operations.md b/ocp-admin/skills/cluster-report/docs/day-2-operations.md deleted file mode 120000 index f81391c7..00000000 --- a/ocp-admin/skills/cluster-report/docs/day-2-operations.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md b/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md deleted file mode 120000 index 0ac3e5a8..00000000 --- a/ocp-admin/skills/cluster-report/docs/etcd-maintenance.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/examples.md b/ocp-admin/skills/cluster-report/docs/examples.md deleted file mode 120000 index ff790b2e..00000000 --- a/ocp-admin/skills/cluster-report/docs/examples.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/host-requirements.md b/ocp-admin/skills/cluster-report/docs/host-requirements.md deleted file mode 120000 index 940ac361..00000000 --- a/ocp-admin/skills/cluster-report/docs/host-requirements.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/idp.md b/ocp-admin/skills/cluster-report/docs/idp.md deleted file mode 120000 index 6ff039bc..00000000 --- a/ocp-admin/skills/cluster-report/docs/idp.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/input-validation-guide.md b/ocp-admin/skills/cluster-report/docs/input-validation-guide.md deleted file mode 120000 index 7fe632b8..00000000 --- a/ocp-admin/skills/cluster-report/docs/input-validation-guide.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/networking.md b/ocp-admin/skills/cluster-report/docs/networking.md deleted file mode 120000 index 74cf579c..00000000 --- a/ocp-admin/skills/cluster-report/docs/networking.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/platforms.md b/ocp-admin/skills/cluster-report/docs/platforms.md deleted file mode 120000 index 1705928b..00000000 --- a/ocp-admin/skills/cluster-report/docs/platforms.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/providers.md b/ocp-admin/skills/cluster-report/docs/providers.md deleted file mode 120000 index a9736c66..00000000 --- a/ocp-admin/skills/cluster-report/docs/providers.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md b/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md deleted file mode 120000 index fc0f73fc..00000000 --- a/ocp-admin/skills/cluster-report/docs/pvc-capacity-planning.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/quick-reference.md b/ocp-admin/skills/cluster-report/docs/quick-reference.md deleted file mode 120000 index 19cf9f54..00000000 --- a/ocp-admin/skills/cluster-report/docs/quick-reference.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/rbac.md b/ocp-admin/skills/cluster-report/docs/rbac.md deleted file mode 120000 index 19e4d531..00000000 --- a/ocp-admin/skills/cluster-report/docs/rbac.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/security-checklist.md b/ocp-admin/skills/cluster-report/docs/security-checklist.md deleted file mode 120000 index 539e3143..00000000 --- a/ocp-admin/skills/cluster-report/docs/security-checklist.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/static-networking-guide.md b/ocp-admin/skills/cluster-report/docs/static-networking-guide.md deleted file mode 120000 index dff4db1b..00000000 --- a/ocp-admin/skills/cluster-report/docs/static-networking-guide.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/storage.md b/ocp-admin/skills/cluster-report/docs/storage.md deleted file mode 120000 index f0d664da..00000000 --- a/ocp-admin/skills/cluster-report/docs/storage.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/troubleshooting.md b/ocp-admin/skills/cluster-report/docs/troubleshooting.md deleted file mode 120000 index 66df404a..00000000 --- a/ocp-admin/skills/cluster-report/docs/troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../cluster-creator/docs/troubleshooting.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/INDEX.md b/ocp-admin/skills/cluster-report/references/INDEX.md new file mode 120000 index 00000000..d582fa92 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/INDEX.md @@ -0,0 +1 @@ +../../cluster-creator/references/INDEX.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/backup-restore.md b/ocp-admin/skills/cluster-report/references/backup-restore.md new file mode 120000 index 00000000..c627d992 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/backup-restore.md @@ -0,0 +1 @@ +../../cluster-creator/references/backup-restore.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/certificate-rotation.md b/ocp-admin/skills/cluster-report/references/certificate-rotation.md new file mode 120000 index 00000000..bd25a3cf --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/certificate-rotation.md @@ -0,0 +1 @@ +../../cluster-creator/references/certificate-rotation.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/credentials-management.md b/ocp-admin/skills/cluster-report/references/credentials-management.md new file mode 120000 index 00000000..52e9a700 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/credentials-management.md @@ -0,0 +1 @@ +../../cluster-creator/references/credentials-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/database-connection-management.md b/ocp-admin/skills/cluster-report/references/database-connection-management.md new file mode 120000 index 00000000..9a2c123b --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/database-connection-management.md @@ -0,0 +1 @@ +../../cluster-creator/references/database-connection-management.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/day-2-operations.md b/ocp-admin/skills/cluster-report/references/day-2-operations.md new file mode 120000 index 00000000..dc14c9e0 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/day-2-operations.md @@ -0,0 +1 @@ +../../cluster-creator/references/day-2-operations.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/etcd-maintenance.md b/ocp-admin/skills/cluster-report/references/etcd-maintenance.md new file mode 120000 index 00000000..fd707015 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/etcd-maintenance.md @@ -0,0 +1 @@ +../../cluster-creator/references/etcd-maintenance.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/examples.md b/ocp-admin/skills/cluster-report/references/examples.md new file mode 120000 index 00000000..28a3e2b3 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/examples.md @@ -0,0 +1 @@ +../../cluster-creator/references/examples.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/host-requirements.md b/ocp-admin/skills/cluster-report/references/host-requirements.md new file mode 120000 index 00000000..91fb23f5 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/host-requirements.md @@ -0,0 +1 @@ +../../cluster-creator/references/host-requirements.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/idp.md b/ocp-admin/skills/cluster-report/references/idp.md new file mode 120000 index 00000000..a8395abd --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/idp.md @@ -0,0 +1 @@ +../../cluster-creator/references/idp.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/input-validation-guide.md b/ocp-admin/skills/cluster-report/references/input-validation-guide.md new file mode 120000 index 00000000..ebfabd0b --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/input-validation-guide.md @@ -0,0 +1 @@ +../../cluster-creator/references/input-validation-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/docs/multi-cluster-auth.md b/ocp-admin/skills/cluster-report/references/multi-cluster-auth.md similarity index 100% rename from ocp-admin/skills/cluster-report/docs/multi-cluster-auth.md rename to ocp-admin/skills/cluster-report/references/multi-cluster-auth.md diff --git a/ocp-admin/skills/cluster-report/references/networking.md b/ocp-admin/skills/cluster-report/references/networking.md new file mode 120000 index 00000000..660a296b --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/networking.md @@ -0,0 +1 @@ +../../cluster-creator/references/networking.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/platforms.md b/ocp-admin/skills/cluster-report/references/platforms.md new file mode 120000 index 00000000..4cb1c7d8 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/platforms.md @@ -0,0 +1 @@ +../../cluster-creator/references/platforms.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/providers.md b/ocp-admin/skills/cluster-report/references/providers.md new file mode 120000 index 00000000..36adeed1 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/providers.md @@ -0,0 +1 @@ +../../cluster-creator/references/providers.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/pvc-capacity-planning.md b/ocp-admin/skills/cluster-report/references/pvc-capacity-planning.md new file mode 120000 index 00000000..38621d65 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/pvc-capacity-planning.md @@ -0,0 +1 @@ +../../cluster-creator/references/pvc-capacity-planning.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/quick-reference.md b/ocp-admin/skills/cluster-report/references/quick-reference.md new file mode 120000 index 00000000..1d1b2659 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/quick-reference.md @@ -0,0 +1 @@ +../../cluster-creator/references/quick-reference.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/rbac.md b/ocp-admin/skills/cluster-report/references/rbac.md new file mode 120000 index 00000000..9f1e9206 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/rbac.md @@ -0,0 +1 @@ +../../cluster-creator/references/rbac.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/security-checklist.md b/ocp-admin/skills/cluster-report/references/security-checklist.md new file mode 120000 index 00000000..d3ae4d2c --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/security-checklist.md @@ -0,0 +1 @@ +../../cluster-creator/references/security-checklist.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/static-networking-guide.md b/ocp-admin/skills/cluster-report/references/static-networking-guide.md new file mode 120000 index 00000000..bbced179 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/static-networking-guide.md @@ -0,0 +1 @@ +../../cluster-creator/references/static-networking-guide.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/storage.md b/ocp-admin/skills/cluster-report/references/storage.md new file mode 120000 index 00000000..9088a84f --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/storage.md @@ -0,0 +1 @@ +../../cluster-creator/references/storage.md \ No newline at end of file diff --git a/ocp-admin/skills/cluster-report/references/troubleshooting.md b/ocp-admin/skills/cluster-report/references/troubleshooting.md new file mode 120000 index 00000000..3d3256d3 --- /dev/null +++ b/ocp-admin/skills/cluster-report/references/troubleshooting.md @@ -0,0 +1 @@ +../../cluster-creator/references/troubleshooting.md \ No newline at end of file diff --git a/rh-ai-engineer/README.md b/rh-ai-engineer/README.md index ff8ee5f8..461709a9 100644 --- a/rh-ai-engineer/README.md +++ b/rh-ai-engineer/README.md @@ -72,7 +72,7 @@ export AI_OBSERVABILITY_MCP_URL=https://$(oc get route aiobs-mcp-server-route -n | NVIDIA NIM | Optimized inference with TensorRT-LLM on NVIDIA GPUs | `/nim-setup` | | Caikit+TGIS | Models in Caikit format with gRPC API | Model conversion | -See [supported-runtimes.md](skills/serving-runtime-config/docs/references/supported-runtimes.md) for detailed runtime comparison. +See [supported-runtimes.md](skills/serving-runtime-config/references/supported-runtimes.md) for detailed runtime comparison. ## Supported Models @@ -86,4 +86,4 @@ Common models with known hardware profiles: | Mixtral 8x7B | 46.7B MoE | 2x A100 80GB | vLLM | | Mistral 7B | 7B | 1x (16GB VRAM) | vLLM | -See [known-model-profiles.md](skills/model-deploy/docs/references/known-model-profiles.md) for full profiles. Models not listed are supported via live documentation lookup. +See [known-model-profiles.md](skills/model-deploy/references/known-model-profiles.md) for full profiles. Models not listed are supported via live documentation lookup. diff --git a/rh-ai-engineer/skills/ai-observability/SKILL.md b/rh-ai-engineer/skills/ai-observability/SKILL.md index e5e9a502..03fcacdb 100644 --- a/rh-ai-engineer/skills/ai-observability/SKILL.md +++ b/rh-ai-engineer/skills/ai-observability/SKILL.md @@ -411,8 +411,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/model-monitor` - TrustyAI bias/drift metrics (complements infrastructure observability) ### Reference Documentation -- [known-model-profiles.md](docs/references/known-model-profiles.md) - Expected performance baselines for common models -- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and known limitations +- [known-model-profiles.md](references/known-model-profiles.md) - Expected performance baselines for common models +- [supported-runtimes.md](references/supported-runtimes.md) - Runtime capabilities and known limitations ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md deleted file mode 120000 index b4dea51f..00000000 --- a/rh-ai-engineer/skills/ai-observability/docs/references/known-model-profiles.md +++ /dev/null @@ -1 +0,0 @@ -../../../model-deploy/docs/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md deleted file mode 120000 index 024ac933..00000000 --- a/rh-ai-engineer/skills/ai-observability/docs/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md deleted file mode 120000 index 38211dbf..00000000 --- a/rh-ai-engineer/skills/ai-observability/docs/references/supported-runtimes.md +++ /dev/null @@ -1 +0,0 @@ -../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/references/common-issues.md b/rh-ai-engineer/skills/ai-observability/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/ai-observability/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/references/common-issues.md b/rh-ai-engineer/skills/ai-observability/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/ai-observability/references/known-model-profiles.md b/rh-ai-engineer/skills/ai-observability/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md b/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md b/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/ai-observability/references/supported-runtimes.md b/rh-ai-engineer/skills/ai-observability/references/supported-runtimes.md new file mode 120000 index 00000000..9d3eaa3d --- /dev/null +++ b/rh-ai-engineer/skills/ai-observability/references/supported-runtimes.md @@ -0,0 +1 @@ +../../serving-runtime-config/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/SKILL.md b/rh-ai-engineer/skills/debug-inference/SKILL.md index 580ef4bb..3cbcbdf0 100644 --- a/rh-ai-engineer/skills/debug-inference/SKILL.md +++ b/rh-ai-engineer/skills/debug-inference/SKILL.md @@ -342,8 +342,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/model-monitor` - Check if TrustyAI monitoring detected issues before they became failures ### Reference Documentation -- [known-model-profiles.md](docs/references/known-model-profiles.md) - Correct resource sizing for common models -- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and known limitations +- [known-model-profiles.md](references/known-model-profiles.md) - Correct resource sizing for common models +- [supported-runtimes.md](references/supported-runtimes.md) - Runtime capabilities and known limitations - [live-doc-lookup.md](references/live-doc-lookup.md) - Protocol for looking up unrecognized errors ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md deleted file mode 120000 index b4dea51f..00000000 --- a/rh-ai-engineer/skills/debug-inference/docs/references/known-model-profiles.md +++ /dev/null @@ -1 +0,0 @@ -../../../model-deploy/docs/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md deleted file mode 120000 index 024ac933..00000000 --- a/rh-ai-engineer/skills/debug-inference/docs/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md deleted file mode 120000 index 38211dbf..00000000 --- a/rh-ai-engineer/skills/debug-inference/docs/references/supported-runtimes.md +++ /dev/null @@ -1 +0,0 @@ -../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/references/common-issues.md b/rh-ai-engineer/skills/debug-inference/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/debug-inference/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/references/common-issues.md b/rh-ai-engineer/skills/debug-inference/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/debug-inference/references/known-model-profiles.md b/rh-ai-engineer/skills/debug-inference/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md b/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md b/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/debug-inference/references/supported-runtimes.md b/rh-ai-engineer/skills/debug-inference/references/supported-runtimes.md new file mode 120000 index 00000000..9d3eaa3d --- /dev/null +++ b/rh-ai-engineer/skills/debug-inference/references/supported-runtimes.md @@ -0,0 +1 @@ +../../serving-runtime-config/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md b/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md b/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/ds-project-setup/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/ds-project-setup/references/known-model-profiles.md b/rh-ai-engineer/skills/ds-project-setup/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/ds-project-setup/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md b/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md b/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/ds-project-setup/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/guardrails-config/references/common-issues.md b/rh-ai-engineer/skills/guardrails-config/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/guardrails-config/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/guardrails-config/references/common-issues.md b/rh-ai-engineer/skills/guardrails-config/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/guardrails-config/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/guardrails-config/references/known-model-profiles.md b/rh-ai-engineer/skills/guardrails-config/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/guardrails-config/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md b/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md b/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/guardrails-config/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/model-deploy/SKILL.md b/rh-ai-engineer/skills/model-deploy/SKILL.md index f191eaa6..8ff48b6a 100644 --- a/rh-ai-engineer/skills/model-deploy/SKILL.md +++ b/rh-ai-engineer/skills/model-deploy/SKILL.md @@ -129,8 +129,8 @@ After the environment is validated, collect remaining deployment configuration. ### Step 3: Determine Runtime **Document Consultation** (read before selecting runtime): -1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand runtime capabilities and selection criteria -2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand runtime capabilities." +1. **Action**: Read [supported-runtimes.md](references/supported-runtimes.md) using the Read tool to understand runtime capabilities and selection criteria +2. **Output to user**: "I consulted [supported-runtimes.md](references/supported-runtimes.md) to understand runtime capabilities." **Runtime Selection Logic:** @@ -145,8 +145,8 @@ After the environment is validated, collect remaining deployment configuration. ### Step 4: Look Up Model Hardware Profile **Document Consultation** (read before determining hardware requirements): -1. **Action**: Read [known-model-profiles.md](docs/references/known-model-profiles.md) using the Read tool to find hardware profile for the requested model -2. **Output to user**: "I consulted [known-model-profiles.md](docs/references/known-model-profiles.md) to find hardware requirements for [model-name]." +1. **Action**: Read [known-model-profiles.md](references/known-model-profiles.md) using the Read tool to find hardware profile for the requested model +2. **Output to user**: "I consulted [known-model-profiles.md](references/known-model-profiles.md) to find hardware requirements for [model-name]." **If model IS in known-model-profiles.md:** - Extract: GPU count, GPU type, VRAM, key vLLM args @@ -441,8 +441,8 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/guardrails-config` - Add content safety guardrails to LLM deployments ### Reference Documentation -- [known-model-profiles.md](docs/references/known-model-profiles.md) - Hardware profiles for common models -- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and selection criteria +- [known-model-profiles.md](references/known-model-profiles.md) - Hardware profiles for common models +- [supported-runtimes.md](references/supported-runtimes.md) - Runtime capabilities and selection criteria - [live-doc-lookup.md](references/live-doc-lookup.md) - Protocol for fetching specs for unknown models ## Critical: Human-in-the-Loop Requirements @@ -459,4 +459,4 @@ See [skill-conventions.md](references/skill-conventions.md) for general HITL and ## Example Usage -See [model-deploy examples](docs/examples/model-deploy.md) for complete deployment walkthroughs (vLLM and NIM). +See [model-deploy examples](references/examples/model-deploy.md) for complete deployment walkthroughs (vLLM and NIM). diff --git a/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md deleted file mode 120000 index 024ac933..00000000 --- a/rh-ai-engineer/skills/model-deploy/docs/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md deleted file mode 120000 index 38211dbf..00000000 --- a/rh-ai-engineer/skills/model-deploy/docs/references/supported-runtimes.md +++ /dev/null @@ -1 +0,0 @@ -../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/references/common-issues.md b/rh-ai-engineer/skills/model-deploy/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/model-deploy/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/references/common-issues.md b/rh-ai-engineer/skills/model-deploy/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/model-deploy/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/model-deploy/docs/examples/model-deploy.md b/rh-ai-engineer/skills/model-deploy/references/examples/model-deploy.md similarity index 100% rename from rh-ai-engineer/skills/model-deploy/docs/examples/model-deploy.md rename to rh-ai-engineer/skills/model-deploy/references/examples/model-deploy.md diff --git a/rh-ai-engineer/skills/model-deploy/docs/references/known-model-profiles.md b/rh-ai-engineer/skills/model-deploy/references/known-model-profiles.md similarity index 100% rename from rh-ai-engineer/skills/model-deploy/docs/references/known-model-profiles.md rename to rh-ai-engineer/skills/model-deploy/references/known-model-profiles.md diff --git a/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/model-deploy/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/model-deploy/references/supported-runtimes.md b/rh-ai-engineer/skills/model-deploy/references/supported-runtimes.md new file mode 120000 index 00000000..9d3eaa3d --- /dev/null +++ b/rh-ai-engineer/skills/model-deploy/references/supported-runtimes.md @@ -0,0 +1 @@ +../../serving-runtime-config/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-monitor/references/common-issues.md b/rh-ai-engineer/skills/model-monitor/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/model-monitor/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-monitor/references/common-issues.md b/rh-ai-engineer/skills/model-monitor/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/model-monitor/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/model-monitor/references/known-model-profiles.md b/rh-ai-engineer/skills/model-monitor/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/model-monitor/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/model-monitor/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/model-registry/references/common-issues.md b/rh-ai-engineer/skills/model-registry/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/model-registry/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-registry/references/common-issues.md b/rh-ai-engineer/skills/model-registry/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/model-registry/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/model-registry/references/known-model-profiles.md b/rh-ai-engineer/skills/model-registry/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/model-registry/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md b/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/model-registry/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/nim-setup/SKILL.md b/rh-ai-engineer/skills/nim-setup/SKILL.md index a877ef49..b6c4313a 100644 --- a/rh-ai-engineer/skills/nim-setup/SKILL.md +++ b/rh-ai-engineer/skills/nim-setup/SKILL.md @@ -81,8 +81,8 @@ If `rhoai` MCP is not available, skip this check and proceed. ### Step 1: Verify GPU Operator and Node Feature Discovery **Document Consultation** (read before verifying operators): -1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand NIM platform requirements -2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand NIM platform requirements." +1. **Action**: Read [supported-runtimes.md](references/supported-runtimes.md) using the Read tool to understand NIM platform requirements +2. **Output to user**: "I consulted [supported-runtimes.md](references/supported-runtimes.md) to understand NIM platform requirements." Check that the NVIDIA GPU Operator and NFD Operator are installed and healthy. @@ -363,7 +363,7 @@ When handing off to `/model-deploy` after NIM setup, note these NIM-specific con - **GPU tolerations**: GPU nodes are almost always tainted in production. `/model-deploy` will automatically detect and add tolerations after deployment. ### Reference Documentation -- [supported-runtimes.md](docs/references/supported-runtimes.md) - NIM runtime capabilities and requirements +- [supported-runtimes.md](references/supported-runtimes.md) - NIM runtime capabilities and requirements - [live-doc-lookup.md](references/live-doc-lookup.md) - Protocol for fetching current RHOAI/NIM documentation ## Critical: Human-in-the-Loop Requirements @@ -378,4 +378,4 @@ See [skill-conventions.md](references/skill-conventions.md) for general HITL and ## Example Usage -See [nim-setup examples](docs/examples/nim-setup.md) for a complete first-time NIM setup walkthrough. +See [nim-setup examples](references/examples/nim-setup.md) for a complete first-time NIM setup walkthrough. diff --git a/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md deleted file mode 120000 index 38211dbf..00000000 --- a/rh-ai-engineer/skills/nim-setup/docs/references/supported-runtimes.md +++ /dev/null @@ -1 +0,0 @@ -../../../serving-runtime-config/docs/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/nim-setup/references/common-issues.md b/rh-ai-engineer/skills/nim-setup/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/nim-setup/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/nim-setup/references/common-issues.md b/rh-ai-engineer/skills/nim-setup/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/nim-setup/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/nim-setup/docs/examples/nim-setup.md b/rh-ai-engineer/skills/nim-setup/references/examples/nim-setup.md similarity index 100% rename from rh-ai-engineer/skills/nim-setup/docs/examples/nim-setup.md rename to rh-ai-engineer/skills/nim-setup/references/examples/nim-setup.md diff --git a/rh-ai-engineer/skills/nim-setup/references/known-model-profiles.md b/rh-ai-engineer/skills/nim-setup/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/nim-setup/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md b/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md b/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/nim-setup/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/nim-setup/references/supported-runtimes.md b/rh-ai-engineer/skills/nim-setup/references/supported-runtimes.md new file mode 120000 index 00000000..9d3eaa3d --- /dev/null +++ b/rh-ai-engineer/skills/nim-setup/references/supported-runtimes.md @@ -0,0 +1 @@ +../../serving-runtime-config/references/supported-runtimes.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md b/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md b/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/pipeline-manage/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/pipeline-manage/references/known-model-profiles.md b/rh-ai-engineer/skills/pipeline-manage/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/pipeline-manage/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md b/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md b/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/pipeline-manage/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/references/common-issues.md b/rh-ai-engineer/skills/references/common-issues.md index 6b4b82d4..0b2da954 100644 --- a/rh-ai-engineer/skills/references/common-issues.md +++ b/rh-ai-engineer/skills/references/common-issues.md @@ -39,7 +39,7 @@ Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. In 2. Reduce `--max-model-len` to lower KV cache memory usage 3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint 4. Verify GPU VRAM is sufficient using `get_gpu_info` -5. Consult [known-model-profiles.md](../../docs/references/known-model-profiles.md) for correct resource sizing +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing ## Image Pull Error from nvcr.io (NIM) diff --git a/rh-ai-engineer/skills/serving-runtime-config/SKILL.md b/rh-ai-engineer/skills/serving-runtime-config/SKILL.md index f2d29b55..3049faaa 100644 --- a/rh-ai-engineer/skills/serving-runtime-config/SKILL.md +++ b/rh-ai-engineer/skills/serving-runtime-config/SKILL.md @@ -87,8 +87,8 @@ Verify the user-specified namespace is an RHOAI Data Science Project. - **Intent**: New runtime from scratch, or customize an existing one? **Document Consultation** (read before listing runtimes): -1. **Action**: Read [supported-runtimes.md](docs/references/supported-runtimes.md) using the Read tool to understand available runtimes and their capabilities -2. **Output to user**: "I consulted [supported-runtimes.md](docs/references/supported-runtimes.md) to understand available runtimes." +1. **Action**: Read [supported-runtimes.md](references/supported-runtimes.md) using the Read tool to understand available runtimes and their capabilities +2. **Output to user**: "I consulted [supported-runtimes.md](references/supported-runtimes.md) to understand available runtimes." **MCP Tool**: `list_serving_runtimes` (from rhoai) @@ -290,7 +290,7 @@ See [Prerequisites](#prerequisites) for the complete list of required and option - `/debug-inference` - Troubleshoot InferenceService failures after deployment ### Reference Documentation -- [supported-runtimes.md](docs/references/supported-runtimes.md) - Runtime capabilities and model format names +- [supported-runtimes.md](references/supported-runtimes.md) - Runtime capabilities and model format names - [live-doc-lookup.md](references/live-doc-lookup.md) - Protocol for fetching specs for unknown frameworks ## Critical: Human-in-the-Loop Requirements diff --git a/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md b/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md b/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/serving-runtime-config/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/serving-runtime-config/references/known-model-profiles.md b/rh-ai-engineer/skills/serving-runtime-config/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/serving-runtime-config/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md b/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md b/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/serving-runtime-config/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-ai-engineer/skills/serving-runtime-config/docs/references/supported-runtimes.md b/rh-ai-engineer/skills/serving-runtime-config/references/supported-runtimes.md similarity index 100% rename from rh-ai-engineer/skills/serving-runtime-config/docs/references/supported-runtimes.md rename to rh-ai-engineer/skills/serving-runtime-config/references/supported-runtimes.md diff --git a/rh-ai-engineer/skills/workbench-manage/references/common-issues.md b/rh-ai-engineer/skills/workbench-manage/references/common-issues.md deleted file mode 120000 index 6f75f48d..00000000 --- a/rh-ai-engineer/skills/workbench-manage/references/common-issues.md +++ /dev/null @@ -1 +0,0 @@ -../../references/common-issues.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/workbench-manage/references/common-issues.md b/rh-ai-engineer/skills/workbench-manage/references/common-issues.md new file mode 100644 index 00000000..0b2da954 --- /dev/null +++ b/rh-ai-engineer/skills/workbench-manage/references/common-issues.md @@ -0,0 +1,183 @@ +--- +title: Common Issues Across Skills +category: references +tags: [troubleshooting, gpu, oom, image-pull, rbac, common-issues, rhoai-mcp, tolerations, notebook-images, pipeline-server] +semantic_keywords: [GPU scheduling failure, OOMKilled, image pull error, RBAC permissions, common deployment errors, RHOAI MCP authentication, notebook image mismatch, model registry DNS, GPU tolerations, dangerous operations disabled] +use_cases: [model-deploy, debug-inference, workbench-manage, nim-setup, serving-runtime-config, ds-project-setup, pipeline-manage, model-registry, guardrails-config, model-monitor] +last_updated: 2026-03-23 +--- + +# Common Issues Across Skills + +Shared troubleshooting patterns that apply to multiple rh-ai-engineer skills. Individual skills reference this document and add skill-specific issues inline. + +## GPU Scheduling Failure + +**Applies to**: `/model-deploy`, `/debug-inference`, `/workbench-manage`, `/guardrails-config` + +**Error**: Pod stuck in Pending with events showing "Insufficient nvidia.com/gpu" + +**Cause**: Cluster does not have enough available GPUs of the required type. + +**Solution:** +1. Check GPU availability: `get_gpu_info` from ai-observability (if available) or inspect node resources via `resources_get` +2. Reduce GPU request or use a quantized model variant +3. Check if other workloads are consuming GPU resources +4. Verify GPU Operator and NFD Operator are healthy +5. Consider using fewer GPUs with `--tensor-parallel-size` reduction and quantization + +## OOMKilled During Model or Workbench Loading + +**Applies to**: `/model-deploy`, `/debug-inference`, `/guardrails-config` + +**Error**: Pod terminated with OOMKilled exit code, often during initial model weight loading + +**Cause**: Model requires more memory than allocated in resource requests/limits. Common with large models or when `--max-model-len` is set too high. + +**Solution:** +1. Increase memory limits in the InferenceService or workbench spec +2. Reduce `--max-model-len` to lower KV cache memory usage +3. Use a quantized model variant (AWQ/GPTQ/FP8) to reduce memory footprint +4. Verify GPU VRAM is sufficient using `get_gpu_info` +5. Consult [known-model-profiles.md](known-model-profiles.md) for correct resource sizing + +## Image Pull Error from nvcr.io (NIM) + +**Applies to**: `/model-deploy`, `/nim-setup` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` for NIM container images referencing `nvcr.io` + +**Cause**: NGC image pull secret is missing, expired, or not in the correct namespace. + +**Solution:** +1. Verify NGC pull secret exists in the target namespace: `resources_get` for the secret +2. Check that the secret contains valid docker credentials for `nvcr.io` +3. Re-run `/nim-setup` to recreate credentials with a fresh NGC API key +4. Ensure the secret is referenced by the ServiceAccount or Account CR + +## Image Pull Error from OCI Registries + +**Applies to**: `/model-deploy`, `/serving-runtime-config` + +**Error**: Pod fails with `ErrImagePull` or `ImagePullBackOff` with `unauthorized` message for `registry.redhat.io/rhelai1/*` or custom container images + +**Cause**: OCI model images or custom container images require authentication credentials not available in the namespace. + +**Solution:** +1. For `registry.redhat.io/rhelai1/*` models: switch to HuggingFace source (`hf://`) which requires no authentication -- this is the recommended default for public models +2. If OCI source is required: verify entitlements are included in the pull secret +3. For custom images: create an image pull secret and link it to the default ServiceAccount (`oc secrets link default --for=pull`) +4. Verify the image URI and tag are correct + +## RBAC / Permission Errors + +**Applies to**: All skills that create or modify Kubernetes resources (including `/model-monitor`, `/guardrails-config`) + +**Error**: API call returns 403 Forbidden or "insufficient permissions" message + +**Cause**: The service account or user credentials in KUBECONFIG lack the required RBAC roles for the target resource type and namespace. + +**Solution:** +1. Report the specific permission error to the user +2. Identify the required role: which API group, resource, and verb is needed +3. Suggest contacting the cluster administrator to grant the necessary RoleBinding or ClusterRoleBinding +4. For namespace-scoped operations: verify the user has at least `edit` role in the target namespace + +## RHOAI MCP Authentication Failures + +**Applies to**: All skills that use RHOAI MCP tools + +**Error**: RHOAI MCP tools return "Unauthorized" (HTTP 401/403) for most operations + +**Cause**: The RHOAI MCP server may use a different authentication mechanism than the user's `oc` token, or the token may have expired. This was observed to cause a 78% failure rate across RHOAI tool calls in testing. + +**Solution:** +1. Skills attempt OpenShift MCP fallback automatically when RHOAI tools fail +2. **Inform the user** about the auth failure and suggest verifying their token: + - "Note: RHOAI tool returned Unauthorized. Falling back to OpenShift direct API. If you experience further issues, try `oc login` to refresh your token." +3. If you want to restore RHOAI MCP functionality: + - Re-login with `oc login` to refresh the token + - Verify `RHOAI_MCP_KUBECONFIG_PATH` points to a valid, current kubeconfig + - Restart Claude Code to reload MCP server connections +3. All RHOAI operations have OpenShift equivalents — see [openshift-fallback-templates.md](openshift-fallback-templates.md) + +## RHOAI MCP API Inconsistencies + +**Applies to**: `/ds-project-setup`, `/workbench-manage`, `/pipeline-manage` + +**Error**: Various RHOAI MCP tool failures: +- `get_project_details` requires `name` parameter but agent may pass `namespace` +- `manage_resource(action=stop)` returns "Unsupported Media Type" +- `create_pipeline_server` returns "Unprocessable Entity" (invalid DSPA manifest) + +**Cause**: RHOAI MCP tool parameter naming differs from Kubernetes conventions, and some tools construct invalid resource manifests. + +**Solution:** +1. `get_project_details`: Always use the `name` parameter (not `namespace`). On error, fall back to `resources_get` for the Namespace. +2. `manage_resource(stop/start)`: Use the annotation-patch fallback — patch the Notebook CR annotation `kubeflow-resource-stopped` via OpenShift MCP. +3. `create_pipeline_server`: **Do not use this tool.** Always create DSPA CRs directly via `resources_create_or_update` with the correct YAML template from [openshift-fallback-templates.md](openshift-fallback-templates.md#datasciencepipelinesapplication-dspa). + +## Notebook Image Names Mismatch + +**Applies to**: `/workbench-manage` + +**Error**: `list_notebook_images` (from rhoai) returns image names like `jupyter-pytorch-notebook:2024.1` that don't exist in the internal registry. The actual ImageStream is named `pytorch` (not `jupyter-pytorch-notebook`). + +**Cause**: The RHOAI MCP tool returns hardcoded display names instead of the actual ImageStream names from the cluster. + +**Solution:** +- **Do not use `list_notebook_images`.** This tool is permanently replaced. +- Use the ImageStream lookup pattern via OpenShift MCP: + 1. `resources_list` ImageStreams in `redhat-ods-applications` namespace with label `opendatahub.io/notebook-image=true` + 2. `resources_get` each ImageStream to extract actual tag names and image references +- See [openshift-fallback-templates.md](openshift-fallback-templates.md#notebook-image-discovery-imagestream-lookup) for the complete pattern. + +## Model Registry Internal DNS Unreachable + +**Applies to**: `/model-registry` + +**Error**: `list_registered_models` and other Model Registry RHOAI tools fail with connection errors or return 404 + +**Cause**: The RHOAI MCP server runs outside the cluster and cannot resolve cluster-internal DNS names (e.g., `modelregistry-sample.rhoai-model-registries.svc.cluster.local`). Additionally, external routes may be behind an OAuth proxy. + +**Solution:** +1. Check if an external Route exists for the model registry: `resources_list` Routes in the model registry namespace +2. If no Route exists, set up port-forwarding: `oc port-forward svc/modelregistry-sample 8085:8085 -n rhoai-model-registries` +3. If an OAuth proxy blocks the Route, obtain a token via `oc whoami -t` and pass it as a Bearer token +4. For registry CRUD operations, use `resources_create_or_update` / `resources_get` / `resources_list` via OpenShift MCP for RegisteredModel, ModelVersion, and ModelArtifact CRs + +## Deploy Model Missing GPU Tolerations + +**Applies to**: `/model-deploy`, `/debug-inference` + +**Error**: Model pod stuck in Pending state after `deploy_model` succeeds. Events show "0/N nodes are available: ... node(s) had untolerated taint" + +**Cause**: The `deploy_model` RHOAI tool does not accept toleration or nodeSelector parameters. In production clusters, GPU nodes are almost always tainted (common taints: `nvidia.com/gpu`, `ai-app=true`, `ai-node=big`). + +**Solution:** +1. After `deploy_model` completes, check GPU node taints: `resources_list` Nodes with label `nvidia.com/gpu.present=true` +2. If taints are found, patch the InferenceService to add tolerations via `resources_create_or_update`: + ```yaml + spec: + predictor: + tolerations: + - key: "nvidia.com/gpu" + operator: "Exists" + effect: "NoSchedule" + # Add cluster-specific taints discovered from node inspection + ``` +3. Delete the stuck pod to force rescheduling with new tolerations +4. See [openshift-fallback-templates.md](openshift-fallback-templates.md#toleration-post-deploy-patch) for the complete pattern + +## Dangerous Operations Disabled in RHOAI MCP + +**Applies to**: `/workbench-manage` + +**Error**: `delete_workbench` and `manage_resource(action=delete)` return "Dangerous operations are disabled" + +**Cause**: The RHOAI MCP server has a safety flag that blocks all destructive operations by default. + +**Solution:** +1. Use `resources_delete` from the OpenShift MCP server instead +2. Always apply human-in-the-loop confirmation before deleting (display resource name, warn about data loss) +3. For workbench deletion, warn that associated PVC data may be lost if the PVC is also deleted diff --git a/rh-ai-engineer/skills/workbench-manage/references/known-model-profiles.md b/rh-ai-engineer/skills/workbench-manage/references/known-model-profiles.md new file mode 120000 index 00000000..92be1e9e --- /dev/null +++ b/rh-ai-engineer/skills/workbench-manage/references/known-model-profiles.md @@ -0,0 +1 @@ +../../model-deploy/references/known-model-profiles.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md b/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md deleted file mode 120000 index 6e74d58b..00000000 --- a/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md +++ /dev/null @@ -1 +0,0 @@ -../../references/live-doc-lookup.md \ No newline at end of file diff --git a/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md b/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md new file mode 100644 index 00000000..f09979aa --- /dev/null +++ b/rh-ai-engineer/skills/workbench-manage/references/live-doc-lookup.md @@ -0,0 +1,106 @@ +--- +title: Live Documentation Lookup Protocol +category: references +tags: [live-lookup, webfetch, documentation, models, runtimes] +semantic_keywords: [live doc lookup, external documentation fetch, model discovery, runtime discovery] +use_cases: [model-deploy, nim-setup, serving-runtime-config, debug-inference] +last_updated: 2026-02-26 +--- + +# Live Documentation Lookup Protocol + +This document defines the protocol for fetching external documentation at runtime when the agent encounters an unfamiliar model, runtime, or error. Because OpenShift AI and the NVIDIA NIM ecosystem evolve rapidly, the agent's training data may be stale. This protocol ensures accurate, up-to-date information. + +## When to Trigger Live Lookup + +The agent MUST trigger a live doc lookup when ANY of these conditions are true: + +1. **Unknown model**: The user requests deployment of a model not listed in [known-model-profiles.md](known-model-profiles.md) +2. **Uncertain hardware requirements**: The agent is not confident about GPU type, VRAM, or GPU count for a model +3. **Unfamiliar runtime or feature**: The user mentions a serving runtime configuration the agent is uncertain about +4. **Unrecognized deployment error**: A deployment fails with an error message the agent cannot diagnose from its training data + +## Lookup Targets + +Query these sources in order of relevance. Stop once sufficient information is found. + +### 1. Red Hat OpenShift AI Documentation + +**URL**: `https://docs.redhat.com/en/documentation/red_hat_openshift_ai_cloud_service/1` + +**When to use**: For RHOAI-specific features, supported runtimes, CRD schemas, model catalog entries, and deployment guides. + +**What to extract**: +- Supported serving runtime versions and configurations +- InferenceService CRD schema updates +- Model catalog entries with deployment parameters +- Known issues and workarounds + +### 2. NVIDIA NIM Model Catalog + +**URL**: `https://build.nvidia.com/models` + +**When to use**: For NIM-specific models — hardware profiles, API specs, deployment parameters, GPU compatibility. + +**What to extract**: +- GPU type and count requirements (e.g., "2x A100 80GB") +- Model-specific deployment parameters +- API specifications and endpoints +- Available model profiles (optimized vs. generic) + +### 3. NVIDIA NIM Supported Models Matrix + +**URL**: `https://docs.nvidia.com/nim/large-language-models/latest/supported-models.html` + +**When to use**: For the definitive list of NIM-supported models with GPU compatibility matrix. + +**What to extract**: +- GPU compatibility per model (which GPU types are supported) +- Model profiles: optimized (TensorRT-LLM) vs. generic (vLLM-based) +- Minimum GPU memory requirements +- Tensor parallelism configuration + +## Lookup Procedure + +### Step 1: Determine the lookup target + +Based on the trigger condition, select the most relevant URL: +- Model hardware requirements → Start with NVIDIA NIM catalog (#2), then RHOAI docs (#1) +- Runtime configuration → RHOAI docs (#1) +- NIM GPU compatibility → NIM supported models matrix (#3) +- General deployment issues → RHOAI docs (#1) + +### Step 2: Fetch the page + +Use the **WebFetch** tool to retrieve the relevant page content. + +### Step 3: Extract relevant information + +Parse the fetched content for: +- GPU type and count requirements +- Model-specific serving parameters (max sequence length, quantization, tensor parallelism) +- Compatible runtimes and their versions +- Known issues or special configuration notes + +### Step 4: Report to user + +**REQUIRED** (Document Consultation Transparency - Design Principle #1): + +Always report what was looked up and from where: + +``` +"I looked up [model-name] on [source-name] to confirm its hardware requirements: +- GPU: [count]x [type] ([VRAM]) +- Key parameters: [list] +- Compatible runtimes: [list]" +``` + +### Step 5: Proceed with deployment + +Use the fetched specs to configure the deployment. The looked-up information takes precedence over any cached or training data. + +## Security Considerations + +- Live lookup URLs are read-only documentation pages +- No credentials are sent to external URLs +- Fetched content is used only for parameter extraction, not executed diff --git a/rh-automation/docs/.ai-index/cross-reference-graph.json b/rh-automation/docs/.ai-index/cross-reference-graph.json deleted file mode 100644 index 5160a810..00000000 --- a/rh-automation/docs/.ai-index/cross-reference-graph.json +++ /dev/null @@ -1,64 +0,0 @@ -{ - "version": "2.0", - "last_updated": "2026-02-26", - "nodes": [ - { - "id": "governance-readiness", - "path": "aap/governance-readiness.md", - "title": "AAP Governance Readiness Assessment" - }, - { - "id": "execution-governance", - "path": "aap/execution-governance.md", - "title": "Execution Governance" - }, - { - "id": "job-troubleshooting", - "path": "aap/job-troubleshooting.md", - "title": "Job Troubleshooting" - }, - { - "id": "error-classification", - "path": "references/error-classification.md", - "title": "Error Classification Taxonomy" - } - ], - "edges": [ - { - "from": "governance-readiness", - "to": "execution-governance", - "relationship": "precedes", - "description": "After assessing readiness, use execution governance for governed execution" - }, - { - "from": "execution-governance", - "to": "job-troubleshooting", - "relationship": "follows_on_failure", - "description": "If execution fails, use troubleshooting for forensic analysis" - }, - { - "from": "job-troubleshooting", - "to": "error-classification", - "relationship": "references", - "description": "Troubleshooting uses error classification for systematic error typing" - }, - { - "from": "execution-governance", - "to": "governance-readiness", - "relationship": "optional_precondition", - "description": "First production execution may trigger readiness assessment" - }, - { - "from": "error-classification", - "to": "governance-readiness", - "relationship": "identifies_gaps", - "description": "Platform errors may indicate governance gaps in readiness domains" - }, - { - "from": "governance-readiness", - "to": "job-troubleshooting", - "relationship": "cross_reference", - "description": "Platform configuration issues discovered in assessment may explain job failures" - } - ] -} diff --git a/rh-automation/docs/.ai-index/semantic-index.json b/rh-automation/docs/.ai-index/semantic-index.json deleted file mode 100644 index aae9f4c2..00000000 --- a/rh-automation/docs/.ai-index/semantic-index.json +++ /dev/null @@ -1,101 +0,0 @@ -{ - "version": "2.0", - "last_updated": "2026-02-26", - "documents": [ - { - "path": "aap/governance-readiness.md", - "title": "AAP Governance Readiness Assessment", - "category": "aap", - "token_estimate": 3500, - "semantic_keywords": [ - "platform readiness assessment", - "governance audit", - "AAP best practices check", - "RBAC compliance", - "credential hygiene", - "workflow governance", - "notification coverage", - "execution environment review", - "workload isolation", - "audit trail verification", - "production readiness", - "cross-domain correlation", - "compound risk analysis", - "adaptive depth queries", - "prioritized remediation", - "scale calibration" - ], - "use_cases": ["governance_readiness_assessment", "platform_audit", "pre_execution_check", "compound_risk_analysis"], - "mcp_servers_used": ["job-management", "inventory-management", "configuration", "security-compliance", "system-monitoring", "user-management"], - "red_hat_sources": 8, - "skills_that_read": ["governance-readiness-assessor"] - }, - { - "path": "aap/execution-governance.md", - "title": "Execution Governance", - "category": "aap", - "token_estimate": 2500, - "semantic_keywords": [ - "execute on production", - "check mode dry run", - "inventory risk classification", - "secret scanning extra_vars", - "rollback failed job", - "phased rollout", - "job template launch", - "diff mode", - "execution safety", - "production governance", - "job history analysis", - "template launch configuration", - "notification bindings", - "workflow coverage check", - "module analysis", - "adaptive risk elevation" - ], - "use_cases": ["governed_execution", "risk_analysis", "check_mode_execution", "rollback", "pre_execution_context"], - "mcp_servers_used": ["job-management", "inventory-management"], - "red_hat_sources": 5, - "skills_that_read": ["execution-risk-analyzer", "governed-job-launcher"] - }, - { - "path": "aap/job-troubleshooting.md", - "title": "Job Troubleshooting", - "category": "aap", - "token_estimate": 2000, - "semantic_keywords": [ - "job failed", - "why did the job fail", - "analyze failure", - "job events", - "host unreachable", - "module failure", - "error analysis", - "root cause", - "failure correlation" - ], - "use_cases": ["job_failure_analysis", "forensic_troubleshooting", "host_correlation"], - "mcp_servers_used": ["job-management", "inventory-management"], - "red_hat_sources": 3, - "skills_that_read": ["job-failure-analyzer", "host-fact-inspector"] - }, - { - "path": "references/error-classification.md", - "title": "Error Classification Taxonomy", - "category": "references", - "token_estimate": 1500, - "semantic_keywords": [ - "error classification", - "platform vs code error", - "resolution path", - "error taxonomy", - "failure type determination", - "troubleshooting decision tree" - ], - "use_cases": ["error_classification", "resolution_path_determination"], - "mcp_servers_used": [], - "red_hat_sources": 3, - "skills_that_read": ["resolution-advisor"] - } - ] -} diff --git a/rh-automation/docs/.ai-index/task-to-docs-mapping.json b/rh-automation/docs/.ai-index/task-to-docs-mapping.json deleted file mode 100644 index 85ffede7..00000000 --- a/rh-automation/docs/.ai-index/task-to-docs-mapping.json +++ /dev/null @@ -1,73 +0,0 @@ -{ - "version": "2.0", - "last_updated": "2026-02-26", - "workflows": { - "governance_assessment": { - "description": "Assess AAP platform governance readiness across 7 domains", - "trigger_phrases": [ - "assess governance readiness", - "is my AAP ready for production", - "audit platform configuration", - "check governance", - "what should I fix before executing jobs" - ], - "documents": [ - { - "path": "aap/governance-readiness.md", - "role": "primary", - "reason": "7-domain assessment framework with Red Hat citations" - } - ], - "agent": "governance-assessor", - "skills": ["aap-mcp-validator", "governance-readiness-assessor", "execution-summary"] - }, - "governed_execution": { - "description": "Execute with risk analysis, check mode, and governance controls", - "trigger_phrases": [ - "execute on production", - "push to prod", - "launch job template", - "execute security patch", - "release to production" - ], - "documents": [ - { - "path": "aap/execution-governance.md", - "role": "primary", - "reason": "Risk classification, check mode, rollback, phased rollout" - }, - { - "path": "aap/governance-readiness.md", - "role": "optional", - "reason": "Optional pre-execution readiness check" - } - ], - "agent": "governance-executor", - "skills": ["aap-mcp-validator", "execution-risk-analyzer", "governed-job-launcher", "execution-summary"] - }, - "forensic_troubleshooting": { - "description": "Analyze failed jobs with event extraction, host correlation, and resolution advisory", - "trigger_phrases": [ - "job failed", - "why did the execution fail", - "analyze the failure", - "what went wrong", - "root cause analysis" - ], - "documents": [ - { - "path": "aap/job-troubleshooting.md", - "role": "primary", - "reason": "Event parsing, failure patterns, host correlation" - }, - { - "path": "references/error-classification.md", - "role": "secondary", - "reason": "Error taxonomy and resolution path mapping" - } - ], - "agent": "forensic-troubleshooter", - "skills": ["aap-mcp-validator", "job-failure-analyzer", "host-fact-inspector", "resolution-advisor", "execution-summary"] - } - } -} diff --git a/rh-automation/docs/INDEX.md b/rh-automation/docs/INDEX.md deleted file mode 100644 index 644d7bdb..00000000 --- a/rh-automation/docs/INDEX.md +++ /dev/null @@ -1,46 +0,0 @@ -# Documentation Index - -Navigation guide for the rh-automation knowledge base. These documents are read by skills at runtime to provide Red Hat documentation-backed intelligence. - -## How Documents Are Used - -``` -User Request → Agent → Skill reads document → Skill queries MCP tools → Skill interprets with document knowledge → Output with Red Hat citations -``` - -## Document Map - -### AAP Category (`docs/aap/`) - -Platform governance, execution, and troubleshooting references for Ansible Automation Platform. - -| Document | Purpose | Skills That Read It | Red Hat Sources | -|----------|---------|-------------------|----------------| -| [governance-readiness.md](aap/governance-readiness.md) | 7-domain platform governance assessment | `governance-readiness-assessor` | 8 sources (Security Best Practices, Workflows, Notifications, RBAC, Instance Groups, Activity Stream, EE Guide, Hardening Guide) | -| [execution-governance.md](aap/execution-governance.md) | Risk classification, check mode, rollback, phased rollout | `execution-risk-analyzer`, `governed-job-launcher` | 5 sources (Job Templates, Security Best Practices, Workflows, Check Mode, Controller Best Practices) | -| [job-troubleshooting.md](aap/job-troubleshooting.md) | Event parsing, host correlation, failure patterns | `job-failure-analyzer`, `host-fact-inspector` | 3 sources (Troubleshooting Guide, Job Events, Administration Guide) | - -### References Category (`docs/references/`) - -Cross-cutting reference material used across multiple use cases. - -| Document | Purpose | Skills That Read It | Red Hat Sources | -|----------|---------|-------------------|----------------| -| [error-classification.md](references/error-classification.md) | Error taxonomy, classification trees, resolution paths | `resolution-advisor` | 3 sources (Troubleshooting Guide, Ansible Module docs, Administration Guide) | - -## Task-to-Document Mapping - -| User Task | Primary Document | Secondary Document | -|-----------|-----------------|-------------------| -| "Assess governance readiness" | governance-readiness.md | -- | -| "Execute on production" | execution-governance.md | governance-readiness.md (optional pre-check) | -| "Analyze failed job" | job-troubleshooting.md | error-classification.md | -| "How to fix this error?" | error-classification.md | job-troubleshooting.md | - -## Semantic Indexing - -The `.ai-index/` directory contains pre-computed indexes for efficient document discovery: - -- `semantic-index.json` -- Document metadata with semantic keywords -- `task-to-docs-mapping.json` -- Pre-computed document sets for common workflows -- `cross-reference-graph.json` -- Document relationship graph diff --git a/rh-automation/docs/SOURCES.md b/rh-automation/docs/SOURCES.md deleted file mode 100644 index 0e064fcc..00000000 --- a/rh-automation/docs/SOURCES.md +++ /dev/null @@ -1,200 +0,0 @@ -# Official Red Hat Sources - -All documentation in this collection is derived from or references official Red Hat and Ansible documentation. Content is used in accordance with Red Hat's documentation license (CC BY-SA 4.0). - -## Primary Sources - -### 1. Red Hat AAP 2.5 - Configuring Automation Execution: Security Best Practices (Ch. 15) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/configuring_automation_execution/controller-security-best-practices - -**Sections Used**: -- Sec. 15.1.2: Minimize administrative accounts -- Sec. 15.1.4: Remove user access to credentials -- Sec. 15.1.5: Enforce separation of duties -- Sec. 15.2.1: Use teams for role-based access -- Sec. 15.2.2: External authentication (LDAP, SAML, OAuth) - -**Referenced By**: governance-readiness.md (Domains 3, 4, Bonus), execution-governance.md (secret scanning) - -**Date Accessed**: 2026-02-20 - ---- - -### 2. Red Hat AAP 2.5 - Automation Controller User Guide: Workflows (Ch. 9) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/using_automation_execution/controller-workflows - -**Sections Used**: -- Workflow job templates -- Sec. 9.4: Workflow RBAC -- Approval nodes - -**Referenced By**: governance-readiness.md (Domain 1), execution-governance.md - -**Date Accessed**: 2026-02-20 - ---- - -### 3. Red Hat AAP 2.5 - Automation Controller User Guide: Notifications (Ch. 25) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/using_automation_execution/controller-notifications - -**Sections Used**: -- Notification templates -- Sec. 25.1: Notification inheritance hierarchy -- Notification types (Email, Slack, Webhook, PagerDuty) - -**Referenced By**: governance-readiness.md (Domain 2) - -**Date Accessed**: 2026-02-20 - ---- - -### 4. Red Hat AAP 2.5 - Automation Controller User Guide: RBAC (Ch. 4) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/access_management_and_authentication/gw-managing-access - -**Sections Used**: -- Role-based access controls -- Role definitions -- Team assignments - -**Referenced By**: governance-readiness.md (Domain 3) - -**Date Accessed**: 2026-02-20 - ---- - -### 5. Red Hat AAP 2.5 - Configuring Automation Execution: Instance Groups (Ch. 17) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-instance-groups - -**Sections Used**: -- Instance groups for workload isolation -- max_forks configuration -- Policy settings - -**Referenced By**: governance-readiness.md (Domain 6) - -**Date Accessed**: 2026-02-20 - ---- - -### 6. Red Hat AAP 2.5 - Automation Controller User Guide: Activity Stream - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/assembly-controller-activity-stream - -**Sections Used**: -- Activity stream audit logging -- Event filtering - -**Referenced By**: governance-readiness.md (Domain 7) - -**Date Accessed**: 2026-02-20 - ---- - -### 7. Red Hat AAP 2.6 - Creating and Using Execution Environments - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/creating_and_using_execution_environments/index - -**Sections Used**: -- Custom EE creation -- Dependency pinning -- ansible-builder - -**Referenced By**: governance-readiness.md (Domain 5), error-classification.md (EE issues) - -**Date Accessed**: 2026-02-20 - ---- - -### 8. Red Hat AAP 2.6 - Hardening Guide - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/hardening_and_compliance/index - -**Sections Used**: -- Platform hardening -- Credential rotation -- Audit requirements - -**Referenced By**: governance-readiness.md - -**Date Accessed**: 2026-02-20 - ---- - -### 9. Red Hat AAP 2.6 - Troubleshooting Guide: Troubleshoot Jobs - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/troubleshooting_ansible_automation_platform/troubleshoot-jobs - -**Sections Used**: -- Job failure analysis -- Common job errors -- Event interpretation - -**Referenced By**: job-troubleshooting.md, error-classification.md - -**Date Accessed**: 2026-02-20 - ---- - -### 10. Red Hat AAP 2.5 - Automation Controller User Guide: Job Templates (Ch. 9) - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/automation_controller_user_guide/controller-job-templates - -**Sections Used**: -- Job template configuration -- job_type (run/check) -- diff_mode, limit, extra_vars -- Job slicing -- Relaunch - -**Referenced By**: execution-governance.md, job-troubleshooting.md - -**Date Accessed**: 2026-02-20 - ---- - -### 11. Red Hat AAP 2.5 - Configuring Automation Execution: Controller Best Practices - -**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/configuring_automation_execution/controller-tips-and-tricks - -**Sections Used**: -- Inventory management -- Environment separation - -**Referenced By**: execution-governance.md (risk classification) - -**Date Accessed**: 2026-02-20 - ---- - -### 12. Ansible Playbook Guide: Check Mode - -**URL**: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_checkmode.html - -**Sections Used**: -- Check mode behavior -- diff mode -- Limitations (shell/command modules) - -**Referenced By**: execution-governance.md (check mode section) - -**Date Accessed**: 2026-02-20 - ---- - -### 13. Ansible Built-in Module Documentation - -**URL**: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html - -**Sections Used**: -- Module return values -- Error conditions -- Check mode behavior per module - -**Referenced By**: error-classification.md - -**Date Accessed**: 2026-02-20 diff --git a/rh-automation/skills/execution-risk-analyzer/SKILL.md b/rh-automation/skills/execution-risk-analyzer/SKILL.md index 9fcec4da..359a4370 100644 --- a/rh-automation/skills/execution-risk-analyzer/SKILL.md +++ b/rh-automation/skills/execution-risk-analyzer/SKILL.md @@ -46,8 +46,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [execution-governance.md](docs/aap/execution-governance.md) using the Read tool to understand inventory risk classification, extra_vars safety scanning, and governance controls -2. **Output to user**: "I consulted [execution-governance.md](docs/aap/execution-governance.md) which cites Red Hat's Security Best Practices and Job Templates documentation for execution governance controls." +1. **Action**: Read [execution-governance.md](references/aap/execution-governance.md) using the Read tool to understand inventory risk classification, extra_vars safety scanning, and governance controls +2. **Output to user**: "I consulted [execution-governance.md](references/aap/execution-governance.md) which cites Red Hat's Security Best Practices and Job Templates documentation for execution governance controls." ### Step 2: Identify the Job Template @@ -244,7 +244,7 @@ Per Red Hat's *Security Best Practices* (Ch. 15, Sec. 15.1.4): "Remove user acce - `execution-summary` - Audit trail ### Reference Documentation -- [execution-governance.md](docs/aap/execution-governance.md) - Risk classification and safety scanning reference +- [execution-governance.md](references/aap/execution-governance.md) - Risk classification and safety scanning reference ## Example Usage diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/execution-risk-analyzer/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md b/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/execution-risk-analyzer/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md b/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/execution-risk-analyzer/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/README.md b/rh-automation/skills/execution-risk-analyzer/references/aap/README.md similarity index 100% rename from rh-automation/skills/execution-risk-analyzer/docs/aap/README.md rename to rh-automation/skills/execution-risk-analyzer/references/aap/README.md diff --git a/rh-automation/skills/execution-risk-analyzer/docs/aap/execution-governance.md b/rh-automation/skills/execution-risk-analyzer/references/aap/execution-governance.md similarity index 99% rename from rh-automation/skills/execution-risk-analyzer/docs/aap/execution-governance.md rename to rh-automation/skills/execution-risk-analyzer/references/aap/execution-governance.md index 21db9cf2..de77ad44 100644 --- a/rh-automation/skills/execution-risk-analyzer/docs/aap/execution-governance.md +++ b/rh-automation/skills/execution-risk-analyzer/references/aap/execution-governance.md @@ -537,7 +537,7 @@ The complete governed execution workflow: - **[governance-readiness.md](governance-readiness.md)** -- Assess platform readiness before first production execution - **[job-troubleshooting.md](job-troubleshooting.md)** -- If execution fails, use forensic troubleshooting to determine root cause -- **[error-classification.md](../references/error-classification.md)** -- Classify execution errors and determine resolution paths +- **[error-classification.md](../error-classification.md)** -- Classify execution errors and determine resolution paths --- diff --git a/rh-automation/skills/execution-risk-analyzer/references/aap/governance-readiness.md b/rh-automation/skills/execution-risk-analyzer/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/references/aap/job-troubleshooting.md b/rh-automation/skills/execution-risk-analyzer/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-risk-analyzer/references/error-classification.md b/rh-automation/skills/execution-risk-analyzer/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/execution-risk-analyzer/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/SKILL.md b/rh-automation/skills/execution-summary/SKILL.md index d8778502..5506e780 100644 --- a/rh-automation/skills/execution-summary/SKILL.md +++ b/rh-automation/skills/execution-summary/SKILL.md @@ -65,10 +65,10 @@ Review the current conversation/session to extract: | Document | Topic | Citation | |---|---|---| -| [governance-readiness.md](docs/aap/governance-readiness.md) | 7-domain assessment framework | Red Hat AAP 2.5 Security Best Practices (Ch. 15), Workflows (Ch. 9), Notifications (Ch. 25) | -| [execution-governance.md](docs/aap/execution-governance.md) | Risk classification, check mode | Red Hat AAP 2.5 Job Templates (Ch. 9), Controller Best Practices | -| [job-troubleshooting.md](docs/aap/job-troubleshooting.md) | Event parsing, failure patterns | Red Hat AAP 2.6 Troubleshooting Guide | -| [error-classification.md](docs/references/error-classification.md) | Error taxonomy | Red Hat AAP 2.6 Troubleshooting Guide | +| [governance-readiness.md](references/aap/governance-readiness.md) | 7-domain assessment framework | Red Hat AAP 2.5 Security Best Practices (Ch. 15), Workflows (Ch. 9), Notifications (Ch. 25) | +| [execution-governance.md](references/aap/execution-governance.md) | Risk classification, check mode | Red Hat AAP 2.5 Job Templates (Ch. 9), Controller Best Practices | +| [job-troubleshooting.md](references/aap/job-troubleshooting.md) | Event parsing, failure patterns | Red Hat AAP 2.6 Troubleshooting Guide | +| [error-classification.md](references/error-classification.md) | Error taxonomy | Red Hat AAP 2.6 Troubleshooting Guide | ### MCP Tools Used diff --git a/rh-automation/skills/execution-summary/docs/aap/execution-governance.md b/rh-automation/skills/execution-summary/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/execution-summary/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md b/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/execution-summary/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md b/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/execution-summary/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/docs/references/error-classification.md b/rh-automation/skills/execution-summary/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/execution-summary/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/references/aap/execution-governance.md b/rh-automation/skills/execution-summary/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/execution-summary/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/references/aap/governance-readiness.md b/rh-automation/skills/execution-summary/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/execution-summary/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/references/aap/job-troubleshooting.md b/rh-automation/skills/execution-summary/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/execution-summary/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/execution-summary/references/error-classification.md b/rh-automation/skills/execution-summary/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/execution-summary/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/SKILL.md b/rh-automation/skills/forensic-troubleshooter/SKILL.md index a57aae9c..e5d57c82 100644 --- a/rh-automation/skills/forensic-troubleshooter/SKILL.md +++ b/rh-automation/skills/forensic-troubleshooter/SKILL.md @@ -53,7 +53,7 @@ Do NOT use when: - Reports structured analysis with Red Hat citations **Document Consultation** (performed by the skill): -The job-failure-analyzer skill reads [job-troubleshooting.md](docs/aap/job-troubleshooting.md) and reports its consultation. +The job-failure-analyzer skill reads [job-troubleshooting.md](references/aap/job-troubleshooting.md) and reports its consultation. ### 3. Correlate with Host Facts @@ -65,7 +65,7 @@ The job-failure-analyzer skill reads [job-troubleshooting.md](docs/aap/job-troub - Reports correlation findings **Document Consultation** (performed by the skill): -The host-fact-inspector skill reads [job-troubleshooting.md](docs/aap/job-troubleshooting.md) for correlation patterns. +The host-fact-inspector skill reads [job-troubleshooting.md](references/aap/job-troubleshooting.md) for correlation patterns. ### 4. Provide Resolution Advisory @@ -76,7 +76,7 @@ The host-fact-inspector skill reads [job-troubleshooting.md](docs/aap/job-troubl - Identifies related governance gaps **Document Consultation** (performed by the skill): -The resolution-advisor skill reads [error-classification.md](docs/references/error-classification.md) and [job-troubleshooting.md](docs/aap/job-troubleshooting.md). +The resolution-advisor skill reads [error-classification.md](references/error-classification.md) and [job-troubleshooting.md](references/aap/job-troubleshooting.md). ### 5. Generate Execution Summary @@ -104,8 +104,8 @@ The resolution-advisor skill reads [error-classification.md](docs/references/err - `governance-assessor` - If root cause points to platform governance gaps ### Reference Documentation -- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Event parsing, failure patterns, correlation -- [error-classification.md](docs/references/error-classification.md) - Error taxonomy and resolution paths +- [job-troubleshooting.md](references/aap/job-troubleshooting.md) - Event parsing, failure patterns, correlation +- [error-classification.md](references/error-classification.md) - Error taxonomy and resolution paths ## Example Usage diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/forensic-troubleshooter/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/forensic-troubleshooter/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md b/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/forensic-troubleshooter/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md b/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/forensic-troubleshooter/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/references/aap/execution-governance.md b/rh-automation/skills/forensic-troubleshooter/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/references/aap/governance-readiness.md b/rh-automation/skills/forensic-troubleshooter/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/references/aap/job-troubleshooting.md b/rh-automation/skills/forensic-troubleshooter/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/forensic-troubleshooter/references/error-classification.md b/rh-automation/skills/forensic-troubleshooter/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/forensic-troubleshooter/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/SKILL.md b/rh-automation/skills/governance-assessor/SKILL.md index f7e737e5..58474e94 100644 --- a/rh-automation/skills/governance-assessor/SKILL.md +++ b/rh-automation/skills/governance-assessor/SKILL.md @@ -68,7 +68,7 @@ Do NOT use when: - Produces the structured Governance Readiness Report with Red Hat citations per domain, compound risk analysis, and prioritized fix order **Document Consultation** (performed by the skill): -The governance-readiness-assessor skill reads [governance-readiness.md](docs/aap/governance-readiness.md) and reports its consultation. +The governance-readiness-assessor skill reads [governance-readiness.md](references/aap/governance-readiness.md) and reports its consultation. ### 3. Present Report and Offer Remediation @@ -108,7 +108,7 @@ Before creating or modifying any AAP resource: - `forensic-troubleshooter` - Follow-up: investigate failures found during assessment ### Reference Documentation -- [governance-readiness.md](docs/aap/governance-readiness.md) - 7-domain assessment framework +- [governance-readiness.md](references/aap/governance-readiness.md) - 7-domain assessment framework ### Sample Reports - [sample-full-assessment.md](references/sample-full-assessment.md) - Full 7+1 domain assessment with compound risk analysis diff --git a/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md b/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/governance-assessor/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md b/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/governance-assessor/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/governance-assessor/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/docs/references/error-classification.md b/rh-automation/skills/governance-assessor/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/governance-assessor/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/references/aap/execution-governance.md b/rh-automation/skills/governance-assessor/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/governance-assessor/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/references/aap/governance-readiness.md b/rh-automation/skills/governance-assessor/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/governance-assessor/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/references/aap/job-troubleshooting.md b/rh-automation/skills/governance-assessor/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/governance-assessor/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/references/error-classification.md b/rh-automation/skills/governance-assessor/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/governance-assessor/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-assessor/references/sample-full-assessment.md b/rh-automation/skills/governance-assessor/references/sample-full-assessment.md index 9f3396a0..c6fd35b5 100644 --- a/rh-automation/skills/governance-assessor/references/sample-full-assessment.md +++ b/rh-automation/skills/governance-assessor/references/sample-full-assessment.md @@ -1,7 +1,7 @@ # Sample Report: Full Governance Readiness Assessment This sample shows the expected output when a user requests a full platform governance audit. -The report follows the output template defined in [governance-readiness.md](../../../docs/aap/governance-readiness.md). +The report follows the output template defined in [governance-readiness.md](../../governance-readiness-assessor/references/aap/governance-readiness.md). --- @@ -13,7 +13,7 @@ The report follows the output template defined in [governance-readiness.md](../. **Scale Calibration**: Enterprise (3 inventories, 87 hosts across production, staging, and development) **Documents Consulted**: -- [governance-readiness.md](docs/aap/governance-readiness.md) -- 7-domain assessment framework, Red Hat citations, decision tables +- [governance-readiness.md](../../governance-readiness-assessor/references/aap/governance-readiness.md) -- 7-domain assessment framework, Red Hat citations, decision tables --- diff --git a/rh-automation/skills/governance-assessor/references/sample-scoped-assessment.md b/rh-automation/skills/governance-assessor/references/sample-scoped-assessment.md index 4ee0db3b..4c5dbb33 100644 --- a/rh-automation/skills/governance-assessor/references/sample-scoped-assessment.md +++ b/rh-automation/skills/governance-assessor/references/sample-scoped-assessment.md @@ -2,7 +2,7 @@ This sample shows the expected output when a user requests a scoped assessment targeting specific governance domains. The report follows the output template -defined in [governance-readiness.md](../../../docs/aap/governance-readiness.md). +defined in [governance-readiness.md](../../governance-readiness-assessor/references/aap/governance-readiness.md). --- @@ -14,7 +14,7 @@ defined in [governance-readiness.md](../../../docs/aap/governance-readiness.md). **Scale Calibration**: Small team (1 inventory, 5 hosts, development only) **Documents Consulted**: -- [governance-readiness.md](docs/aap/governance-readiness.md) -- Domains 3 and 4 assessment criteria, Red Hat citations +- [governance-readiness.md](../../governance-readiness-assessor/references/aap/governance-readiness.md) -- Domains 3 and 4 assessment criteria, Red Hat citations --- diff --git a/rh-automation/skills/governance-executor/SKILL.md b/rh-automation/skills/governance-executor/SKILL.md index e73b5f60..8712d178 100644 --- a/rh-automation/skills/governance-executor/SKILL.md +++ b/rh-automation/skills/governance-executor/SKILL.md @@ -57,7 +57,7 @@ Do NOT use when: - Reports risk assessment with Red Hat citations AND operational context **Document Consultation** (performed by the skill): -The execution-risk-analyzer skill reads [execution-governance.md](docs/aap/execution-governance.md) and reports its consultation. +The execution-risk-analyzer skill reads [execution-governance.md](references/aap/execution-governance.md) and reports its consultation. **If secrets detected**: STOP. Report the finding and recommend using AAP credentials. @@ -109,7 +109,7 @@ The execution-risk-analyzer skill reads [execution-governance.md](docs/aap/execu - `governance-assessor` - Pre-execution platform readiness check ### Reference Documentation -- [execution-governance.md](docs/aap/execution-governance.md) - Risk classification, check mode, rollback +- [execution-governance.md](references/aap/execution-governance.md) - Risk classification, check mode, rollback ## Example Usage diff --git a/rh-automation/skills/governance-executor/docs/aap/execution-governance.md b/rh-automation/skills/governance-executor/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/governance-executor/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md b/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/governance-executor/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/governance-executor/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/docs/references/error-classification.md b/rh-automation/skills/governance-executor/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/governance-executor/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/references/aap/execution-governance.md b/rh-automation/skills/governance-executor/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/governance-executor/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/references/aap/governance-readiness.md b/rh-automation/skills/governance-executor/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/governance-executor/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/references/aap/job-troubleshooting.md b/rh-automation/skills/governance-executor/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/governance-executor/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-executor/references/error-classification.md b/rh-automation/skills/governance-executor/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/governance-executor/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/SKILL.md b/rh-automation/skills/governance-readiness-assessor/SKILL.md index 95d7f5cd..0a5dd591 100644 --- a/rh-automation/skills/governance-readiness-assessor/SKILL.md +++ b/rh-automation/skills/governance-readiness-assessor/SKILL.md @@ -60,8 +60,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [governance-readiness.md](docs/aap/governance-readiness.md) using the Read tool to understand the 7-domain assessment framework, Red Hat source citations, decision tables, and output template -2. **Output to user**: "I consulted [governance-readiness.md](docs/aap/governance-readiness.md) to understand Red Hat's governance best practices for the 7-domain assessment framework." +1. **Action**: Read [governance-readiness.md](references/aap/governance-readiness.md) using the Read tool to understand the 7-domain assessment framework, Red Hat source citations, decision tables, and output template +2. **Output to user**: "I consulted [governance-readiness.md](references/aap/governance-readiness.md) to understand Red Hat's governance best practices for the 7-domain assessment framework." ### Step 1.5: Determine Assessment Scope @@ -287,7 +287,7 @@ For any domains with GAP or WARN status, offer to remediate using MCP write tool - `execution-summary` - Generate audit trail after assessment ### Reference Documentation -- [governance-readiness.md](docs/aap/governance-readiness.md) - The 7-domain assessment reference +- [governance-readiness.md](references/aap/governance-readiness.md) - The 7-domain assessment reference ## Critical: Human-in-the-Loop Requirements diff --git a/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md b/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/governance-readiness-assessor/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md b/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/governance-readiness-assessor/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md b/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/governance-readiness-assessor/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/references/aap/execution-governance.md b/rh-automation/skills/governance-readiness-assessor/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/docs/aap/governance-readiness.md b/rh-automation/skills/governance-readiness-assessor/references/aap/governance-readiness.md similarity index 99% rename from rh-automation/skills/governance-readiness-assessor/docs/aap/governance-readiness.md rename to rh-automation/skills/governance-readiness-assessor/references/aap/governance-readiness.md index 3abd44fb..ae8eb542 100644 --- a/rh-automation/skills/governance-readiness-assessor/docs/aap/governance-readiness.md +++ b/rh-automation/skills/governance-readiness-assessor/references/aap/governance-readiness.md @@ -921,7 +921,7 @@ Domains that can be addressed in parallel: [list independent domains] - **[execution-governance.md](execution-governance.md)** -- After assessing readiness, use this document for governed execution with risk classification and check mode - **[job-troubleshooting.md](job-troubleshooting.md)** -- If jobs fail during execution, use this document for forensic troubleshooting with event parsing and host correlation -- **[error-classification.md](../references/error-classification.md)** -- Reference for systematic error classification and resolution path determination +- **[error-classification.md](../error-classification.md)** -- Reference for systematic error classification and resolution path determination --- diff --git a/rh-automation/skills/governance-readiness-assessor/references/aap/job-troubleshooting.md b/rh-automation/skills/governance-readiness-assessor/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governance-readiness-assessor/references/error-classification.md b/rh-automation/skills/governance-readiness-assessor/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/governance-readiness-assessor/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/SKILL.md b/rh-automation/skills/governed-job-launcher/SKILL.md index d5d13967..dd54f2a6 100644 --- a/rh-automation/skills/governed-job-launcher/SKILL.md +++ b/rh-automation/skills/governed-job-launcher/SKILL.md @@ -46,8 +46,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [execution-governance.md](docs/aap/execution-governance.md) using the Read tool to understand check mode execution, interpretation, phased rollout, and rollback patterns -2. **Output to user**: "I consulted [execution-governance.md](docs/aap/execution-governance.md) to understand Red Hat's check mode behavior, rollback patterns, and phased rollout strategy." +1. **Action**: Read [execution-governance.md](references/aap/execution-governance.md) using the Read tool to understand check mode execution, interpretation, phased rollout, and rollback patterns +2. **Output to user**: "I consulted [execution-governance.md](references/aap/execution-governance.md) to understand Red Hat's check mode behavior, rollback patterns, and phased rollout strategy." ### Step 2: Adapt Execution Strategy Based on Risk Signals @@ -280,7 +280,7 @@ If the job fails, offer rollback options per execution-governance.md: - `execution-summary` - Audit trail after launch ### Reference Documentation -- [execution-governance.md](docs/aap/execution-governance.md) - Check mode, rollback, phased rollout patterns +- [execution-governance.md](references/aap/execution-governance.md) - Check mode, rollback, phased rollout patterns ## Critical: Human-in-the-Loop Requirements diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md b/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/governed-job-launcher/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md b/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/governed-job-launcher/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md b/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/governed-job-launcher/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md b/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/governed-job-launcher/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/references/aap/execution-governance.md b/rh-automation/skills/governed-job-launcher/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/references/aap/governance-readiness.md b/rh-automation/skills/governed-job-launcher/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/references/aap/job-troubleshooting.md b/rh-automation/skills/governed-job-launcher/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/governed-job-launcher/references/error-classification.md b/rh-automation/skills/governed-job-launcher/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/governed-job-launcher/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/SKILL.md b/rh-automation/skills/host-fact-inspector/SKILL.md index bf971eaa..df1291b4 100644 --- a/rh-automation/skills/host-fact-inspector/SKILL.md +++ b/rh-automation/skills/host-fact-inspector/SKILL.md @@ -45,8 +45,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand the host fact correlation table and error-to-fact mapping -2. **Output to user**: "I consulted [job-troubleshooting.md](docs/aap/job-troubleshooting.md) to understand which host facts correlate with the identified failure patterns." +1. **Action**: Read [job-troubleshooting.md](references/aap/job-troubleshooting.md) using the Read tool to understand the host fact correlation table and error-to-fact mapping +2. **Output to user**: "I consulted [job-troubleshooting.md](references/aap/job-troubleshooting.md) to understand which host facts correlate with the identified failure patterns." ### Step 2: Look Up Affected Hosts @@ -136,7 +136,7 @@ If facts appear stale or missing, report this: "Host facts may not be current. F - `execution-summary` - Audit trail ### Reference Documentation -- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Host fact correlation table +- [job-troubleshooting.md](references/aap/job-troubleshooting.md) - Host fact correlation table ## Example Usage diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md b/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/host-fact-inspector/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md b/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/host-fact-inspector/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md b/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/host-fact-inspector/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md b/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/host-fact-inspector/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/references/aap/execution-governance.md b/rh-automation/skills/host-fact-inspector/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/references/aap/governance-readiness.md b/rh-automation/skills/host-fact-inspector/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/references/aap/job-troubleshooting.md b/rh-automation/skills/host-fact-inspector/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/host-fact-inspector/references/error-classification.md b/rh-automation/skills/host-fact-inspector/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/host-fact-inspector/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/SKILL.md b/rh-automation/skills/job-failure-analyzer/SKILL.md index 42728c76..6fc2a3a7 100644 --- a/rh-automation/skills/job-failure-analyzer/SKILL.md +++ b/rh-automation/skills/job-failure-analyzer/SKILL.md @@ -43,8 +43,8 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE any MCP tool invocations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand event extraction, failure patterns, host summary interpretation, and root cause classification -2. **Output to user**: "I consulted [job-troubleshooting.md](docs/aap/job-troubleshooting.md) which references Red Hat's AAP 2.6 Troubleshooting Guide for failure analysis patterns." +1. **Action**: Read [job-troubleshooting.md](references/aap/job-troubleshooting.md) using the Read tool to understand event extraction, failure patterns, host summary interpretation, and root cause classification +2. **Output to user**: "I consulted [job-troubleshooting.md](references/aap/job-troubleshooting.md) which references Red Hat's AAP 2.6 Troubleshooting Guide for failure analysis patterns." ### Step 2: Retrieve Job Status @@ -167,7 +167,7 @@ Sort events by `counter` and produce a chronological failure narrative: - `execution-summary` - Audit trail ### Reference Documentation -- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Event parsing and failure patterns +- [job-troubleshooting.md](references/aap/job-troubleshooting.md) - Event parsing and failure patterns ## Example Usage diff --git a/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md b/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/job-failure-analyzer/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md b/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/job-failure-analyzer/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md b/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md deleted file mode 120000 index 71b66be0..00000000 --- a/rh-automation/skills/job-failure-analyzer/docs/references/error-classification.md +++ /dev/null @@ -1 +0,0 @@ -../../../resolution-advisor/docs/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/references/aap/execution-governance.md b/rh-automation/skills/job-failure-analyzer/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/references/aap/governance-readiness.md b/rh-automation/skills/job-failure-analyzer/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/job-failure-analyzer/docs/aap/job-troubleshooting.md b/rh-automation/skills/job-failure-analyzer/references/aap/job-troubleshooting.md similarity index 98% rename from rh-automation/skills/job-failure-analyzer/docs/aap/job-troubleshooting.md rename to rh-automation/skills/job-failure-analyzer/references/aap/job-troubleshooting.md index 3ce7636a..6302182c 100644 --- a/rh-automation/skills/job-failure-analyzer/docs/aap/job-troubleshooting.md +++ b/rh-automation/skills/job-failure-analyzer/references/aap/job-troubleshooting.md @@ -56,7 +56,7 @@ When an AAP job fails, the raw information exists in three places: **job events* **Do NOT use when**: - User wants to execute a job (use [execution-governance.md](execution-governance.md)) - User wants to assess platform readiness (use [governance-readiness.md](governance-readiness.md)) -- User needs error classification taxonomy (use [error-classification.md](../references/error-classification.md) as companion reference) +- User needs error classification taxonomy (use [error-classification.md](../error-classification.md) as companion reference) --- @@ -360,7 +360,7 @@ Consulted host facts for [hostname]: Per [Red Hat source]: [resolution recommendation] -See [error-classification.md](../references/error-classification.md) for detailed resolution paths. +See [error-classification.md](../error-classification.md) for detailed resolution paths. ``` --- @@ -369,7 +369,7 @@ See [error-classification.md](../references/error-classification.md) for detaile - **[execution-governance.md](execution-governance.md)** -- For rollback options after determining root cause - **[governance-readiness.md](governance-readiness.md)** -- Platform configuration issues may indicate governance gaps -- **[error-classification.md](../references/error-classification.md)** -- Detailed error taxonomy and resolution path mapping +- **[error-classification.md](../error-classification.md)** -- Detailed error taxonomy and resolution path mapping --- diff --git a/rh-automation/skills/job-failure-analyzer/references/error-classification.md b/rh-automation/skills/job-failure-analyzer/references/error-classification.md new file mode 120000 index 00000000..1aa175de --- /dev/null +++ b/rh-automation/skills/job-failure-analyzer/references/error-classification.md @@ -0,0 +1 @@ +../../resolution-advisor/references/error-classification.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/SKILL.md b/rh-automation/skills/resolution-advisor/SKILL.md index e85200fd..656e432d 100644 --- a/rh-automation/skills/resolution-advisor/SKILL.md +++ b/rh-automation/skills/resolution-advisor/SKILL.md @@ -42,9 +42,9 @@ Do NOT use when: **CRITICAL**: Document consultation MUST happen BEFORE providing recommendations. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [error-classification.md](docs/references/error-classification.md) using the Read tool to understand the error taxonomy, classification decision tree, and resolution path mapping -2. **Action**: Read [job-troubleshooting.md](docs/aap/job-troubleshooting.md) using the Read tool to understand failure pattern details and Red Hat source citations -3. **Output to user**: "I consulted [error-classification.md](docs/references/error-classification.md) and [job-troubleshooting.md](docs/aap/job-troubleshooting.md) to determine the resolution path based on Red Hat's troubleshooting guidance." +1. **Action**: Read [error-classification.md](references/error-classification.md) using the Read tool to understand the error taxonomy, classification decision tree, and resolution path mapping +2. **Action**: Read [job-troubleshooting.md](references/aap/job-troubleshooting.md) using the Read tool to understand failure pattern details and Red Hat source citations +3. **Output to user**: "I consulted [error-classification.md](references/error-classification.md) and [job-troubleshooting.md](references/aap/job-troubleshooting.md) to determine the resolution path based on Red Hat's troubleshooting guidance." ### Step 2: Determine Resolution Path @@ -125,8 +125,8 @@ If the failure correlates with a governance readiness domain, recommend the user - `execution-summary` - Audit trail ### Reference Documentation -- [error-classification.md](docs/references/error-classification.md) - Error taxonomy and resolution paths -- [job-troubleshooting.md](docs/aap/job-troubleshooting.md) - Failure patterns and Red Hat citations +- [error-classification.md](references/error-classification.md) - Error taxonomy and resolution paths +- [job-troubleshooting.md](references/aap/job-troubleshooting.md) - Failure patterns and Red Hat citations ## Example Usage diff --git a/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md b/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md deleted file mode 120000 index 76d56e98..00000000 --- a/rh-automation/skills/resolution-advisor/docs/aap/execution-governance.md +++ /dev/null @@ -1 +0,0 @@ -../../../execution-risk-analyzer/docs/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md b/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md deleted file mode 120000 index f3187dee..00000000 --- a/rh-automation/skills/resolution-advisor/docs/aap/governance-readiness.md +++ /dev/null @@ -1 +0,0 @@ -../../../governance-readiness-assessor/docs/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md b/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md deleted file mode 120000 index 1e59ab9b..00000000 --- a/rh-automation/skills/resolution-advisor/docs/aap/job-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../job-failure-analyzer/docs/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/references/README.md b/rh-automation/skills/resolution-advisor/references/README.md similarity index 100% rename from rh-automation/skills/resolution-advisor/docs/references/README.md rename to rh-automation/skills/resolution-advisor/references/README.md diff --git a/rh-automation/skills/resolution-advisor/references/aap/execution-governance.md b/rh-automation/skills/resolution-advisor/references/aap/execution-governance.md new file mode 120000 index 00000000..2ac5f3f2 --- /dev/null +++ b/rh-automation/skills/resolution-advisor/references/aap/execution-governance.md @@ -0,0 +1 @@ +../../../execution-risk-analyzer/references/aap/execution-governance.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/references/aap/governance-readiness.md b/rh-automation/skills/resolution-advisor/references/aap/governance-readiness.md new file mode 120000 index 00000000..5d91608b --- /dev/null +++ b/rh-automation/skills/resolution-advisor/references/aap/governance-readiness.md @@ -0,0 +1 @@ +../../../governance-readiness-assessor/references/aap/governance-readiness.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/references/aap/job-troubleshooting.md b/rh-automation/skills/resolution-advisor/references/aap/job-troubleshooting.md new file mode 120000 index 00000000..728b9df7 --- /dev/null +++ b/rh-automation/skills/resolution-advisor/references/aap/job-troubleshooting.md @@ -0,0 +1 @@ +../../../job-failure-analyzer/references/aap/job-troubleshooting.md \ No newline at end of file diff --git a/rh-automation/skills/resolution-advisor/docs/references/error-classification.md b/rh-automation/skills/resolution-advisor/references/error-classification.md similarity index 95% rename from rh-automation/skills/resolution-advisor/docs/references/error-classification.md rename to rh-automation/skills/resolution-advisor/references/error-classification.md index 342fbf4c..5c15b46a 100644 --- a/rh-automation/skills/resolution-advisor/docs/references/error-classification.md +++ b/rh-automation/skills/resolution-advisor/references/error-classification.md @@ -43,13 +43,13 @@ Not all job failures are the same. A host connectivity issue requires platform i ## When to Use This Document **Use when**: -- After analyzing job events (companion to [job-troubleshooting.md](../aap/job-troubleshooting.md)) +- After analyzing job events (companion to [job-troubleshooting.md](aap/job-troubleshooting.md)) - When the resolution-advisor skill needs to determine resolution paths - When classifying errors for the execution summary report **Do NOT use when**: -- For initial event extraction (use [job-troubleshooting.md](../aap/job-troubleshooting.md) first) -- For execution decisions (use [execution-governance.md](../aap/execution-governance.md)) +- For initial event extraction (use [job-troubleshooting.md](aap/job-troubleshooting.md) first) +- For execution decisions (use [execution-governance.md](aap/execution-governance.md)) --- @@ -307,9 +307,9 @@ Errors caused by mismatches between the playbook's expectations and the target s ## Cross-References -- **[job-troubleshooting.md](../aap/job-troubleshooting.md)** -- Use first for event extraction and host correlation before classifying errors -- **[execution-governance.md](../aap/execution-governance.md)** -- For rollback options after classification determines the error requires immediate remediation -- **[governance-readiness.md](../aap/governance-readiness.md)** -- Platform errors may indicate governance gaps (e.g., single instance group causing capacity issues) +- **[job-troubleshooting.md](aap/job-troubleshooting.md)** -- Use first for event extraction and host correlation before classifying errors +- **[execution-governance.md](aap/execution-governance.md)** -- For rollback options after classification determines the error requires immediate remediation +- **[governance-readiness.md](aap/governance-readiness.md)** -- Platform errors may indicate governance gaps (e.g., single instance group causing capacity issues) --- diff --git a/rh-developer/.catalog/collection.json b/rh-developer/.catalog/collection.json index cb5470d8..5c27d71c 100644 --- a/rh-developer/.catalog/collection.json +++ b/rh-developer/.catalog/collection.json @@ -188,43 +188,43 @@ "resources": [ { "description": "OpenShift platform guides for developers and administrators.", - "embedded_doc": "skills/validate-environment/docs/prerequisites.md", + "embedded_doc": "skills/validate-environment/references/prerequisites.md", "title": "OpenShift documentation", "url": "https://docs.redhat.com/en/documentation/openshift_container_platform/" }, { "description": "Helm install, upgrade, and chart authoring.", - "embedded_doc": "skills/recommend-image/docs/dynamic-validation.md", + "embedded_doc": "skills/recommend-image/references/dynamic-validation.md", "title": "Helm documentation", "url": "https://helm.sh/docs/" }, { "description": "OpenShift builds and S2I concepts.", - "embedded_doc": "skills/detect-project/docs/builder-images.md", + "embedded_doc": "skills/detect-project/references/builder-images.md", "title": "Source-to-Image (S2I)", "url": "https://docs.openshift.com/container-platform/latest/cicd/builds/understanding-image-builds.html" }, { "description": "UBI and base image guidance.", - "embedded_doc": "skills/recommend-image/docs/image-selection-criteria.md", + "embedded_doc": "skills/recommend-image/references/image-selection-criteria.md", "title": "Red Hat Universal Base Images", "url": "https://developers.redhat.com/products/rhel/ubi" }, { "description": "Local container workflows used by the pack.", - "embedded_doc": "skills/debug-build/docs/debugging-patterns.md", + "embedded_doc": "skills/debug-build/references/debugging-patterns.md", "title": "Podman", "url": "https://docs.podman.io/" }, { "description": "Pack policy for confirmations and destructive actions.", - "embedded_doc": "skills/validate-environment/docs/human-in-the-loop.md", + "embedded_doc": "skills/validate-environment/references/human-in-the-loop.md", "title": "Human-in-the-loop (pack)", "url": "https://github.com/RHEcosystemAppEng/agentic-plugins" }, { "description": "SSH/systemd patterns for `/rhel-deploy`.", - "embedded_doc": "skills/rhel-deploy/docs/rhel-deployment.md", + "embedded_doc": "skills/rhel-deploy/references/rhel-deployment.md", "title": "RHEL deployment notes (pack)", "url": "https://github.com/RHEcosystemAppEng/agentic-plugins" } diff --git a/rh-developer/.catalog/collection.yaml b/rh-developer/.catalog/collection.yaml index 9b9ad303..2bd9823a 100644 --- a/rh-developer/.catalog/collection.yaml +++ b/rh-developer/.catalog/collection.yaml @@ -276,31 +276,31 @@ resources: - title: OpenShift documentation url: https://docs.redhat.com/en/documentation/openshift_container_platform/ description: OpenShift platform guides for developers and administrators. - embedded_doc: skills/validate-environment/docs/prerequisites.md + embedded_doc: skills/validate-environment/references/prerequisites.md - title: Helm documentation url: https://helm.sh/docs/ description: Helm install, upgrade, and chart authoring. - embedded_doc: skills/recommend-image/docs/dynamic-validation.md + embedded_doc: skills/recommend-image/references/dynamic-validation.md - title: Source-to-Image (S2I) url: https://docs.openshift.com/container-platform/latest/cicd/builds/understanding-image-builds.html description: OpenShift builds and S2I concepts. - embedded_doc: skills/detect-project/docs/builder-images.md + embedded_doc: skills/detect-project/references/builder-images.md - title: Red Hat Universal Base Images url: https://developers.redhat.com/products/rhel/ubi description: UBI and base image guidance. - embedded_doc: skills/recommend-image/docs/image-selection-criteria.md + embedded_doc: skills/recommend-image/references/image-selection-criteria.md - title: Podman url: https://docs.podman.io/ description: Local container workflows used by the pack. - embedded_doc: skills/debug-build/docs/debugging-patterns.md + embedded_doc: skills/debug-build/references/debugging-patterns.md - title: Human-in-the-loop (pack) url: https://github.com/RHEcosystemAppEng/agentic-plugins description: Pack policy for confirmations and destructive actions. - embedded_doc: skills/validate-environment/docs/human-in-the-loop.md + embedded_doc: skills/validate-environment/references/human-in-the-loop.md - title: RHEL deployment notes (pack) url: https://github.com/RHEcosystemAppEng/agentic-plugins description: SSH/systemd patterns for `/rhel-deploy`. - embedded_doc: skills/rhel-deploy/docs/rhel-deployment.md + embedded_doc: skills/rhel-deploy/references/rhel-deployment.md legal_resources: license_agreement_url: https://github.com/RHEcosystemAppEng/agentic-plugins/blob/main/LICENSE privacy_policy_url: https://www.redhat.com/en/about/privacy-policy diff --git a/rh-developer/skills/containerize-deploy/SKILL.md b/rh-developer/skills/containerize-deploy/SKILL.md index 0f8684f6..e06e6906 100644 --- a/rh-developer/skills/containerize-deploy/SKILL.md +++ b/rh-developer/skills/containerize-deploy/SKILL.md @@ -27,7 +27,7 @@ Use `/containerize-deploy` when a user wants a complete guided workflow from sou ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -471,9 +471,9 @@ Present a summary including: - `/debug-rhel` - RHEL deployment failures (systemd, SELinux, firewall) ### Reference Documentation -- [docs/builder-images.md](docs/builder-images.md) - Language detection, S2I builder images -- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Image variant selection, LTS timelines -- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python S2I configuration -- [docs/rhel-deployment.md](docs/rhel-deployment.md) - RHEL host deployment -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](docs/prerequisites.md) - All required tools by skill +- [references/builder-images.md](references/builder-images.md) - Language detection, S2I builder images +- [references/image-selection-criteria.md](references/image-selection-criteria.md) - Image variant selection, LTS timelines +- [references/python-s2i-entrypoints.md](references/python-s2i-entrypoints.md) - Python S2I configuration +- [references/rhel-deployment.md](references/rhel-deployment.md) - RHEL host deployment +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns and troubleshooting +- [references/prerequisites.md](references/prerequisites.md) - All required tools by skill diff --git a/rh-developer/skills/containerize-deploy/docs/builder-images.md b/rh-developer/skills/containerize-deploy/docs/builder-images.md deleted file mode 120000 index d7f4c63c..00000000 --- a/rh-developer/skills/containerize-deploy/docs/builder-images.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md b/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/containerize-deploy/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md b/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/containerize-deploy/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md b/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md deleted file mode 120000 index e55b7311..00000000 --- a/rh-developer/skills/containerize-deploy/docs/image-selection-criteria.md +++ /dev/null @@ -1 +0,0 @@ -../../recommend-image/docs/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/prerequisites.md b/rh-developer/skills/containerize-deploy/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/containerize-deploy/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md b/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md deleted file mode 120000 index c3416418..00000000 --- a/rh-developer/skills/containerize-deploy/docs/python-s2i-entrypoints.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md b/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md deleted file mode 120000 index 2536fab6..00000000 --- a/rh-developer/skills/containerize-deploy/docs/rhel-deployment.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md b/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/containerize-deploy/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/builder-images.md b/rh-developer/skills/containerize-deploy/references/builder-images.md new file mode 120000 index 00000000..97f9de54 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/builder-images.md @@ -0,0 +1 @@ +../../detect-project/references/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/debugging-patterns.md b/rh-developer/skills/containerize-deploy/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/human-in-the-loop.md b/rh-developer/skills/containerize-deploy/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/image-selection-criteria.md b/rh-developer/skills/containerize-deploy/references/image-selection-criteria.md new file mode 120000 index 00000000..fcd845e9 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/image-selection-criteria.md @@ -0,0 +1 @@ +../../recommend-image/references/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/prerequisites.md b/rh-developer/skills/containerize-deploy/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/python-s2i-entrypoints.md b/rh-developer/skills/containerize-deploy/references/python-s2i-entrypoints.md new file mode 120000 index 00000000..8aebe7b4 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/references/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/rhel-deployment.md b/rh-developer/skills/containerize-deploy/references/rhel-deployment.md new file mode 120000 index 00000000..49e5e7ba --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/rhel-deployment.md @@ -0,0 +1 @@ +../../rhel-deploy/references/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/containerize-deploy/references/selinux-troubleshooting.md b/rh-developer/skills/containerize-deploy/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/containerize-deploy/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/SKILL.md b/rh-developer/skills/debug-build/SKILL.md index a205e3c9..7a1c0416 100644 --- a/rh-developer/skills/debug-build/SKILL.md +++ b/rh-developer/skills/debug-build/SKILL.md @@ -27,7 +27,7 @@ Use this skill when OpenShift builds fail, hang, or produce unexpected results. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -298,7 +298,7 @@ Select an option: ## Build Failure Categories -For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [docs/debugging-patterns.md](docs/debugging-patterns.md). +For S2I build phase failures, common error patterns (Node.js, Python, Java), and troubleshooting decision trees, see [references/debugging-patterns.md](references/debugging-patterns.md). ## Dependencies @@ -311,7 +311,7 @@ For S2I build phase failures, common error patterns (Node.js, Python, Java), and - `/deploy` - To deploy after a successful build ### Reference Documentation -- [docs/builder-images.md](docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification +- [references/builder-images.md](references/builder-images.md) - S2I builder image selection, version mapping +- [references/python-s2i-entrypoints.md](references/python-s2i-entrypoints.md) - Python APP_MODULE configuration +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-build/docs/builder-images.md b/rh-developer/skills/debug-build/docs/builder-images.md deleted file mode 120000 index d7f4c63c..00000000 --- a/rh-developer/skills/debug-build/docs/builder-images.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/human-in-the-loop.md b/rh-developer/skills/debug-build/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-build/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/prerequisites.md b/rh-developer/skills/debug-build/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-build/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md b/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md deleted file mode 120000 index c3416418..00000000 --- a/rh-developer/skills/debug-build/docs/python-s2i-entrypoints.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-build/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/references/builder-images.md b/rh-developer/skills/debug-build/references/builder-images.md new file mode 120000 index 00000000..97f9de54 --- /dev/null +++ b/rh-developer/skills/debug-build/references/builder-images.md @@ -0,0 +1 @@ +../../detect-project/references/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/docs/debugging-patterns.md b/rh-developer/skills/debug-build/references/debugging-patterns.md similarity index 100% rename from rh-developer/skills/debug-build/docs/debugging-patterns.md rename to rh-developer/skills/debug-build/references/debugging-patterns.md diff --git a/rh-developer/skills/debug-build/references/human-in-the-loop.md b/rh-developer/skills/debug-build/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-build/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/references/prerequisites.md b/rh-developer/skills/debug-build/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-build/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/references/python-s2i-entrypoints.md b/rh-developer/skills/debug-build/references/python-s2i-entrypoints.md new file mode 120000 index 00000000..8aebe7b4 --- /dev/null +++ b/rh-developer/skills/debug-build/references/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/references/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/debug-build/references/selinux-troubleshooting.md b/rh-developer/skills/debug-build/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-build/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/SKILL.md b/rh-developer/skills/debug-container/SKILL.md index eccae87b..456968fb 100644 --- a/rh-developer/skills/debug-container/SKILL.md +++ b/rh-developer/skills/debug-container/SKILL.md @@ -35,7 +35,7 @@ Diagnose local Podman/Docker container issues by automatically gathering contain ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## When to Use This Skill @@ -287,7 +287,7 @@ Continue to diagnosis summary? (yes/no) - Evidence: [from logs] - Impact: [application cannot access data] -See [debugging-patterns.md](docs/debugging-patterns.md) for exit code reference. +See [debugging-patterns.md](references/debugging-patterns.md) for exit code reference. ### Recommended Actions @@ -330,7 +330,7 @@ Select an option: **WAIT for user to select next action.** -For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](docs/debugging-patterns.md). +For exit codes, common container issues, and SELinux volume guidance, see [debugging-patterns.md](references/debugging-patterns.md). ## Dependencies @@ -342,5 +342,5 @@ For exit codes, common container issues, and SELinux volume guidance, see [debug - `/recommend-image` - select a better base image ### Reference Documentation -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns, exit codes -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (podman) +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns, exit codes +- [references/prerequisites.md](references/prerequisites.md) - Required tools (podman) diff --git a/rh-developer/skills/debug-container/docs/debugging-patterns.md b/rh-developer/skills/debug-container/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-container/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/human-in-the-loop.md b/rh-developer/skills/debug-container/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-container/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/prerequisites.md b/rh-developer/skills/debug-container/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-container/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-container/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/references/debugging-patterns.md b/rh-developer/skills/debug-container/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-container/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/references/human-in-the-loop.md b/rh-developer/skills/debug-container/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-container/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/references/prerequisites.md b/rh-developer/skills/debug-container/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-container/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-container/references/selinux-troubleshooting.md b/rh-developer/skills/debug-container/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-container/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/SKILL.md b/rh-developer/skills/debug-network/SKILL.md index b5520f04..2e0a970b 100644 --- a/rh-developer/skills/debug-network/SKILL.md +++ b/rh-developer/skills/debug-network/SKILL.md @@ -27,7 +27,7 @@ Use this skill when services cannot communicate, routes return 503/502 errors, o ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -317,7 +317,7 @@ Select an option: ## Common Connectivity Issues -For detailed diagnosis and fix tables covering service, route, and network policy issues, see [docs/debugging-patterns.md](docs/debugging-patterns.md). +For detailed diagnosis and fix tables covering service, route, and network policy issues, see [references/debugging-patterns.md](references/debugging-patterns.md). ## Dependencies @@ -329,5 +329,5 @@ For detailed diagnosis and fix tables covering service, route, and network polic - `/deploy` - To fix and redeploy the service ### Reference Documentation -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-network/docs/debugging-patterns.md b/rh-developer/skills/debug-network/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-network/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/human-in-the-loop.md b/rh-developer/skills/debug-network/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-network/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/prerequisites.md b/rh-developer/skills/debug-network/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-network/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-network/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/references/debugging-patterns.md b/rh-developer/skills/debug-network/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-network/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/references/human-in-the-loop.md b/rh-developer/skills/debug-network/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-network/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/references/prerequisites.md b/rh-developer/skills/debug-network/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-network/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-network/references/selinux-troubleshooting.md b/rh-developer/skills/debug-network/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-network/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/SKILL.md b/rh-developer/skills/debug-pipeline/SKILL.md index 15a2e25d..1d6a1394 100644 --- a/rh-developer/skills/debug-pipeline/SKILL.md +++ b/rh-developer/skills/debug-pipeline/SKILL.md @@ -43,7 +43,7 @@ Use this skill when OpenShift Pipelines (Tekton) fail, hang, or produce unexpect ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -290,7 +290,7 @@ Select an option: ## Pipeline Failure Reference -For failure categories, error patterns, and troubleshooting decision trees, see [docs/debugging-patterns.md](docs/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). +For failure categories, error patterns, and troubleshooting decision trees, see [references/debugging-patterns.md](references/debugging-patterns.md) (sections: Pipeline/Tekton Failure Patterns, Common Tekton Error Messages). ## Dependencies @@ -304,5 +304,5 @@ For failure categories, error patterns, and troubleshooting decision trees, see - `/validate-environment` - To verify OpenShift and pipeline operator setup ### Reference Documentation -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns and pipeline troubleshooting trees +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md b/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-pipeline/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md b/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-pipeline/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/prerequisites.md b/rh-developer/skills/debug-pipeline/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-pipeline/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-pipeline/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/references/debugging-patterns.md b/rh-developer/skills/debug-pipeline/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-pipeline/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/references/human-in-the-loop.md b/rh-developer/skills/debug-pipeline/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-pipeline/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/references/prerequisites.md b/rh-developer/skills/debug-pipeline/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-pipeline/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pipeline/references/selinux-troubleshooting.md b/rh-developer/skills/debug-pipeline/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-pipeline/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/SKILL.md b/rh-developer/skills/debug-pod/SKILL.md index 088e21e0..508c6d27 100644 --- a/rh-developer/skills/debug-pod/SKILL.md +++ b/rh-developer/skills/debug-pod/SKILL.md @@ -27,7 +27,7 @@ Use this skill when pods are not running, restarting frequently, or stuck in non ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -245,7 +245,7 @@ Select an option: **WAIT for user confirmation before proceeding.** -For pod failure categories and exit code reference, see [debugging-patterns.md](docs/debugging-patterns.md). +For pod failure categories and exit code reference, see [debugging-patterns.md](references/debugging-patterns.md). ## Dependencies @@ -258,5 +258,5 @@ For pod failure categories and exit code reference, see [debugging-patterns.md]( - `/deploy` - To redeploy after fixing issues ### Reference Documentation -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting trees -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns and troubleshooting trees +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc), cluster access verification diff --git a/rh-developer/skills/debug-pod/docs/debugging-patterns.md b/rh-developer/skills/debug-pod/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-pod/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/human-in-the-loop.md b/rh-developer/skills/debug-pod/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-pod/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/prerequisites.md b/rh-developer/skills/debug-pod/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-pod/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-pod/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/references/debugging-patterns.md b/rh-developer/skills/debug-pod/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-pod/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/references/human-in-the-loop.md b/rh-developer/skills/debug-pod/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-pod/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/references/prerequisites.md b/rh-developer/skills/debug-pod/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-pod/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-pod/references/selinux-troubleshooting.md b/rh-developer/skills/debug-pod/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-pod/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/SKILL.md b/rh-developer/skills/debug-rbac/SKILL.md index 4be8596e..71899f2a 100644 --- a/rh-developer/skills/debug-rbac/SKILL.md +++ b/rh-developer/skills/debug-rbac/SKILL.md @@ -39,7 +39,7 @@ Diagnose RBAC permission failures on OpenShift by analyzing pod logs, readiness ## Prerequisites -**Required MCP Servers:** `openshift` ([setup](docs/prerequisites.md)) +**Required MCP Servers:** `openshift` ([setup](references/prerequisites.md)) **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, Pod, ServiceAccount, Role, and RoleBinding details @@ -425,7 +425,7 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events ([setup](docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, ServiceAccounts, Roles, RoleBindings, and Events ([setup](references/prerequisites.md)) ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, Pod, ServiceAccount, Role, RoleBinding) @@ -440,7 +440,7 @@ Select an option: - `/debug-network` — If pods can't reach services (network, not API access) ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [references/debugging-patterns.md](references/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [Using RBAC - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/using-rbac.html) ## Example Usage diff --git a/rh-developer/skills/debug-rbac/docs/debugging-patterns.md b/rh-developer/skills/debug-rbac/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-rbac/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/docs/prerequisites.md b/rh-developer/skills/debug-rbac/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-rbac/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-rbac/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/references/debugging-patterns.md b/rh-developer/skills/debug-rbac/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-rbac/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/references/prerequisites.md b/rh-developer/skills/debug-rbac/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-rbac/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rbac/references/selinux-troubleshooting.md b/rh-developer/skills/debug-rbac/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-rbac/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/SKILL.md b/rh-developer/skills/debug-rhel/SKILL.md index 53d30afb..70b8235f 100644 --- a/rh-developer/skills/debug-rhel/SKILL.md +++ b/rh-developer/skills/debug-rhel/SKILL.md @@ -35,7 +35,7 @@ Diagnose RHEL system issues by automatically gathering systemd status, journal l ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Note: SSH/Bash Required @@ -439,7 +439,7 @@ Select an option: **WAIT for user to select next action.** -For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](docs/debugging-patterns.md) and [selinux-troubleshooting.md](docs/selinux-troubleshooting.md). +For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [debugging-patterns.md](references/debugging-patterns.md) and [selinux-troubleshooting.md](references/selinux-troubleshooting.md). ## Dependencies @@ -451,7 +451,7 @@ For common RHEL issues (systemd exit codes, SELinux denials, firewall), see [deb - `/debug-container` - debug Podman containers on the host ### Reference Documentation -- [docs/selinux-troubleshooting.md](docs/selinux-troubleshooting.md) - SELinux denial analysis -- [docs/rhel-deployment.md](docs/rhel-deployment.md) - RHEL deployment patterns -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools and setup +- [references/selinux-troubleshooting.md](references/selinux-troubleshooting.md) - SELinux denial analysis +- [references/rhel-deployment.md](references/rhel-deployment.md) - RHEL deployment patterns +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns +- [references/prerequisites.md](references/prerequisites.md) - Required tools and setup diff --git a/rh-developer/skills/debug-rhel/docs/debugging-patterns.md b/rh-developer/skills/debug-rhel/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-rhel/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md b/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/debug-rhel/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/prerequisites.md b/rh-developer/skills/debug-rhel/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-rhel/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/rhel-deployment.md b/rh-developer/skills/debug-rhel/docs/rhel-deployment.md deleted file mode 120000 index 2536fab6..00000000 --- a/rh-developer/skills/debug-rhel/docs/rhel-deployment.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-rhel/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/references/debugging-patterns.md b/rh-developer/skills/debug-rhel/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-rhel/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/references/human-in-the-loop.md b/rh-developer/skills/debug-rhel/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/debug-rhel/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/references/prerequisites.md b/rh-developer/skills/debug-rhel/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-rhel/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/references/rhel-deployment.md b/rh-developer/skills/debug-rhel/references/rhel-deployment.md new file mode 120000 index 00000000..49e5e7ba --- /dev/null +++ b/rh-developer/skills/debug-rhel/references/rhel-deployment.md @@ -0,0 +1 @@ +../../rhel-deploy/references/rhel-deployment.md \ No newline at end of file diff --git a/rh-developer/skills/debug-rhel/references/selinux-troubleshooting.md b/rh-developer/skills/debug-rhel/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-rhel/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/SKILL.md b/rh-developer/skills/debug-scc/SKILL.md index 4ae10776..04206920 100644 --- a/rh-developer/skills/debug-scc/SKILL.md +++ b/rh-developer/skills/debug-scc/SKILL.md @@ -39,7 +39,7 @@ Diagnose OpenShift SCC violations that block pod creation by analyzing security ## Prerequisites -**Required MCP Servers:** `openshift` ([setup](docs/prerequisites.md)) +**Required MCP Servers:** `openshift` ([setup](references/prerequisites.md)) **Required MCP Tools:** - `resources_get` (from openshift) — Retrieve Deployment, ReplicaSet, and ServiceAccount details @@ -435,7 +435,7 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints ([setup](docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, ReplicaSets, Events, ServiceAccounts, and SecurityContextConstraints ([setup](references/prerequisites.md)) ### Required MCP Tools - `resources_get` (from openshift) — Retrieve individual resource details (Deployment, ReplicaSet, ServiceAccount) @@ -448,7 +448,7 @@ Select an option: - `/debug-rbac` — If pods run but fail with 403 Forbidden API errors (RBAC, not SCC) ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [references/debugging-patterns.md](references/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [Managing SCCs - OpenShift](https://docs.openshift.com/container-platform/latest/authentication/managing-security-context-constraints.html) ## Example Usage diff --git a/rh-developer/skills/debug-scc/docs/debugging-patterns.md b/rh-developer/skills/debug-scc/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/debug-scc/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/docs/prerequisites.md b/rh-developer/skills/debug-scc/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/debug-scc/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md b/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/debug-scc/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/references/debugging-patterns.md b/rh-developer/skills/debug-scc/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/debug-scc/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/references/prerequisites.md b/rh-developer/skills/debug-scc/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/debug-scc/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/debug-scc/references/selinux-troubleshooting.md b/rh-developer/skills/debug-scc/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/debug-scc/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/SKILL.md b/rh-developer/skills/deploy/SKILL.md index 5198e805..aaee16d4 100644 --- a/rh-developer/skills/deploy/SKILL.md +++ b/rh-developer/skills/deploy/SKILL.md @@ -27,7 +27,7 @@ Use `/deploy` after building a container image (via `/s2i-build` or external reg ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -275,5 +275,5 @@ Your application is now live! - `/debug-build` - Build failures before deployment ### Reference Documentation -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc), cluster access verification -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc), cluster access verification +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns and troubleshooting diff --git a/rh-developer/skills/deploy/docs/debugging-patterns.md b/rh-developer/skills/deploy/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/deploy/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/human-in-the-loop.md b/rh-developer/skills/deploy/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/deploy/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/prerequisites.md b/rh-developer/skills/deploy/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/deploy/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/docs/selinux-troubleshooting.md b/rh-developer/skills/deploy/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/deploy/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/references/debugging-patterns.md b/rh-developer/skills/deploy/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/deploy/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/references/human-in-the-loop.md b/rh-developer/skills/deploy/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/deploy/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/references/prerequisites.md b/rh-developer/skills/deploy/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/deploy/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/deploy/references/selinux-troubleshooting.md b/rh-developer/skills/deploy/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/deploy/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/SKILL.md b/rh-developer/skills/detect-project/SKILL.md index 933c0389..5028d868 100644 --- a/rh-developer/skills/detect-project/SKILL.md +++ b/rh-developer/skills/detect-project/SKILL.md @@ -27,7 +27,7 @@ Analyze the project to detect language/framework and recommend a build strategy. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -274,6 +274,6 @@ After successful detection, these values should be available for other skills: - `/rhel-deploy` - Deploy to RHEL using detected project info ### Reference Documentation -- [docs/builder-images.md](docs/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection -- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (git) +- [references/builder-images.md](references/builder-images.md) - Language detection matrix, version-to-image mapping, S2I builder selection +- [references/python-s2i-entrypoints.md](references/python-s2i-entrypoints.md) - Python entry point detection, APP_MODULE configuration +- [references/prerequisites.md](references/prerequisites.md) - Required tools (git) diff --git a/rh-developer/skills/detect-project/docs/human-in-the-loop.md b/rh-developer/skills/detect-project/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/detect-project/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/docs/prerequisites.md b/rh-developer/skills/detect-project/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/detect-project/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/docs/builder-images.md b/rh-developer/skills/detect-project/references/builder-images.md similarity index 100% rename from rh-developer/skills/detect-project/docs/builder-images.md rename to rh-developer/skills/detect-project/references/builder-images.md diff --git a/rh-developer/skills/detect-project/references/human-in-the-loop.md b/rh-developer/skills/detect-project/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/detect-project/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/references/prerequisites.md b/rh-developer/skills/detect-project/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/detect-project/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/detect-project/docs/python-s2i-entrypoints.md b/rh-developer/skills/detect-project/references/python-s2i-entrypoints.md similarity index 100% rename from rh-developer/skills/detect-project/docs/python-s2i-entrypoints.md rename to rh-developer/skills/detect-project/references/python-s2i-entrypoints.md diff --git a/rh-developer/skills/helm-deploy/SKILL.md b/rh-developer/skills/helm-deploy/SKILL.md index cc7fed5d..460a4d25 100644 --- a/rh-developer/skills/helm-deploy/SKILL.md +++ b/rh-developer/skills/helm-deploy/SKILL.md @@ -28,7 +28,7 @@ Deploy applications to OpenShift using Helm charts. Supports existing charts or ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -353,6 +353,6 @@ Your application is live! - `/debug-network` - Diagnose networking issues with deployed services ### Reference Documentation -- [docs/builder-images.md](docs/builder-images.md) - Container image references for chart values -- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Image variant selection for production deployments -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc, helm) +- [references/builder-images.md](references/builder-images.md) - Container image references for chart values +- [references/image-selection-criteria.md](references/image-selection-criteria.md) - Image variant selection for production deployments +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc, helm) diff --git a/rh-developer/skills/helm-deploy/docs/builder-images.md b/rh-developer/skills/helm-deploy/docs/builder-images.md deleted file mode 120000 index d7f4c63c..00000000 --- a/rh-developer/skills/helm-deploy/docs/builder-images.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md b/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/helm-deploy/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md b/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md deleted file mode 120000 index e55b7311..00000000 --- a/rh-developer/skills/helm-deploy/docs/image-selection-criteria.md +++ /dev/null @@ -1 +0,0 @@ -../../recommend-image/docs/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/docs/prerequisites.md b/rh-developer/skills/helm-deploy/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/helm-deploy/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/references/builder-images.md b/rh-developer/skills/helm-deploy/references/builder-images.md new file mode 120000 index 00000000..97f9de54 --- /dev/null +++ b/rh-developer/skills/helm-deploy/references/builder-images.md @@ -0,0 +1 @@ +../../detect-project/references/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/references/human-in-the-loop.md b/rh-developer/skills/helm-deploy/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/helm-deploy/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/references/image-selection-criteria.md b/rh-developer/skills/helm-deploy/references/image-selection-criteria.md new file mode 120000 index 00000000..fcd845e9 --- /dev/null +++ b/rh-developer/skills/helm-deploy/references/image-selection-criteria.md @@ -0,0 +1 @@ +../../recommend-image/references/image-selection-criteria.md \ No newline at end of file diff --git a/rh-developer/skills/helm-deploy/references/prerequisites.md b/rh-developer/skills/helm-deploy/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/helm-deploy/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/SKILL.md b/rh-developer/skills/incident-triage/SKILL.md index 7fa2ab52..fc1c8ec3 100644 --- a/rh-developer/skills/incident-triage/SKILL.md +++ b/rh-developer/skills/incident-triage/SKILL.md @@ -40,7 +40,7 @@ Structured incident investigation for OpenShift — traces from symptoms to root ## Prerequisites **Required MCP Servers:** -- `openshift` ([setup](docs/prerequisites.md)) — Kubernetes/OpenShift resource access +- `openshift` ([setup](references/prerequisites.md)) — Kubernetes/OpenShift resource access - `observability` — Prometheus metric discovery and PromQL query execution **Required MCP Tools:** @@ -455,7 +455,7 @@ Select an option: ## Dependencies ### Required MCP Servers -- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, Events, Services, and cluster resources ([setup](docs/prerequisites.md)) +- `openshift` — Kubernetes/OpenShift resource access for Deployments, Pods, Events, Services, and cluster resources ([setup](references/prerequisites.md)) - `observability` — Prometheus metric discovery, metadata, series, and PromQL query execution ### Required MCP Tools @@ -477,7 +477,7 @@ Select an option: - `/deploy` — Redeployment after fixes ### Reference Documentation -- **Internal:** [docs/debugging-patterns.md](docs/debugging-patterns.md) — Common error patterns and troubleshooting trees +- **Internal:** [references/debugging-patterns.md](references/debugging-patterns.md) — Common error patterns and troubleshooting trees - **Official:** [OpenShift Troubleshooting](https://docs.openshift.com/container-platform/latest/support/troubleshooting/troubleshooting-operator-issues.html) ## Example Usage diff --git a/rh-developer/skills/incident-triage/docs/debugging-patterns.md b/rh-developer/skills/incident-triage/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/incident-triage/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/docs/prerequisites.md b/rh-developer/skills/incident-triage/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/incident-triage/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md b/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/incident-triage/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/references/debugging-patterns.md b/rh-developer/skills/incident-triage/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/incident-triage/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/references/prerequisites.md b/rh-developer/skills/incident-triage/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/incident-triage/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/incident-triage/references/selinux-troubleshooting.md b/rh-developer/skills/incident-triage/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/incident-triage/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/SKILL.md b/rh-developer/skills/recommend-image/SKILL.md index 28d6d883..e862d167 100644 --- a/rh-developer/skills/recommend-image/SKILL.md +++ b/rh-developer/skills/recommend-image/SKILL.md @@ -24,7 +24,7 @@ Provide intelligent, use-case-aware container image recommendations that go beyo ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -116,7 +116,7 @@ For each language, evaluate available variants against user requirements. **Key Scoring Factors:** Image size, security posture, build tools availability, startup time, LTS status -> **See [docs/image-selection-criteria.md](docs/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). +> **See [references/image-selection-criteria.md](references/image-selection-criteria.md)** for comprehensive scoring matrices with weighted criteria by environment (production/development/edge/serverless). ### Step 3.5: Dynamic Image Validation @@ -143,7 +143,7 @@ To provide accurate image recommendations, I need `skopeo` to inspect container - Check architecture support (amd64, arm64) - Show when the image was last built -**Install skopeo:** See [docs/prerequisites.md](docs/prerequisites.md) for installation commands by OS. +**Install skopeo:** See [references/prerequisites.md](references/prerequisites.md) for installation commands by OS. After installing, run `/recommend-image` again for enhanced recommendations. @@ -266,7 +266,7 @@ Return to Step 2 with new inputs. - **Development** → Full variant - **Serverless** → Smallest available (minimal or native binary) -> **See [docs/image-selection-criteria.md](docs/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). +> **See [references/image-selection-criteria.md](references/image-selection-criteria.md)** for comprehensive image size references, LTS timelines, decision trees, and framework-specific recommendations (Quarkus, Spring Boot, Next.js, Django/Flask). ## Dependencies @@ -278,7 +278,7 @@ Return to Step 2 with new inputs. - `/s2i-build` - Build with the recommended image ### Reference Documentation -- [docs/image-selection-criteria.md](docs/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees -- [docs/builder-images.md](docs/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability -- [docs/dynamic-validation.md](docs/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns -- [docs/prerequisites.md](docs/prerequisites.md) - Skopeo installation instructions +- [references/image-selection-criteria.md](references/image-selection-criteria.md) - Comprehensive scoring matrices, image size reference, LTS timelines, decision trees +- [references/builder-images.md](references/builder-images.md) - UBI image registry, framework-specific recommendations, variant availability +- [references/dynamic-validation.md](references/dynamic-validation.md) - Skopeo commands, Red Hat Security Data API, image verification patterns +- [references/prerequisites.md](references/prerequisites.md) - Skopeo installation instructions diff --git a/rh-developer/skills/recommend-image/docs/builder-images.md b/rh-developer/skills/recommend-image/docs/builder-images.md deleted file mode 120000 index d7f4c63c..00000000 --- a/rh-developer/skills/recommend-image/docs/builder-images.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/docs/human-in-the-loop.md b/rh-developer/skills/recommend-image/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/recommend-image/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/docs/prerequisites.md b/rh-developer/skills/recommend-image/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/recommend-image/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/references/builder-images.md b/rh-developer/skills/recommend-image/references/builder-images.md new file mode 120000 index 00000000..97f9de54 --- /dev/null +++ b/rh-developer/skills/recommend-image/references/builder-images.md @@ -0,0 +1 @@ +../../detect-project/references/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/docs/dynamic-validation.md b/rh-developer/skills/recommend-image/references/dynamic-validation.md similarity index 100% rename from rh-developer/skills/recommend-image/docs/dynamic-validation.md rename to rh-developer/skills/recommend-image/references/dynamic-validation.md diff --git a/rh-developer/skills/recommend-image/references/human-in-the-loop.md b/rh-developer/skills/recommend-image/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/recommend-image/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/recommend-image/docs/image-selection-criteria.md b/rh-developer/skills/recommend-image/references/image-selection-criteria.md similarity index 100% rename from rh-developer/skills/recommend-image/docs/image-selection-criteria.md rename to rh-developer/skills/recommend-image/references/image-selection-criteria.md diff --git a/rh-developer/skills/recommend-image/references/prerequisites.md b/rh-developer/skills/recommend-image/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/recommend-image/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/SKILL.md b/rh-developer/skills/rhel-deploy/SKILL.md index ffacd851..10442b00 100644 --- a/rh-developer/skills/rhel-deploy/SKILL.md +++ b/rh-developer/skills/rhel-deploy/SKILL.md @@ -43,7 +43,7 @@ Use `/rhel-deploy` when deploying applications to standalone RHEL, Fedora, or Ce ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -242,7 +242,7 @@ ssh [target] "podman pull [image-reference]" | Environment | [list env vars] | | Run Mode | [rootless / rootful] | -**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [docs/rhel-deployment.md](docs/rhel-deployment.md) for SELinux configuration details. +**SELinux Volume Labels:** Use `:z` for shared volumes, `:Z` for private volumes. See [references/rhel-deployment.md](references/rhel-deployment.md) for SELinux configuration details. Proceed with this configuration? (yes/modify/cancel) ``` @@ -324,7 +324,7 @@ Proceed with firewall configuration? (yes/skip) **Runtime packages for [language]:** -See [docs/rhel-deployment.md](docs/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). +See [references/rhel-deployment.md](references/rhel-deployment.md) for the complete runtime package mapping by language and RHEL version (Node.js, Python, Java, Go, Ruby, PHP). **Commands to execute:** ```bash @@ -381,7 +381,7 @@ Proceed with deployment? (yes/no) | `${PORT}` | [container-port] | Application listen port | | `${START_COMMAND}` | [see below] | Language-specific start command | -**Start commands by language:** See [docs/rhel-deployment.md](docs/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). +**Start commands by language:** See [references/rhel-deployment.md](references/rhel-deployment.md) for language-specific systemd unit templates (Node.js, Python, Java, Go). **Target location:** `/etc/systemd/system/[app-name].service` @@ -478,7 +478,7 @@ Select an option: - `/debug-container` - Container startup issues on RHEL host ### Reference Documentation -- [docs/rhel-deployment.md](docs/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages -- [docs/selinux-troubleshooting.md](docs/selinux-troubleshooting.md) - SELinux denial analysis and fixes -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common error patterns and troubleshooting -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (ssh, podman) +- [references/rhel-deployment.md](references/rhel-deployment.md) - Systemd templates, SELinux, firewall, runtime packages +- [references/selinux-troubleshooting.md](references/selinux-troubleshooting.md) - SELinux denial analysis and fixes +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common error patterns and troubleshooting +- [references/prerequisites.md](references/prerequisites.md) - Required tools (ssh, podman) diff --git a/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md b/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/rhel-deploy/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md b/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/rhel-deploy/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/docs/prerequisites.md b/rh-developer/skills/rhel-deploy/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/rhel-deploy/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/references/debugging-patterns.md b/rh-developer/skills/rhel-deploy/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/rhel-deploy/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/references/human-in-the-loop.md b/rh-developer/skills/rhel-deploy/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/rhel-deploy/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/references/prerequisites.md b/rh-developer/skills/rhel-deploy/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/rhel-deploy/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/rhel-deploy/docs/rhel-deployment.md b/rh-developer/skills/rhel-deploy/references/rhel-deployment.md similarity index 100% rename from rh-developer/skills/rhel-deploy/docs/rhel-deployment.md rename to rh-developer/skills/rhel-deploy/references/rhel-deployment.md diff --git a/rh-developer/skills/rhel-deploy/docs/selinux-troubleshooting.md b/rh-developer/skills/rhel-deploy/references/selinux-troubleshooting.md similarity index 100% rename from rh-developer/skills/rhel-deploy/docs/selinux-troubleshooting.md rename to rh-developer/skills/rhel-deploy/references/selinux-troubleshooting.md diff --git a/rh-developer/skills/s2i-build/SKILL.md b/rh-developer/skills/s2i-build/SKILL.md index 15903e47..686f1694 100644 --- a/rh-developer/skills/s2i-build/SKILL.md +++ b/rh-developer/skills/s2i-build/SKILL.md @@ -27,7 +27,7 @@ Use this skill after `/detect-project` to build container images from source cod ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. ## Workflow @@ -387,7 +387,7 @@ What would you like to do? - `/deploy` - After successful build, to deploy the image ### Reference Documentation -- [docs/builder-images.md](docs/builder-images.md) - S2I builder image selection, version mapping -- [docs/python-s2i-entrypoints.md](docs/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting -- [docs/debugging-patterns.md](docs/debugging-patterns.md) - Common build error patterns and troubleshooting -- [docs/prerequisites.md](docs/prerequisites.md) - Required tools (oc) +- [references/builder-images.md](references/builder-images.md) - S2I builder image selection, version mapping +- [references/python-s2i-entrypoints.md](references/python-s2i-entrypoints.md) - Python APP_MODULE configuration, entry point troubleshooting +- [references/debugging-patterns.md](references/debugging-patterns.md) - Common build error patterns and troubleshooting +- [references/prerequisites.md](references/prerequisites.md) - Required tools (oc) diff --git a/rh-developer/skills/s2i-build/docs/builder-images.md b/rh-developer/skills/s2i-build/docs/builder-images.md deleted file mode 120000 index d7f4c63c..00000000 --- a/rh-developer/skills/s2i-build/docs/builder-images.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/debugging-patterns.md b/rh-developer/skills/s2i-build/docs/debugging-patterns.md deleted file mode 120000 index b446f69b..00000000 --- a/rh-developer/skills/s2i-build/docs/debugging-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../debug-build/docs/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/human-in-the-loop.md b/rh-developer/skills/s2i-build/docs/human-in-the-loop.md deleted file mode 120000 index 9a524eda..00000000 --- a/rh-developer/skills/s2i-build/docs/human-in-the-loop.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/prerequisites.md b/rh-developer/skills/s2i-build/docs/prerequisites.md deleted file mode 120000 index 9572b8c5..00000000 --- a/rh-developer/skills/s2i-build/docs/prerequisites.md +++ /dev/null @@ -1 +0,0 @@ -../../validate-environment/docs/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md b/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md deleted file mode 120000 index c3416418..00000000 --- a/rh-developer/skills/s2i-build/docs/python-s2i-entrypoints.md +++ /dev/null @@ -1 +0,0 @@ -../../detect-project/docs/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md b/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md deleted file mode 120000 index 43136b67..00000000 --- a/rh-developer/skills/s2i-build/docs/selinux-troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../rhel-deploy/docs/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/builder-images.md b/rh-developer/skills/s2i-build/references/builder-images.md new file mode 120000 index 00000000..97f9de54 --- /dev/null +++ b/rh-developer/skills/s2i-build/references/builder-images.md @@ -0,0 +1 @@ +../../detect-project/references/builder-images.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/debugging-patterns.md b/rh-developer/skills/s2i-build/references/debugging-patterns.md new file mode 120000 index 00000000..2beddbbb --- /dev/null +++ b/rh-developer/skills/s2i-build/references/debugging-patterns.md @@ -0,0 +1 @@ +../../debug-build/references/debugging-patterns.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/human-in-the-loop.md b/rh-developer/skills/s2i-build/references/human-in-the-loop.md new file mode 120000 index 00000000..f1ad4f41 --- /dev/null +++ b/rh-developer/skills/s2i-build/references/human-in-the-loop.md @@ -0,0 +1 @@ +../../validate-environment/references/human-in-the-loop.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/prerequisites.md b/rh-developer/skills/s2i-build/references/prerequisites.md new file mode 120000 index 00000000..fcbcb5f2 --- /dev/null +++ b/rh-developer/skills/s2i-build/references/prerequisites.md @@ -0,0 +1 @@ +../../validate-environment/references/prerequisites.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/python-s2i-entrypoints.md b/rh-developer/skills/s2i-build/references/python-s2i-entrypoints.md new file mode 120000 index 00000000..8aebe7b4 --- /dev/null +++ b/rh-developer/skills/s2i-build/references/python-s2i-entrypoints.md @@ -0,0 +1 @@ +../../detect-project/references/python-s2i-entrypoints.md \ No newline at end of file diff --git a/rh-developer/skills/s2i-build/references/selinux-troubleshooting.md b/rh-developer/skills/s2i-build/references/selinux-troubleshooting.md new file mode 120000 index 00000000..f48ad852 --- /dev/null +++ b/rh-developer/skills/s2i-build/references/selinux-troubleshooting.md @@ -0,0 +1 @@ +../../rhel-deploy/references/selinux-troubleshooting.md \ No newline at end of file diff --git a/rh-developer/skills/validate-environment/SKILL.md b/rh-developer/skills/validate-environment/SKILL.md index abd85418..26d11cb2 100644 --- a/rh-developer/skills/validate-environment/SKILL.md +++ b/rh-developer/skills/validate-environment/SKILL.md @@ -22,7 +22,7 @@ Check that required tools and environment are properly configured. ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](references/human-in-the-loop.md) for mandatory checkpoint behavior. **Key Rules:** 1. WAIT for user to select validation scope before running checks @@ -65,7 +65,7 @@ check_tool() { **Tools to check:** git, curl, jq, oc, helm, podman, docker, skopeo, ssh -> **See [docs/prerequisites.md](docs/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. +> **See [references/prerequisites.md](references/prerequisites.md)** for the complete tool requirements by skill, check commands, and installation instructions. ### Step 3: Check OpenShift Connectivity (if TARGET includes openshift) @@ -185,7 +185,7 @@ Select an option or describe what you'd like to do: This tool is required for [skill-names]. -See [docs/prerequisites.md](docs/prerequisites.md) for installation commands by OS. +See [references/prerequisites.md](references/prerequisites.md) for installation commands by OS. ``` ### Cluster Connection Failed @@ -231,4 +231,4 @@ Options: - `/deploy` - Deployment requiring oc and cluster access ### Reference Documentation -- [docs/prerequisites.md](docs/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification +- [references/prerequisites.md](references/prerequisites.md) - Comprehensive tool requirements by skill, installation commands, cluster access verification diff --git a/rh-developer/skills/validate-environment/docs/human-in-the-loop.md b/rh-developer/skills/validate-environment/references/human-in-the-loop.md similarity index 97% rename from rh-developer/skills/validate-environment/docs/human-in-the-loop.md rename to rh-developer/skills/validate-environment/references/human-in-the-loop.md index 696fccf1..d228a4bb 100644 --- a/rh-developer/skills/validate-environment/docs/human-in-the-loop.md +++ b/rh-developer/skills/validate-environment/references/human-in-the-loop.md @@ -69,7 +69,7 @@ Add this section after Prerequisites in your SKILL.md: ```markdown ## Critical: Human-in-the-Loop Requirements -See [Human-in-the-Loop Requirements](../docs/human-in-the-loop.md) for mandatory checkpoint behavior. +See [Human-in-the-Loop Requirements](human-in-the-loop.md) for mandatory checkpoint behavior. **Key Rules:** 1. WAIT for explicit user confirmation at each phase diff --git a/rh-developer/skills/validate-environment/docs/prerequisites.md b/rh-developer/skills/validate-environment/references/prerequisites.md similarity index 100% rename from rh-developer/skills/validate-environment/docs/prerequisites.md rename to rh-developer/skills/validate-environment/references/prerequisites.md diff --git a/rh-sre/.catalog/collection.json b/rh-sre/.catalog/collection.json index 87cf91c2..304565c4 100644 --- a/rh-sre/.catalog/collection.json +++ b/rh-sre/.catalog/collection.json @@ -143,43 +143,43 @@ }, { "description": "Creating remediation plans, playbook generation.", - "embedded_doc": "skills/playbook-generator/docs/ansible/cve-remediation-templates.md", + "embedded_doc": "skills/playbook-generator/references/ansible/cve-remediation-templates.md", "title": "Red Hat Lightspeed Remediations Guide", "url": "https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index" }, { "description": "MCP server used by this collection; parameter reference.", - "embedded_doc": "skills/cve-impact/docs/references/lightspeed-mcp-parameters.md", + "embedded_doc": "skills/cve-impact/references/lightspeed-mcp-parameters.md", "title": "Red Hat Lightspeed MCP", "url": "https://github.com/RedHatInsights/insights-mcp" }, { "description": "CVE identification, classification, threat intelligence.", - "embedded_doc": "skills/cve-validation/docs/insights/vulnerability-logic.md", + "embedded_doc": "skills/cve-validation/references/insights/vulnerability-logic.md", "title": "Assessing and Monitoring Security Vulnerabilities on RHEL Systems", "url": "https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview" }, { "description": "DNF commands, updating packages, repository management.", - "embedded_doc": "skills/playbook-generator/docs/rhel/package-management.md", + "embedded_doc": "skills/playbook-generator/references/rhel/package-management.md", "title": "Managing Software with the DNF Tool (RHEL 9)", "url": "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index" }, { "description": "Red Hat severity ratings, CVSS usage.", - "embedded_doc": "skills/cve-validation/docs/references/cvss-scoring.md", + "embedded_doc": "skills/cve-validation/references/cvss-scoring.md", "title": "Severity Ratings (Red Hat Customer Portal)", "url": "https://access.redhat.com/security/updates/classification" }, { "description": "AAP 2.6 docs; projects, job templates, playbook integration.", - "embedded_doc": "skills/playbook-executor/docs/ansible/playbook-integration-aap.md", + "embedded_doc": "skills/playbook-executor/references/ansible/playbook-integration-aap.md", "title": "Red Hat Ansible Automation Platform Documentation", "url": "https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6" }, { "description": "Job templates, check mode, dry-run execution.", - "embedded_doc": "skills/playbook-executor/docs/ansible/aap-job-execution.md", + "embedded_doc": "skills/playbook-executor/references/ansible/aap-job-execution.md", "title": "AAP Job Execution", "url": "https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates" }, diff --git a/rh-sre/.catalog/collection.yaml b/rh-sre/.catalog/collection.yaml index ee5c57dc..ea5178ae 100644 --- a/rh-sre/.catalog/collection.yaml +++ b/rh-sre/.catalog/collection.yaml @@ -266,31 +266,31 @@ resources: - title: Red Hat Lightspeed Remediations Guide url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html-single/red_hat_lightspeed_remediations_guide/index description: Creating remediation plans, playbook generation. - embedded_doc: skills/playbook-generator/docs/ansible/cve-remediation-templates.md + embedded_doc: skills/playbook-generator/references/ansible/cve-remediation-templates.md - title: Red Hat Lightspeed MCP url: https://github.com/RedHatInsights/insights-mcp description: MCP server used by this collection; parameter reference. - embedded_doc: skills/cve-impact/docs/references/lightspeed-mcp-parameters.md + embedded_doc: skills/cve-impact/references/lightspeed-mcp-parameters.md - title: Assessing and Monitoring Security Vulnerabilities on RHEL Systems url: https://docs.redhat.com/en/documentation/red_hat_lightspeed/1-latest/html/assessing_and_monitoring_security_vulnerabilities_on_rhel_systems/vuln-cves_vuln-overview description: CVE identification, classification, threat intelligence. - embedded_doc: skills/cve-validation/docs/insights/vulnerability-logic.md + embedded_doc: skills/cve-validation/references/insights/vulnerability-logic.md - title: Managing Software with the DNF Tool (RHEL 9) url: https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html-single/managing_software_with_the_dnf_tool/index description: DNF commands, updating packages, repository management. - embedded_doc: skills/playbook-generator/docs/rhel/package-management.md + embedded_doc: skills/playbook-generator/references/rhel/package-management.md - title: Severity Ratings (Red Hat Customer Portal) url: https://access.redhat.com/security/updates/classification description: Red Hat severity ratings, CVSS usage. - embedded_doc: skills/cve-validation/docs/references/cvss-scoring.md + embedded_doc: skills/cve-validation/references/cvss-scoring.md - title: Red Hat Ansible Automation Platform Documentation url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6 description: AAP 2.6 docs; projects, job templates, playbook integration. - embedded_doc: skills/playbook-executor/docs/ansible/playbook-integration-aap.md + embedded_doc: skills/playbook-executor/references/ansible/playbook-integration-aap.md - title: AAP Job Execution url: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-job-templates description: Job templates, check mode, dry-run execution. - embedded_doc: skills/playbook-executor/docs/ansible/aap-job-execution.md + embedded_doc: skills/playbook-executor/references/ansible/aap-job-execution.md - title: Ansible Automation Platform url: https://www.redhat.com/en/technologies/management/ansible description: AAP product overview for playbook execution. diff --git a/rh-sre/docs/.ai-index/cross-reference-graph.json b/rh-sre/references/.ai-index/cross-reference-graph.json similarity index 100% rename from rh-sre/docs/.ai-index/cross-reference-graph.json rename to rh-sre/references/.ai-index/cross-reference-graph.json diff --git a/rh-sre/docs/.ai-index/semantic-index.json b/rh-sre/references/.ai-index/semantic-index.json similarity index 100% rename from rh-sre/docs/.ai-index/semantic-index.json rename to rh-sre/references/.ai-index/semantic-index.json diff --git a/rh-sre/docs/.ai-index/task-to-docs-mapping.json b/rh-sre/references/.ai-index/task-to-docs-mapping.json similarity index 100% rename from rh-sre/docs/.ai-index/task-to-docs-mapping.json rename to rh-sre/references/.ai-index/task-to-docs-mapping.json diff --git a/rh-sre/docs/INDEX.md b/rh-sre/references/INDEX.md similarity index 100% rename from rh-sre/docs/INDEX.md rename to rh-sre/references/INDEX.md diff --git a/rh-sre/docs/SOURCES.md b/rh-sre/references/SOURCES.md similarity index 99% rename from rh-sre/docs/SOURCES.md rename to rh-sre/references/SOURCES.md index 06478094..43461750 100644 --- a/rh-sre/docs/SOURCES.md +++ b/rh-sre/references/SOURCES.md @@ -97,7 +97,7 @@ This source list is maintained as part of the Remediation Agent plugin. When doc 1. Update this SOURCES.md file with new entries 2. Update the YAML frontmatter in affected documentation files -3. Regenerate the semantic index using `docs/.ai-index/generate-index.py` +3. Regenerate the semantic index using `references/.ai-index/generate-index.py` 4. Update the "Last Verified" date in the table above ## Contact diff --git a/rh-sre/skills/cve-impact/SKILL.md b/rh-sre/skills/cve-impact/SKILL.md index e1fe1080..b7546038 100644 --- a/rh-sre/skills/cve-impact/SKILL.md +++ b/rh-sre/skills/cve-impact/SKILL.md @@ -24,7 +24,7 @@ This skill helps SREs analyze CVE vulnerabilities to understand their impact on ## Invocation Note (Host-Specific) -When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-impact". See [skill-invocation.md](docs/references/skill-invocation.md). +When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-impact". See [skill-invocation.md](references/skill-invocation.md). ## Prerequisites @@ -193,8 +193,8 @@ How would you like to proceed? (first page / all pages / N pages) **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand CVSS score interpretation and severity mapping -2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand CVSS score interpretation and severity mapping." +1. **Action**: Read [cvss-scoring.md](references/cvss-scoring.md) using the Read tool to understand CVSS score interpretation and severity mapping +2. **Output to user**: "I consulted [cvss-scoring.md](references/cvss-scoring.md) to understand CVSS score interpretation and severity mapping." **MCP Tool**: `get_cve` or `vulnerability__get_cve` (from lightspeed-mcp) @@ -230,8 +230,8 @@ Last Modified: YYYY-MM-DD **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [insights-api.md](docs/insights/insights-api.md) using the Read tool to understand the system identification response format -2. **Output to user**: "I consulted [insights-api.md](docs/insights/insights-api.md) to understand the system identification response format." +1. **Action**: Read [insights-api.md](references/insights/insights-api.md) using the Read tool to understand the system identification response format +2. **Output to user**: "I consulted [insights-api.md](references/insights/insights-api.md) to understand the system identification response format." **MCP Tool**: `get_cve_systems` or `vulnerability__get_cve_systems` (from lightspeed-mcp) @@ -261,8 +261,8 @@ Total Affected Systems: N **CRITICAL**: Document consultation MUST happen BEFORE classification logic. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [fleet-management.md](docs/insights/fleet-management.md) using the Read tool to understand system tagging and classification strategies -2. **Output to user**: "I consulted [fleet-management.md](docs/insights/fleet-management.md) to understand system tagging and classification strategies." +1. **Action**: Read [fleet-management.md](references/insights/fleet-management.md) using the Read tool to understand system tagging and classification strategies +2. **Output to user**: "I consulted [fleet-management.md](references/insights/fleet-management.md) to understand system tagging and classification strategies." Classify affected systems by environment and criticality based on tags from Red Hat Lightspeed: ``` @@ -279,8 +279,8 @@ System Classification: **CRITICAL**: Document consultation MUST happen BEFORE risk assessment. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand risk prioritization based on CVSS vectors -2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand risk prioritization based on CVSS vectors." +1. **Action**: Read [cvss-scoring.md](references/cvss-scoring.md) using the Read tool to understand risk prioritization based on CVSS vectors +2. **Output to user**: "I consulted [cvss-scoring.md](references/cvss-scoring.md) to understand risk prioritization based on CVSS vectors." Provide a risk assessment based on: - CVSS score and severity @@ -334,7 +334,7 @@ Check if automated playbook or manual steps are available. | [03-output-templates.md](references/03-output-templates.md) | Report format | | [04-examples.md](references/04-examples.md) | Query-type examples | | [05-error-handling.md](references/05-error-handling.md) | CVE not found, no systems, Lightspeed failures | -| [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md) | explain_cves dnf_modules workaround | +| [lightspeed-mcp-tool-failures.md](references/lightspeed-mcp-tool-failures.md) | explain_cves dnf_modules workaround | ## Parsing MCP Responses @@ -406,10 +406,10 @@ Save each MCP tool result to a file, then run the parser with one or more paths. - Purpose: Understand overall infrastructure before assessing CVE impact ### Reference Documentation -- [cvss-scoring.md](docs/references/cvss-scoring.md) - CVSS score interpretation and severity mapping -- [vulnerability-logic.md](docs/insights/vulnerability-logic.md) - CVE severity classification and filtering -- [insights-api.md](docs/insights/insights-api.md) - System identification response format -- [fleet-management.md](docs/insights/fleet-management.md) - System tagging and classification strategies +- [cvss-scoring.md](references/cvss-scoring.md) - CVSS score interpretation and severity mapping +- [vulnerability-logic.md](references/insights/vulnerability-logic.md) - CVE severity classification and filtering +- [insights-api.md](references/insights/insights-api.md) - System identification response format +- [fleet-management.md](references/insights/fleet-management.md) - System tagging and classification strategies - [references/02-cve-parsing-guide.md](references/02-cve-parsing-guide.md) - Parse MCP vulnerability responses; use the parser script instead of generating inline Python ## Tools Reference diff --git a/rh-sre/skills/cve-impact/docs/SOURCES.md b/rh-sre/skills/cve-impact/docs/SOURCES.md deleted file mode 120000 index 50989401..00000000 --- a/rh-sre/skills/cve-impact/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md b/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/cve-impact/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/cve-impact/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/error-handling.md b/rh-sre/skills/cve-impact/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/cve-impact/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/ansible/idempotency.md b/rh-sre/skills/cve-impact/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/cve-impact/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/fleet-management.md b/rh-sre/skills/cve-impact/docs/insights/fleet-management.md deleted file mode 120000 index 8ecd1956..00000000 --- a/rh-sre/skills/cve-impact/docs/insights/fleet-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../fleet-inventory/docs/insights/fleet-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/insights-api.md b/rh-sre/skills/cve-impact/docs/insights/insights-api.md deleted file mode 120000 index 48ae0c69..00000000 --- a/rh-sre/skills/cve-impact/docs/insights/insights-api.md +++ /dev/null @@ -1 +0,0 @@ -../../../fleet-inventory/docs/insights/insights-api.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md b/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/cve-impact/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md b/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/cve-impact/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md b/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/cve-impact/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/references/skill-invocation.md b/rh-sre/skills/cve-impact/docs/references/skill-invocation.md deleted file mode 120000 index f7e6fef0..00000000 --- a/rh-sre/skills/cve-impact/docs/references/skill-invocation.md +++ /dev/null @@ -1 +0,0 @@ -../../../remediation/docs/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/package-management.md b/rh-sre/skills/cve-impact/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/cve-impact/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md b/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/cve-impact/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md b/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/cve-impact/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md b/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/cve-impact/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/05-error-handling.md b/rh-sre/skills/cve-impact/references/05-error-handling.md index 006aee55..4843847a 100644 --- a/rh-sre/skills/cve-impact/references/05-error-handling.md +++ b/rh-sre/skills/cve-impact/references/05-error-handling.md @@ -21,4 +21,4 @@ No action required. ## Lightspeed Tool Failures -If explain_cves fails with `'dnf_modules'`: Do NOT show raw error. Use workaround from [lightspeed-mcp-tool-failures.md](../../../docs/references/lightspeed-mcp-tool-failures.md) (get_cve + get_host_details synthesis). +If explain_cves fails with `'dnf_modules'`: Do NOT show raw error. Use workaround from [lightspeed-mcp-tool-failures.md](lightspeed-mcp-tool-failures.md) (get_cve + get_host_details synthesis). diff --git a/rh-sre/skills/cve-impact/docs/references/README.md b/rh-sre/skills/cve-impact/references/README.md similarity index 96% rename from rh-sre/skills/cve-impact/docs/references/README.md rename to rh-sre/skills/cve-impact/references/README.md index 4c6481e1..1eeb9cd5 100644 --- a/rh-sre/skills/cve-impact/docs/references/README.md +++ b/rh-sre/skills/cve-impact/references/README.md @@ -36,4 +36,4 @@ This directory contains reference materials supporting CVE remediation decisions - Red Hat Security: https://access.redhat.com/security/ - CVSS Calculator: https://www.first.org/cvss/calculator/3.1 -- Source attribution: [../SOURCES.md](../SOURCES.md) +- Source attribution: [SOURCES.md](SOURCES.md) diff --git a/rh-sre/skills/cve-impact/references/SOURCES.md b/rh-sre/skills/cve-impact/references/SOURCES.md new file mode 120000 index 00000000..888744ee --- /dev/null +++ b/rh-sre/skills/cve-impact/references/SOURCES.md @@ -0,0 +1 @@ +../../../references/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/ansible/aap-integration.md b/rh-sre/skills/cve-impact/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/cve-impact/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-impact/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/ansible/error-handling.md b/rh-sre/skills/cve-impact/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/ansible/idempotency.md b/rh-sre/skills/cve-impact/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/compliance-frameworks.md b/rh-sre/skills/cve-impact/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/cve-impact/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/cvss-scoring.md b/rh-sre/skills/cve-impact/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/flows/01-account-cves.md b/rh-sre/skills/cve-impact/references/flows/01-account-cves.md index a5057ec0..c1d1a670 100644 --- a/rh-sre/skills/cve-impact/references/flows/01-account-cves.md +++ b/rh-sre/skills/cve-impact/references/flows/01-account-cves.md @@ -13,8 +13,8 @@ ## Step 1: Document Consultation (REQUIRED - Execute FIRST) -1. **Action**: Read [vulnerability-logic.md](../../../docs/insights/vulnerability-logic.md) using the Read tool -2. **Output to user**: "I consulted [vulnerability-logic.md](../../../docs/insights/vulnerability-logic.md) to understand CVE severity classification and filtering." +1. **Action**: Read [vulnerability-logic.md](../insights/vulnerability-logic.md) using the Read tool +2. **Output to user**: "I consulted [vulnerability-logic.md](../insights/vulnerability-logic.md) to understand CVE severity classification and filtering." ## Step 2: HITL Checkpoint — Pagination / Limit @@ -108,7 +108,7 @@ vulnerability__get_cves( ## Step 5: Follow-up -- Offer to analyze a specific CVE (see [SKILL.md](../SKILL.md) — Step 2: CVE Information Retrieval) +- Offer to analyze a specific CVE (see [SKILL.md](../../SKILL.md) — Step 2: CVE Information Retrieval) - Offer to create remediation plan (invoke `/remediation` skill) ## Impact Level Reference diff --git a/rh-sre/skills/cve-impact/references/flows/02-system-all-cves.md b/rh-sre/skills/cve-impact/references/flows/02-system-all-cves.md index 3ba6228c..9440483a 100644 --- a/rh-sre/skills/cve-impact/references/flows/02-system-all-cves.md +++ b/rh-sre/skills/cve-impact/references/flows/02-system-all-cves.md @@ -15,7 +15,7 @@ ## Step 1: HITL — Pagination Strategy (Done in SKILL.md Step -1) -**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name`, `vulnerability__load_cve_dashboard`, or `vulnerability__get_system_cves` until the user responds. +**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name`, `vulnerability__load_cve_dashboard`, or `vulnerability__get_system_cves` until the user responds. ``` This system may have many CVEs. I will paginate through them (limit=100 per page). @@ -36,8 +36,8 @@ How would you like to proceed? (first page / all pages / N pages) ## Step 2: Document Consultation (REQUIRED - Execute AFTER HITL) -1. **Action**: Read [insights-api.md](../../../docs/insights/insights-api.md) using the Read tool -2. **Output to user**: "I consulted [insights-api.md](../../../docs/insights/insights-api.md) to understand system identification." +1. **Action**: Read [insights-api.md](../insights/insights-api.md) using the Read tool +2. **Output to user**: "I consulted [insights-api.md](../insights/insights-api.md) to understand system identification." ## Step 3: Resolve Hostname to System UUID @@ -98,5 +98,5 @@ while (strategy allows): ## Step 7: Follow-up -- Offer to analyze a specific CVE (see [SKILL.md](../SKILL.md) — Step 2: CVE Information Retrieval) +- Offer to analyze a specific CVE (see [SKILL.md](../../SKILL.md) — Step 2: CVE Information Retrieval) - Offer to create remediation plan (invoke `/remediation` skill) diff --git a/rh-sre/skills/cve-impact/references/flows/03-system-remediatable-cves.md b/rh-sre/skills/cve-impact/references/flows/03-system-remediatable-cves.md index 410c59df..563a48d0 100644 --- a/rh-sre/skills/cve-impact/references/flows/03-system-remediatable-cves.md +++ b/rh-sre/skills/cve-impact/references/flows/03-system-remediatable-cves.md @@ -16,7 +16,7 @@ ## Step 1: HITL — Pagination Strategy (Done in SKILL.md Step -1) -**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name`, `vulnerability__load_cve_dashboard`, or `vulnerability__get_system_cves` until the user responds. +**If you have not yet replied to the user with the pagination prompt**: Stop. Go to [SKILL.md](../../SKILL.md) Step -1. Your first reply to the user must be the prompt below. Do NOT call `inventory__find_host_by_name`, `vulnerability__load_cve_dashboard`, or `vulnerability__get_system_cves` until the user responds. ``` To fetch remediatable CVEs on this system, I will: @@ -42,8 +42,8 @@ How would you like to proceed? (first page / all pages / N pages) ## Step 2: Document Consultation (REQUIRED - Execute AFTER HITL) -1. **Action**: Read [insights-api.md](../../../docs/insights/insights-api.md) using the Read tool -2. **Output to user**: "I consulted [insights-api.md](../../../docs/insights/insights-api.md) to understand system identification." +1. **Action**: Read [insights-api.md](../insights/insights-api.md) using the Read tool +2. **Output to user**: "I consulted [insights-api.md](../insights/insights-api.md) to understand system identification." ## Step 3: Resolve Hostname to System UUID @@ -105,5 +105,5 @@ After filtering for remediatable, optionally filter by severity: ## Step 7: Follow-up -- Offer to analyze a specific CVE (see [SKILL.md](../SKILL.md) — Step 2: CVE Information Retrieval) +- Offer to analyze a specific CVE (see [SKILL.md](../../SKILL.md) — Step 2: CVE Information Retrieval) - Offer to create remediation plan (invoke `/remediation` skill) diff --git a/rh-sre/skills/cve-impact/references/insights/fleet-management.md b/rh-sre/skills/cve-impact/references/insights/fleet-management.md new file mode 120000 index 00000000..c2cbeaa7 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/insights/fleet-management.md @@ -0,0 +1 @@ +../../../fleet-inventory/references/insights/fleet-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/insights/insights-api.md b/rh-sre/skills/cve-impact/references/insights/insights-api.md new file mode 120000 index 00000000..2ef357e8 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/insights/insights-api.md @@ -0,0 +1 @@ +../../../fleet-inventory/references/insights/insights-api.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/insights/vulnerability-logic.md b/rh-sre/skills/cve-impact/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-parameters.md b/rh-sre/skills/cve-impact/references/lightspeed-mcp-parameters.md similarity index 100% rename from rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-parameters.md rename to rh-sre/skills/cve-impact/references/lightspeed-mcp-parameters.md diff --git a/rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/skills/cve-impact/references/lightspeed-mcp-tool-failures.md similarity index 100% rename from rh-sre/skills/cve-impact/docs/references/lightspeed-mcp-tool-failures.md rename to rh-sre/skills/cve-impact/references/lightspeed-mcp-tool-failures.md diff --git a/rh-sre/skills/cve-impact/references/rhel/package-management.md b/rh-sre/skills/cve-impact/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/rhel/selinux-context.md b/rh-sre/skills/cve-impact/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/cve-impact/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/rhel/systemd-services.md b/rh-sre/skills/cve-impact/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/cve-impact/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/rhel/version-compatibility.md b/rh-sre/skills/cve-impact/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/cve-impact/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/cve-impact/references/skill-invocation.md b/rh-sre/skills/cve-impact/references/skill-invocation.md new file mode 120000 index 00000000..10a26f24 --- /dev/null +++ b/rh-sre/skills/cve-impact/references/skill-invocation.md @@ -0,0 +1 @@ +../../remediation/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/SKILL.md b/rh-sre/skills/cve-validation/SKILL.md index cd56e2c0..fdf1576d 100644 --- a/rh-sre/skills/cve-validation/SKILL.md +++ b/rh-sre/skills/cve-validation/SKILL.md @@ -31,7 +31,7 @@ This skill validates CVE identifiers and checks remediation availability in Red ## Invocation Note (Host-Specific) -When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-validation". See [skill-invocation.md](docs/references/skill-invocation.md). +When invoked by another skill (e.g. remediation), use the Skill tool—do NOT use "Task Output" with the skill name as task ID. That causes "No task found with ID: cve-validation". See [skill-invocation.md](references/skill-invocation.md). ## Prerequisites @@ -138,9 +138,9 @@ Let the API determine existence. A 404 from get_cve means "not found"; format va **CRITICAL**: Document consultation MUST happen BEFORE tool invocation. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [vulnerability-logic.md](docs/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria +1. **Action**: Read [vulnerability-logic.md](references/insights/vulnerability-logic.md) using the Read tool to understand CVE validation criteria 2. **Action**: Read [references/01-remediation-indicators.md](references/01-remediation-indicators.md) to interpret get_cve response—**CRITICAL** to avoid misinterpreting remediation availability -3. **Output to user**: "I consulted [vulnerability-logic.md](docs/insights/vulnerability-logic.md) and [01-remediation-indicators.md](references/01-remediation-indicators.md) for CVE validation and remediation indicator interpretation." +3. **Output to user**: "I consulted [vulnerability-logic.md](references/insights/vulnerability-logic.md) and [01-remediation-indicators.md](references/01-remediation-indicators.md) for CVE validation and remediation indicator interpretation." **MCP Tool**: `get_cve` or `vulnerability__get_cve` (from lightspeed-mcp) @@ -191,8 +191,8 @@ Retrieve CVE metadata from Red Hat Lightspeed: **CRITICAL**: Document consultation MUST happen BEFORE validation logic. **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [cvss-scoring.md](docs/references/cvss-scoring.md) using the Read tool to understand Red Hat severity classification and CVSS score ranges -2. **Output to user**: "I consulted [cvss-scoring.md](docs/references/cvss-scoring.md) to understand Red Hat severity classification and CVSS score ranges." +1. **Action**: Read [cvss-scoring.md](references/cvss-scoring.md) using the Read tool to understand Red Hat severity classification and CVSS score ranges +2. **Output to user**: "I consulted [cvss-scoring.md](references/cvss-scoring.md) to understand Red Hat severity classification and CVSS score ranges." Perform comprehensive validation: @@ -331,10 +331,10 @@ Validate format first; if regex matches, ALWAYS call get_cve (do not reject on y - Purpose: Create automated remediation for valid, remediable CVEs ### Reference Documentation -- [vulnerability-logic.md](docs/insights/vulnerability-logic.md) - CVE validation criteria +- [vulnerability-logic.md](references/insights/vulnerability-logic.md) - CVE validation criteria - [references/01-remediation-indicators.md](references/01-remediation-indicators.md) - **REQUIRED** - Correct interpretation of get_cve response (advisory_available, remediation, advisories_list). Do NOT use rules[] for remediation decision. -- [cvss-scoring.md](docs/references/cvss-scoring.md) - Red Hat severity classification and CVSS score ranges -- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) - Manual remediation templates for CVEs without automated playbooks +- [cvss-scoring.md](references/cvss-scoring.md) - Red Hat severity classification and CVSS score ranges +- [cve-remediation-templates.md](references/ansible/cve-remediation-templates.md) - Manual remediation templates for CVEs without automated playbooks ## Tools Reference diff --git a/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md b/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/cve-validation/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/cve-validation/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/error-handling.md b/rh-sre/skills/cve-validation/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/cve-validation/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/ansible/idempotency.md b/rh-sre/skills/cve-validation/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/cve-validation/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md b/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/cve-validation/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/references/skill-invocation.md b/rh-sre/skills/cve-validation/docs/references/skill-invocation.md deleted file mode 120000 index f7e6fef0..00000000 --- a/rh-sre/skills/cve-validation/docs/references/skill-invocation.md +++ /dev/null @@ -1 +0,0 @@ -../../../remediation/docs/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/package-management.md b/rh-sre/skills/cve-validation/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/cve-validation/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md b/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/cve-validation/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md b/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/cve-validation/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md b/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/cve-validation/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/ansible/aap-integration.md b/rh-sre/skills/cve-validation/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/cve-validation/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/ansible/cve-remediation-templates.md b/rh-sre/skills/cve-validation/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/ansible/error-handling.md b/rh-sre/skills/cve-validation/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/ansible/idempotency.md b/rh-sre/skills/cve-validation/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/compliance-frameworks.md b/rh-sre/skills/cve-validation/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/cve-validation/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/docs/references/cvss-scoring.md b/rh-sre/skills/cve-validation/references/cvss-scoring.md similarity index 98% rename from rh-sre/skills/cve-validation/docs/references/cvss-scoring.md rename to rh-sre/skills/cve-validation/references/cvss-scoring.md index e0ccd3dc..61b3ab04 100644 --- a/rh-sre/skills/cve-validation/docs/references/cvss-scoring.md +++ b/rh-sre/skills/cve-validation/references/cvss-scoring.md @@ -612,8 +612,8 @@ Downgrade priority if: ## Related Documentation -- **[Red Hat Lightspeed Vulnerability Logic](../insights/vulnerability-logic.md)** - How Lightspeed assesses CVEs -- **[CVE Remediation Templates](../ansible/cve-remediation-templates.md)** - Playbooks for remediation +- **[Red Hat Lightspeed Vulnerability Logic](insights/vulnerability-logic.md)** - How Lightspeed assesses CVEs +- **[CVE Remediation Templates](ansible/cve-remediation-templates.md)** - Playbooks for remediation - **[Compliance Frameworks](compliance-frameworks.md)** - PCI-DSS, SOC 2, NIST requirements ## Official Red Hat Sources diff --git a/rh-sre/skills/cve-validation/docs/insights/vulnerability-logic.md b/rh-sre/skills/cve-validation/references/insights/vulnerability-logic.md similarity index 98% rename from rh-sre/skills/cve-validation/docs/insights/vulnerability-logic.md rename to rh-sre/skills/cve-validation/references/insights/vulnerability-logic.md index 0edc1ebd..46119e16 100644 --- a/rh-sre/skills/cve-validation/docs/insights/vulnerability-logic.md +++ b/rh-sre/skills/cve-validation/references/insights/vulnerability-logic.md @@ -445,7 +445,7 @@ Map CVE remediation to compliance frameworks: - **SOC 2**: Vulnerability management process documented - **NIST**: CVE scoring aligns with NIST guidelines -See: [compliance-frameworks.md](../references/compliance-frameworks.md) +See: [compliance-frameworks.md](../compliance-frameworks.md) ## Common Scenarios @@ -544,9 +544,9 @@ insights-client --force-reregister ## Related Documentation -- **[CVSS Scoring Reference](../references/cvss-scoring.md)** - Detailed CVSS interpretation +- **[CVSS Scoring Reference](../cvss-scoring.md)** - Detailed CVSS interpretation - **[CVE Remediation Templates](../ansible/cve-remediation-templates.md)** - Playbook templates for remediation -- **[Compliance Frameworks](../references/compliance-frameworks.md)** - Compliance requirements per CVE severity +- **[Compliance Frameworks](../compliance-frameworks.md)** - Compliance requirements per CVE severity ## Official Red Hat Sources diff --git a/rh-sre/skills/cve-validation/references/rhel/package-management.md b/rh-sre/skills/cve-validation/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/rhel/selinux-context.md b/rh-sre/skills/cve-validation/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/cve-validation/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/rhel/systemd-services.md b/rh-sre/skills/cve-validation/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/cve-validation/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/rhel/version-compatibility.md b/rh-sre/skills/cve-validation/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/cve-validation/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/cve-validation/references/skill-invocation.md b/rh-sre/skills/cve-validation/references/skill-invocation.md new file mode 120000 index 00000000..10a26f24 --- /dev/null +++ b/rh-sre/skills/cve-validation/references/skill-invocation.md @@ -0,0 +1 @@ +../../remediation/references/skill-invocation.md \ No newline at end of file diff --git a/rh-sre/skills/execution-summary/SKILL.md b/rh-sre/skills/execution-summary/SKILL.md index 53a8edaf..28a60c70 100644 --- a/rh-sre/skills/execution-summary/SKILL.md +++ b/rh-sre/skills/execution-summary/SKILL.md @@ -57,9 +57,9 @@ Do NOT use when: - Include server prefix 4. **Documentation consulted** - Look for Read tool calls on documentation files - - Pattern: Files under `rh-sre/docs/` or `rh-sre/skills/*/SKILL.md` - - Extract only from `docs/` onwards - - Example: `/path/to/rh-sre/docs/ansible/playbook-templates.md` → `docs/ansible/playbook-templates.md` + - Pattern: Files under `rh-sre/references/` or `rh-sre/skills/*/SKILL.md` + - Extract only from `references/` onwards + - Example: `/path/to/rh-sre/references/ansible/playbook-templates.md` → `references/ansible/playbook-templates.md` - Example: `/path/to/rh-sre/skills/fleet-inventory/SKILL.md` → `skills/fleet-inventory/SKILL.md` - Include "I consulted [filename]" statements in conversation diff --git a/rh-sre/skills/fleet-inventory/SKILL.md b/rh-sre/skills/fleet-inventory/SKILL.md index 06c298e3..44934748 100644 --- a/rh-sre/skills/fleet-inventory/SKILL.md +++ b/rh-sre/skills/fleet-inventory/SKILL.md @@ -104,8 +104,8 @@ Proceeding with fleet inventory query... ### Step 1: Retrieve System Inventory **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [insights-api.md](docs/insights/insights-api.md) using the Read tool to understand `inventory__list_hosts` response format and pagination handling -2. **Output to user**: "I consulted [insights-api.md](docs/insights/insights-api.md) to understand the `inventory__list_hosts` response format and pagination handling." +1. **Action**: Read [insights-api.md](references/insights/insights-api.md) using the Read tool to understand `inventory__list_hosts` response format and pagination handling +2. **Output to user**: "I consulted [insights-api.md](references/insights/insights-api.md) to understand the `inventory__list_hosts` response format and pagination handling." **MCP Tools**: `inventory__load_inventory_dashboard` and `inventory__list_hosts` (from lightspeed-mcp) @@ -142,8 +142,8 @@ Proceeding with fleet inventory query... ### Step 2: Filter and Organize Systems **Document Consultation** (REQUIRED - Execute FIRST): -1. **Action**: Read [fleet-management.md](docs/insights/fleet-management.md) using the Read tool to understand fleet inventory reporting structure and best practices -2. **Output to user**: "I consulted [fleet-management.md](docs/insights/fleet-management.md) to structure this inventory report." +1. **Action**: Read [fleet-management.md](references/insights/fleet-management.md) using the Read tool to understand fleet inventory reporting structure and best practices +2. **Output to user**: "I consulted [fleet-management.md](references/insights/fleet-management.md) to structure this inventory report." Apply user-requested filters and grouping. See [references/01-parameter-reference.md](references/01-parameter-reference.md) for filtering and sorting patterns. @@ -252,8 +252,8 @@ Examples: - Use after: "Show affected systems" → "Remediate those systems" ### Reference Documentation -- [insights-api.md](docs/insights/insights-api.md) - Red Hat Lightspeed API patterns and response formats -- [fleet-management.md](docs/insights/fleet-management.md) - System inventory best practices and filtering strategies +- [insights-api.md](references/insights/insights-api.md) - Red Hat Lightspeed API patterns and response formats +- [fleet-management.md](references/insights/fleet-management.md) - System inventory best practices and filtering strategies ### Skill Orchestration Pattern diff --git a/rh-sre/skills/fleet-inventory/references/03-output-templates.md b/rh-sre/skills/fleet-inventory/references/03-output-templates.md index 16c644e3..4517a168 100644 --- a/rh-sre/skills/fleet-inventory/references/03-output-templates.md +++ b/rh-sre/skills/fleet-inventory/references/03-output-templates.md @@ -9,7 +9,7 @@ Read when completing a fleet inventory report to format the output. ```markdown # Managed Fleet Inventory -I consulted [fleet-management.md](../../../docs/insights/fleet-management.md) to structure this inventory report. +I consulted [fleet-management.md](insights/fleet-management.md) to structure this inventory report. Retrieved from Red Hat Lightspeed on YYYY-MM-DDTHH:MM:SSZ diff --git a/rh-sre/skills/fleet-inventory/docs/insights/fleet-management.md b/rh-sre/skills/fleet-inventory/references/insights/fleet-management.md similarity index 100% rename from rh-sre/skills/fleet-inventory/docs/insights/fleet-management.md rename to rh-sre/skills/fleet-inventory/references/insights/fleet-management.md diff --git a/rh-sre/skills/fleet-inventory/docs/insights/insights-api.md b/rh-sre/skills/fleet-inventory/references/insights/insights-api.md similarity index 92% rename from rh-sre/skills/fleet-inventory/docs/insights/insights-api.md rename to rh-sre/skills/fleet-inventory/references/insights/insights-api.md index 8c179603..3b170c4c 100644 --- a/rh-sre/skills/fleet-inventory/docs/insights/insights-api.md +++ b/rh-sre/skills/fleet-inventory/references/insights/insights-api.md @@ -90,5 +90,5 @@ Paginate with `offset += limit` until the page returns fewer records than `limit ## Related references -- [01-parameter-reference.md](../../references/01-parameter-reference.md) — parameter tables for all fleet-inventory tools -- [lightspeed-mcp-parameters.md](../../../cve-impact/docs/references/lightspeed-mcp-parameters.md) — shared Lightspeed MCP parameter reference (inventory and vulnerability tools) +- [01-parameter-reference.md](../01-parameter-reference.md) — parameter tables for all fleet-inventory tools +- [lightspeed-mcp-parameters.md](../../../cve-impact/references/lightspeed-mcp-parameters.md) — shared Lightspeed MCP parameter reference (inventory and vulnerability tools) diff --git a/rh-sre/skills/mcp-aap-validator/SKILL.md b/rh-sre/skills/mcp-aap-validator/SKILL.md index 1ba827f9..5cf15269 100644 --- a/rh-sre/skills/mcp-aap-validator/SKILL.md +++ b/rh-sre/skills/mcp-aap-validator/SKILL.md @@ -72,4 +72,4 @@ Use ✅ for success, ❌ for failure, ⚠️ for partial (e.g. one server OK, on - `/job-template-creator` - Requires AAP MCP validation before template operations ### Reference Documentation -- [AAP Integration Test Guide](docs/testing/aap-integration-test-guide.md) - AAP MCP setup, env vars, connectivity verification +- [AAP Integration Test Guide](references/testing/aap-integration-test-guide.md) - AAP MCP setup, env vars, connectivity verification diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md deleted file mode 120000 index 31d880e7..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-job-execution.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-executor/docs/ansible/aap-job-execution.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md b/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md deleted file mode 120000 index e6e5e180..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/ansible/playbook-integration-aap.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-executor/docs/ansible/playbook-integration-aap.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md b/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md b/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md b/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/mcp-aap-validator/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/aap-integration.md b/rh-sre/skills/mcp-aap-validator/references/ansible/aap-integration.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/ansible/aap-integration.md rename to rh-sre/skills/mcp-aap-validator/references/ansible/aap-integration.md diff --git a/rh-sre/skills/mcp-aap-validator/references/ansible/aap-job-execution.md b/rh-sre/skills/mcp-aap-validator/references/ansible/aap-job-execution.md new file mode 120000 index 00000000..82e9571b --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/ansible/aap-job-execution.md @@ -0,0 +1 @@ +../../../playbook-executor/references/ansible/aap-job-execution.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/references/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-aap-validator/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/error-handling.md b/rh-sre/skills/mcp-aap-validator/references/ansible/error-handling.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/ansible/error-handling.md rename to rh-sre/skills/mcp-aap-validator/references/ansible/error-handling.md diff --git a/rh-sre/skills/mcp-aap-validator/docs/ansible/idempotency.md b/rh-sre/skills/mcp-aap-validator/references/ansible/idempotency.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/ansible/idempotency.md rename to rh-sre/skills/mcp-aap-validator/references/ansible/idempotency.md diff --git a/rh-sre/skills/mcp-aap-validator/references/ansible/playbook-integration-aap.md b/rh-sre/skills/mcp-aap-validator/references/ansible/playbook-integration-aap.md new file mode 120000 index 00000000..f582e205 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/ansible/playbook-integration-aap.md @@ -0,0 +1 @@ +../../../playbook-executor/references/ansible/playbook-integration-aap.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/references/compliance-frameworks.md b/rh-sre/skills/mcp-aap-validator/references/compliance-frameworks.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/references/compliance-frameworks.md rename to rh-sre/skills/mcp-aap-validator/references/compliance-frameworks.md diff --git a/rh-sre/skills/mcp-aap-validator/references/cvss-scoring.md b/rh-sre/skills/mcp-aap-validator/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/references/insights/vulnerability-logic.md b/rh-sre/skills/mcp-aap-validator/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/references/rhel/package-management.md b/rh-sre/skills/mcp-aap-validator/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/mcp-aap-validator/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/selinux-context.md b/rh-sre/skills/mcp-aap-validator/references/rhel/selinux-context.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/rhel/selinux-context.md rename to rh-sre/skills/mcp-aap-validator/references/rhel/selinux-context.md diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/systemd-services.md b/rh-sre/skills/mcp-aap-validator/references/rhel/systemd-services.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/rhel/systemd-services.md rename to rh-sre/skills/mcp-aap-validator/references/rhel/systemd-services.md diff --git a/rh-sre/skills/mcp-aap-validator/docs/rhel/version-compatibility.md b/rh-sre/skills/mcp-aap-validator/references/rhel/version-compatibility.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/rhel/version-compatibility.md rename to rh-sre/skills/mcp-aap-validator/references/rhel/version-compatibility.md diff --git a/rh-sre/skills/mcp-aap-validator/docs/testing/aap-integration-test-guide.md b/rh-sre/skills/mcp-aap-validator/references/testing/aap-integration-test-guide.md similarity index 100% rename from rh-sre/skills/mcp-aap-validator/docs/testing/aap-integration-test-guide.md rename to rh-sre/skills/mcp-aap-validator/references/testing/aap-integration-test-guide.md diff --git a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md index d9e1d432..cd3935e3 100644 --- a/rh-sre/skills/mcp-lightspeed-validator/SKILL.md +++ b/rh-sre/skills/mcp-lightspeed-validator/SKILL.md @@ -67,4 +67,4 @@ Use ✅ for success, ❌ for failure, ⚠️ for partial (e.g. connected but err - `/cve-validation`, `/cve-impact`, `/fleet-inventory` - All require Lightspeed MCP ### Reference Documentation -- [Red Hat Lightspeed Documentation Overview](docs/insights/README.md) - Lightspeed setup, CVE assessment, vulnerability logic +- [Red Hat Lightspeed Documentation Overview](references/insights/README.md) - Lightspeed setup, CVE assessment, vulnerability logic diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md b/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md deleted file mode 120000 index 50989401..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md b/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md b/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md b/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md b/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md b/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/mcp-lightspeed-validator/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/SOURCES.md b/rh-sre/skills/mcp-lightspeed-validator/references/SOURCES.md new file mode 120000 index 00000000..888744ee --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/SOURCES.md @@ -0,0 +1 @@ +../../../references/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/ansible/aap-integration.md b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/ansible/cve-remediation-templates.md b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/ansible/error-handling.md b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/ansible/idempotency.md b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/compliance-frameworks.md b/rh-sre/skills/mcp-lightspeed-validator/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/cvss-scoring.md b/rh-sre/skills/mcp-lightspeed-validator/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/docs/insights/README.md b/rh-sre/skills/mcp-lightspeed-validator/references/insights/README.md similarity index 100% rename from rh-sre/skills/mcp-lightspeed-validator/docs/insights/README.md rename to rh-sre/skills/mcp-lightspeed-validator/references/insights/README.md diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/insights/vulnerability-logic.md b/rh-sre/skills/mcp-lightspeed-validator/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/rhel/package-management.md b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/rhel/selinux-context.md b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/rhel/systemd-services.md b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/mcp-lightspeed-validator/references/rhel/version-compatibility.md b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/mcp-lightspeed-validator/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/SKILL.md b/rh-sre/skills/playbook-executor/SKILL.md index e2f3f009..5041736a 100644 --- a/rh-sre/skills/playbook-executor/SKILL.md +++ b/rh-sre/skills/playbook-executor/SKILL.md @@ -413,8 +413,8 @@ If user chooses relaunch: **MCP Tool** `jobs_relaunch_retrieve` with `hosts: "fa ### Reference Documentation - [references/](references/) - Step-numbered reference files (01–05) for templates and examples -- [AAP Job Execution Guide](docs/ansible/aap-job-execution.md) - AAP job execution best practices -- [Playbook Integration with AAP](docs/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow +- [AAP Job Execution Guide](references/ansible/aap-job-execution.md) - AAP job execution best practices +- [Playbook Integration with AAP](references/ansible/playbook-integration-aap.md) - Playbook-to-AAP workflow ## Critical: Human-in-the-Loop Requirements diff --git a/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md b/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/playbook-executor/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/playbook-executor/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md b/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/playbook-executor/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md b/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/playbook-executor/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md b/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/playbook-executor/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md b/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/playbook-executor/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md b/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/playbook-executor/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/package-management.md b/rh-sre/skills/playbook-executor/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/playbook-executor/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md b/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/playbook-executor/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md b/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/playbook-executor/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md b/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/playbook-executor/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/ansible/aap-integration.md b/rh-sre/skills/playbook-executor/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/aap-job-execution.md b/rh-sre/skills/playbook-executor/references/ansible/aap-job-execution.md similarity index 100% rename from rh-sre/skills/playbook-executor/docs/ansible/aap-job-execution.md rename to rh-sre/skills/playbook-executor/references/ansible/aap-job-execution.md diff --git a/rh-sre/skills/playbook-executor/references/ansible/cve-remediation-templates.md b/rh-sre/skills/playbook-executor/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/ansible/error-handling.md b/rh-sre/skills/playbook-executor/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/ansible/idempotency.md b/rh-sre/skills/playbook-executor/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/docs/ansible/playbook-integration-aap.md b/rh-sre/skills/playbook-executor/references/ansible/playbook-integration-aap.md similarity index 100% rename from rh-sre/skills/playbook-executor/docs/ansible/playbook-integration-aap.md rename to rh-sre/skills/playbook-executor/references/ansible/playbook-integration-aap.md diff --git a/rh-sre/skills/playbook-executor/references/compliance-frameworks.md b/rh-sre/skills/playbook-executor/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/cvss-scoring.md b/rh-sre/skills/playbook-executor/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/insights/vulnerability-logic.md b/rh-sre/skills/playbook-executor/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/rhel/package-management.md b/rh-sre/skills/playbook-executor/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/rhel/selinux-context.md b/rh-sre/skills/playbook-executor/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/rhel/systemd-services.md b/rh-sre/skills/playbook-executor/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-executor/references/rhel/version-compatibility.md b/rh-sre/skills/playbook-executor/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/playbook-executor/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/SKILL.md b/rh-sre/skills/playbook-generator/SKILL.md index fb3893b1..c4b509b1 100644 --- a/rh-sre/skills/playbook-generator/SKILL.md +++ b/rh-sre/skills/playbook-generator/SKILL.md @@ -149,8 +149,8 @@ Do NOT validate for "best practices" or add missing elements—return AS IS. - `playbook-executor` - Executes generated playbooks and tracks job status ### Reference Documentation -- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) - Ansible playbook templates for different CVE types -- [package-management.md](docs/rhel/package-management.md) - RHEL package management best practices (DNF vs YUM, reboot detection) +- [cve-remediation-templates.md](references/ansible/cve-remediation-templates.md) - Ansible playbook templates for different CVE types +- [package-management.md](references/rhel/package-management.md) - RHEL package management best practices (DNF vs YUM, reboot detection) ## Critical: Human-in-the-Loop Requirements diff --git a/rh-sre/skills/playbook-generator/docs/SOURCES.md b/rh-sre/skills/playbook-generator/docs/SOURCES.md deleted file mode 120000 index 50989401..00000000 --- a/rh-sre/skills/playbook-generator/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md b/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/playbook-generator/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md b/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/playbook-generator/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md b/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/playbook-generator/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md b/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/playbook-generator/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md b/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/playbook-generator/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md b/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/playbook-generator/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md b/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/playbook-generator/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md b/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/playbook-generator/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md b/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/playbook-generator/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/SOURCES.md b/rh-sre/skills/playbook-generator/references/SOURCES.md new file mode 120000 index 00000000..888744ee --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/SOURCES.md @@ -0,0 +1 @@ +../../../references/SOURCES.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/README.md b/rh-sre/skills/playbook-generator/references/ansible/README.md similarity index 100% rename from rh-sre/skills/playbook-generator/docs/ansible/README.md rename to rh-sre/skills/playbook-generator/references/ansible/README.md diff --git a/rh-sre/skills/playbook-generator/references/ansible/aap-integration.md b/rh-sre/skills/playbook-generator/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/playbook-generator/references/ansible/cve-remediation-templates.md similarity index 99% rename from rh-sre/skills/playbook-generator/docs/ansible/cve-remediation-templates.md rename to rh-sre/skills/playbook-generator/references/ansible/cve-remediation-templates.md index d612b2f6..b0d851af 100644 --- a/rh-sre/skills/playbook-generator/docs/ansible/cve-remediation-templates.md +++ b/rh-sre/skills/playbook-generator/references/ansible/cve-remediation-templates.md @@ -1445,7 +1445,7 @@ After execution, find detailed reports in `/var/log/cve-remediation//` ### For Risk Assessment - **[vulnerability-logic.md](../insights/vulnerability-logic.md)** - Red Hat Lightspeed risk methodology -- **[cvss-scoring.md](../references/cvss-scoring.md)** - CVSS interpretation +- **[cvss-scoring.md](../cvss-scoring.md)** - CVSS interpretation --- diff --git a/rh-sre/skills/playbook-generator/references/ansible/error-handling.md b/rh-sre/skills/playbook-generator/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/ansible/idempotency.md b/rh-sre/skills/playbook-generator/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/compliance-frameworks.md b/rh-sre/skills/playbook-generator/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/cvss-scoring.md b/rh-sre/skills/playbook-generator/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/insights/vulnerability-logic.md b/rh-sre/skills/playbook-generator/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/docs/rhel/README.md b/rh-sre/skills/playbook-generator/references/rhel/README.md similarity index 100% rename from rh-sre/skills/playbook-generator/docs/rhel/README.md rename to rh-sre/skills/playbook-generator/references/rhel/README.md diff --git a/rh-sre/skills/playbook-generator/docs/rhel/package-management.md b/rh-sre/skills/playbook-generator/references/rhel/package-management.md similarity index 100% rename from rh-sre/skills/playbook-generator/docs/rhel/package-management.md rename to rh-sre/skills/playbook-generator/references/rhel/package-management.md diff --git a/rh-sre/skills/playbook-generator/references/rhel/selinux-context.md b/rh-sre/skills/playbook-generator/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/rhel/systemd-services.md b/rh-sre/skills/playbook-generator/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/playbook-generator/references/rhel/version-compatibility.md b/rh-sre/skills/playbook-generator/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/playbook-generator/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/SKILL.md b/rh-sre/skills/remediation/SKILL.md index c783a965..37a281ca 100644 --- a/rh-sre/skills/remediation/SKILL.md +++ b/rh-sre/skills/remediation/SKILL.md @@ -80,7 +80,7 @@ Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, **Sequencing (MANDATORY)**: Invoke validators **one at a time**. **Do NOT proceed to Step 1 until Step 0 is complete.** Wait for each validator to return explicit results (PASSED / FAILED / PARTIAL) before moving on. "Successfully loaded skill" alone does NOT mean validation completed—you must see the actual validation outcome. -**Invocation**: Use the Skill tool for ALL sub-skill invocations (validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier). **Do NOT use "Task Output" with the skill name as task ID**—that causes "No task found" errors (e.g. "No task found with ID: cve-validation"). See [skill-invocation.md](docs/references/skill-invocation.md). +**Invocation**: Use the Skill tool for ALL sub-skill invocations (validators, cve-validation, cve-impact, system-context, playbook-generator, playbook-executor, remediation-verifier). **Do NOT use "Task Output" with the skill name as task ID**—that causes "No task found" errors (e.g. "No task found with ID: cve-validation"). See [skill-invocation.md](references/skill-invocation.md). **Handle result**: If validation fails, stop and provide setup instructions. If passed, proceed to Step 1. **If any skill invocation fails** (e.g. "No task found with ID: ..."): Proceed with a warning—do not block. Later steps will surface real errors if MCP is unavailable. @@ -207,9 +207,9 @@ Execute skills in this order. **MANDATORY**: Use actual Skill tool invocations, ### Reference Documentation - [references/01-remediation-plan-template.md](references/01-remediation-plan-template.md) - Plan format for user validation -- [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md) - Backend errors (e.g. explain_cves), user-friendly message, workarounds -- [cve-remediation-templates.md](docs/ansible/cve-remediation-templates.md) -- [package-management.md](docs/rhel/package-management.md) +- [lightspeed-mcp-tool-failures.md](references/lightspeed-mcp-tool-failures.md) - Backend errors (e.g. explain_cves), user-friendly message, workarounds +- [cve-remediation-templates.md](references/ansible/cve-remediation-templates.md) +- [package-management.md](references/rhel/package-management.md) ## Critical: Human-in-the-Loop Requirements @@ -239,7 +239,7 @@ This skill requires explicit user confirmation at: **vulnerability__explain_cves**: Requires a valid `system_uuid` from inventory. Do NOT call it unless you have the resolved UUID from Step 3 (system-context) or Step 1 (cve-impact). Never pass `system_uuid: "undefined"` or placeholder values—this causes validation errors. For remediation availability at Step 2, use `get_cve` via cve-validation only. -**Lightspeed tool failures**: If a tool fails with a cryptic backend error (e.g. `'dnf_modules'`), do NOT retry or expose the raw error. Use workarounds from [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md). +**Lightspeed tool failures**: If a tool fails with a cryptic backend error (e.g. `'dnf_modules'`), do NOT retry or expose the raw error. Use workarounds from [lightspeed-mcp-tool-failures.md](references/lightspeed-mcp-tool-failures.md). ## Error Handling @@ -247,7 +247,7 @@ This skill requires explicit user confirmation at: - **No Remediation Available**: "CVE-XXXX-YYYY doesn't have an automated remediation playbook. Manual patching required." - **System Not Found**: "System XXXX is not in the Lightspeed inventory. Please ensure it's registered." - **Batch Partial Failure**: "Successfully processed X of Y CVEs. Failed: [list]. Reason: [explanations]" -- **Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Use user-friendly message and workaround from [lightspeed-mcp-tool-failures.md](docs/references/lightspeed-mcp-tool-failures.md). +- **Lightspeed tool failures** (e.g. explain_cves `'dnf_modules'`): Do NOT show raw error. Use user-friendly message and workaround from [lightspeed-mcp-tool-failures.md](references/lightspeed-mcp-tool-failures.md). ## Output Format diff --git a/rh-sre/skills/remediation/docs/ansible/aap-integration.md b/rh-sre/skills/remediation/docs/ansible/aap-integration.md deleted file mode 120000 index e9f9036f..00000000 --- a/rh-sre/skills/remediation/docs/ansible/aap-integration.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md b/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md deleted file mode 120000 index 269e56f2..00000000 --- a/rh-sre/skills/remediation/docs/ansible/cve-remediation-templates.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/error-handling.md b/rh-sre/skills/remediation/docs/ansible/error-handling.md deleted file mode 120000 index c4b7b276..00000000 --- a/rh-sre/skills/remediation/docs/ansible/error-handling.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/ansible/idempotency.md b/rh-sre/skills/remediation/docs/ansible/idempotency.md deleted file mode 120000 index c97ef9a0..00000000 --- a/rh-sre/skills/remediation/docs/ansible/idempotency.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md b/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md deleted file mode 120000 index a4b16aa8..00000000 --- a/rh-sre/skills/remediation/docs/insights/vulnerability-logic.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/compliance-frameworks.md b/rh-sre/skills/remediation/docs/references/compliance-frameworks.md deleted file mode 120000 index 333cdfdf..00000000 --- a/rh-sre/skills/remediation/docs/references/compliance-frameworks.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/cvss-scoring.md b/rh-sre/skills/remediation/docs/references/cvss-scoring.md deleted file mode 120000 index 30fd4ef7..00000000 --- a/rh-sre/skills/remediation/docs/references/cvss-scoring.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-validation/docs/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md b/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md deleted file mode 120000 index 394e7b5c..00000000 --- a/rh-sre/skills/remediation/docs/references/lightspeed-mcp-tool-failures.md +++ /dev/null @@ -1 +0,0 @@ -../../../cve-impact/docs/references/lightspeed-mcp-tool-failures.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/package-management.md b/rh-sre/skills/remediation/docs/rhel/package-management.md deleted file mode 120000 index 65fda622..00000000 --- a/rh-sre/skills/remediation/docs/rhel/package-management.md +++ /dev/null @@ -1 +0,0 @@ -../../../playbook-generator/docs/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/selinux-context.md b/rh-sre/skills/remediation/docs/rhel/selinux-context.md deleted file mode 120000 index 5159d6cf..00000000 --- a/rh-sre/skills/remediation/docs/rhel/selinux-context.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/systemd-services.md b/rh-sre/skills/remediation/docs/rhel/systemd-services.md deleted file mode 120000 index a3bbcb2c..00000000 --- a/rh-sre/skills/remediation/docs/rhel/systemd-services.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/rhel/version-compatibility.md b/rh-sre/skills/remediation/docs/rhel/version-compatibility.md deleted file mode 120000 index 1f952f5c..00000000 --- a/rh-sre/skills/remediation/docs/rhel/version-compatibility.md +++ /dev/null @@ -1 +0,0 @@ -../../../mcp-aap-validator/docs/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/ansible/aap-integration.md b/rh-sre/skills/remediation/references/ansible/aap-integration.md new file mode 120000 index 00000000..c42d4a6a --- /dev/null +++ b/rh-sre/skills/remediation/references/ansible/aap-integration.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/aap-integration.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/ansible/cve-remediation-templates.md b/rh-sre/skills/remediation/references/ansible/cve-remediation-templates.md new file mode 120000 index 00000000..de1c8b04 --- /dev/null +++ b/rh-sre/skills/remediation/references/ansible/cve-remediation-templates.md @@ -0,0 +1 @@ +../../../playbook-generator/references/ansible/cve-remediation-templates.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/ansible/error-handling.md b/rh-sre/skills/remediation/references/ansible/error-handling.md new file mode 120000 index 00000000..291ad184 --- /dev/null +++ b/rh-sre/skills/remediation/references/ansible/error-handling.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/error-handling.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/ansible/idempotency.md b/rh-sre/skills/remediation/references/ansible/idempotency.md new file mode 120000 index 00000000..d31c93f5 --- /dev/null +++ b/rh-sre/skills/remediation/references/ansible/idempotency.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/ansible/idempotency.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/compliance-frameworks.md b/rh-sre/skills/remediation/references/compliance-frameworks.md new file mode 120000 index 00000000..80860b3e --- /dev/null +++ b/rh-sre/skills/remediation/references/compliance-frameworks.md @@ -0,0 +1 @@ +../../mcp-aap-validator/references/compliance-frameworks.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/cvss-scoring.md b/rh-sre/skills/remediation/references/cvss-scoring.md new file mode 120000 index 00000000..ba836ca1 --- /dev/null +++ b/rh-sre/skills/remediation/references/cvss-scoring.md @@ -0,0 +1 @@ +../../cve-validation/references/cvss-scoring.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/insights/vulnerability-logic.md b/rh-sre/skills/remediation/references/insights/vulnerability-logic.md new file mode 120000 index 00000000..e3765d65 --- /dev/null +++ b/rh-sre/skills/remediation/references/insights/vulnerability-logic.md @@ -0,0 +1 @@ +../../../cve-validation/references/insights/vulnerability-logic.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/lightspeed-mcp-tool-failures.md b/rh-sre/skills/remediation/references/lightspeed-mcp-tool-failures.md new file mode 120000 index 00000000..8d7b3211 --- /dev/null +++ b/rh-sre/skills/remediation/references/lightspeed-mcp-tool-failures.md @@ -0,0 +1 @@ +../../cve-impact/references/lightspeed-mcp-tool-failures.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/rhel/package-management.md b/rh-sre/skills/remediation/references/rhel/package-management.md new file mode 120000 index 00000000..e37bb4e5 --- /dev/null +++ b/rh-sre/skills/remediation/references/rhel/package-management.md @@ -0,0 +1 @@ +../../../playbook-generator/references/rhel/package-management.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/rhel/selinux-context.md b/rh-sre/skills/remediation/references/rhel/selinux-context.md new file mode 120000 index 00000000..c9e215ea --- /dev/null +++ b/rh-sre/skills/remediation/references/rhel/selinux-context.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/selinux-context.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/rhel/systemd-services.md b/rh-sre/skills/remediation/references/rhel/systemd-services.md new file mode 120000 index 00000000..f7abdc3f --- /dev/null +++ b/rh-sre/skills/remediation/references/rhel/systemd-services.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/systemd-services.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/references/rhel/version-compatibility.md b/rh-sre/skills/remediation/references/rhel/version-compatibility.md new file mode 120000 index 00000000..1edc8daf --- /dev/null +++ b/rh-sre/skills/remediation/references/rhel/version-compatibility.md @@ -0,0 +1 @@ +../../../mcp-aap-validator/references/rhel/version-compatibility.md \ No newline at end of file diff --git a/rh-sre/skills/remediation/docs/references/skill-invocation.md b/rh-sre/skills/remediation/references/skill-invocation.md similarity index 100% rename from rh-sre/skills/remediation/docs/references/skill-invocation.md rename to rh-sre/skills/remediation/references/skill-invocation.md diff --git a/rh-virt/README.md b/rh-virt/README.md index d3fad530..31614166 100644 --- a/rh-virt/README.md +++ b/rh-virt/README.md @@ -404,7 +404,7 @@ The **vm-create** skill includes automatic error diagnosis and workaround propos - **ErrorUnschedulable** - Node taints/tolerations mismatch, resource constraints, node selector issues - **ErrorDataVolumeNotReady** - Storage provisioning delays, storage class issues, quota exceeded -**For comprehensive troubleshooting guidance**, see [docs/troubleshooting/INDEX.md](skills/vm-rebalance/docs/troubleshooting/INDEX.md). +**For comprehensive troubleshooting guidance**, see [docs/troubleshooting/INDEX.md](skills/vm-rebalance/references/troubleshooting/INDEX.md). ### MCP Server Won't Start diff --git a/rh-virt/docs/troubleshooting/.ai-index/semantic-index.json b/rh-virt/references/troubleshooting/.ai-index/semantic-index.json similarity index 100% rename from rh-virt/docs/troubleshooting/.ai-index/semantic-index.json rename to rh-virt/references/troubleshooting/.ai-index/semantic-index.json diff --git a/rh-virt/skills/vm-clone/SKILL.md b/rh-virt/skills/vm-clone/SKILL.md index e1774b3c..16e5e815 100644 --- a/rh-virt/skills/vm-clone/SKILL.md +++ b/rh-virt/skills/vm-clone/SKILL.md @@ -244,8 +244,8 @@ Use `resources_get` on DataVolume, check `status.phase` (Pending/Succeeded/Faile **Document Consultation** (OPTIONAL - when cloning fails): - **When to consult**: Storage cloning fails, VM creation fails, PVC clone not supported, storage class issues - **When NOT to consult**: VM already exists, RBAC errors, namespace not found (clear causes) -- **Action**: Read [storage-errors.md](docs/troubleshooting/storage-errors.md) for VM cloning failures, storage provisioning, DataVolume errors -- **Output to user**: "I consulted [storage-errors.md](docs/troubleshooting/storage-errors.md) to understand potential causes." +- **Action**: Read [storage-errors.md](references/troubleshooting/storage-errors.md) for VM cloning failures, storage provisioning, DataVolume errors +- **Output to user**: "I consulted [storage-errors.md](references/troubleshooting/storage-errors.md) to understand potential causes." ```markdown ## ❌ VM Cloning Failed @@ -260,7 +260,7 @@ Use `resources_get` on DataVolume, check `status.phase` (Pending/Succeeded/Faile - PVC clone not supported - Storage class doesn't support cloning - Source VM still running - Some storage backends require source VM stopped -**Troubleshooting** (see [storage-errors.md](docs/troubleshooting/storage-errors.md)): +**Troubleshooting** (see [storage-errors.md](references/troubleshooting/storage-errors.md)): 1. Check storage quota: `resources_list` for ResourceQuota in target namespace 2. Check permissions: `resources_list` to verify RBAC (note: `oc auth can-i` has no MCP equivalent) 3. Check storage class: `resources_get` for StorageClass config, `resources_list` for available classes @@ -327,8 +327,8 @@ Allow modifications during clone: instance type/size, storage size, network conf - `vm-delete` - Clean up failed clones or unwanted copies ### Reference Documentation -- [storage-errors.md](docs/troubleshooting/storage-errors.md) - VM cloning failure scenarios, storage provisioning issues, and DataVolume cloning errors (optionally consulted when cloning operations fail) -- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Navigation hub for discovering additional error categories when encountering unexpected issues outside the categories above +- [storage-errors.md](references/troubleshooting/storage-errors.md) - VM cloning failure scenarios, storage provisioning issues, and DataVolume cloning errors (optionally consulted when cloning operations fail) +- [Troubleshooting INDEX](references/troubleshooting/INDEX.md) - Navigation hub for discovering additional error categories when encountering unexpected issues outside the categories above - [OpenShift Virtualization Cloning](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt/virtual_machines/cloning_vms/virt-cloning-vm.html) - [DataVolume Cloning](https://github.com/kubevirt/containerized-data-importer/blob/main/doc/datavolumes.md#cloning) - [KubeVirt VirtualMachine API](https://kubevirt.io/api-reference/) diff --git a/rh-virt/skills/vm-clone/docs/README.md b/rh-virt/skills/vm-clone/docs/README.md deleted file mode 120000 index fa619329..00000000 --- a/rh-virt/skills/vm-clone/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/SOURCES.md b/rh-virt/skills/vm-clone/docs/SOURCES.md deleted file mode 120000 index 8ecd7839..00000000 --- a/rh-virt/skills/vm-clone/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md deleted file mode 120000 index a3fcc197..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md deleted file mode 120000 index 693aee70..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/lifecycle-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md deleted file mode 120000 index 334c0fc8..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/network-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md deleted file mode 120000 index 728999a3..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/runtime-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md deleted file mode 120000 index c95dda33..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/scheduling-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md deleted file mode 120000 index c3fb9854..00000000 --- a/rh-virt/skills/vm-clone/docs/troubleshooting/storage-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/README.md b/rh-virt/skills/vm-clone/references/README.md new file mode 120000 index 00000000..ae64320f --- /dev/null +++ b/rh-virt/skills/vm-clone/references/README.md @@ -0,0 +1 @@ +../../vm-delete/references/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/SOURCES.md b/rh-virt/skills/vm-clone/references/SOURCES.md new file mode 120000 index 00000000..2c23c847 --- /dev/null +++ b/rh-virt/skills/vm-clone/references/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/references/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/INDEX.md b/rh-virt/skills/vm-clone/references/troubleshooting/INDEX.md new file mode 120000 index 00000000..89e9445e --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-clone/references/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..3614be4e --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/network-errors.md b/rh-virt/skills/vm-clone/references/troubleshooting/network-errors.md new file mode 120000 index 00000000..800077cd --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-clone/references/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..7ba2662d --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-clone/references/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..f830ff02 --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-clone/references/troubleshooting/storage-errors.md b/rh-virt/skills/vm-clone/references/troubleshooting/storage-errors.md new file mode 120000 index 00000000..3a25ed53 --- /dev/null +++ b/rh-virt/skills/vm-clone/references/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/SKILL.md b/rh-virt/skills/vm-create/SKILL.md index dd02dacb..1b322098 100644 --- a/rh-virt/skills/vm-create/SKILL.md +++ b/rh-virt/skills/vm-create/SKILL.md @@ -173,7 +173,7 @@ Confirm: yes/no/modify #### 5a. Diagnostic Workflow (ErrorUnschedulable) **CRITICAL: Document Consultation FIRST:** -1. Read [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) using Read tool +1. Read [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) using Read tool 2. Output: "I detected ErrorUnschedulable. I consulted [scheduling-errors.md] to understand diagnosis strategies." **Gather diagnostics:** @@ -298,11 +298,11 @@ Troubleshooting: See Common Issues - `vm-lifecycle-manager` - Start VMs | `vm-inventory` - List VMs | `vm-delete` - Delete VMs | `vm-clone` - Clone VMs | `vm-snapshot-create` - Snapshot VMs ### Reference Documentation -- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable (consulted Step 5a) -- [storage-errors.md](docs/troubleshooting/storage-errors.md) - ErrorDataVolumeNotReady -- [network-errors.md](docs/troubleshooting/network-errors.md) - Network failures -- [runtime-errors.md](docs/troubleshooting/runtime-errors.md) - CrashLoopBackOff -- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Full error index +- [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) - ErrorUnschedulable (consulted Step 5a) +- [storage-errors.md](references/troubleshooting/storage-errors.md) - ErrorDataVolumeNotReady +- [network-errors.md](references/troubleshooting/network-errors.md) - Network failures +- [runtime-errors.md](references/troubleshooting/runtime-errors.md) - CrashLoopBackOff +- [Troubleshooting INDEX](references/troubleshooting/INDEX.md) - Full error index - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index) - [KubeVirt API](https://kubevirt.io/api-reference/) - [OpenShift MCP](https://github.com/openshift/openshift-mcp-server) diff --git a/rh-virt/skills/vm-create/docs/README.md b/rh-virt/skills/vm-create/docs/README.md deleted file mode 120000 index fa619329..00000000 --- a/rh-virt/skills/vm-create/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/SOURCES.md b/rh-virt/skills/vm-create/docs/SOURCES.md deleted file mode 120000 index 8ecd7839..00000000 --- a/rh-virt/skills/vm-create/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md deleted file mode 120000 index a3fcc197..00000000 --- a/rh-virt/skills/vm-create/docs/troubleshooting/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md deleted file mode 120000 index 693aee70..00000000 --- a/rh-virt/skills/vm-create/docs/troubleshooting/lifecycle-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md deleted file mode 120000 index c95dda33..00000000 --- a/rh-virt/skills/vm-create/docs/troubleshooting/scheduling-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md deleted file mode 120000 index c3fb9854..00000000 --- a/rh-virt/skills/vm-create/docs/troubleshooting/storage-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/references/README.md b/rh-virt/skills/vm-create/references/README.md new file mode 120000 index 00000000..ae64320f --- /dev/null +++ b/rh-virt/skills/vm-create/references/README.md @@ -0,0 +1 @@ +../../vm-delete/references/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/references/SOURCES.md b/rh-virt/skills/vm-create/references/SOURCES.md new file mode 120000 index 00000000..2c23c847 --- /dev/null +++ b/rh-virt/skills/vm-create/references/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/references/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/references/troubleshooting/INDEX.md b/rh-virt/skills/vm-create/references/troubleshooting/INDEX.md new file mode 120000 index 00000000..89e9445e --- /dev/null +++ b/rh-virt/skills/vm-create/references/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/references/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-create/references/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..3614be4e --- /dev/null +++ b/rh-virt/skills/vm-create/references/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-create/references/troubleshooting/network-errors.md similarity index 100% rename from rh-virt/skills/vm-create/docs/troubleshooting/network-errors.md rename to rh-virt/skills/vm-create/references/troubleshooting/network-errors.md diff --git a/rh-virt/skills/vm-create/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-create/references/troubleshooting/runtime-errors.md similarity index 99% rename from rh-virt/skills/vm-create/docs/troubleshooting/runtime-errors.md rename to rh-virt/skills/vm-create/references/troubleshooting/runtime-errors.md index 804d3cbc..b5179ccf 100644 --- a/rh-virt/skills/vm-create/docs/troubleshooting/runtime-errors.md +++ b/rh-virt/skills/vm-create/references/troubleshooting/runtime-errors.md @@ -569,7 +569,7 @@ When implementing diagnostic workflows: ```markdown **Document Consultation** (REQUIRED): -1. **Action**: Read [runtime-errors.md](../../docs/troubleshooting/runtime-errors.md) to understand CrashLoopBackOff causes +1. **Action**: Read [runtime-errors.md](../troubleshooting/runtime-errors.md) to understand CrashLoopBackOff causes 2. **Output to user**: "I consulted runtime-errors.md to diagnose the CrashLoopBackOff issue." ``` diff --git a/rh-virt/skills/vm-create/references/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-create/references/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..f830ff02 --- /dev/null +++ b/rh-virt/skills/vm-create/references/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-create/references/troubleshooting/storage-errors.md b/rh-virt/skills/vm-create/references/troubleshooting/storage-errors.md new file mode 120000 index 00000000..3a25ed53 --- /dev/null +++ b/rh-virt/skills/vm-create/references/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/SKILL.md b/rh-virt/skills/vm-delete/SKILL.md index be1d1959..d91228e2 100644 --- a/rh-virt/skills/vm-delete/SKILL.md +++ b/rh-virt/skills/vm-delete/SKILL.md @@ -214,7 +214,7 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele **Partial failure (storage failed):** -**OPTIONAL**: Read [storage-errors.md](docs/troubleshooting/storage-errors.md) for PVC cleanup. Output: "Consulted storage-errors.md for failure." +**OPTIONAL**: Read [storage-errors.md](references/troubleshooting/storage-errors.md) for PVC cleanup. Output: "Consulted storage-errors.md for failure." ```markdown ## ⚠️ Partial Deletion @@ -224,7 +224,7 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele **Complete failure:** -**OPTIONAL**: Read [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) for deletion failures. Output: "Consulted lifecycle-errors.md for failure causes." +**OPTIONAL**: Read [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) for deletion failures. Output: "Consulted lifecycle-errors.md for failure causes." ```markdown ## ❌ VM Deletion Failed @@ -244,11 +244,11 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele ### Issue 3: VM Has Finalizers **Error**: "VM deletion blocked by finalizers" -**Solution**: Consult [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) "VM Stuck in Terminating" for MCP-first approach using `resources_get` to check finalizers, `resources_create_or_update` to remove if needed. +**Solution**: Consult [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) "VM Stuck in Terminating" for MCP-first approach using `resources_get` to check finalizers, `resources_create_or_update` to remove if needed. ### Issue 4: Storage Deletion Failure **Error**: "PVC deletion failed: resource in use" -**Solution**: Verify VM deleted first. Consult [storage-errors.md](docs/troubleshooting/storage-errors.md) for MCP-first diagnostics using `pods_list_in_namespace` to check mounts, `resources_get` for PVC status. +**Solution**: Verify VM deleted first. Consult [storage-errors.md](references/troubleshooting/storage-errors.md) for MCP-first diagnostics using `pods_list_in_namespace` to check mounts, `resources_get` for PVC status. ### Issue 5: Confirmation Mismatch **Error**: "Names do not match" @@ -275,9 +275,9 @@ Report: `🗑️ Deleting storage... ✓ DV deleted (storage freed) ✓ PVC dele - `vm-lifecycle-manager` - Stop VMs | `vm-inventory` - List VMs | `vm-create` - Create VMs | `vm-clone` - Clone VMs ### Reference Documentation -- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - Deletion failures, finalizers, stuck Terminating (consulted on deletion failure) -- [storage-errors.md](docs/troubleshooting/storage-errors.md) - Storage deletion, PVC cleanup (consulted on storage failure) -- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Full error index +- [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) - Deletion failures, finalizers, stuck Terminating (consulted on deletion failure) +- [storage-errors.md](references/troubleshooting/storage-errors.md) - Storage deletion, PVC cleanup (consulted on storage failure) +- [Troubleshooting INDEX](references/troubleshooting/INDEX.md) - Full error index - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index) - [KubeVirt API](https://kubevirt.io/api-reference/) - [K8s Finalizers](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md deleted file mode 120000 index a3fcc197..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md deleted file mode 120000 index 693aee70..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/lifecycle-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md deleted file mode 120000 index 334c0fc8..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/network-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md deleted file mode 120000 index 728999a3..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/runtime-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md deleted file mode 120000 index c95dda33..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/scheduling-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md deleted file mode 120000 index c3fb9854..00000000 --- a/rh-virt/skills/vm-delete/docs/troubleshooting/storage-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/docs/README.md b/rh-virt/skills/vm-delete/references/README.md similarity index 100% rename from rh-virt/skills/vm-delete/docs/README.md rename to rh-virt/skills/vm-delete/references/README.md diff --git a/rh-virt/skills/vm-delete/docs/SOURCES.md b/rh-virt/skills/vm-delete/references/SOURCES.md similarity index 100% rename from rh-virt/skills/vm-delete/docs/SOURCES.md rename to rh-virt/skills/vm-delete/references/SOURCES.md diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/INDEX.md b/rh-virt/skills/vm-delete/references/troubleshooting/INDEX.md new file mode 120000 index 00000000..89e9445e --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-delete/references/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..3614be4e --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/network-errors.md b/rh-virt/skills/vm-delete/references/troubleshooting/network-errors.md new file mode 120000 index 00000000..800077cd --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-delete/references/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..7ba2662d --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-delete/references/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..f830ff02 --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-delete/references/troubleshooting/storage-errors.md b/rh-virt/skills/vm-delete/references/troubleshooting/storage-errors.md new file mode 120000 index 00000000..3a25ed53 --- /dev/null +++ b/rh-virt/skills/vm-delete/references/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/SKILL.md b/rh-virt/skills/vm-lifecycle-manager/SKILL.md index e24343fd..60746594 100644 --- a/rh-virt/skills/vm-lifecycle-manager/SKILL.md +++ b/rh-virt/skills/vm-lifecycle-manager/SKILL.md @@ -134,7 +134,7 @@ Confirm: yes/no **On Failure:** -**OPTIONAL**: Read [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) for start/stop failures or [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) for ErrorUnschedulable. Output: "Consulted lifecycle-errors.md for failure." +**OPTIONAL**: Read [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) for start/stop failures or [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) for ErrorUnschedulable. Output: "Consulted lifecycle-errors.md for failure." **When to consult**: Start/stop failures, stuck transitions, unexpected errors. **NOT**: Already in state, not found, RBAC errors. @@ -201,9 +201,9 @@ Confirm: yes/no - `vm-troubleshooter` (planned) - Diagnose startup/shutdown issues ### Reference Documentation -- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - Start/stop failures, stuck transitions (consulted on failures) -- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, resource constraints (consulted when VM won't start) -- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Navigation hub for error categories +- [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) - Start/stop failures, stuck transitions (consulted on failures) +- [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, resource constraints (consulted when VM won't start) +- [Troubleshooting INDEX](references/troubleshooting/INDEX.md) - Navigation hub for error categories - [OpenShift Virt Docs](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt/about_virt/about-virt.html) - [KubeVirt Lifecycle](https://kubevirt.io/user-guide/virtual_machines/lifecycle/) - [RunStrategy Docs](https://kubevirt.io/user-guide/virtual_machines/run_strategies/) diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/README.md b/rh-virt/skills/vm-lifecycle-manager/docs/README.md deleted file mode 120000 index fa619329..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md b/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md deleted file mode 120000 index 8ecd7839..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md deleted file mode 120000 index a3fcc197..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md deleted file mode 120000 index 693aee70..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/lifecycle-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md deleted file mode 120000 index 334c0fc8..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/network-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md deleted file mode 120000 index 728999a3..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/runtime-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md deleted file mode 120000 index c95dda33..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/scheduling-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md deleted file mode 120000 index c3fb9854..00000000 --- a/rh-virt/skills/vm-lifecycle-manager/docs/troubleshooting/storage-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-rebalance/docs/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/README.md b/rh-virt/skills/vm-lifecycle-manager/references/README.md new file mode 120000 index 00000000..ae64320f --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/README.md @@ -0,0 +1 @@ +../../vm-delete/references/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/SOURCES.md b/rh-virt/skills/vm-lifecycle-manager/references/SOURCES.md new file mode 120000 index 00000000..2c23c847 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/references/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/INDEX.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/INDEX.md new file mode 120000 index 00000000..89e9445e --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/INDEX.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/INDEX.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/lifecycle-errors.md new file mode 120000 index 00000000..3614be4e --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/lifecycle-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/lifecycle-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/network-errors.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/network-errors.md new file mode 120000 index 00000000..800077cd --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..7ba2662d --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/scheduling-errors.md new file mode 120000 index 00000000..f830ff02 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/scheduling-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/scheduling-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/storage-errors.md b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/storage-errors.md new file mode 120000 index 00000000..3a25ed53 --- /dev/null +++ b/rh-virt/skills/vm-lifecycle-manager/references/troubleshooting/storage-errors.md @@ -0,0 +1 @@ +../../../vm-rebalance/references/troubleshooting/storage-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/REBALANCE_AUTOMATIC.md b/rh-virt/skills/vm-rebalance/REBALANCE_AUTOMATIC.md index 936a4f3b..5a4e30e8 100644 --- a/rh-virt/skills/vm-rebalance/REBALANCE_AUTOMATIC.md +++ b/rh-virt/skills/vm-rebalance/REBALANCE_AUTOMATIC.md @@ -195,7 +195,7 @@ For each candidate migration, check: - Verify VM has matching tolerations - If mismatch, skip that target or propose adding tolerations -**Concurrency Limits** (see [references/performance-tuning.md](./references/performance-tuning.md)): +**Concurrency Limits** (see [references/performance-tuning.md](references/performance-tuning.md)): - Cluster limit: 5 concurrent migrations (default) - Per-node limit: 2 outbound migrations (default) - Plan migration batches respecting limits @@ -383,7 +383,7 @@ Count migrations where `.status.phase` is NOT "Succeeded" or "Failed". **Wait if at limit** before starting new migrations. -**Reference**: [references/performance-tuning.md](./references/performance-tuning.md#concurrency-limits-tuning) +**Reference**: [references/performance-tuning.md](references/performance-tuning.md#concurrency-limits-tuning) --- @@ -545,7 +545,7 @@ Display similar format but include: ### Intelligent Workload Analysis -**Categorize VMs by workload type** (see [references/production-considerations.md](./references/production-considerations.md)): +**Categorize VMs by workload type** (see [references/production-considerations.md](references/production-considerations.md)): - **Database** (high dirty page rate) → Schedule during low-activity window, consider cold migration - **Web servers** (low dirty page rate) → Safe for concurrent live migration @@ -574,7 +574,7 @@ Review `.network.interfaces[].rxBytes` and `.network.interfaces[].txBytes`. - Set bandwidth limits per migration - Suggest dedicated migration network -**Reference**: [references/live-migration-best-practices.md#dedicated-migration-network](./references/live-migration-best-practices.md#dedicated-migration-network-production-best-practice) +**Reference**: [references/live-migration-best-practices.md#dedicated-migration-network](references/live-migration-best-practices.md#dedicated-migration-network-production-best-practice) ### Multi-Constraint Optimization @@ -652,7 +652,7 @@ Review `.network.interfaces[].rxBytes` and `.network.interfaces[].txBytes`. - Have rollback plan for critical workloads - Consider snapshots before risky migrations (use `/vm-snapshot-create`) -**Reference**: [references/anti-patterns.md](./references/anti-patterns.md) +**Reference**: [references/anti-patterns.md](references/anti-patterns.md) --- diff --git a/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md b/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md index f1e9d2c6..b29db491 100644 --- a/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md +++ b/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md @@ -100,7 +100,7 @@ Use this mode when the user specifies: **Estimated Duration:** ~30-60 seconds for typical VM (depends on memory size) -**Reference**: See [references/live-migration-best-practices.md](./references/live-migration-best-practices.md) for configuration parameters, storage requirements, and network optimization +**Reference**: See [references/live-migration-best-practices.md](references/live-migration-best-practices.md) for configuration parameters, storage requirements, and network optimization **Rollback:** If migration fails, VM continues running on current node @@ -150,7 +150,7 @@ Confirm this migration or tell me what to change: **Note on Node Affinity:** We use nodeAffinity (not nodeSelector) for better long-term resilience. After migration, you'll have the option to remove it, allowing the VM to reschedule to other nodes if fails in the future. -**Reference**: See [references/production-considerations.md](./references/production-considerations.md) for workload categorization and downtime planning strategies +**Reference**: See [references/production-considerations.md](references/production-considerations.md) for workload categorization and downtime planning strategies Confirm this migration or tell me what to change: - yes - Proceed with cold migration @@ -226,7 +226,7 @@ Confirm this migration or tell me what to change: **Timeout**: Stop polling after 10 minutes (600 seconds) and report timeout error to user. Most migrations complete within 1-5 minutes depending on VM memory size. -**Reference**: See [references/performance-tuning.md](./references/performance-tuning.md) for timeout configuration and migration optimization strategies +**Reference**: See [references/performance-tuning.md](references/performance-tuning.md) for timeout configuration and migration optimization strategies **Expected Output**: VMIM resource with status field @@ -381,7 +381,7 @@ Preserve all existing VM fields and only modify the affinity section. **Error Handling with Clear Explanations:** - If VM fails to start → Explain: "VM failed to start on . This usually means the node doesn't have enough resources (CPU/memory) or has scheduling constraints preventing this VM." - - Consult [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) + - Consult [scheduling-errors.md](../troubleshooting/scheduling-errors.md) - Suggest: Check node capacity, verify node is Ready, check for taints - If VM scheduled on wrong node → Explain: "VM started but Kubernetes placed it on instead of . This means couldn't accommodate the VM due to resource constraints, taints, or other scheduling rules." - Report actual vs expected node @@ -588,10 +588,10 @@ VM has restarted, verify services are healthy. **Document Consultation** (OPTIONAL - when migration fails): 1. **Action**: Read relevant troubleshooting guides to understand VM migration failure scenarios: - - [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) - For ErrorUnschedulable, node taints, resource constraints - - [lifecycle-errors.md](../../docs/troubleshooting/lifecycle-errors.md) - For VM start/stop failures during cold migration - - [storage-errors.md](../../docs/troubleshooting/storage-errors.md) - For PVC access mode issues affecting live migration -2. **Output to user**: "I consulted [scheduling-errors.md](../../docs/troubleshooting/scheduling-errors.md) to understand potential causes for the migration failure." + - [scheduling-errors.md](../troubleshooting/scheduling-errors.md) - For ErrorUnschedulable, node taints, resource constraints + - [lifecycle-errors.md](../troubleshooting/lifecycle-errors.md) - For VM start/stop failures during cold migration + - [storage-errors.md](../troubleshooting/storage-errors.md) - For PVC access mode issues affecting live migration +2. **Output to user**: "I consulted [scheduling-errors.md](../troubleshooting/scheduling-errors.md) to understand potential causes for the migration failure." **When to consult**: - Live migration fails (check storage, network, resource constraints) @@ -678,7 +678,7 @@ Would you like help troubleshooting this error? - ⚠️ **Batches >10 VMs**: Strongly recommend splitting into multiple batches (e.g., 5 VMs at a time) - ⚠️ **Multiple cold migrations**: Warn about cumulative downtime impact -**Reference**: See [references/anti-patterns.md](./references/anti-patterns.md) for common mistakes when performing batch migrations and network saturation issues +**Reference**: See [references/anti-patterns.md](references/anti-patterns.md) for common mistakes when performing batch migrations and network saturation issues **Workflow:** 1. Validate all VMs exist and are migratable @@ -837,10 +837,10 @@ Agent: [Switches to cold migration workflow] **Reference Documentation:** **Internal Skill Documentation**: -- [references/live-migration-best-practices.md](./references/live-migration-best-practices.md) - Configuration, requirements, dedicated networks -- [references/performance-tuning.md](./references/performance-tuning.md) - Right-sizing, overcommit, bandwidth tuning -- [references/anti-patterns.md](./references/anti-patterns.md) - Common mistakes to avoid -- [references/production-considerations.md](./references/production-considerations.md) - HA strategies, capacity planning +- [references/live-migration-best-practices.md](references/live-migration-best-practices.md) - Configuration, requirements, dedicated networks +- [references/performance-tuning.md](references/performance-tuning.md) - Right-sizing, overcommit, bandwidth tuning +- [references/anti-patterns.md](references/anti-patterns.md) - Common mistakes to avoid +- [references/production-considerations.md](references/production-considerations.md) - HA strategies, capacity planning **Official KubeVirt Documentation**: - [Live Migration - KubeVirt User Guide](https://kubevirt.io/user-guide/compute/live_migration/) diff --git a/rh-virt/skills/vm-rebalance/SKILL.md b/rh-virt/skills/vm-rebalance/SKILL.md index 948285bb..af224ec2 100644 --- a/rh-virt/skills/vm-rebalance/SKILL.md +++ b/rh-virt/skills/vm-rebalance/SKILL.md @@ -134,7 +134,7 @@ Orchestrate VM migrations across OpenShift cluster nodes for load balancing, mai **Error for live migration**: If RWO → "Cannot live migrate. Use cold migration (brief downtime ~30-60s)." -**Reference**: [references/live-migration-best-practices.md](./references/live-migration-best-practices.md) +**Reference**: [references/live-migration-best-practices.md](references/live-migration-best-practices.md) ### Validation 4: Verify Target Node Exists @@ -144,7 +144,7 @@ Orchestrate VM migrations across OpenShift cluster nodes for load balancing, mai **Errors**: Not found → "Node doesn't exist" | Not Ready → "Choose different target" | Cordoned → "Uncordon or choose different target" -**Reference**: [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) +**Reference**: [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) ## Node Selection for Automatic Rebalancing @@ -167,7 +167,7 @@ Filter where ALL true: **Cold Migration**: Brief downtime (~30-60s). Works with any storage. Stop VM → Update placement → Start on target. -**Reference**: [references/live-migration-best-practices.md](./references/live-migration-best-practices.md) +**Reference**: [references/live-migration-best-practices.md](references/live-migration-best-practices.md) ## Common Plan Visualization @@ -273,22 +273,22 @@ If any node's CPU or Memory percentage **exceeds 100%** after rebalancing: ### Error 1: Live Migration Fails - Storage Not RWX **Symptom**: "Cannot live migrate: PVC access mode is ReadWriteOnce" **Solution**: Use cold migration OR convert PVC to RWX -**Reference**: [storage-errors.md](docs/troubleshooting/storage-errors.md) +**Reference**: [storage-errors.md](references/troubleshooting/storage-errors.md) ### Error 2: VM Stuck ErrorUnschedulable After Cold Migration **Symptom**: "VM cannot be scheduled: ErrorUnschedulable" **Solution**: Check node capacity (`nodes_top`), verify no blocking taints (`resources_get` Node), add tolerations, choose different target, remove nodeSelector -**Reference**: [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) +**Reference**: [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) ### Error 3: Live Migration Times Out **Symptom**: "Migration exceeded timeout: 150s per GiB" **Solution**: Retry migration, reduce VM workload, use cold migration, increase timeout in HyperConverged CR -**Reference**: [references/performance-tuning.md](./references/performance-tuning.md) +**Reference**: [references/performance-tuning.md](references/performance-tuning.md) ### Error 4: Migration Rejected - Cluster Limit Reached **Symptom**: "Migration rejected: cluster limit reached (5 concurrent)" **Solution**: Wait for migrations to complete (`resources_list` VirtualMachineInstanceMigration), retry, migrate sequentially, increase limit -**Reference**: [references/performance-tuning.md](./references/performance-tuning.md) +**Reference**: [references/performance-tuning.md](references/performance-tuning.md) ### Error 5: RBAC Permission Denied **Symptom**: "Forbidden: User cannot create VirtualMachineInstanceMigration" @@ -297,7 +297,7 @@ If any node's CPU or Memory percentage **exceeds 100%** after rebalancing: ### Error 6: Network Saturation **Symptom**: Multiple migrations slow/fail, high network utilization **Solution**: Reduce concurrent migrations, set bandwidth limit, use dedicated migration network -**Reference**: [references/performance-tuning.md](./references/performance-tuning.md) +**Reference**: [references/performance-tuning.md](references/performance-tuning.md) ### Error 7: Resource Version Conflict During Cold Migration **Symptom**: "Apply failed: conflict with 'kubernetes-mcp-server' using .spec.runStrategy" @@ -326,16 +326,16 @@ If any node's CPU or Memory percentage **exceeds 100%** after rebalancing: - [REBALANCE_AUTOMATIC.md](./REBALANCE_AUTOMATIC.md) - AI-driven rebalancing **Performance and Best Practices**: -- [references/live-migration-best-practices.md](./references/live-migration-best-practices.md) - Configuration, requirements, networks -- [references/performance-tuning.md](./references/performance-tuning.md) - Right-sizing, overcommit, bandwidth -- [references/anti-patterns.md](./references/anti-patterns.md) - Common mistakes -- [references/production-considerations.md](./references/production-considerations.md) - HA, capacity, security +- [references/live-migration-best-practices.md](references/live-migration-best-practices.md) - Configuration, requirements, networks +- [references/performance-tuning.md](references/performance-tuning.md) - Right-sizing, overcommit, bandwidth +- [references/anti-patterns.md](references/anti-patterns.md) - Common mistakes +- [references/production-considerations.md](references/production-considerations.md) - HA, capacity, security **Troubleshooting**: -- [Troubleshooting INDEX](docs/troubleshooting/INDEX.md) - Master index -- [scheduling-errors.md](docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, taints -- [storage-errors.md](docs/troubleshooting/storage-errors.md) - PVC access modes -- [lifecycle-errors.md](docs/troubleshooting/lifecycle-errors.md) - VM start/stop +- [Troubleshooting INDEX](references/troubleshooting/INDEX.md) - Master index +- [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) - ErrorUnschedulable, taints +- [storage-errors.md](references/troubleshooting/storage-errors.md) - PVC access modes +- [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) - VM start/stop **Official Documentation**: - [OpenShift Virt - Live Migration](https://docs.redhat.com/en/documentation/openshift_container_platform/4.21/html-single/virtualization/index#virt-live-migration) diff --git a/rh-virt/skills/vm-rebalance/docs/README.md b/rh-virt/skills/vm-rebalance/docs/README.md deleted file mode 120000 index fa619329..00000000 --- a/rh-virt/skills/vm-rebalance/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/SOURCES.md b/rh-virt/skills/vm-rebalance/docs/SOURCES.md deleted file mode 120000 index 8ecd7839..00000000 --- a/rh-virt/skills/vm-rebalance/docs/SOURCES.md +++ /dev/null @@ -1 +0,0 @@ -../../vm-delete/docs/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md deleted file mode 120000 index 334c0fc8..00000000 --- a/rh-virt/skills/vm-rebalance/docs/troubleshooting/network-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md deleted file mode 120000 index 728999a3..00000000 --- a/rh-virt/skills/vm-rebalance/docs/troubleshooting/runtime-errors.md +++ /dev/null @@ -1 +0,0 @@ -../../../vm-create/docs/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/references/README.md b/rh-virt/skills/vm-rebalance/references/README.md new file mode 120000 index 00000000..ae64320f --- /dev/null +++ b/rh-virt/skills/vm-rebalance/references/README.md @@ -0,0 +1 @@ +../../vm-delete/references/README.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/references/SOURCES.md b/rh-virt/skills/vm-rebalance/references/SOURCES.md new file mode 120000 index 00000000..2c23c847 --- /dev/null +++ b/rh-virt/skills/vm-rebalance/references/SOURCES.md @@ -0,0 +1 @@ +../../vm-delete/references/SOURCES.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/references/live-migration-best-practices.md b/rh-virt/skills/vm-rebalance/references/live-migration-best-practices.md index 7df97527..2b39645c 100644 --- a/rh-virt/skills/vm-rebalance/references/live-migration-best-practices.md +++ b/rh-virt/skills/vm-rebalance/references/live-migration-best-practices.md @@ -785,7 +785,7 @@ Use `resources_get` to fetch HyperConverged CR, modify `.spec.liveMigrationConfi - [Performance Tuning Guide](./performance-tuning.md) - Advanced tuning for migration performance - [Anti-Patterns](./anti-patterns.md) - Common mistakes to avoid - [Production Considerations](./production-considerations.md) - Right-sizing, workload planning, HA strategies -- [Troubleshooting: Scheduling Errors](../../../docs/troubleshooting/scheduling-errors.md) - ErrorUnschedulable after cold migration +- [Troubleshooting: Scheduling Errors](troubleshooting/scheduling-errors.md) - ErrorUnschedulable after cold migration --- diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/INDEX.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/INDEX.md similarity index 100% rename from rh-virt/skills/vm-rebalance/docs/troubleshooting/INDEX.md rename to rh-virt/skills/vm-rebalance/references/troubleshooting/INDEX.md diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/lifecycle-errors.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/lifecycle-errors.md similarity index 100% rename from rh-virt/skills/vm-rebalance/docs/troubleshooting/lifecycle-errors.md rename to rh-virt/skills/vm-rebalance/references/troubleshooting/lifecycle-errors.md diff --git a/rh-virt/skills/vm-rebalance/references/troubleshooting/network-errors.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/network-errors.md new file mode 120000 index 00000000..800077cd --- /dev/null +++ b/rh-virt/skills/vm-rebalance/references/troubleshooting/network-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/network-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/references/troubleshooting/runtime-errors.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/runtime-errors.md new file mode 120000 index 00000000..7ba2662d --- /dev/null +++ b/rh-virt/skills/vm-rebalance/references/troubleshooting/runtime-errors.md @@ -0,0 +1 @@ +../../../vm-create/references/troubleshooting/runtime-errors.md \ No newline at end of file diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/scheduling-errors.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/scheduling-errors.md similarity index 100% rename from rh-virt/skills/vm-rebalance/docs/troubleshooting/scheduling-errors.md rename to rh-virt/skills/vm-rebalance/references/troubleshooting/scheduling-errors.md diff --git a/rh-virt/skills/vm-rebalance/docs/troubleshooting/storage-errors.md b/rh-virt/skills/vm-rebalance/references/troubleshooting/storage-errors.md similarity index 100% rename from rh-virt/skills/vm-rebalance/docs/troubleshooting/storage-errors.md rename to rh-virt/skills/vm-rebalance/references/troubleshooting/storage-errors.md diff --git a/scripts/validate_compass_manifests.py b/scripts/validate_compass_manifests.py index 489b96e2..ba8ef85f 100644 --- a/scripts/validate_compass_manifests.py +++ b/scripts/validate_compass_manifests.py @@ -1,6 +1,6 @@ #!/usr/bin/env python3 """ -Validate Compass catalog-info.yaml manifests for agentic packs in the root Location. +Validate Compass catalog-info.yaml manifests and skill references layout. Structural checks (no SKILL.md semantic inference): - Roster parity: skills on disk vs pack Location targets vs manifest files @@ -10,10 +10,14 @@ - Forbidden partOf/hasPart on skill manifests; redundant plugin dependsOn system - Dangling airesource refs; canonical mcpserver:redhat/* allowed without local file - Basic field conventions on skill manifests (namespace, owner, agents, distribution) + - Skill documentation layout (all packs with skills/): + no skills//docs/; no references/references/ nesting; + no internal docs/ links; symlinks under references/ must not target docs/ """ from __future__ import annotations +import os import re import sys from pathlib import Path @@ -28,6 +32,8 @@ _CANONICAL_MCP_PREFIXES = ("mcpserver:redhat/", "mcpserver:default/") _EXPECTED_OWNER = "group:redhat/ai5-marketplace" _EXPECTED_NAMESPACE = "ai5-marketplace" +_MD_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") +_SKILL_DOCS_STANDARD = "https://agent-plugins.org/specification" def _load_yaml(path: Path) -> dict: @@ -44,6 +50,16 @@ def _refs(spec: dict, key: str) -> list[str]: return [str(item) for item in value] +def all_packs_with_skills() -> list[str]: + packs: list[str] = [] + for entry in sorted(_REPO_ROOT.iterdir()): + if not entry.is_dir() or entry.name.startswith("."): + continue + if (entry / "skills").is_dir(): + packs.append(entry.name) + return packs + + def registered_packs() -> list[str]: data = _load_yaml(_ROOT_CATALOG) packs: list[str] = [] @@ -101,6 +117,82 @@ def _is_allowed_dangling_mcp(ref: str) -> bool: return ref.startswith(_CANONICAL_MCP_PREFIXES) +def _is_external_link(target: str) -> bool: + lower = target.lower() + return ( + lower.startswith("http://") + or lower.startswith("https://") + or lower.startswith("mailto:") + or lower.startswith("#") + ) + + +def _is_forbidden_docs_link(target: str) -> bool: + if _is_external_link(target): + return False + normalized = target.split("#", 1)[0].strip().replace("\\", "/") + if normalized.startswith("docs/") or normalized.startswith("./docs/"): + return True + return "/docs/" in normalized + + +def _check_skill_docs_layout(skill_dir: Path, errors: list[str]) -> None: + """Enforce agent-plugins.org / agentskills.io references/ layout (APPENG-6308).""" + docs_dir = skill_dir / "docs" + if docs_dir.is_dir(): + rel = docs_dir.relative_to(_REPO_ROOT) + errors.append( + f"{rel}: skill documentation must use references/ not docs/ " + f"(rename to references/, update links, then delete docs/; " + f"see {_SKILL_DOCS_STANDARD})" + ) + + nested_refs = skill_dir / "references" / "references" + if nested_refs.is_dir(): + rel = nested_refs.relative_to(_REPO_ROOT) + errors.append( + f"{rel}: flatten references/references/ into skills//references/ " + f"(no nested references directories; see {_SKILL_DOCS_STANDARD})" + ) + + references_dir = skill_dir / "references" + if references_dir.is_dir(): + for path in sorted(references_dir.rglob("*")): + if not path.is_symlink(): + continue + raw = os.readlink(path) + normalized = raw.replace("\\", "/") + if "/docs/" in normalized or normalized.startswith("docs/"): + rel = path.relative_to(_REPO_ROOT) + errors.append( + f"{rel}: symlink still targets docs/ path '{raw}' — " + "update to references/ after migration" + ) + + for md_file in sorted(skill_dir.rglob("*.md")): + if md_file.is_symlink() and not md_file.exists(): + continue + try: + text = md_file.read_text(encoding="utf-8") + except (OSError, UnicodeDecodeError): + continue + rel_md = md_file.relative_to(_REPO_ROOT) + for line_no, line in enumerate(text.splitlines(), start=1): + for match in _MD_LINK_RE.finditer(line): + raw_target = match.group(1).strip() + if _is_forbidden_docs_link(raw_target): + errors.append( + f"{rel_md}:{line_no}: update docs/ link to references/: " + f"'{raw_target}'" + ) + target = raw_target.split("#", 1)[0].strip().replace("\\", "/") + if "references/references/" in target: + errors.append( + f"{rel_md}:{line_no}: flatten references/references/ link to " + f"references/: '{raw_target}'" + ) + + def _check_skill_conventions(path: Path, data: dict, errors: list[str]) -> None: meta = data.get("metadata", {}) spec = data.get("spec", {}) @@ -119,6 +211,12 @@ def _check_skill_conventions(path: Path, data: dict, errors: list[str]) -> None: errors.append(f"{rel}: spec.type must be skill") +def validate_pack_layout(pack: str, errors: list[str]) -> None: + pack_dir = _REPO_ROOT / pack + for skill in sorted(skills_on_disk(pack_dir)): + _check_skill_docs_layout(pack_dir / "skills" / skill, errors) + + def validate_pack(pack: str, owned_mcps: dict[str, Path], errors: list[str]) -> None: pack_dir = _REPO_ROOT / pack loc_path = pack_dir / "catalog-info.yaml" @@ -176,7 +274,10 @@ def validate_pack(pack: str, owned_mcps: dict[str, Path], errors: list[str]) -> pack_skill_mcp_union: set[str] = set() for skill in sorted(disk): - manifest = pack_dir / "skills" / skill / "catalog-info.yaml" + skill_dir = pack_dir / "skills" / skill + _check_skill_docs_layout(skill_dir, errors) + + manifest = skill_dir / "catalog-info.yaml" if not manifest.is_file(): errors.append(f"{pack}: missing {manifest.relative_to(_REPO_ROOT)}") continue @@ -267,14 +368,21 @@ def main() -> int: errors: list[str] = [] owned_mcps = load_owned_mcps() + registered: list[str] = [] if not _ROOT_CATALOG.is_file(): errors.append( f"missing root catalog Location: {_ROOT_CATALOG.relative_to(_REPO_ROOT)}" ) else: - for pack in registered_packs(): + registered = registered_packs() + for pack in registered: validate_pack(pack, owned_mcps, errors) + registered_set = set(registered) + for pack in all_packs_with_skills(): + if pack not in registered_set: + validate_pack_layout(pack, errors) + if errors: print("Compass manifest validation failed:", file=sys.stderr) for err in errors: diff --git a/scripts/validate_docs_tree_links.py b/scripts/validate_docs_tree_links.py index 9e21e2f1..7d6c3264 100644 --- a/scripts/validate_docs_tree_links.py +++ b/scripts/validate_docs_tree_links.py @@ -3,7 +3,7 @@ Validate markdown link integrity for runtime-adjacent docs trees. Scope: -- skills/*/docs/**/*.md +- skills/*/references/**/*.md - /README.md - /.catalog/*.md @@ -72,7 +72,7 @@ def resolve_packs(paths: Iterable[str]) -> set[Path]: def scan_targets(pack_root: Path) -> list[Path]: targets: list[Path] = [] - targets.extend(sorted((pack_root / "skills").glob("*/docs/**/*.md"))) + targets.extend(sorted((pack_root / "skills").glob("*/references/**/*.md"))) readme = pack_root / "README.md" if readme.exists(): targets.append(readme) @@ -85,7 +85,7 @@ def scan_targets(pack_root: Path) -> list[Path]: def validate_file(path: Path, pack_root: Path) -> list[str]: errs: list[str] = [] text = path.read_text(encoding="utf-8", errors="ignore") - is_skill_docs = "/skills/" in path.as_posix() and "/docs/" in path.as_posix() + is_skill_docs = "/skills/" in path.as_posix() and "/references/" in path.as_posix() is_pack_meta = (path == (pack_root / "README.md")) or (path.parent == (pack_root / ".catalog")) for line_no, line in enumerate(text.splitlines(), start=1): for m in MD_LINK_RE.finditer(line): @@ -98,7 +98,7 @@ def validate_file(path: Path, pack_root: Path) -> list[str]: # For pack README / catalog fragments, validate only pack-local docs references. if is_pack_meta: - if not (base.startswith("docs/") or base.startswith("skills/")): + if not (base.startswith("references/") or base.startswith("skills/")): continue link_path = (pack_root / base) else: diff --git a/scripts/validate_skill_doc_links.py b/scripts/validate_skill_doc_links.py index 774a6b47..78297cff 100644 --- a/scripts/validate_skill_doc_links.py +++ b/scripts/validate_skill_doc_links.py @@ -1,11 +1,11 @@ #!/usr/bin/env python3 """ -Validate skill markdown links to enforce skill-local docs convention. +Validate skill markdown links to enforce skill-local references convention. Rules: -- Forbid upward traversal into pack docs (../docs, ../../docs, etc). -- Internal docs links must use docs/... path from skill directory. -- Linked docs files must exist (symlinks allowed, dangling symlinks rejected). +- Forbid upward traversal into pack docs (../references, ../../references, etc). +- Internal docs links must use references/... path from skill directory. +- Linked reference files must exist (symlinks allowed, dangling symlinks rejected). - Resolved targets must stay within the pack root. """ @@ -69,6 +69,11 @@ def is_external_link(target: str) -> bool: ) +def _is_skill_local_references_link(target: str) -> bool: + normalized = target.replace("\\", "/") + return normalized.startswith("references/") or normalized.startswith("./references/") + + def validate_skill_file(skill_file: Path, result: ValidationResult) -> None: skill_dir = skill_file.parent pack_root = skill_file.parent.parent.parent.resolve() @@ -82,26 +87,27 @@ def validate_skill_file(skill_file: Path, result: ValidationResult) -> None: continue target = raw_target.split("#", 1)[0].strip() - if ".md" not in target or "docs/" not in target: + if ".md" not in target or "references/" not in target: continue result.checked_docs_links += 1 normalized = target.replace("\\", "/") - # Forbid upward traversal to docs. + # Forbid upward traversal to references. if normalized.startswith("../") or "/../" in normalized: result.errors.append( - f"{skill_file}:{line_no}: forbidden upward docs path '{raw_target}'" + f"{skill_file}:{line_no}: forbidden upward references path '{raw_target}'" ) - # Enforce skill-local docs path. - if not normalized.startswith("docs/"): + # Enforce skill-local references path (references/ or ./references/). + if not _is_skill_local_references_link(normalized): result.errors.append( - f"{skill_file}:{line_no}: docs link must be skill-local 'docs/...', got '{raw_target}'" + f"{skill_file}:{line_no}: references link must be skill-local " + f"'references/...' or './references/...', got '{raw_target}'" ) continue - link_path = skill_dir / normalized + link_path = (skill_dir / normalized).resolve() try: resolved = link_path.resolve(strict=True) except FileNotFoundError: From c871bf680efe7b7723492ca0b2032df0e7e39236 Mon Sep 17 00:00:00 2001 From: rhartuv Date: Tue, 8 Sep 2026 12:41:46 +0300 Subject: [PATCH 2/2] fix: update files that point at docs/ --- rh-automation/README.md | 13 +- .../.ai-index/cross-reference-graph.json | 64 ++++++ .../references/.ai-index/semantic-index.json | 101 +++++++++ .../.ai-index/task-to-docs-mapping.json | 73 +++++++ rh-automation/references/INDEX.md | 50 +++++ rh-automation/references/SOURCES.md | 200 ++++++++++++++++++ rh-sre/.catalog/documentation_section.md | 2 +- rh-sre/README.md | 6 +- .../.ai-index/cross-reference-graph.json | 42 ++-- .../references/.ai-index/semantic-index.json | 58 ++--- .../.ai-index/task-to-docs-mapping.json | 122 +++++------ rh-sre/references/INDEX.md | 113 +++++----- .../skills/vm-rebalance/REBALANCE_MANUAL.md | 10 +- scripts/validate_docs_tree_links.py | 77 +++++-- scripts/validate_skill_doc_links.py | 17 +- 15 files changed, 746 insertions(+), 202 deletions(-) create mode 100644 rh-automation/references/.ai-index/cross-reference-graph.json create mode 100644 rh-automation/references/.ai-index/semantic-index.json create mode 100644 rh-automation/references/.ai-index/task-to-docs-mapping.json create mode 100644 rh-automation/references/INDEX.md create mode 100644 rh-automation/references/SOURCES.md diff --git a/rh-automation/README.md b/rh-automation/README.md index 002a9114..e5be644f 100644 --- a/rh-automation/README.md +++ b/rh-automation/README.md @@ -94,7 +94,7 @@ export AAP_API_TOKEN="your-personal-access-token" | `job-troubleshooting.md` | Event parsing, host correlation, failure patterns | AAP 2.6 Troubleshooting Guide, Job Events | | `error-classification.md` | Error taxonomy, classification trees, resolution paths | AAP 2.6 Troubleshooting Guide, Ansible Module docs | -See [docs/INDEX.md](docs/INDEX.md) for the complete documentation map and [docs/SOURCES.md](docs/SOURCES.md) for all source attributions. +See [references/INDEX.md](references/INDEX.md) for the complete documentation map and [references/SOURCES.md](references/SOURCES.md) for all source attributions. ## Architecture @@ -113,13 +113,10 @@ rh-automation/ │ ├── host-fact-inspector/ # UC3: Host correlation │ ├── resolution-advisor/ # UC3: Resolution guidance │ └── execution-summary/ # Shared: Audit trail -└── docs/ - ├── aap/ - │ ├── governance-readiness.md # 7-domain assessment reference - │ ├── execution-governance.md # Execution governance reference - │ └── job-troubleshooting.md # Failure analysis reference - └── references/ - └── error-classification.md # Error taxonomy reference +└── references/ + ├── INDEX.md # Documentation map + ├── SOURCES.md # Red Hat source attributions + └── .ai-index/ # Semantic indexing ``` ## References diff --git a/rh-automation/references/.ai-index/cross-reference-graph.json b/rh-automation/references/.ai-index/cross-reference-graph.json new file mode 100644 index 00000000..7c27e6d9 --- /dev/null +++ b/rh-automation/references/.ai-index/cross-reference-graph.json @@ -0,0 +1,64 @@ +{ + "version": "2.0", + "last_updated": "2026-02-26", + "nodes": [ + { + "id": "governance-readiness", + "path": "skills/governance-readiness-assessor/references/aap/governance-readiness.md", + "title": "AAP Governance Readiness Assessment" + }, + { + "id": "execution-governance", + "path": "skills/execution-risk-analyzer/references/aap/execution-governance.md", + "title": "Execution Governance" + }, + { + "id": "job-troubleshooting", + "path": "skills/job-failure-analyzer/references/aap/job-troubleshooting.md", + "title": "Job Troubleshooting" + }, + { + "id": "error-classification", + "path": "skills/resolution-advisor/references/error-classification.md", + "title": "Error Classification Taxonomy" + } + ], + "edges": [ + { + "from": "governance-readiness", + "to": "execution-governance", + "relationship": "precedes", + "description": "After assessing readiness, use execution governance for governed execution" + }, + { + "from": "execution-governance", + "to": "job-troubleshooting", + "relationship": "follows_on_failure", + "description": "If execution fails, use troubleshooting for forensic analysis" + }, + { + "from": "job-troubleshooting", + "to": "error-classification", + "relationship": "references", + "description": "Troubleshooting uses error classification for systematic error typing" + }, + { + "from": "execution-governance", + "to": "governance-readiness", + "relationship": "optional_precondition", + "description": "First production execution may trigger readiness assessment" + }, + { + "from": "error-classification", + "to": "governance-readiness", + "relationship": "identifies_gaps", + "description": "Platform errors may indicate governance gaps in readiness domains" + }, + { + "from": "governance-readiness", + "to": "job-troubleshooting", + "relationship": "cross_reference", + "description": "Platform configuration issues discovered in assessment may explain job failures" + } + ] +} diff --git a/rh-automation/references/.ai-index/semantic-index.json b/rh-automation/references/.ai-index/semantic-index.json new file mode 100644 index 00000000..84078ee3 --- /dev/null +++ b/rh-automation/references/.ai-index/semantic-index.json @@ -0,0 +1,101 @@ +{ + "version": "2.0", + "last_updated": "2026-02-26", + "documents": [ + { + "path": "skills/governance-readiness-assessor/references/aap/governance-readiness.md", + "title": "AAP Governance Readiness Assessment", + "category": "aap", + "token_estimate": 3500, + "semantic_keywords": [ + "platform readiness assessment", + "governance audit", + "AAP best practices check", + "RBAC compliance", + "credential hygiene", + "workflow governance", + "notification coverage", + "execution environment review", + "workload isolation", + "audit trail verification", + "production readiness", + "cross-domain correlation", + "compound risk analysis", + "adaptive depth queries", + "prioritized remediation", + "scale calibration" + ], + "use_cases": ["governance_readiness_assessment", "platform_audit", "pre_execution_check", "compound_risk_analysis"], + "mcp_servers_used": ["job-management", "inventory-management", "configuration", "security-compliance", "system-monitoring", "user-management"], + "red_hat_sources": 8, + "skills_that_read": ["governance-readiness-assessor"] + }, + { + "path": "skills/execution-risk-analyzer/references/aap/execution-governance.md", + "title": "Execution Governance", + "category": "aap", + "token_estimate": 2500, + "semantic_keywords": [ + "execute on production", + "check mode dry run", + "inventory risk classification", + "secret scanning extra_vars", + "rollback failed job", + "phased rollout", + "job template launch", + "diff mode", + "execution safety", + "production governance", + "job history analysis", + "template launch configuration", + "notification bindings", + "workflow coverage check", + "module analysis", + "adaptive risk elevation" + ], + "use_cases": ["governed_execution", "risk_analysis", "check_mode_execution", "rollback", "pre_execution_context"], + "mcp_servers_used": ["job-management", "inventory-management"], + "red_hat_sources": 5, + "skills_that_read": ["execution-risk-analyzer", "governed-job-launcher"] + }, + { + "path": "skills/job-failure-analyzer/references/aap/job-troubleshooting.md", + "title": "Job Troubleshooting", + "category": "aap", + "token_estimate": 2000, + "semantic_keywords": [ + "job failed", + "why did the job fail", + "analyze failure", + "job events", + "host unreachable", + "module failure", + "error analysis", + "root cause", + "failure correlation" + ], + "use_cases": ["job_failure_analysis", "forensic_troubleshooting", "host_correlation"], + "mcp_servers_used": ["job-management", "inventory-management"], + "red_hat_sources": 3, + "skills_that_read": ["job-failure-analyzer", "host-fact-inspector"] + }, + { + "path": "skills/resolution-advisor/references/error-classification.md", + "title": "Error Classification Taxonomy", + "category": "references", + "token_estimate": 1500, + "semantic_keywords": [ + "error classification", + "platform vs code error", + "resolution path", + "error taxonomy", + "failure type determination", + "troubleshooting decision tree" + ], + "use_cases": ["error_classification", "resolution_path_determination"], + "mcp_servers_used": [], + "red_hat_sources": 3, + "skills_that_read": ["resolution-advisor"] + } + ] +} diff --git a/rh-automation/references/.ai-index/task-to-docs-mapping.json b/rh-automation/references/.ai-index/task-to-docs-mapping.json new file mode 100644 index 00000000..fb8b6c4f --- /dev/null +++ b/rh-automation/references/.ai-index/task-to-docs-mapping.json @@ -0,0 +1,73 @@ +{ + "version": "2.0", + "last_updated": "2026-02-26", + "workflows": { + "governance_assessment": { + "description": "Assess AAP platform governance readiness across 7 domains", + "trigger_phrases": [ + "assess governance readiness", + "is my AAP ready for production", + "audit platform configuration", + "check governance", + "what should I fix before executing jobs" + ], + "documents": [ + { + "path": "skills/governance-readiness-assessor/references/aap/governance-readiness.md", + "role": "primary", + "reason": "7-domain assessment framework with Red Hat citations" + } + ], + "agent": "governance-assessor", + "skills": ["aap-mcp-validator", "governance-readiness-assessor", "execution-summary"] + }, + "governed_execution": { + "description": "Execute with risk analysis, check mode, and governance controls", + "trigger_phrases": [ + "execute on production", + "push to prod", + "launch job template", + "execute security patch", + "release to production" + ], + "documents": [ + { + "path": "skills/execution-risk-analyzer/references/aap/execution-governance.md", + "role": "primary", + "reason": "Risk classification, check mode, rollback, phased rollout" + }, + { + "path": "skills/governance-readiness-assessor/references/aap/governance-readiness.md", + "role": "optional", + "reason": "Optional pre-execution readiness check" + } + ], + "agent": "governance-executor", + "skills": ["aap-mcp-validator", "execution-risk-analyzer", "governed-job-launcher", "execution-summary"] + }, + "forensic_troubleshooting": { + "description": "Analyze failed jobs with event extraction, host correlation, and resolution advisory", + "trigger_phrases": [ + "job failed", + "why did the execution fail", + "analyze the failure", + "what went wrong", + "root cause analysis" + ], + "documents": [ + { + "path": "skills/job-failure-analyzer/references/aap/job-troubleshooting.md", + "role": "primary", + "reason": "Event parsing, failure patterns, host correlation" + }, + { + "path": "skills/resolution-advisor/references/error-classification.md", + "role": "secondary", + "reason": "Error taxonomy and resolution path mapping" + } + ], + "agent": "forensic-troubleshooter", + "skills": ["aap-mcp-validator", "job-failure-analyzer", "host-fact-inspector", "resolution-advisor", "execution-summary"] + } + } +} diff --git a/rh-automation/references/INDEX.md b/rh-automation/references/INDEX.md new file mode 100644 index 00000000..d973f744 --- /dev/null +++ b/rh-automation/references/INDEX.md @@ -0,0 +1,50 @@ +# Documentation Index + +Navigation guide for the rh-automation knowledge base. Runtime copies live under each skill's `references/` directory (canonical files plus shared-pool symlinks). This pack index maps those files for repository navigation. + +## How Documents Are Used + +``` +User Request → Agent → Skill reads document → Skill queries MCP tools → Skill interprets with document knowledge → Output with Red Hat citations +``` + +Paths in `.ai-index/` are pack-relative (from `rh-automation/`). + +## Document Map + +### AAP Category + +Platform governance, execution, and troubleshooting references for Ansible Automation Platform. + +| Document | Purpose | Skills That Read It | Red Hat Sources | +|----------|---------|-------------------|----------------| +| [governance-readiness.md](../skills/governance-readiness-assessor/references/aap/governance-readiness.md) | 7-domain platform governance assessment | `governance-readiness-assessor` | 8 sources (Security Best Practices, Workflows, Notifications, RBAC, Instance Groups, Activity Stream, EE Guide, Hardening Guide) | +| [execution-governance.md](../skills/execution-risk-analyzer/references/aap/execution-governance.md) | Risk classification, check mode, rollback, phased rollout | `execution-risk-analyzer`, `governed-job-launcher` | 5 sources (Job Templates, Security Best Practices, Workflows, Check Mode, Controller Best Practices) | +| [job-troubleshooting.md](../skills/job-failure-analyzer/references/aap/job-troubleshooting.md) | Event parsing, host correlation, failure patterns | `job-failure-analyzer`, `host-fact-inspector` | 3 sources (Troubleshooting Guide, Job Events, Administration Guide) | + +### Error classification + +Cross-cutting reference material used across multiple use cases. + +| Document | Purpose | Skills That Read It | Red Hat Sources | +|----------|---------|-------------------|----------------| +| [error-classification.md](../skills/resolution-advisor/references/error-classification.md) | Error taxonomy, classification trees, resolution paths | `resolution-advisor` | 3 sources (Troubleshooting Guide, Ansible Module docs, Administration Guide) | + +## Task-to-Document Mapping + +| User Task | Primary Document | Secondary Document | +|-----------|-----------------|-------------------| +| "Assess governance readiness" | governance-readiness.md | -- | +| "Execute on production" | execution-governance.md | governance-readiness.md (optional pre-check) | +| "Analyze failed job" | job-troubleshooting.md | error-classification.md | +| "How to fix this error?" | error-classification.md | job-troubleshooting.md | + +## Semantic Indexing + +The `.ai-index/` directory contains pre-computed indexes for efficient document discovery: + +- `semantic-index.json` -- Document metadata with semantic keywords +- `task-to-docs-mapping.json` -- Pre-computed document sets for common workflows +- `cross-reference-graph.json` -- Document relationship graph + +See [SOURCES.md](SOURCES.md) for official Red Hat source attribution. diff --git a/rh-automation/references/SOURCES.md b/rh-automation/references/SOURCES.md new file mode 100644 index 00000000..0e064fcc --- /dev/null +++ b/rh-automation/references/SOURCES.md @@ -0,0 +1,200 @@ +# Official Red Hat Sources + +All documentation in this collection is derived from or references official Red Hat and Ansible documentation. Content is used in accordance with Red Hat's documentation license (CC BY-SA 4.0). + +## Primary Sources + +### 1. Red Hat AAP 2.5 - Configuring Automation Execution: Security Best Practices (Ch. 15) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/configuring_automation_execution/controller-security-best-practices + +**Sections Used**: +- Sec. 15.1.2: Minimize administrative accounts +- Sec. 15.1.4: Remove user access to credentials +- Sec. 15.1.5: Enforce separation of duties +- Sec. 15.2.1: Use teams for role-based access +- Sec. 15.2.2: External authentication (LDAP, SAML, OAuth) + +**Referenced By**: governance-readiness.md (Domains 3, 4, Bonus), execution-governance.md (secret scanning) + +**Date Accessed**: 2026-02-20 + +--- + +### 2. Red Hat AAP 2.5 - Automation Controller User Guide: Workflows (Ch. 9) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/using_automation_execution/controller-workflows + +**Sections Used**: +- Workflow job templates +- Sec. 9.4: Workflow RBAC +- Approval nodes + +**Referenced By**: governance-readiness.md (Domain 1), execution-governance.md + +**Date Accessed**: 2026-02-20 + +--- + +### 3. Red Hat AAP 2.5 - Automation Controller User Guide: Notifications (Ch. 25) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/using_automation_execution/controller-notifications + +**Sections Used**: +- Notification templates +- Sec. 25.1: Notification inheritance hierarchy +- Notification types (Email, Slack, Webhook, PagerDuty) + +**Referenced By**: governance-readiness.md (Domain 2) + +**Date Accessed**: 2026-02-20 + +--- + +### 4. Red Hat AAP 2.5 - Automation Controller User Guide: RBAC (Ch. 4) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/access_management_and_authentication/gw-managing-access + +**Sections Used**: +- Role-based access controls +- Role definitions +- Team assignments + +**Referenced By**: governance-readiness.md (Domain 3) + +**Date Accessed**: 2026-02-20 + +--- + +### 5. Red Hat AAP 2.5 - Configuring Automation Execution: Instance Groups (Ch. 17) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/controller-instance-groups + +**Sections Used**: +- Instance groups for workload isolation +- max_forks configuration +- Policy settings + +**Referenced By**: governance-readiness.md (Domain 6) + +**Date Accessed**: 2026-02-20 + +--- + +### 6. Red Hat AAP 2.5 - Automation Controller User Guide: Activity Stream + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/using_automation_execution/assembly-controller-activity-stream + +**Sections Used**: +- Activity stream audit logging +- Event filtering + +**Referenced By**: governance-readiness.md (Domain 7) + +**Date Accessed**: 2026-02-20 + +--- + +### 7. Red Hat AAP 2.6 - Creating and Using Execution Environments + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html-single/creating_and_using_execution_environments/index + +**Sections Used**: +- Custom EE creation +- Dependency pinning +- ansible-builder + +**Referenced By**: governance-readiness.md (Domain 5), error-classification.md (EE issues) + +**Date Accessed**: 2026-02-20 + +--- + +### 8. Red Hat AAP 2.6 - Hardening Guide + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/hardening_and_compliance/index + +**Sections Used**: +- Platform hardening +- Credential rotation +- Audit requirements + +**Referenced By**: governance-readiness.md + +**Date Accessed**: 2026-02-20 + +--- + +### 9. Red Hat AAP 2.6 - Troubleshooting Guide: Troubleshoot Jobs + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.6/html/troubleshooting_ansible_automation_platform/troubleshoot-jobs + +**Sections Used**: +- Job failure analysis +- Common job errors +- Event interpretation + +**Referenced By**: job-troubleshooting.md, error-classification.md + +**Date Accessed**: 2026-02-20 + +--- + +### 10. Red Hat AAP 2.5 - Automation Controller User Guide: Job Templates (Ch. 9) + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/automation_controller_user_guide/controller-job-templates + +**Sections Used**: +- Job template configuration +- job_type (run/check) +- diff_mode, limit, extra_vars +- Job slicing +- Relaunch + +**Referenced By**: execution-governance.md, job-troubleshooting.md + +**Date Accessed**: 2026-02-20 + +--- + +### 11. Red Hat AAP 2.5 - Configuring Automation Execution: Controller Best Practices + +**URL**: https://docs.redhat.com/en/documentation/red_hat_ansible_automation_platform/2.5/html/configuring_automation_execution/controller-tips-and-tricks + +**Sections Used**: +- Inventory management +- Environment separation + +**Referenced By**: execution-governance.md (risk classification) + +**Date Accessed**: 2026-02-20 + +--- + +### 12. Ansible Playbook Guide: Check Mode + +**URL**: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_checkmode.html + +**Sections Used**: +- Check mode behavior +- diff mode +- Limitations (shell/command modules) + +**Referenced By**: execution-governance.md (check mode section) + +**Date Accessed**: 2026-02-20 + +--- + +### 13. Ansible Built-in Module Documentation + +**URL**: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html + +**Sections Used**: +- Module return values +- Error conditions +- Check mode behavior per module + +**Referenced By**: error-classification.md + +**Date Accessed**: 2026-02-20 diff --git a/rh-sre/.catalog/documentation_section.md b/rh-sre/.catalog/documentation_section.md index d7099c7a..837bbb0e 100644 --- a/rh-sre/.catalog/documentation_section.md +++ b/rh-sre/.catalog/documentation_section.md @@ -12,7 +12,7 @@ ### In-repository documentation -This pack ships an AI-oriented knowledge base under **`docs/`**. Start at **[docs/INDEX.md](docs/INDEX.md)** and use **`docs/.ai-index/`** (semantic index, task mapping) for token-efficient discovery. +This pack ships an AI-oriented knowledge base under **`references/`** (index and source attribution) and **`skills/*/references/`** (runtime skill docs). Start at **[references/INDEX.md](references/INDEX.md)** and use **`references/.ai-index/`** (semantic index, task mapping) for token-efficient discovery. ### Configuration and architecture diff --git a/rh-sre/README.md b/rh-sre/README.md index f59754da..2699bf16 100644 --- a/rh-sre/README.md +++ b/rh-sre/README.md @@ -384,7 +384,7 @@ The remediation skill orchestrates 6 specialized skills to provide complete CVE ## Documentation -The rh-sre pack includes AI-optimized documentation in the `docs/` directory demonstrating advanced documentation patterns: +The rh-sre pack includes AI-optimized documentation under `references/` (pack index) and `skills/*/references/` (runtime skill docs): ### Semantic Indexing System @@ -400,7 +400,7 @@ The rh-sre pack includes AI-optimized documentation in the `docs/` directory dem - **Lightspeed**: Red Hat Lightspeed platform integration - **References**: CVSS scoring, security standards -See [docs/INDEX.md](docs/INDEX.md) for the complete documentation map. +See [references/INDEX.md](references/INDEX.md) for the complete documentation map. ## MCP Server Integrations @@ -606,7 +606,7 @@ rh-sre/ │ ├── job-template-creator/SKILL.md │ ├── job-template-remediation-validator/SKILL.md │ └── execution-summary/SKILL.md -└── docs/ # AI-optimized documentation +└── references/ # Pack documentation map and attributions ├── INDEX.md ├── SOURCES.md └── .ai-index/ # Semantic indexing diff --git a/rh-sre/references/.ai-index/cross-reference-graph.json b/rh-sre/references/.ai-index/cross-reference-graph.json index 20837038..9f90f7a1 100644 --- a/rh-sre/references/.ai-index/cross-reference-graph.json +++ b/rh-sre/references/.ai-index/cross-reference-graph.json @@ -3,16 +3,16 @@ "generated": "2026-01-20T00:00:00Z", "description": "Document relationship graph for intelligent follow-up doc discovery. Enables 'if you read X, you probably also need Y' inference.", "graph": { - "ansible/cve-remediation-templates.md": { + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": { "complements": [ { - "doc": "rhel/package-management.md", + "doc": "skills/playbook-generator/references/rhel/package-management.md", "reason": "Templates reference DNF/YUM patterns and reboot detection methods", "confidence": 0.95, "use_when": "Any package update template (1, 4, 6)" }, { - "doc": "ansible/error-handling.md", + "doc": "skills/mcp-aap-validator/references/ansible/error-handling.md", "reason": "Templates should include error handling and rollback strategies", "confidence": 0.85, "use_when": "Batch remediation or complex workflows" @@ -20,7 +20,7 @@ ], "prerequisites": [ { - "doc": "ansible/README.md", + "doc": "skills/playbook-generator/references/ansible/README.md", "reason": "Overview of Ansible documentation structure", "confidence": 0.50, "use_when": "First-time users or orientation needed" @@ -28,7 +28,7 @@ ], "specializations": [ { - "doc": "rhel/selinux-context.md", + "doc": "skills/mcp-aap-validator/references/rhel/selinux-context.md", "condition": "if selinux_cve", "reason": "SELinux CVEs need context restoration patterns", "confidence": 0.90, @@ -36,22 +36,22 @@ } ] }, - "rhel/package-management.md": { + "skills/playbook-generator/references/rhel/package-management.md": { "complements": [ { - "doc": "ansible/cve-remediation-templates.md", + "doc": "skills/playbook-generator/references/ansible/cve-remediation-templates.md", "reason": "Playbook templates implement these package management patterns", "confidence": 0.95, "use_when": "Creating or modifying remediation playbooks" }, { - "doc": "rhel/version-compatibility.md", + "doc": "skills/mcp-aap-validator/references/rhel/version-compatibility.md", "reason": "Multi-version environments need compatibility guidance", "confidence": 0.75, "use_when": "Managing RHEL 7, 8, and 9 simultaneously" }, { - "doc": "rhel/systemd-services.md", + "doc": "skills/mcp-aap-validator/references/rhel/systemd-services.md", "reason": "Package updates often require service restarts", "confidence": 0.70, "use_when": "Service restart needed after package update" @@ -60,48 +60,48 @@ "prerequisites": [], "specializations": [] }, - "ansible/README.md": { + "skills/playbook-generator/references/ansible/README.md": { "leads_to": [ { - "doc": "ansible/cve-remediation-templates.md", + "doc": "skills/playbook-generator/references/ansible/cve-remediation-templates.md", "reason": "Primary Ansible documentation for CVE remediation", "confidence": 0.95, "use_when": "User navigating from overview to detailed templates" }, { - "doc": "ansible/error-handling.md", + "doc": "skills/mcp-aap-validator/references/ansible/error-handling.md", "reason": "Error handling patterns for production playbooks", "confidence": 0.70, "use_when": "Need advanced error handling beyond templates" } ] }, - "rhel/README.md": { + "skills/playbook-generator/references/rhel/README.md": { "leads_to": [ { - "doc": "rhel/package-management.md", + "doc": "skills/playbook-generator/references/rhel/package-management.md", "reason": "Primary RHEL documentation for CVE remediation", "confidence": 0.95, "use_when": "User navigating from overview to package management" }, { - "doc": "rhel/version-compatibility.md", + "doc": "skills/mcp-aap-validator/references/rhel/version-compatibility.md", "reason": "RHEL version differences and compatibility", "confidence": 0.75, "use_when": "Multi-version environment" } ] }, - "insights/vulnerability-logic.md": { + "skills/cve-validation/references/insights/vulnerability-logic.md": { "complements": [ { - "doc": "references/cvss-scoring.md", + "doc": "skills/cve-validation/references/cvss-scoring.md", "reason": "CVSS scoring complements Red Hat vulnerability assessment", "confidence": 0.90, "use_when": "Performing risk assessment" }, { - "doc": "ansible/cve-remediation-templates.md", + "doc": "skills/playbook-generator/references/ansible/cve-remediation-templates.md", "reason": "After assessment, create remediation playbook", "confidence": 0.85, "use_when": "Proceeding from assessment to remediation" @@ -110,16 +110,16 @@ "prerequisites": [], "specializations": [] }, - "references/cvss-scoring.md": { + "skills/cve-validation/references/cvss-scoring.md": { "complements": [ { - "doc": "insights/vulnerability-logic.md", + "doc": "skills/cve-validation/references/insights/vulnerability-logic.md", "reason": "Red Hat-specific risk assessment methodology", "confidence": 0.90, "use_when": "Understanding Red Hat severity ratings" }, { - "doc": "references/compliance-frameworks.md", + "doc": "skills/mcp-aap-validator/references/compliance-frameworks.md", "reason": "Compliance requirements often tied to CVSS scores", "confidence": 0.70, "use_when": "Compliance-driven remediation" diff --git a/rh-sre/references/.ai-index/semantic-index.json b/rh-sre/references/.ai-index/semantic-index.json index 9cfee28f..593c466c 100644 --- a/rh-sre/references/.ai-index/semantic-index.json +++ b/rh-sre/references/.ai-index/semantic-index.json @@ -3,7 +3,7 @@ "generated": "2026-01-20T00:00:00Z", "documents": [ { - "path": "ansible/cve-remediation-templates.md", + "path": "skills/playbook-generator/references/ansible/cve-remediation-templates.md", "title": "CVE Remediation Playbook Templates", "category": "ansible", "tags": ["cve", "remediation", "playbooks", "templates", "ansible"], @@ -34,13 +34,13 @@ "applies_to_systems": ["bare_metal", "vm", "kubernetes", "openshift"], "content_summary": "6 production-ready Ansible playbook templates for CVE remediation with error handling, rollback, and audit logging. Includes package updates, kernel updates, service restarts, config changes, SELinux fixes, and batch operations.", "related_docs": [ - "rhel/package-management.md", - "ansible/error-handling.md" + "skills/playbook-generator/references/rhel/package-management.md", + "skills/mcp-aap-validator/references/ansible/error-handling.md" ], "token_estimate": 2500 }, { - "path": "rhel/package-management.md", + "path": "skills/playbook-generator/references/rhel/package-management.md", "title": "RHEL Package Management for CVE Remediation", "category": "rhel", "tags": ["dnf", "yum", "package-management", "rhel", "updates", "reboot-detection"], @@ -66,14 +66,14 @@ "applies_to_systems": ["bare_metal", "vm", "kubernetes", "openshift"], "content_summary": "Comprehensive RHEL 7/8/9 package management patterns including DNF/YUM workflows, reboot detection with needs-restarting, service restart logic, repository management, and subscription manager integration.", "related_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/version-compatibility.md", - "rhel/systemd-services.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/mcp-aap-validator/references/rhel/version-compatibility.md", + "skills/mcp-aap-validator/references/rhel/systemd-services.md" ], "token_estimate": 1600 }, { - "path": "insights/vulnerability-logic.md", + "path": "skills/cve-validation/references/insights/vulnerability-logic.md", "title": "Red Hat Lightspeed Vulnerability Assessment Logic", "category": "insights", "tags": ["insights", "vulnerability", "cve", "risk-assessment", "remediation"], @@ -103,14 +103,14 @@ "applies_to_systems": ["bare_metal", "vm", "kubernetes", "openshift"], "content_summary": "Explains how Red Hat Lightspeed assesses CVE vulnerabilities using vulnerable vs affected classification, Security Rules designation, Red Hat severity ratings, and remediation prioritization methodology. Includes priority decision matrix and integration guidance.", "related_docs": [ - "references/cvss-scoring.md", - "ansible/cve-remediation-templates.md", - "references/compliance-frameworks.md" + "skills/cve-validation/references/cvss-scoring.md", + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/mcp-aap-validator/references/compliance-frameworks.md" ], "token_estimate": 900 }, { - "path": "references/cvss-scoring.md", + "path": "skills/cve-validation/references/cvss-scoring.md", "title": "CVSS Scoring and Red Hat Severity Mappings", "category": "references", "tags": ["cvss", "severity", "scoring", "risk-assessment", "priority"], @@ -142,9 +142,9 @@ "applies_to_systems": ["bare_metal", "vm", "kubernetes", "openshift"], "content_summary": "CVSS v3.1 interpretation guide with all 8 metrics explained, Red Hat severity mappings, priority decision matrix, real-world CVE examples, and compliance framework requirements (PCI-DSS, SOC 2, NIST).", "related_docs": [ - "insights/vulnerability-logic.md", - "references/compliance-frameworks.md", - "ansible/cve-remediation-templates.md" + "skills/cve-validation/references/insights/vulnerability-logic.md", + "skills/mcp-aap-validator/references/compliance-frameworks.md", + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "token_estimate": 1000 } @@ -152,8 +152,8 @@ "task_mappings": { "package_update_rhel": { "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": ["templates", "package-mgmt"], @@ -162,10 +162,10 @@ }, "service_restart_cve": { "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "rhel/package-management.md" + "skills/playbook-generator/references/rhel/package-management.md" ], "workflow_order": ["templates", "package-mgmt"], "estimated_tokens": 4100, @@ -173,10 +173,10 @@ }, "selinux_remediation": { "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "rhel/selinux-context.md" + "skills/mcp-aap-validator/references/rhel/selinux-context.md" ], "workflow_order": ["templates", "selinux-context"], "estimated_tokens": 2500, @@ -184,12 +184,12 @@ }, "batch_remediation": { "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "ansible/error-handling.md", - "rhel/version-compatibility.md", - "rhel/package-management.md" + "skills/mcp-aap-validator/references/ansible/error-handling.md", + "skills/mcp-aap-validator/references/rhel/version-compatibility.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "workflow_order": ["templates", "package-mgmt", "error-handling"], "estimated_tokens": 4100, @@ -197,11 +197,11 @@ }, "risk_assessment": { "required_docs": [ - "insights/vulnerability-logic.md", - "references/cvss-scoring.md" + "skills/cve-validation/references/insights/vulnerability-logic.md", + "skills/cve-validation/references/cvss-scoring.md" ], "optional_docs": [ - "references/compliance-frameworks.md" + "skills/mcp-aap-validator/references/compliance-frameworks.md" ], "workflow_order": ["vulnerability-logic", "cvss-scoring"], "estimated_tokens": 1900, @@ -292,6 +292,6 @@ "for_agents": "Read this semantic index first (~200 tokens) to intelligently discover relevant documentation. Use task_mappings for common workflows or semantic_keywords for custom queries. Follow workflow_order for optimal context loading.", "query_based_discovery": "Match user query terms against semantic_keywords across all documents. Filter by rhel_versions and applies_to_systems based on context. Use inference_hints to detect CVE type and system type automatically.", "token_optimization": "Load only required_docs first. Add optional_docs only if needed based on task complexity. Check estimated_tokens to manage context budget.", - "maintenance": "Regenerate this index when docs are added/updated using docs/.ai-index/generate-index.py. Version is semantic (MAJOR.MINOR for breaking changes)." + "maintenance": "Regenerate this index when docs are added/updated using references/.ai-index/generate-index.py. Version is semantic (MAJOR.MINOR for breaking changes)." } } diff --git a/rh-sre/references/.ai-index/task-to-docs-mapping.json b/rh-sre/references/.ai-index/task-to-docs-mapping.json index 19eff879..77e6b601 100644 --- a/rh-sre/references/.ai-index/task-to-docs-mapping.json +++ b/rh-sre/references/.ai-index/task-to-docs-mapping.json @@ -6,18 +6,18 @@ "kernel_cve_bare_metal": { "description": "Kernel CVE on bare metal or VM RHEL systems", "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 4: Kernel Update with Reboot", - "rhel/package-management.md": "Pattern 3: Kernel Package Updates, Reboot Detection Patterns" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 4: Kernel Update with Reboot", + "skills/playbook-generator/references/rhel/package-management.md": "Pattern 3: Kernel Package Updates, Reboot Detection Patterns" }, "prerequisites": [ "System backup created", @@ -27,18 +27,18 @@ "package_update_rhel": { "description": "Standard package update CVE on RHEL systems (non-Kubernetes)", "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 1: Package Update", - "rhel/package-management.md": "Pattern 1: Single Package Update, Pattern 2: Multiple Related Packages" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 1: Package Update", + "skills/playbook-generator/references/rhel/package-management.md": "Pattern 1: Single Package Update, Pattern 2: Multiple Related Packages" }, "prerequisites": [ "RHEL subscription active", @@ -48,19 +48,19 @@ "service_restart_cve": { "description": "CVE requiring service configuration changes and restart", "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "rhel/package-management.md" + "skills/playbook-generator/references/rhel/package-management.md" ], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 2: Service Restart", - "rhel/package-management.md": "Service Restart After Package Updates" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 2: Service Restart", + "skills/playbook-generator/references/rhel/package-management.md": "Service Restart After Package Updates" }, "prerequisites": [ "Service configuration backup", @@ -70,17 +70,17 @@ "config_file_cve": { "description": "CVE requiring system configuration file updates", "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "rhel/package-management.md" + "skills/playbook-generator/references/rhel/package-management.md" ], "workflow_order": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "estimated_tokens": 2500, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 3: Configuration File Update" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 3: Configuration File Update" }, "prerequisites": [ "Configuration backup created", @@ -90,18 +90,18 @@ "selinux_remediation": { "description": "CVE affecting SELinux file contexts or policies", "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "rhel/selinux-context.md" + "skills/mcp-aap-validator/references/rhel/selinux-context.md" ], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/selinux-context.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/mcp-aap-validator/references/rhel/selinux-context.md" ], "estimated_tokens": 2500, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 5: SELinux Context Update" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 5: SELinux Context Update" }, "prerequisites": [ "SELinux enabled and enforcing", @@ -111,22 +111,22 @@ "batch_remediation": { "description": "Multiple CVEs across fleet of RHEL systems", "required_docs": [ - "ansible/cve-remediation-templates.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md" ], "optional_docs": [ - "ansible/error-handling.md", - "rhel/version-compatibility.md", - "rhel/package-management.md" + "skills/mcp-aap-validator/references/ansible/error-handling.md", + "skills/mcp-aap-validator/references/rhel/version-compatibility.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md", - "ansible/error-handling.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md", + "skills/mcp-aap-validator/references/ansible/error-handling.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 6: Batch Remediation", - "rhel/package-management.md": "Pattern 2: Multiple Related Packages" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 6: Batch Remediation", + "skills/playbook-generator/references/rhel/package-management.md": "Pattern 2: Multiple Related Packages" }, "prerequisites": [ "Inventory grouped by environment", @@ -137,20 +137,20 @@ "risk_assessment": { "description": "Analyze CVE impact without creating remediation", "required_docs": [ - "insights/vulnerability-logic.md", - "references/cvss-scoring.md" + "skills/cve-validation/references/insights/vulnerability-logic.md", + "skills/cve-validation/references/cvss-scoring.md" ], "optional_docs": [ - "references/compliance-frameworks.md" + "skills/mcp-aap-validator/references/compliance-frameworks.md" ], "workflow_order": [ - "insights/vulnerability-logic.md", - "references/cvss-scoring.md" + "skills/cve-validation/references/insights/vulnerability-logic.md", + "skills/cve-validation/references/cvss-scoring.md" ], "estimated_tokens": 1000, "critical_sections": { - "insights/vulnerability-logic.md": "CVE Risk Assessment Methodology", - "references/cvss-scoring.md": "Red Hat Severity Mappings" + "skills/cve-validation/references/insights/vulnerability-logic.md": "CVE Risk Assessment Methodology", + "skills/cve-validation/references/cvss-scoring.md": "Red Hat Severity Mappings" }, "prerequisites": [ "CVE ID known", @@ -160,18 +160,18 @@ "httpd_cve": { "description": "Apache httpd package CVE remediation", "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 1: Package Update (httpd example)", - "rhel/package-management.md": "Pattern 2: Multiple Related Packages (httpd + httpd-tools)" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 1: Package Update (httpd example)", + "skills/playbook-generator/references/rhel/package-management.md": "Pattern 2: Multiple Related Packages (httpd + httpd-tools)" }, "prerequisites": [ "httpd service can be restarted", @@ -181,18 +181,18 @@ "openssl_cve": { "description": "OpenSSL library CVE requiring service restarts", "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 1: Package Update (service restart patterns)", - "rhel/package-management.md": "Pattern 2: Multiple Related Packages (openssl + openssl-libs), Service Restart After Package Updates" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 1: Package Update (service restart patterns)", + "skills/playbook-generator/references/rhel/package-management.md": "Pattern 2: Multiple Related Packages (openssl + openssl-libs), Service Restart After Package Updates" }, "prerequisites": [ "All services using openssl identified", @@ -202,18 +202,18 @@ "glibc_cve": { "description": "glibc CVE requiring reboot", "required_docs": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "optional_docs": [], "workflow_order": [ - "ansible/cve-remediation-templates.md", - "rhel/package-management.md" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md", + "skills/playbook-generator/references/rhel/package-management.md" ], "estimated_tokens": 4100, "critical_sections": { - "ansible/cve-remediation-templates.md": "Template 1: Package Update (reboot handling)", - "rhel/package-management.md": "Reboot Detection Patterns (needs-restarting)" + "skills/playbook-generator/references/ansible/cve-remediation-templates.md": "Template 1: Package Update (reboot handling)", + "skills/playbook-generator/references/rhel/package-management.md": "Reboot Detection Patterns (needs-restarting)" }, "prerequisites": [ "Reboot can be scheduled", diff --git a/rh-sre/references/INDEX.md b/rh-sre/references/INDEX.md index 4fa6725f..c9dd086c 100644 --- a/rh-sre/references/INDEX.md +++ b/rh-sre/references/INDEX.md @@ -11,36 +11,36 @@ last_updated: 2026-02-24 # Red Hat Remediation Agent - Documentation Index -This knowledge base provides comprehensive Red Hat-specific patterns for CVE remediation on Kubernetes-managed RHEL systems. +This knowledge base provides comprehensive Red Hat-specific patterns for CVE remediation on Kubernetes-managed RHEL systems. Canonical runtime documents live under `skills//references/`; this pack-level index is for navigation and source attribution. ## Quick Navigation ### Priority P0 (Core Documentation) -- **[CVE Remediation Playbook Templates](ansible/cve-remediation-templates.md)** ⭐ HIGHEST VALUE +- **[CVE Remediation Playbook Templates](../skills/playbook-generator/references/ansible/cve-remediation-templates.md)** ⭐ HIGHEST VALUE - 6 production-ready Ansible playbook templates - Package updates, kernel updates, service restarts, SELinux, batch remediation -- **[RHEL Package Management](rhel/package-management.md)** +- **[RHEL Package Management](../skills/playbook-generator/references/rhel/package-management.md)** - DNF/YUM workflows for RHEL 7/8/9 - Systemd service management - Reboot detection and handling ### Priority P1 (Extended Documentation) -- **[Red Hat Lightspeed Vulnerability Logic](insights/vulnerability-logic.md)** ✅ +- **[Red Hat Lightspeed Vulnerability Logic](../skills/cve-validation/references/insights/vulnerability-logic.md)** ✅ - CVE risk assessment methodology - CVSS score interpretation - System inventory correlation -- **[CVSS Scoring Reference](references/cvss-scoring.md)** ✅ +- **[CVSS Scoring Reference](../skills/cve-validation/references/cvss-scoring.md)** ✅ - CVSS v3.1 metrics breakdown - Red Hat severity mappings (Critical/Important/Moderate/Low) - Priority decision matrix -- **[Lightspeed MCP Parameters](references/lightspeed-mcp-parameters.md)** ✅ +- **[Lightspeed MCP Parameters](../skills/cve-impact/references/lightspeed-mcp-parameters.md)** ✅ - Correct parameter names for Lightspeed MCP tools (e.g. `per_page` not `page_size` for list_hosts) - Consult before calling inventory__list_hosts to avoid validation errors -- **[Lightspeed MCP Tool Failures](references/lightspeed-mcp-tool-failures.md)** ✅ +- **[Lightspeed MCP Tool Failures](../skills/cve-impact/references/lightspeed-mcp-tool-failures.md)** ✅ - Generic pattern for backend errors (e.g. explain_cves `'dnf_modules'`) — user-friendly message, workarounds, no raw error exposure - **RHEL Version Compatibility** (planned) @@ -102,47 +102,46 @@ This knowledge base provides comprehensive Red Hat-specific patterns for CVE rem ## Documentation Structure ``` -docs/ -├── INDEX.md (this file) ✅ -├── SOURCES.md (official Red Hat source attribution) ✅ -├── rhel/ # RHEL-specific patterns -│ ├── README.md ✅ -│ ├── package-management.md (P0) ✅ -│ ├── selinux-context.md (P1 - planned) -│ ├── systemd-services.md (P2 - planned) -│ ├── version-compatibility.md (P1 - planned) -│ └── security-hardening-rhel9.md (P1 - planned) -├── ansible/ # Ansible playbook patterns -│ ├── README.md ✅ -│ ├── cve-remediation-templates.md (P0) ⭐ ✅ -│ ├── playbook-patterns.md (P2 - planned) -│ ├── error-handling.md (P1 - planned) -│ ├── idempotency.md (P2 - planned) -│ └── aap-integration.md (P2 - planned) -├── insights/ # Red Hat Lightspeed patterns -│ ├── README.md ✅ -│ ├── vulnerability-logic.md (P1) ✅ -│ ├── remediation-workflow.md (P2 - planned) -│ └── system-inventory.md (P2 - planned) -├── references/ # Reference documentation -│ ├── README.md ✅ -│ ├── cvss-scoring.md (P1) ✅ -│ ├── compliance-frameworks.md (P2 - planned) -│ └── glossary.md (P2 - planned) -└── .ai-index/ # AI inference optimization - ├── semantic-index.json ✅ - ├── task-to-docs-mapping.json ✅ - ├── cross-reference-graph.json ✅ - └── generate-index.py (planned) +rh-sre/ +├── references/ # Pack navigation and source attribution (this tree) +│ ├── INDEX.md (this file) ✅ +│ ├── SOURCES.md ✅ +│ └── .ai-index/ # AI inference optimization +│ ├── semantic-index.json ✅ +│ ├── task-to-docs-mapping.json ✅ +│ ├── cross-reference-graph.json ✅ +│ └── generate-index.py (planned) +└── skills/ # Canonical runtime docs (skill-local references/) + ├── playbook-generator/references/ + │ ├── ansible/cve-remediation-templates.md (P0) ⭐ ✅ + │ ├── ansible/README.md ✅ + │ ├── rhel/package-management.md (P0) ✅ + │ └── rhel/README.md ✅ + ├── cve-validation/references/ + │ ├── insights/vulnerability-logic.md (P1) ✅ + │ └── cvss-scoring.md (P1) ✅ + ├── cve-impact/references/ + │ ├── lightspeed-mcp-parameters.md ✅ + │ └── lightspeed-mcp-tool-failures.md ✅ + └── mcp-aap-validator/references/ + ├── ansible/error-handling.md + ├── rhel/selinux-context.md + ├── rhel/systemd-services.md + ├── rhel/version-compatibility.md + └── compliance-frameworks.md ``` +Shared copies in other skills are symlinks to these canonical files. Do **not** nest `references/references/`. + ## How to Use This Documentation (For AI Agents) ### 1. Intelligent Document Discovery **Always start by reading the semantic index**: ``` -Read: docs/.ai-index/semantic-index.json (~200 tokens) +Read: references/.ai-index/semantic-index.json (~200 tokens) + +Index `path` values are pack-relative (from `rh-sre/`). ``` The semantic index enables: @@ -158,8 +157,8 @@ The semantic index enables: 1. Read semantic-index.json 2. Detect: CVE type = "kernel" (requires reboot) 3. Load from task_mappings["kernel_cve"]: - - ansible/cve-remediation-templates.md (Template 4: Kernel Update) - - rhel/package-management.md (DNF/YUM workflows) + - skills/playbook-generator/references/ansible/cve-remediation-templates.md (Template 4: Kernel Update) + - skills/playbook-generator/references/rhel/package-management.md (DNF/YUM workflows) 4. Generate playbook using patterns from loaded docs ``` @@ -176,10 +175,10 @@ The semantic index enables: Use the cross-reference graph to find related documentation: ``` -If reading: ansible/cve-remediation-templates.md +If reading: skills/playbook-generator/references/ansible/cve-remediation-templates.md Also consider: - - rhel/package-management.md (complements: DNF patterns) ✅ - - insights/vulnerability-logic.md (prerequisite: for risk assessment) ✅ + - skills/playbook-generator/references/rhel/package-management.md (complements: DNF patterns) ✅ + - skills/cve-validation/references/insights/vulnerability-logic.md (prerequisite: for risk assessment) ✅ ``` ## Common Remediation Workflows @@ -188,36 +187,36 @@ Also consider: **Task**: "Remediate CVE-2024-XXXX affecting httpd package on RHEL 8" **Required Docs**: -1. `ansible/cve-remediation-templates.md` (Template 1: Package Update) ✅ -2. `rhel/package-management.md` (DNF workflows) ✅ +1. `skills/playbook-generator/references/ansible/cve-remediation-templates.md` (Template 1: Package Update) ✅ +2. `skills/playbook-generator/references/rhel/package-management.md` (DNF workflows) ✅ ### Workflow 2: Kernel CVE **Task**: "Remediate kernel CVE on RHEL production nodes" **Required Docs**: -1. `ansible/cve-remediation-templates.md` (Template 4: Kernel Update) ✅ -2. `rhel/package-management.md` (kernel update procedures) ✅ +1. `skills/playbook-generator/references/ansible/cve-remediation-templates.md` (Template 4: Kernel Update) ✅ +2. `skills/playbook-generator/references/rhel/package-management.md` (kernel update procedures) ✅ ### Workflow 3: Batch Remediation **Task**: "Remediate 5 CVEs across 20 RHEL servers" **Required Docs**: -1. `ansible/cve-remediation-templates.md` (Template 6: Batch) ✅ -2. `rhel/package-management.md` (for RHEL-specific patterns) ✅ +1. `skills/playbook-generator/references/ansible/cve-remediation-templates.md` (Template 6: Batch) ✅ +2. `skills/playbook-generator/references/rhel/package-management.md` (for RHEL-specific patterns) ✅ ### Workflow 4: Risk Assessment **Task**: "Analyze impact of CVE-2024-YYYY" **Required Docs**: -1. `insights/vulnerability-logic.md` (Red Hat risk methodology) ✅ -2. `references/cvss-scoring.md` (CVSS interpretation) ✅ +1. `skills/cve-validation/references/insights/vulnerability-logic.md` (Red Hat risk methodology) ✅ +2. `skills/cve-validation/references/cvss-scoring.md` (CVSS interpretation) ✅ ### Workflow 5: SELinux CVE **Task**: "Fix SELinux context vulnerability" **Required Docs**: -1. `ansible/cve-remediation-templates.md` (Template 5: SELinux) ✅ -2. `rhel/package-management.md` (for RHEL-specific SELinux package handling) ✅ +1. `skills/playbook-generator/references/ansible/cve-remediation-templates.md` (Template 5: SELinux) ✅ +2. `skills/playbook-generator/references/rhel/package-management.md` (for RHEL-specific SELinux package handling) ✅ ## Documentation Quality Standards @@ -292,7 +291,7 @@ See [SOURCES.md](SOURCES.md) for complete source attribution table including: ## AI Inference Optimization -This knowledge base includes an AI-optimized indexing layer in `docs/.ai-index/`: +This knowledge base includes an AI-optimized indexing layer in `references/.ai-index/`: ### Semantic Index (`semantic-index.json`) - Document metadata with semantic keywords @@ -370,7 +369,7 @@ This knowledge base includes an AI-optimized indexing layer in `docs/.ai-index/` ### Update Process 1. Update or add markdown documentation 2. Update YAML frontmatter with sources and metadata -3. Run `python docs/.ai-index/generate-index.py` to regenerate indexes +3. Run `python references/.ai-index/generate-index.py` to regenerate indexes 4. Verify source URLs in SOURCES.md are current 5. Update "Last Verified" dates diff --git a/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md b/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md index b29db491..43c7a2d8 100644 --- a/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md +++ b/rh-virt/skills/vm-rebalance/REBALANCE_MANUAL.md @@ -381,7 +381,7 @@ Preserve all existing VM fields and only modify the affinity section. **Error Handling with Clear Explanations:** - If VM fails to start → Explain: "VM failed to start on . This usually means the node doesn't have enough resources (CPU/memory) or has scheduling constraints preventing this VM." - - Consult [scheduling-errors.md](../troubleshooting/scheduling-errors.md) + - Consult [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) - Suggest: Check node capacity, verify node is Ready, check for taints - If VM scheduled on wrong node → Explain: "VM started but Kubernetes placed it on instead of . This means couldn't accommodate the VM due to resource constraints, taints, or other scheduling rules." - Report actual vs expected node @@ -588,10 +588,10 @@ VM has restarted, verify services are healthy. **Document Consultation** (OPTIONAL - when migration fails): 1. **Action**: Read relevant troubleshooting guides to understand VM migration failure scenarios: - - [scheduling-errors.md](../troubleshooting/scheduling-errors.md) - For ErrorUnschedulable, node taints, resource constraints - - [lifecycle-errors.md](../troubleshooting/lifecycle-errors.md) - For VM start/stop failures during cold migration - - [storage-errors.md](../troubleshooting/storage-errors.md) - For PVC access mode issues affecting live migration -2. **Output to user**: "I consulted [scheduling-errors.md](../troubleshooting/scheduling-errors.md) to understand potential causes for the migration failure." + - [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) - For ErrorUnschedulable, node taints, resource constraints + - [lifecycle-errors.md](references/troubleshooting/lifecycle-errors.md) - For VM start/stop failures during cold migration + - [storage-errors.md](references/troubleshooting/storage-errors.md) - For PVC access mode issues affecting live migration +2. **Output to user**: "I consulted [scheduling-errors.md](references/troubleshooting/scheduling-errors.md) to understand potential causes for the migration failure." **When to consult**: - Live migration fails (check storage, network, resource constraints) diff --git a/scripts/validate_docs_tree_links.py b/scripts/validate_docs_tree_links.py index 7d6c3264..a3b0303f 100644 --- a/scripts/validate_docs_tree_links.py +++ b/scripts/validate_docs_tree_links.py @@ -4,6 +4,9 @@ Scope: - skills/*/references/**/*.md +- skills/*/*.md (skill-root markdown such as SKILL.md and REBALANCE_*.md) +- /references/**/*.md +- leftover /docs/**/*.md (if present after incomplete migration) - /README.md - /.catalog/*.md @@ -12,6 +15,10 @@ - symlink targets resolve - no symlink loops - resolved targets do not escape pack root + +Pack README / catalog fragments: validate pack-local docs links +(`references/`, `skills/`, and leftover `docs/`) so stale `docs/INDEX.md` +pointers fail CI after a `docs/` → `references/` migration. """ from __future__ import annotations @@ -70,22 +77,59 @@ def resolve_packs(paths: Iterable[str]) -> set[Path]: return packs +def _dedupe(paths: Iterable[Path]) -> list[Path]: + # Dedupe by the path used for relative-link resolution, not the symlink target. + # Shared-pool copies must be scanned from each skill directory. + seen: set[str] = set() + out: list[Path] = [] + for path in paths: + key = str(path) + if key in seen: + continue + seen.add(key) + out.append(path) + return out + + +def _is_pack_local_doc_link(base: str) -> bool: + """README/catalog links that must resolve from the pack root.""" + normalized = base.replace("\\", "/") + if normalized.startswith("./"): + normalized = normalized[2:] + return ( + normalized.startswith("references/") + or normalized.startswith("skills/") + or normalized.startswith("docs/") + ) + + def scan_targets(pack_root: Path) -> list[Path]: targets: list[Path] = [] - targets.extend(sorted((pack_root / "skills").glob("*/references/**/*.md"))) + skills_dir = pack_root / "skills" + if skills_dir.exists(): + for skill_dir in sorted(skills_dir.glob("*")): + if not skill_dir.is_dir() or not (skill_dir / "SKILL.md").exists(): + continue + targets.extend(sorted(skill_dir.glob("references/**/*.md"))) + targets.extend(sorted(skill_dir.glob("*.md"))) + pack_refs = pack_root / "references" + if pack_refs.exists(): + targets.extend(sorted(pack_refs.glob("**/*.md"))) + pack_docs = pack_root / "docs" + if pack_docs.exists(): + targets.extend(sorted(pack_docs.glob("**/*.md"))) readme = pack_root / "README.md" if readme.exists(): targets.append(readme) catalog = pack_root / ".catalog" if catalog.exists(): targets.extend(sorted(catalog.glob("*.md"))) - return targets + return _dedupe(targets) def validate_file(path: Path, pack_root: Path) -> list[str]: errs: list[str] = [] text = path.read_text(encoding="utf-8", errors="ignore") - is_skill_docs = "/skills/" in path.as_posix() and "/references/" in path.as_posix() is_pack_meta = (path == (pack_root / "README.md")) or (path.parent == (pack_root / ".catalog")) for line_no, line in enumerate(text.splitlines(), start=1): for m in MD_LINK_RE.finditer(line): @@ -96,13 +140,17 @@ def validate_file(path: Path, pack_root: Path) -> list[str]: if not base.endswith(".md"): continue - # For pack README / catalog fragments, validate only pack-local docs references. + # For pack README / catalog fragments, validate pack-local docs references + # including leftover docs/ links from incomplete migrations. if is_pack_meta: - if not (base.startswith("references/") or base.startswith("skills/")): + if not _is_pack_local_doc_link(base): continue - link_path = (pack_root / base) + link_base = base.replace("\\", "/") + if link_base.startswith("./"): + link_base = link_base[2:] + link_path = pack_root / link_base else: - link_path = (path.parent / base) + link_path = path.parent / base try: resolved = link_path.resolve(strict=True) except FileNotFoundError: @@ -112,13 +160,12 @@ def validate_file(path: Path, pack_root: Path) -> list[str]: errs.append(f"{path}:{line_no}: symlink loop for '{raw}'") continue - if is_skill_docs: - try: - resolved.relative_to(pack_root) - except ValueError: - errs.append( - f"{path}:{line_no}: link escapes pack root '{raw}' -> '{resolved}'" - ) + try: + resolved.relative_to(pack_root) + except ValueError: + errs.append( + f"{path}:{line_no}: link escapes pack root '{raw}' -> '{resolved}'" + ) if link_path.is_symlink(): raw_link = os.readlink(link_path) @@ -136,7 +183,7 @@ def validate_file(path: Path, pack_root: Path) -> list[str]: def main() -> int: parser = argparse.ArgumentParser( - description="Validate markdown links in skills docs trees, pack README, and catalog fragments" + description="Validate markdown links in skill docs, pack references, README, and catalog fragments" ) parser.add_argument( "paths", diff --git a/scripts/validate_skill_doc_links.py b/scripts/validate_skill_doc_links.py index 78297cff..e743bbfa 100644 --- a/scripts/validate_skill_doc_links.py +++ b/scripts/validate_skill_doc_links.py @@ -7,6 +7,9 @@ - Internal docs links must use references/... path from skill directory. - Linked reference files must exist (symlinks allowed, dangling symlinks rejected). - Resolved targets must stay within the pack root. + +Scans SKILL.md and other skill-root markdown (for example REBALANCE_*.md). +Pack-level references/**/*.md is covered by validate_docs_tree_links.py. """ from __future__ import annotations @@ -32,6 +35,16 @@ MD_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)") +def _skill_root_markdown(skills_dir: Path) -> list[Path]: + """SKILL.md plus companion skill-root markdown; skip shared pools like skills/references/.""" + files: list[Path] = [] + for skill_dir in sorted(skills_dir.glob("*")): + if not skill_dir.is_dir() or not (skill_dir / "SKILL.md").exists(): + continue + files.extend(sorted(skill_dir.glob("*.md"))) + return files + + @dataclass class ValidationResult: scanned_files: int = 0 @@ -50,11 +63,11 @@ def iter_skill_files(paths: Iterable[str]) -> list[Path]: if path.is_dir(): skills_dir = path / "skills" if skills_dir.exists(): - files.extend(sorted(skills_dir.glob("*/SKILL.md"))) + files.extend(_skill_root_markdown(skills_dir)) continue pack_path = Path(p) if (pack_path / "skills").exists(): - files.extend(sorted((pack_path / "skills").glob("*/SKILL.md"))) + files.extend(_skill_root_markdown(pack_path / "skills")) dedup = sorted(set(files)) return dedup