docs: add Developer tools nav tab

.claude/reference/information-architecture.md

@@ -0,0 +1,39 @@
+# Information architecture decisions
+
+Read this before proposing or evaluating a structural change. It records durable classification decisions so each new IA question doesn't get re-litigated from scratch. It is not a live map of the nav — for that, read `mkdocs.yml` per `docs-review-structure`.
+
+## Developer tools vs. everything else
+
+The product is a developer tool by definition, so "for developers" doesn't separate anything on its own. The test that does: **where does the reader act from?**
+
+- **Developer tools** = surfaces you install, run, or call from outside app.codacy.com — your terminal, your IDE, your CI pipeline, your AI agent's tool-calling layer. You write config or code against them.
+- **Everything else** = surfaces you interact with inside app.codacy.com — dashboards, org settings, repo configuration, account management. You click through them.
+
+By this test, "Developer tools" holds: the API, Codacy Cloud CLI, the IDE extensions (VS Code, IntelliJ), and Codacy Guardrails. Coverage Reporter technically qualifies (it's a CLI) but stays under "Configuring your repositories" — a deliberate exclusion made when this section was proposed, not a definitional one. Revisit deliberately if it comes up again; don't assume the exclusion still holds without asking.
+
+## Codacy AI vs. Developer tools
+
+Both involve AI; the test is **who's calling whom**, not whether the word "AI" appears:
+
+- **Codacy AI** = Codacy uses AI as an internal mechanism to produce something you review passively (AI-enhanced comments, Smart False Positive Triage, AI Reviewer). You're the consumer; the AI runs inside Codacy's own pipeline.
+- **Developer tools, agent-facing side** = Codacy exposes a surface that *your* agent calls programmatically (Codacy MCP Server, Codacy Skills). You're the operator; Codacy is what gets called.
+
+`organizations/ai-risk-hub.md` is neither bucket despite the name — it's governance over AI-generated code risk in the reader's own repositories, correctly filed under Organizations.
+
+## Why Codacy Guardrails counts as a developer tool, not just an IDE extension
+
+The nav title "(IDE Extension)" on this section describes one delivery path, not the product. `codacy-guardrails-getting-started.md`'s "How to install - Manually" section sets up the identical capability — Analysis CLI, MCP Server, AI rules — with no IDE extension involved. Guardrails passes the direction-of-consumption test on its own terms, independent of how it's installed.
+
+Guardrails interleaves CLI setup and MCP setup as one continuous flow inside a single page, in service of one outcome. Don't split that content to file separate pieces under generic "CLIs" or "MCP" sections — the split breaks the page's `#install-cli` / `#install-mcp-server` anchors for any inbound link outside this repo (product UI, blog, support macros), and there's no config-level fix for an anchor that moves to a different page. Move the whole section as one unit; don't extract from it.
+
+## Codacy Skills' home
+
+Skills is a natural-language wrapper around Codacy Cloud CLI specifically, not general-purpose agent access to all of Codacy — the CLI's own page already frames it that way ("Pair it with Codacy Skills to interact with your Codacy data in plain language"). It belongs under Codacy Cloud CLI, not in a standalone agent-tools section.
+
+## A structural move can still be the wrong call for reasons outside IA
+
+Guardrails currently sits prominently under "Getting started" with active marketing behind it (a blog-post CTA). Relocating it into "Developer tools" is IA-correct by the test above, but it's also a visibility change for a product someone may be actively driving signups to. That's a positioning call, not a structure call — flag it to whoever owns that placement rather than deciding it here.
+
+## See also
+
+- [`docs-review-structure`](../skills/docs-review-structure/SKILL.md) — the general process this file's decisions feed into.

.github/styles/config/vocabularies/Codacy/accept.txt

@@ -31,6 +31,7 @@ dartanalyzer
 deadcode
 Dependabot
 detekt
+dev
 Dockerfile
 endif
 ESLint

.gitignore

@@ -37,3 +37,4 @@ tools/*.csv
 # .claude/ is the shared, committed docs-writing system and stays tracked.
 .claude/settings.local.json
 .claude/worktrees/
+.claude/plans/

CLAUDE.md

@@ -46,12 +46,14 @@ A direct instruction from the person you are working with outranks items 2–4.
 - **Do not invent a step, UI label, endpoint, filename, or behavior.** Confirm it in the code, in existing docs, or from the person asking. Otherwise mark it `<!-- TODO: verify ... -->` and list every marker when you hand off.
 - **Do not claim a check passed without running it.** If you could not run one, name it and say why in a sentence at handoff. Silence reads as success, and that is how a broken build ships with a confident summary. "Follows the guidelines" is not a substitute for naming what you actually verified.
 - **Do not commit or push unless you were asked to.** Leave the work in the tree and describe it. Someone else opens the pull request.
-- **Do not apply an information-architecture change on your own initiative.** Moving pages between sections, renaming a nav section, or splitting a page changes what readers can find. Write up the proposal and stop there.
+- **Do not apply an information-architecture change on your own initiative.** Moving pages between sections, renaming a nav section, or splitting a page changes what readers can find. Write up the proposal and stop there to get human approval — the person you're working with has reviewed the specific proposal and explicitly confirms applying it, in which case apply exactly what was written up.
 - **Do not skip alt text, `nav:` registration, or redirects.** These are the failures that break the site without warning anyone.
 - **Do not suppress a linter warning** without an inline sentence saying why. A suppression should read as an obvious false positive to whoever finds it next.
 - **Do not write marketing adjectives or filler.** "Powerful", "seamless", "robust", "effortless", "it's worth noting that", "in order to", "simply", "just". Show the product working instead of grading it.
 - **Do not widen the diff past the request.** Opportunistic reflowing, renaming, and prose improvement hide the real change from the reviewer, and the reviewer is the point. Mention what else you spotted; do not fix it in the same pass.
 
+A direct instruction from the person you are working with outranks items 2–4. Say which rule it conflicts with, in one sentence, then do what was asked — they may know something these files do not. Item 1 is not subject to that. In particular, "make the change" does not convert a *propose this first* rule into permission to apply it.
+
 ## Mechanics that fail silently
 
 The build (`mkdocs build --strict`) does not catch these. Check each one by hand.
@@ -71,4 +73,5 @@ Shared across every workflow. Read the relevant one rather than re-deriving it.
 - [`.claude/reference/formatting.md`](.claude/reference/formatting.md) — markdown and structural rules: admonitions, tables, headings, links, images, nesting. The design contract for page bodies.
 - [`.claude/reference/voice.md`](.claude/reference/voice.md) — tone, with before/after pairs, plus canonical product names.
 - [`.claude/reference/repo-map.md`](.claude/reference/repo-map.md) — how the site is assembled, what each check does and does not catch, and the commands that answer questions about the current state of the repo.
+- [`.claude/reference/information-architecture.md`](.claude/reference/information-architecture.md) — durable classification decisions (developer tools vs. the rest of the product, Codacy AI vs. developer tools, where borderline features belong) so structure questions aren't re-derived each time.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — local build, preview, and release mechanics for humans.

docs/developer-tools/index.md

@@ -0,0 +1,38 @@
+---
+description: Overview of how to use Codacy from outside the Codacy web app, through the API, Codacy Cloud CLI, IDE integrations, and Codacy Guardrails.
+---
+
+# Codacy dev tools
+
+Codacy also works from outside the Codacy web app: from your terminal, your IDE, or your AI agent's tool-calling layer. This page lists the tools available for each of those entry points.
+
+<div class="content-columns-wrapper">
+  <section class="content-link-column" aria-labelledby="dev-tools-options">
+    <h2 id="dev-tools-options">Available tools</h2>
+
+    <a class="content-link" href="../codacy-guardrails/codacy-guardrails-getting-started/">
+      <h3>Codacy Guardrails</h3>
+      <p>Scan AI-generated code for security and quality issues as it's written, and query your Codacy findings from your IDE's AI chat panel.</p>
+    </a>
+
+    <a class="content-link" href="../codacy-api/using-the-codacy-api/">
+      <h3>Codacy API</h3>
+      <p>Retrieve and analyze your Codacy data, and make a few configuration changes, programmatically.</p>
+    </a>
+
+    <a class="content-link" href="../codacy-cloud-cli/">
+      <h3>Codacy Cloud CLI</h3>
+      <p>Add repositories, review issues, and inspect pull requests from your terminal. Pair it with Codacy Skills to ask for the same in plain language from your AI assistant.</p>
+    </a>
+
+    <a class="content-link" href="../getting-started/integrating-codacy-with-visual-studio-code/">
+      <h3>Visual Studio Code extension</h3>
+      <p>Review the Codacy analysis for a pull request without leaving your editor.</p>
+    </a>
+
+    <a class="content-link" href="../getting-started/integrating-codacy-with-intellij-ides/">
+      <h3>IntelliJ plugin</h3>
+      <p>Review the Codacy analysis for a pull request from an IntelliJ-based IDE.</p>
+    </a>
+  </section>
+</div>

mkdocs.yml

@@ -73,9 +73,11 @@ extra:
     # level == 2 handling in theme/partials/nav-item.html).
     sidebar_icons:
         "Documentation home": "home-outline"
+        "Codacy dev tools": "settings-outline"
         "Getting started": "rocket-outline"
-        "Codacy Guardrails (IDE Extension)": "shield-checkmark-outline"
-        "Codacy Cloud CLI": "terminal-outline"
+        "Codacy Guardrails": "shield-checkmark-outline"
+        "Codacy CLIs": "terminal-outline"
+        "IDE integrations": "share-social-outline"
         "Codacy AI": "sparkles-outline"
         "Repositories on Codacy": "folder-open-outline"
         "Configuring your repositories": "settings-outline"
@@ -642,21 +644,9 @@ nav:
                 - getting-started/codacy-quickstart.md
                 - getting-started/configuring-your-repository.md
                 - getting-started/integrating-codacy-with-your-git-workflow.md
-                - Integrating Codacy with your IDE:
-                      - getting-started/integrating-codacy-with-intellij-ides.md
-                      - getting-started/integrating-codacy-with-visual-studio-code.md
                 - getting-started/supported-languages-and-tools.md
                 - getting-started/which-permissions-does-codacy-need-from-my-account.md
                 - getting-started/adding-a-codacy-badge.md
-          - Codacy Guardrails (IDE Extension):
-                - codacy-guardrails/codacy-guardrails-getting-started.md
-                - codacy-guardrails/codacy-guardrails-how-to-use.md
-                - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md
-                - codacy-guardrails/codacy-guardrails-limitations.md
-                - codacy-guardrails/codacy-guardrails-troubleshooting.md
-                - codacy-guardrails/codacy-guardrails-faq.md
-          - Codacy Cloud CLI:
-                - codacy-cloud-cli/index.md
           - Codacy AI:
                 - codacy-ai/codacy-ai.md
           - Repositories on Codacy:
@@ -719,20 +709,6 @@ nav:
                 - account/managing-your-profile.md
                 - account/emails.md
                 - account/user-session-management.md
-          - Codacy API:
-                - codacy-api/using-the-codacy-api.md
-                - codacy-api/api-tokens.md
-                - API v3 reference (recommended): https://api.codacy.com/api/api-docs
-                - API v2 reference: https://api.codacy.com/api-docs
-                - Examples:
-                      - codacy-api/examples/adding-people-to-codacy-programmatically.md
-                      - codacy-api/examples/adding-repositories-to-codacy-programmatically.md
-                      - codacy-api/examples/creating-repository-api-tokens-programmatically.md
-                      - codacy-api/examples/obtaining-code-quality-metrics-for-files.md
-                      - codacy-api/examples/obtaining-current-issues-in-repositories.md
-                      - codacy-api/examples/identifying-commits-without-coverage-data.md
-                      - codacy-api/examples/uploading-dast-results.md
-                      - codacy-api/examples/triggering-dast-scans.md
           - Managing Codacy Self-hosted: "!include submodules/chart/mkdocs.yml"
           - Troubleshooting and FAQs:
                 - General:
@@ -769,6 +745,32 @@ nav:
                       - faq/troubleshooting/why-is-my-file-over-150-kb-missing.md
                       - faq/troubleshooting/error-line-endings.md
           - special-thanks.md
+    - Developer tools:
+          - Codacy dev tools: "developer-tools/index.md"
+          - Codacy Guardrails:
+                - codacy-guardrails/codacy-guardrails-getting-started.md
+                - codacy-guardrails/codacy-guardrails-how-to-use.md
+                - codacy-guardrails/codacy-guardrails-how-to-configure-rules.md
+                - codacy-guardrails/codacy-guardrails-limitations.md
+                - codacy-guardrails/codacy-guardrails-troubleshooting.md
+                - codacy-guardrails/codacy-guardrails-faq.md
+          - Codacy API:
+                - codacy-api/using-the-codacy-api.md
+                - codacy-api/api-tokens.md
+                - Examples:
+                      - codacy-api/examples/adding-people-to-codacy-programmatically.md
+                      - codacy-api/examples/adding-repositories-to-codacy-programmatically.md
+                      - codacy-api/examples/creating-repository-api-tokens-programmatically.md
+                      - codacy-api/examples/obtaining-code-quality-metrics-for-files.md
+                      - codacy-api/examples/obtaining-current-issues-in-repositories.md
+                      - codacy-api/examples/identifying-commits-without-coverage-data.md
+                      - codacy-api/examples/uploading-dast-results.md
+                      - codacy-api/examples/triggering-dast-scans.md
+          - Codacy CLIs:
+                - codacy-cloud-cli/index.md
+          - IDE integrations:
+                - getting-started/integrating-codacy-with-visual-studio-code.md
+                - getting-started/integrating-codacy-with-intellij-ides.md
     - Release notes:
           - release-notes/index.md
           - Cloud: