From a79d7de48214c2a772a62a62dab56b4f987252f8 Mon Sep 17 00:00:00 2001
From: Trisha <145396833+trishalalit@users.noreply.github.com>
Date: Wed, 11 Mar 2026 02:41:54 -0400
Subject: [PATCH] [bug:6117:docs]: fix inconsistent configuration and
 troubleshooting guidance (#6118)

---
 CONTRIBUTING.md       | 49 ++++++++++++++-----------------------------
 SECURITY.md           |  4 ++--
 docs/configuration.md |  2 +-
 3 files changed, 19 insertions(+), 36 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 019952eb..c5f76f15 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -74,42 +74,25 @@ Install `make` using:
 
 ```bash
 sudo apt install make
+```
 
-uv: command not found
-
-Install uv using:
-
-curl -LsSf https://astral.sh/uv/install.sh | sh
-source ~/.bashrc
-
-ruff: not found
-
-If linting fails due to a missing ruff command, install it with:
-
-uv tool install ruff
-
-WSL Path Recommendation
-
-When using WSL, it is recommended to clone the repository inside your Linux home directory (e.g., ~/hive) instead of under /mnt/c/... to avoid potential performance and permission issues.
-
-
----
-
-# ✅ Why This Is Good
-
-- Clear
-- Professional tone
-- No unnecessary explanation
-- Under micro-fix size
-- Based on real contributor experience
-- Won’t annoy maintainers
-
----
-
-Now:
+### `uv: command not found`
+Install `uv` using:
 
 ```bash
-git checkout -b docs/setup-troubleshooting
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+```
+
+### `ruff: not found`
+If linting fails due to a missing `ruff` command, install it with:
+
+```bash
+uv tool install ruff
+```
+
+### WSL Path Recommendation
+When using WSL, it is recommended to clone the repository inside your Linux home directory (e.g., ~/hive) instead of under /mnt/c/... to avoid potential performance and permission issues.
 
 ## Commit Convention
 
diff --git a/SECURITY.md b/SECURITY.md
index 184d80d0..0c2ccda3 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -39,8 +39,8 @@ We consider security research conducted in accordance with this policy to be:
 ## Security Best Practices for Users
 
 1. **Keep Updated**: Always run the latest version
-2. **Secure Configuration**: Review `config.yaml` settings, especially in production
-3. **Environment Variables**: Never commit `.env` files or `config.yaml` with secrets
+2. **Secure Configuration**: Review your `~/.hive/configuration.json`, `.mcp.json`, and environment variable settings, especially in production
+3. **Environment Variables**: Never commit `.env` files or any configuration files that contain secrets
 4. **Network Security**: Use HTTPS in production, configure firewalls appropriately
 5. **Database Security**: Use strong passwords, limit network access
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 9fa0ebd1..4afd94c9 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -172,7 +172,7 @@ Add to `.vscode/settings.json`:
 ## Security Best Practices
 
 1. **Never commit API keys** - Use environment variables or `.env` files
-2. **`.env` is git-ignored** - Copy `.env.example` to `.env` at the project root and fill in your values
+2. **If you use a local `.env` file, keep it private** - This repository does not include a root `.env.example`; use your own local `.env` file or shell environment variables for secrets
 3. **Use real provider keys in non-production environments** - validate configuration with low-risk inputs before production rollout
 4. **Credential isolation** - Each tool validates its own credentials at runtime