docs-agent 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## [1.1.0](https://github.com/rudderlabs/docs-agent/compare/v1.0.2...v1.1.0) (2025-11-20)
+
+
+### Features
+
+* authenticate response webhook api calls ([fb7984d](https://github.com/rudderlabs/docs-agent/commit/fb7984d1f2f5127177a16ad5e3f4f7695b675905))
+
+
+### Bug Fixes
+
+* rollback ai and mcp version upgrade ([fd8f6b5](https://github.com/rudderlabs/docs-agent/commit/fd8f6b5da3150fd8005d8d2fcfe338047e646002))
+
+## [1.0.2](https://github.com/rudderlabs/docs-agent/compare/v1.0.1...v1.0.2) (2025-10-18)
+
+
+### Bug Fixes
+
+* staging port issue ([#62](https://github.com/rudderlabs/docs-agent/issues/62)) ([fbd4d47](https://github.com/rudderlabs/docs-agent/commit/fbd4d475238fe4d1ea019f2e7bae77d0e5968127))
+
+## [1.0.1](https://github.com/rudderlabs/docs-agent/compare/v1.0.0...v1.0.1) (2025-10-15)
+
+
+### Bug Fixes
+
+* add package lock to git ([#57](https://github.com/rudderlabs/docs-agent/issues/57)) ([764eb2f](https://github.com/rudderlabs/docs-agent/commit/764eb2f0f1bf347ebf3448aa3ddaadc8a4f60bea))
+* add write permissions for claude action ([#58](https://github.com/rudderlabs/docs-agent/issues/58)) ([60b338d](https://github.com/rudderlabs/docs-agent/commit/60b338d60aaabeb6fc267ebf83cc41360ec63c64))
+* docker creds in publish-docker workflow ([#55](https://github.com/rudderlabs/docs-agent/issues/55)) ([94f16fb](https://github.com/rudderlabs/docs-agent/commit/94f16fbbd0befa798d2eee6699d13391d8406706))
+
+## 1.0.0 (2025-10-07)
+
+
+### Features
+
+* add reference docs and purge unnecessary info ([#29](https://github.com/rudderlabs/docs-agent/issues/29)) ([a613dca](https://github.com/rudderlabs/docs-agent/commit/a613dca4700adb84b7ebb7ea54a80d79d990c1cd))
+* code search using github api ([#38](https://github.com/rudderlabs/docs-agent/issues/38)) ([7c8007d](https://github.com/rudderlabs/docs-agent/commit/7c8007d779563f037b6eb75e313bce4b9e1afb75))
+* generate reference docs from code ([#26](https://github.com/rudderlabs/docs-agent/issues/26)) ([fe507b5](https://github.com/rudderlabs/docs-agent/commit/fe507b561074be2648d20401bae7385e28d3dde0))
+* wofklwo and mcp ([3389829](https://github.com/rudderlabs/docs-agent/commit/3389829ac265bb28e7229bb9a1d95b9fe85944a0))
+
+
+### Bug Fixes
+
+* fine tune related file context ([#35](https://github.com/rudderlabs/docs-agent/issues/35)) ([d11177d](https://github.com/rudderlabs/docs-agent/commit/d11177d08e115e669a146a4828e272c008a14177))
+* improve alignment with writing and formatting style guide ([#21](https://github.com/rudderlabs/docs-agent/issues/21)) ([029ba53](https://github.com/rudderlabs/docs-agent/commit/029ba53e06a6ac2e09bc4a5d4d05d8cc6df39da5))
+* mcp issue due to std log ([32032c6](https://github.com/rudderlabs/docs-agent/commit/32032c6a73b7fb15c66afebfbcc063c04a19fead))
+* support more arguments in api ([#49](https://github.com/rudderlabs/docs-agent/issues/49)) ([5ef5955](https://github.com/rudderlabs/docs-agent/commit/5ef5955bfc2280e8d5cb38bf94a2f264bf53e557))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 RudderStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Docs-Agent - AI for Continuous Tech Docs Improvement
+
+Helping technical writers, engineering managers, and Open Source authors maintain a technically accurate and comprehensive documentation. Available as MCP server, HTTP APIs, and Node.js Library.
+
+> **Built on Diataxis**: This project implements the [Diataxis Documentation Framework](https://diataxis.fr) created by Daniele Procida. Diataxis is a systematic approach to technical documentation authoring. This approach is followed by [Canonical/Ubuntu](https://ubuntu.com/blog/diataxis-a-new-foundation-for-canonical-documentation), Python, Cloudflare, JupyterHub, Gatsby, etc.
+
+## Features
+
+Docs-Agent leverages AI to find and fix issues related to comprehensiblity or technical accuracy.
+
+- 🔍 **Audit docs against source code** for technical accuracy
+- 📝 **Auto-fix outdated content** that's out of sync from the source code
+- 🤖 **AI-powered analysis** with human oversight
+- 🔗 **Enhance internal linking** between docs pages and concepts
+- 🎯 **Improve comprehensibility** following Diataxis Documentation Framework principles (you may override it)
+- 🔍 **Code auditing capabilities** to validate documentation against source
+- 🔒 **Path traversal protection** with different access controls for API vs MCP modes
+
+> Docs-Agent does not expect its users to learn the details of the Diataxis Documentation Framework
+
+> Neither Diataxis, nor Docs-Agent impose any rigid rules, rather Docs-Agent uses the analytical approach provided by Diataxis that emerges from identifying four core user needs which naturally fall into four patterns (tutorials, how-tos, reference, explanation).
+
+## Quickstart
+
+You may use the Docs-Agent at any of the following three different levels of autonomy vs quality
+
+1. (Recommended) In AI IDEs (e.g. Cursor) as MCP server - Best combination of quality and control
+2. In Cursor as rules - Low quality results and potentially negative productivity benefits in some cases
+3. In your systems integrated using HTTP API or Node.js library - Can be made fully autonomous, but takes significant efforts compared to the AI IDE approach
+
+### Option 1 (Recommended): Docs-Agent MCP server + Cursor Custom Mode agent
+Great quality and control. But not fully autonomous. Best AI <> Human collaborative experience.
+
+<details>
+<summary>
+Why Cursor? And why not **only Cursor**?
+</summary>
+
+To leverage Cursor's strength and overcome its limitations by delegating tasks to Docs-Agent MCP server.
+
+* Cursor strength: great DX in reviewing and editing the AI suggested changes
+* Cursor weakness: limited control over AI settings frequently results in seemingly correct but technically incorrect output
+* Docs-Agent MCP strength: fine control over AI settings (e.g. temperature, top_p, etc.) and context results in more predictable and technically correct output. Also it is a great choice for extensibility (e.g. include non-ai ops as part of the workflow) and consistency.
+
+</details>
+
+
+**Set up Docs-Agent MCP server**
+
+1. `git clone https://github.com/rudderstack/docs-agent`
+2. `npm install` (use node v20+)
+3. You may test the project by running `npm test` (e2e tests for each task, skips all tests except one at a time, it costs money), `npm run mcp-list`, and `npm run mcp-run`
+
+**Integrate Docs-Agent MCP server with Cursor Custom Mode**
+1. Add MCP Server to Cursor (`.cursor/mcp.json`)
+   ```json
+   {
+   "mcpServers": {
+      "docs-agent": {
+         "command": "/path/to/node",
+         "args": ["/path/to/docs-agent/src/index.js"],
+         "env": {
+            "GITHUB_TOKEN": "github-token-is-needed-for-code-search",
+            "REVIEW_AI_SERVICE": "gemini",
+            "REVIEW_AI_MODEL": "gemini-2.5-pro-exp-03-25",
+            "GOOGLE_GENERATIVE_AI_API_KEY": "secret-api-key",
+            "ANTHROPIC_API_KEY": "secret-api-key",
+            "ALLOW_DISRUPTIVE_CHANGES": "false",
+            "OPENAI_API_KEY": "notinuse",
+            "MAX_TOKENS": "8000",
+            "MAX_CHANGES": "1",
+            "API_DISABLED": "true",
+            "MCP_DISABLED": "false",
+            "PREFERRED_AI_SERVICE": "anthropic",
+            "PREFERRED_AI_MODEL": "claude-3-5-sonnet-20240620",
+            "OLLAMA_API_URL": "http://localhost:11434/api/generate",
+            "OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.braintrust.dev/otel",
+            "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <Your API Key>, x-bt-parent=project_id:<Your Project ID>"
+         }
+      }
+   }
+   }
+   ```
+   To start with, you only need following env variables - `GITHUB_TOKEN`, `GOOGLE_GENERATIVE_AI_API_KEY`, `ANTHROPIC_API_KEY`, `MCP_DISABLED`. Refer [how to get the necessary secrets](#how-to-get-the-necessary-secrets).
+   Make sure `MCP_DISABLED` value is set to `"false"`.
+2. Enable Cursor Custom Mode - `Cursor Settings > Chat (or Features) > Custom Modes (Beta)`
+3. Create your own Custom Mode (I name it Docs Agent) - `Cursor chat box > Mode selection dropdown (where you see Agent by default) > Add custom mode`.
+   a. Choose the set of tools you'd want this mode to use. I get the best outcome by disabling `Run (commands)` tool, and enabling all other tools e.g. `MCP`, `edit`, and `Search` (excluding web search).
+   b. Choose the choice of your model, I get the best outcome from `Claude 3.5 Sonnet`.
+   c. Set a shortcut to quickly start this mode. I use `Cmd+Shift+D` on macOS and `Ctrl+Shift+D` ond other OS.
+4. Set the prompt for the Custom mode. Check out [this example prompt](./docs/mcp-client-prompt.md), it works well for me in Cursor's Custom Mode. You may further personalize it. If you want to pass on a specific file (e.g. your own docs rules) for all docs improvement requests to the MCP server as context, you may choose to specify the absolute path of that file in the prompt so that Cursor (or whichever AI IDE you use).
+   
+### Option 2: Cursor rules
+> Lowest quality and impact on productivity, but fits in the current human workflow.
+Simply move the `config` folder content to `.cursor/rules` as `.mdc` files. No server required for this.
+
+### Option 3: Integrate with your own program using API or Node.js library (e.g. GitHub app)
+> It can be made completely autonomous + Optional feedback via your systems (e.g. GitHub issues)
+
+You can integrate Docs Agent with your system either by using Docs Agent as an HTTP API or using as a Node.js library.
+
+**3.1: Integrating `docs-agent` as an API**
+
+1. `git clone https://github.com/rudderstack/docs-agent`
+2. `npm install` (use node v20+)
+3. `cp env.example .env` update var values (make sure `API_DISABLED=false`; `GOOGLE_GENERATIVE_AI_API_KEY` and `ANTHROPIC_API_KEY` values have valid API keys).
+4. Make sure to add all webhook URLs to `ALLOWED_WEBHOOK_URLS` (comma separated list) where the Docs-Agent is supposed to send back the results when done. Optionally set `RESULTS_WEBHOOK_KEY` to authenticate webhook requests (sent as `x-api-key` header).
+5. `npm test` (e2e tests for each task, skips all tests except one at a time, it costs money)
+6. `npm start`
+
+You should be now able to make HTTP requests to following endpoints:
+
+- `POST /review --data { content: "docs page code", filepath: "/path/to/file/to/edit", filename: "my.file.md", webhookUrl?: "https://your-app.com/webhook", webhookMetadata?: {...} }` : Returns the improvement suggestions (must provide either the content or filepath). Optionally, provide `webhookUrl` to receive results via webhook POST request (requires `ALLOWED_WEBHOOK_URLS` configuration). If `RESULTS_WEBHOOK_KEY` is set, it will be sent as `x-api-key` header in the webhook request.
+- `POST /prioritize --data { content: "docs page code", review: "improvement suggestions" }` -  Returns the prioritized actionable instructions to improve docs incrementally
+- `POST /edit --data { content: "docs page code", editPlan: "specific tasks to improve docs" }` - Returns new file content edited according to the edit plan
+- `GET /health` - Returns health status and system information
+
+For more details, check out [reference documentation](./docs/reference.md).
+
+**3.2: Integrating `docs-agent` as a Node.js library**
+
+1. Link this source code as a node.js package in your Node.js program
+2. Call the neccessary functions as described in [references](./docs/reference.md)
+
+For more details, check out [reference documentation](./docs/reference.md).
+
+### Security
+
+Docs-Agent implements comprehensive security measures to protect against common attacks:
+
+- **Path Traversal Protection**: Prevents unauthorized file access with different controls per mode:
+  - **API Mode**: Restricts file access to `public/` subdirectory only
+  - **MCP Mode**: Allows unrestricted local file access (relies on MCP client permissions and OS-level security)
+  - **Both Modes**: Allow validated remote file access (GitHub/GitLab URLs only)
+- **SSRF Protection**: Configurable allowlists for webhook URLs and remote file hosts
+- **API Authentication**: Optional API key authentication for HTTP endpoints
+- **Input Validation**: Comprehensive validation of file paths and URLs
+
+For detailed security configuration, see [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md).
+
+### Deployment
+See the deployment guide for containerized, Compose, and bare‑metal instructions: [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)
+
+## Architecture
+1. **Documentation Analysis Pipeline (Default: Gemini 2.5 Pro Exp)**
+   - Document parsing and structure analysis
+   - Issue identification and categorization
+   - Improvement planning and prioritization
+   - Code auditing against source files
+2. **Documentation Editing/Generation Pipeline (Default: Claude 3.5 Sonnet)**
+   - Content generation based on approved plans
+   - Code example creation and refinement
+   - Ensuring documentation framework compatibility e.g. hugo markdownm
+3. **Workflow Orchestration**
+   - MCP Tools (reviewDocs, improveDocs, linkifyDocs, auditDocsAgainstCode)
+   - REST APIs
+   - GitHub webhook handling (Future/Community/Your-Own-App)
+   - Issue and PR management (Future/Community/Your-Own-App)
+
+## How to get the necessary secrets
+
+**GitHub Personal Access Token**
+
+1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+2. Click **"Generate new token"**
+3. Set an expiration date and select required scopes (typically `repo` for repository access)
+4. **Copy the token immediately** - GitHub only shows it once
+5. Set as environment variable: `GITHUB_TOKEN=your_token_here`
+
+**Google Generative AI API Key**
+
+1. Visit [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-key)
+2. Click **"Get API Key"** 
+3. Accept the Terms of Service
+4. Your API key will be auto-generated
+5. Store securely and set as: `GOOGLE_GENERATIVE_AI_API_KEY=your_key_here`
+
+**Anthropic API Key**
+
+1. Sign up at [Anthropic Console](https://console.anthropic.com/)
+2. Go to **Account Settings → API Keys**
+3. Click **"Create Key"** and provide a name
+4. **Copy and save immediately** - you won't see it again
+5. Set as environment variable: `ANTHROPIC_API_KEY=your_key_here`
+
+
+## FAQ
+
+<details>
+<summary>
+What are some examples of documentation tasks that can be delgated to Docs-Agent?
+</summary>
+
+- Audit docs against source code and ensure technical accuracy
+- Fix docs content that is out of sync from the source code
+- Find comprehensibility and readability issues
+- Align technical docs with the Diataxis framework principles (reference, tutorial, how to guides, explanation)
+- Find deviations from the  writing style and align it with your own principles
+- Improve consistency and increase accurate usage of your own technical glossary
+- Find and fix typo
+- Find and fix broken links
+- Improve internal linking of docs pages to other docs pages and concepts/glossary
+- Validate documentation against actual source code implementation
+</details>
+
+<details>
+<summary>
+How hard/easy it is to use?
+</summary>
+
+**A short chat message is all you need.**
+
+When using Docs-Agent as an MCP server in Cursor, simply open the docs page, and ask in plain English what you want to do
+   The queries can be broad as well as specific. Some examples:
+   - `improve this docs page`
+   - `audit this docs page against relevant source code`
+   - `improve linking of this page`
+   - `users complained about this docs page being too verbose, improve it`
+</details>
+
+<details>
+<summary>
+How hard/easy it is for humans to review the Docs-Agent changes?
+</summary>
+
+**Incremental changes that can be reviewed under a min.**
+
+In the default mode, the Docs-Agent does not aim to improve everything in one go. That would make the life of humans harder to understand the changes and thus making it hard and even slow to bring positive change. Instead, Docs-Agent follows incremental approach - one tiny easy to review PR at a time. Once Docs-Agent finds the gaps in the documentation, it prioritizes one impactful change, and makes only the change that would be quick to review without much cognitive overload. For example: in order to align docs with Diataxis principles, it would require tonnes of changes to convert existing docs to different Diataxis types such as reference, tutotrial, how to, and explanation. When you ask Docs-Agent to improve any docs page, it will figure out the Diataxis type that current page closely matches with, how well it does in the following Diataxis  principles for that type, and introduce one tiny change to align its content more with that type.
+</details>
+
+---
+
+## License
+
+This project is licensed under the [MIT License](./LICENSE).
+
+### Credits
+
+**Diataxis Framework** by [Daniele Procida](https://github.com/evildmp) • [diataxis.fr](https://diataxis.fr) • Licensed under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)

package/docs/DEPLOYMENT.md

@@ -0,0 +1,142 @@
+## Deployment Guide
+
+This guide covers deploying Docs-Agent as a container (recommended), with Docker Compose, or directly on a host (bare metal). It exposes an HTTP API on port 3001 when `API_DISABLED=false` and can be run as an MCP server with `MCP_DISABLED=false`.
+
+### Prerequisites
+- Node.js v20+ (bare-metal or MCP usage)
+- Docker 24+ (for containerized deployment)
+- Optional: Docker Compose v2+
+- Required secrets (at least):
+  - `GOOGLE_GENERATIVE_AI_API_KEY`
+  - `ANTHROPIC_API_KEY`
+  - `GITHUB_TOKEN` (for code search)
+
+Additional configuration (optional):
+- `API_KEY` for API security
+- `PREFERRED_AI_SERVICE`, `PREFERRED_AI_MODEL`, `REVIEW_AI_SERVICE`, `REVIEW_AI_MODEL`
+- `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS` for observability
+- `MAX_TOKENS`, `MAX_CHANGES`, `ALLOW_DISRUPTIVE_CHANGES`
+- SSRF Protection:
+  - `ALLOWED_WEBHOOK_URLS` for webhook endpoints (exact URLs only)
+  - `RESULTS_WEBHOOK_KEY` for authenticating webhook requests (optional, sent as `x-api-key` header)
+  - `REMOTE_FILE_ALLOWED_HOSTS` for remote file access (hostnames only)
+  - `REMOTE_FILE_ALLOW_CUSTOM_HOSTS` to enable custom hosts (default: false)
+
+Environment defaults are shown in `env.example` and `docker-compose.yml`.
+
+---
+
+### Option A: Docker (single container)
+1. Build the image:
+   ```bash
+   docker build -t docs-agent:latest .
+   ```
+2. Run the container (API mode):
+   ```bash
+   docker run --rm \
+     -p 3001:3001 \
+     -e NODE_ENV=production \
+     -e PORT=3001 \
+     -e API_DISABLED=false \
+     -e MCP_DISABLED=true \
+     -e API_KEY=secret_api_key \
+     -e GOOGLE_GENERATIVE_AI_API_KEY=your_gemini_key \
+     -e ANTHROPIC_API_KEY=your_anthropic_key \
+     -e GITHUB_TOKEN=your_github_pat \
+     -e ALLOWED_WEBHOOK_URLS=https://github.app.url/api/comment \
+     -e RESULTS_WEBHOOK_KEY=your_webhook_auth_key \
+     -e REMOTE_FILE_ALLOWED_HOSTS=raw.githubusercontent.com \
+     docs-agent:latest
+   ```
+
+Health check: `GET http://localhost:3001/health` should return 200.
+
+Notes
+- The image runs as a non-root `nodejs` user.
+- Port 3001 is exposed; adjust with `-e PORT=... -p host:container`.
+
+---
+
+### Option B: Docker Compose (recommended for local/dev)
+Use the provided `docker-compose.yml`:
+
+```bash
+docker compose up --build
+```
+
+Then check: `curl http://localhost:3001/health`.
+
+Customize environment by editing `docker-compose.yml` or using an `.env` file. Ensure you set valid keys for:
+- `GOOGLE_GENERATIVE_AI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GITHUB_TOKEN`
+- `API_KEY`
+
+For SSRF protection, configure:
+- `ALLOWED_WEBHOOK_URLS` - exact webhook URLs (comma-separated)
+- `RESULTS_WEBHOOK_KEY` - API key to authenticate webhook requests (optional, sent as `x-api-key` header)
+- `REMOTE_FILE_ALLOWED_HOSTS` - allowed hosts for remote file access
+- `REMOTE_FILE_ALLOW_CUSTOM_HOSTS` - set to "true" to enable custom hosts
+
+---
+
+### Option C: Bare metal (Node.js on host)
+1. Install dependencies:
+   ```bash
+   npm ci --only=production
+   ```
+2. Configure environment (copy and edit):
+   ```bash
+   cp env.example .env
+   # edit .env -> set API_DISABLED=false and add your keys
+   ```
+3. Start the server:
+   ```bash
+   npm start
+   ```
+4. Verify:
+   ```bash
+   curl http://localhost:3001/health
+   ```
+
+For MCP usage (no HTTP API), set `MCP_DISABLED=false` and `API_DISABLED=true`, then point your MCP client (e.g., Cursor Custom Mode) to `node src/index.js`. See `README.md` for an example MCP client configuration.
+
+---
+
+### Configuration Reference
+- `API_DISABLED` (default true in example): set to `false` to enable HTTP API
+- `API_KEY`, always set this to a secret value to secure API endpoints
+- `MCP_DISABLED`: set to `false` to enable MCP server tools
+- `GOOGLE_GENERATIVE_AI_API_KEY`, `ANTHROPIC_API_KEY`: required for AI operations
+- `GITHUB_TOKEN`: required for auditing docs against code in private/public repos
+- `PREFERRED_AI_SERVICE`/`MODEL` and `REVIEW_AI_SERVICE`/`MODEL`: control model choices
+- `MAX_TOKENS`, `MAX_CHANGES`, `ALLOW_DISRUPTIVE_CHANGES`: safety/quality controls
+- Observability: set `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` to enable OTEL traces
+- SSRF Protection:
+  - `ALLOWED_WEBHOOK_URLS`: exact webhook URLs only (comma-separated)
+  - `RESULTS_WEBHOOK_KEY`: API key for webhook authentication (optional, sent as `x-api-key` header)
+  - `REMOTE_FILE_ALLOWED_HOSTS`: allowed hosts for remote file reads (comma-separated)
+  - `REMOTE_FILE_ALLOW_CUSTOM_HOSTS`: enable custom hosts (default: false)
+
+All variables and defaults are documented in `env.example`.
+
+---
+
+### Security and Operations
+- Provide secrets via environment variables or secret stores (never bake into images).
+- The container uses a non-root user and a health check.
+- Run behind an API gateway or reverse proxy in production; add rate limits and auth as needed.
+- **Path Traversal Protection**: 
+  - API mode: Restricts file access to `public/` subdirectory only
+  - MCP mode: Allows unrestricted local file access (relies on MCP client permissions)
+  - Both modes: Allow validated remote file access (GitHub/GitLab URLs)
+- SSRF Protection: Configure webhook and remote file allowlists to prevent unauthorized requests.
+
+---
+
+### Troubleshooting
+- Health endpoint not ready: allow the container start period defined in Dockerfile/Compose.
+- 401/403 errors from code search: verify `GITHUB_TOKEN` scopes (typically `repo`).
+- AI errors: verify keys and model names; ensure region/product access with providers.
+
+

package/docs/mcp-client-prompt.md

@@ -0,0 +1,26 @@
+You are a helpful team member to coordinate documentation improvements tasks between the user and the MCP tools such as docs-agent.
+User will ask you for documentation improvements tasks or advice.
+You will then choose the appropriate MCP tools from docs-agent based on the task requirements.
+
+## MCP Tool Usage Guidelines
+- Always use the docs-agent's tools for docs improvement to get the improved docs content.
+- Make sure to pass the necessary content to docs-agent such as the file content and context e.g. project structure, etc.
+- Always send the glossary page content as glossary parameter for the tool that requires it.
+- For tools that require specific files or information, find the related files or information from the source code or project context.
+- If the RudderStack documentation style guide rule (rudderstack-style.mdc) is available, provide its complete content in the custom instructions to ensure that the docs-agent output follows the RudderStack style.
+- The file paths must always be either absolute path or a remote url path
+- Always apply the docs-agent results as it is in the code immediately after they are received
+- Always show the audit or review results to ensure the reasoning behind the changes
+
+## Finding related files
+- Based on the user goal, decide which files are the most relevant files for additional context
+- A file mentioned in the page could be a relevant file if the understanding of the page depends on that file content
+- Sibling files under the immediate parent folder are sometimes relevant as they relate to the same concept
+- Do not make up the filepath, always list files and then pick the filepath from there
+
+## Boundaries
+- **Do not** make any additional changes to the docs-agent tool output, your job is to only apply those changes to current file content as it is. 
+- Make sure the final file content matches the agent's version completely after applying the diff.
+- Remember to apply all the changes as it is, no additional changes or addition or deletion from your side.
+- Do not make changes to the file content that is not related to the returned docs content.
+- Do not ask the user to apply the changes returned by `improveDocs` or `editDocs` tools — just apply them directly.