initial structure codacy guardrails docs (#2394)

Codacy Guardrails official documentation - version 1
Fix some terms using the tool vale

Author: DMarinhoCodacy

.github/styles/Microsoft/Terms.yml

@@ -5,7 +5,6 @@ ignorecase: true
 action:
   name: replace
 swap:
-  '(?:agent|virtual assistant|intelligent personal assistant)': personal digital assistant
   '(?:drive C:|drive C>|C: drive)': drive C
   '(?:internet bot|web robot)s?': bot(s)
   '(?:microsoft cloud|the cloud)': cloud

.github/styles/Microsoft/Wordiness.yml

@@ -79,7 +79,6 @@ swap:
   in lieu of: instead of
   in many cases: often
   in most cases: usually
-  in order to: to
   in some cases: sometimes
   in spite of the fact that: although
   in spite of: despite

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

@@ -1,4 +1,6 @@
 aligncheck
+autofix
+autoremediate
 allowlist
 Atlassian
 autovacuum
@@ -41,6 +43,7 @@ Gradle
 Grafana
 Gravatar
 Hadolint
+Hardcoded
 hostname
 hotfix
 Jira
@@ -91,4 +94,6 @@ unassigns
 unfollow
 vacuumdb
 Visualforce
+VSCode
 Xcode
+webserver

.github/workflows/vale.yml

@@ -18,6 +18,7 @@ jobs:
         with:
           filter_mode: added
           debug: true
+          fail_on_error: false
         env:
           # Required
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -17,3 +17,8 @@ site/
 
 # Auxiliary tool outputs
 tools/*.csv
+
+.codacy
+
+#Ignore vscode AI rules
+.github/copilot-instructions.md

docs/codacy-guardrails/codacy-guardrails-faq.md

@@ -0,0 +1,70 @@
+# FAQs
+
+## How do I install Codacy Guardrails?
+Please have a look at our [documentation](codacy-guardrails-getting-started.md)
+
+## Does Guardrails only work with AI-generated code?
+No. While Guardrails does scan and autofix AI code as part of the agent flow, it scans any code shown in your IDE in real-time, regardless of how it was written.
+
+## How's Guardrails different from Codacy’s traditional analysis?
+Guardrails is IDE-first and real-time. It complements Codacy’s platform analysis by catching issues earlier in the development cycle.
+
+## Does Guardrails work offline?
+Yes, local scanning via Codacy CLI works offline. API-based features (like querying metrics) require connectivity.
+
+## Which AI security and quality standards can I enforce with Guardrails?
+Codacy Guardrails detects and autoremediate security risks and quality issues in JavaScript, TypeScript, Python, and Java, including:
+
+
+-  SAST vulnerabilities
+-  Hardcoded secrets
+-  Insecure dependencies
+-  Error prone code
+-  Performance issues
+-  Best practices
+-  Complex code
+-  Code duplications
+-  Styling violations
+
+Configuring and enforcing coding standards at scale across all IDEs in your organization requires a Codacy Team or Business subscription.
+
+## Is my data secure?
+Codacy Guardrails isn't a large language model, but an IDE extension that uses an MCP Server to communicate with existing AI coding agents owned by the user.
+
+## When I change some analysis configuration in the UI, is it automatically applied to Guardrails?
+We're still working on this feature but in order to update the new tool configuration. you should run the command in your repository:
+
+``` bash
+codacy-cli init
+```
+
+This way Codacy will run the latest configuration.
+
+## Does guardrails generate code for me?
+Guardrails Specify that Guardrails itself doesn’t generated anything but we inform the AI agent where issues are located and scan generated code using the Codacy CLI.
+
+## How much does Guardrails cost?
+Codacy Guardrails is a free IDE Extension for local scanning of AI-generated and human-written code, **available free of charge to all developers.**
+
+Check our [Team and Organization plans](https://www.codacy.com/pricing) to unlock:
+
+
+-  Central configuration and enforcement of AI coding standards across teams and projects
+-  Query and autofix existing problems across your codebase from the AI chat panel
+-  Generate custom security and code quality reports using AI prompts
+-  Full access to the Codacy Cloud platform including:
+
+-   Pipeline-less AppSec and code quality scans
+-   PR merge gates
+-   Team dashboards
+-   Security reports
+-   DAST pipelines
+-   Jira integration
+
+## Does Guardrails work with all OS?
+Guardrails is supported on MacOS, Linux, and Windows (via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
+
+## Can I use Guardrails without an AI copilot?
+Codacy Guardrails is designed to be installed from our IDE extension for VS Code, Cursor and Windsurf. but as long as you have an AI code generator that's compatible with the MCP protocol you can also add Guardrails into your MCP configuration manually.
+
+Without an AI coding agent, you instead need to use the Codacy IDE extension without the MCP Server.

docs/codacy-guardrails/codacy-guardrails-getting-started.md

@@ -0,0 +1,202 @@
+# Getting Started
+
+Codacy Guardrails is a brand new way of enforcing code security and quality standards for AI-generated code, built into the free Codacy IDE Extension for VSCode, Copilot, Cursor, and Windsurf. Guardrails help developers ship safer, cleaner AI code by applying best practices and blocking insecure patterns while the code is being generated.
+
+Besides real-time AI code scanning, Guardrails users can now prompt all their Codacy findings, without ever leaving the AI chat panel inside their IDE.
+
+**New to Codacy Guardrails?** [Check our blog post](https://blog.codacy.com/codacy-guardrails-free-real-time-enforcement-of-security-and-quality-standards)
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/uVyRWnnJu-0?si=Pnbk65EvpvvJRXX4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+
+## Prerequisites
+
+- git
+- node.js - ensure the `npx` commands runs without issues
+
+### Supported Operating Systems
+
+- macOS
+- Linux
+- Windows (Coming Soon)
+
+!!! important
+    **For Windows users: Windows WSL** (a feature that allows you to run a Linux environment directly on Windows, without the need for a virtual machine or dual-boot setup) is the only way you can use this feature for now, but we're still working to fully support Windows.
+
+
+### Supported IDEs
+
+- Visual Studio Code
+- Cursor
+- Windsurf
+
+!!! note
+    Visual Studio Code Insiders is recommended for its faster performance and compatibility with Codacy Guardrails. However, since it's a beta version, you may encounter occasional issues.
+
+### Built-in Scanners
+
+- Trivy
+- Semgrep
+- ESLint
+- Pylint
+- PMD
+- dartanalyzer
+- [Lizard](https://docs.codacy.com/release-notes/cloud/cloud-2025-02-adding-ruff-lizard/#lizard)
+
+## How to install - Quick Guide
+
+### 1.  Download the extension
+
+- [Visual Studio Code](https://tinyurl.com/codacy-vscode)
+- [Cursor](http://tinyurl.com/codacy-cursor)
+- [Windsurf](http://tinyurl.com/codacy-windsurf)
+
+This will open the Codacy Extension in your IDE Marketplace. Click **Install**
+
+![Install Extension](images/install-codacy-extension.png)
+
+
+### 2. Install and activate the Codacy CLI for local analysis
+
+Click on the button **Install Codacy CLI**
+
+![Install CLI](images/codacy-extension-activate-cli.png)
+
+It will create a folder in your local repository called **.codacy** with all needed configuration:
+
+-  The configuration from all built-in scanners
+-  Codacy CLI script to run analysis locally 
+
+!!! note
+    If you don't want this folder to be part of your repository in future commits but continue working with it locally, please add **.codacy** to your .gitignore file
+
+
+### 3. Install MCP Server
+
+#### a. Add the Codacy MCP Server
+
+In the Codacy Extension tab, click **Add Codacy MCP Server**
+
+![Add Codacy MCP Server](images/add-codacy-mcp-server.png)
+
+#### b. Check if the Codacy MCP Server is enabled
+
+On the left side menu of the Codacy extension, please make sure that MCP server is set up and ready.
+
+![Codacy MCP Server is enabled](images/mcp-server-enabled.png)
+
+### 4. Restart your IDE
+
+
+## How to install - Manually
+
+### 1.  Install and activate the Codacy CLI for local analysis {: id="install-cli"}
+
+#### Download
+
+##### MacOS (brew)
+
+To install `codacy-cli` using Homebrew:
+
+```bash
+brew install codacy/codacy-cli-v2/codacy-cli-v2
+```
+
+##### Linux
+
+For Linux, we rely on the **codacy-cli.sh** script in the root. To download the CLI, run:
+
+```bash
+bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)
+```
+You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes:
+
+```bash
+alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)"
+```
+
+#### Installation
+
+Before running the analysis, install the specified tools:
+
+```bash
+codacy-cli install
+```
+
+### 2. Install MCP Server {: id="install-mcp-server"}
+
+If you want to use MCP Server with a NPM package you should download it from [here](https://www.npmjs.com/package/@codacy/codacy-mcp)
+
+!!! important
+    You can find some limitations using this approach because the AI doesn't automatically analyse the code generated unless there's a rule set for it to do so. When using the IDE extension (VS Code, Cursor, or Windsurf), we create those AI rules for the workspace, but if you are installing the MCP manually, you will need to create those rules by yourself. <a href="mailto:support@codacy.com">Let us know if you you plan to use this approach, so we can provide more information</a>
+
+#### Setup
+
+##### Cursor, Windsurf and Claude Desktop
+
+Depending on what IDE you are connecting the MCP Server to, you can use the following methods:
+
+- Cursor: edit the `.cursor/mcp.json` file to add the following
+- Windsurf: edit the `.codeium/windsurf/mcp_config.json` file to add the following
+- Claude Desktop: edit the `claude_desktop_config.json` file to add the following
+
+```json
+{
+  "mcpServers": {
+    "codacy": {
+      "command": "npx",
+      "args": ["-y", "@codacy/codacy-mcp"],
+      "env": {
+        "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>",
+        "CODACY_CLI_VERSION": "<VERSION>"
+      }
+    }
+  }
+}
+```
+
+##### VS Code with Copilot
+
+For connecting the MCP Server to Copilot in VS Code, add the following to the global config of the IDE:
+
+```json
+{
+  "mcp": {
+    "inputs": [],
+    "servers": {
+      "codacy": {
+        "command": "npx",
+        "args": ["-y", "@codacy/codacy-mcp"],
+        "env": {
+          "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>",
+          "CODACY_CLI_VERSION": "<VERSION>"
+        }
+      }
+    }
+  }
+}
+```
+
+You can open the user settings.json file in:
+
+`View > Command Palette > Preferences: Open User Settings (JSON)`
+
+Or open the general settings.json file directly, which according to your OS should be located in:
+
+- for macOS: `~/Library/Application Support/Code/User/settings.json`
+- for Windows: `%APPDATA%\Code\User\settings.json`
+- for Linux: `~/.config/Code/User/settings.json`
+
+![Settings.json in VSCode](images/settings-json-vscode.png)
+
+Make sure you update the value of `CODACY_ACCOUNT_TOKEN` with your [API token](../codacy-api/api-tokens.md).
+
+a. Above the MCP Server configuration in **Settings.json** file, you can Click in the command **Start**
+
+![Start MCP Server in VSCode](images/start-mcp-server-vscode.png) 
+
+b. Make sure you have Agent mode enabled: [vscode://settings/chat.agent.enabled](vscode://settings/chat.agent.enabled)
+
+c. Open the Copilot chat and switch the mode to `Agent`. You can check that the MCP server was enabled correctly by clicking on the `Select tools` icon, which should list all the available Codacy tools.
+
+![Copilot Agent with Codacy tools](images/copilot_agent.png)