docs: add ReadTheDocs documentation site with MkDocs Material#2
Conversation
…ocs config Set up documentation site infrastructure: - mkdocs.yml with Material theme, code highlighting, dark mode, tabs - .readthedocs.yaml for RTD deployment (Python 3.12, ubuntu-24.04) - docs/requirements.txt pinning mkdocs-material 9.x - 30 stub pages matching full nav structure - Updated .gitignore to exclude site/ build output
…oval workflow guides
… and rate limiting guides
…ling, and decision record guides
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 93ef52d2f8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The injection check runs first in the evaluation pipeline. It scores the tool arguments for adversarial patterns and, depending on configuration, either blocks the call outright, downgrades it to require human approval, or logs it and proceeds. The check is optional and opt-in: configure `injectionDetection` on `GuardOptions` to enable it. | ||
|
|
||
| ```typescript | ||
| import { createGuard } from "ai-tool-guard"; |
There was a problem hiding this comment.
The new guides repeatedly import createGuard/guardTool from ai-tool-guard, but those symbols are not exported by the package (the root API is createToolGuard, and tool wrapping is done via guard.guardTool(...)). As written, users who copy these examples will hit immediate TypeScript/runtime import errors, so the docs are not executable in their current form; I confirmed the mismatch in src/index.ts and it appears in multiple new guide files (argument validation, injection detection, output filtering, and rate limiting).
Useful? React with 👍 / 👎.
…formatting Remove internal requirement column from features table, center text in architecture diagram box, fix PolicyBackend box width, and align inline comments in error handling example. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
💡 Codex Review Call guard.guardTool with a tool name in concepts snippet
This example uses ai-tool-guard/docs/guides/rate-limiting.md Line 212 in 86dff4b Remove retryAfterMs access from ToolGuardError example
The catch block reads ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
…ToolGuard) Address PR review: guide code examples used non-existent createGuard and standalone guardTool imports. Replace with the actual public API names createToolGuard and guard.guardTool(name, tool, config) across all affected guides (argument validation, injection detection, output filtering, rate limiting). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…usage Add missing tool name arg to guard.guardTool() in concepts guide. Replace err.retryAfterMs (not a ToolGuardError property) with err.message in rate-limiting error handling example. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: afb62e1105
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| 3. **Policy evaluation** — The guard evaluates all matching rules (built-in defaults, custom rules, and responses from any configured external backend) and resolves a final verdict using escalation semantics. | ||
|
|
||
| 4. **Approval flow** — If the resolved verdict is `require-approval`, execution pauses and the `onApprovalRequired` callback is invoked. The callback receives the full decision context and must return `"approved"` or `"denied"` to continue or abort. |
There was a problem hiding this comment.
This states that onApprovalRequired must return the strings "approved"/"denied", but the runtime expects an ApprovalResolution object with an approved boolean (and optional patchedArgs). If users follow this text and return a string, ApprovalManager.resolveToken sees resolution.approved as falsy and denies every approval-gated tool call, so all require-approval flows fail.
Useful? React with 👍 / 👎.
| ```typescript | ||
| const guard = createToolGuard({ | ||
| // GuardOptions — applies to every tool | ||
| rules: [defaultPolicy()], |
There was a problem hiding this comment.
The example wraps defaultPolicy() in an extra array, but defaultPolicy() already returns PolicyRule[]. Copying this produces PolicyRule[][], which either fails type-checking or reaches runtime where rule iteration expects rule.toolPatterns on each element and crashes when the element is an array.
Useful? React with 👍 / 👎.
| argGuards: { | ||
| email: { pii: true }, | ||
| }, |
There was a problem hiding this comment.
This snippet models argGuards as an object map, but ToolGuardConfig.argGuards is an ArgGuard[]. In plain JS, this object has no length, so the guard pipeline condition config.argGuards.length > 0 is false and argument validation is skipped entirely, silently disabling the protections this section is trying to teach.
Useful? React with 👍 / 👎.
… type in concepts - Describe onApprovalRequired as returning ApprovalResolution object (not string literals) - Remove extra array wrapper around defaultPolicy() which already returns PolicyRule[] - Change argGuards from object map to ArgGuard[] array using piiGuard() Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 participant
Summary
.readthedocs.yamlfor automated RTD deployment (Python 3.12, ubuntu-24.04)mkdocs build --stricton every PRDocumentation structure
Additional changes
docs:buildanddocs:servescripts topackage.jsondocsjob to CI workflow (.github/workflows/ci.yml).gitignoreto excludesite/build outputTest plan
mkdocs build --strictpasses with zero warningssrc/index.tsis documented in API referencemkdocs serverenders all pages with working navigationNote
Low Risk
Documentation- and CI-only changes; no runtime/library code or security-sensitive logic is modified.
Overview
Introduces a MkDocs Material documentation site (new
mkdocs.yml,docs/content, anddocs/requirements.txt) and adds Read the Docs deployment via.readthedocs.yaml.Updates CI to run a dedicated docs build (
mkdocs build --strict) and ignores the generatedsite/output;README.mdformatting is adjusted to align with the new docs and improve table/diagram rendering.Written by Cursor Bugbot for commit 4e32eb6. This will update automatically on new commits. Configure here.