Improve troubleshooting structure

[buixor]

• Breakdown troubleshooting section(s)
• Document structure via claude.md + reminder to keep it up-to-date

[Copilot]

Pull request overview

This PR refactors the troubleshooting/debug documentation into a clearer hierarchy (common vs symptom-driven vs feature-specific), updates the skill router and cross-links accordingly, and documents the intended documentation structure in CLAUDE.md with an explicit “keep this current” reminder.

Changes:

• Reorganized debug references into references/debug/common/ and references/debug/symptoms/, updating SKILL routing and all impacted links.
• Added a new consolidated “platform gotchas” page for container/k8s/MAC-specific failure modes and routed symptom docs to it where appropriate.
• Documented the documentation layout/organizing axes in CLAUDE.md.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/crowdsec/SKILL.md	Updates the intent/symptom router to point at the new debug structure and adds new debug categories.
skills/crowdsec/references/operate/health-check.md	Updates parsing/not-blocked troubleshooting links to new symptom paths.
skills/crowdsec/references/install/kubernetes.md	Updates parsing symptom link to new location.
skills/crowdsec/references/install/bare-metal.md	Updates parsing + common errors links to new locations.
skills/crowdsec/references/debug/symptoms/parsing.md	Routes platform-specific “0 lines read” causes to the new platform gotchas page.
skills/crowdsec/references/debug/symptoms/not-blocked.md	Fixes relative paths to configure/appsec docs from the symptom location.
skills/crowdsec/references/debug/symptoms/no-alerts.md	Fixes relative paths to operate/configure/debug common docs from the symptom location.
skills/crowdsec/references/debug/common/triage.md	Updates internal routing from triage to the new symptom/common pages and fixes relative links to configure/install docs.
skills/crowdsec/references/debug/common/platform-gotchas.md	New doc consolidating platform-specific failure modes (mounts, container runtime, SELinux/AppArmor, journald group).
skills/crowdsec/references/debug/common/errors.md	Updates links to new symptom docs and adjusts paths due to deeper nesting.
skills/crowdsec/references/configure/hub.md	Updates link to the moved triage doc.
skills/crowdsec/references/configure/bouncers/web-servers.md	Updates “not blocking” reference link to the new symptom doc.
skills/crowdsec/references/configure/bouncers/firewall.md	Updates “not blocking” reference link to the new symptom doc.
skills/crowdsec/references/configure/acquisition.md	Updates parsing symptom link to the new location.
CLAUDE.md	Adds explicit authoring rules plus a directory/axis map for references/ and a reminder to keep it updated.

Comments suppressed due to low confidence (5)

skills/crowdsec/references/debug/common/errors.md:35

• The link renders as "../appsec/configure.md" but the target is "../../appsec/configure.md". The link works, but the displayed path is misleading (especially if a reader copies it). Update the link text to match the actual relative path or replace it with a descriptive label (e.g., “AppSec — Configure”).

This issue also appears on line 58 of the same file.
skills/crowdsec/references/debug/common/errors.md:58

• This row links to "../../operate/multi-server.md" but the rendered text shows "../operate/multi-server.md". For consistency and to avoid confusion, align the link text with the actual relative path (or use a descriptive label).
  skills/crowdsec/references/debug/common/triage.md:102
• The link text shows "../configure/allowlists.md" but the actual link target is "../../configure/allowlists.md". The destination is correct, but the rendered path is misleading—please update the link text (or use a descriptive label) to match.

This issue also appears on line 146 of the same file.
skills/crowdsec/references/debug/common/triage.md:146

• Same issue as above: the link target is "../../configure/allowlists.md" but the rendered text is "../configure/allowlists.md". Align the link text with the actual relative path (or switch to a descriptive label).
  skills/crowdsec/references/debug/symptoms/not-blocked.md:30
• The link points to "../../configure/allowlists.md" but renders as "../configure/allowlists.md". The link resolves, but the displayed relative path is incorrect and can confuse readers; update the link text (or use a descriptive label).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.