[SALhik]

Summary

Fixes documentation drift across docs/ so the reference and operations material describes the shipped code rather than an aspirational or older system. Executed in six reviewed waves from the 2026-07-01 accuracy audit and remediation plan.

What changed

• Version: single-sourced at 3.4.0 (pentestgpt/_version.py), pyproject.toml synced, drift-guard test added.
• Dev docs: CI/CD, CONTRIBUTING, CODE_QUALITY reconciled to the real 2-job pipeline (Poetry 2.2.1 / Python 3.12, real Makefile targets, no isort/phantom jobs).
• Config: env-var reference matched to AppSettings (16 phantom vars removed, real fields added, DB default fixed).
• API reference: regenerated from live OpenAPI via new scripts/dump_openapi.py; 204 real routes documented; phantom /auth/* and hyphenated paths removed; nonexistent SDK docs deleted.
• Operations: DEPLOYMENT.md rewritten against the real runtime (no invented HTTP server or v1.0.0 build).
• Guides: INTEGRATION and PLUGINS fixed to the real module layout (PluginInterface, communication hub, OrchestratorFactory).
• Architecture: stealth/MITRE paths corrected, technique count 50+ to 38, network subsystem documented.
• CLI: full 20-flag reference generated from pentestgpt --help.
• Housekeeping: fixed index links, retired the stale roadmap, indexed the orphaned testing guide.
• Guard: new scripts/check_docs.py (links, module paths, CLI flags, API paths) wired into quality.yml to fail CI on future drift. It already caught 4 real stale imports in INTEGRATION.md.
• Dependency: declared the previously-undeclared python-nmap (imported by the network subsystem).

Verification

• mypy . clean (615 files); ruff check . clean; pytest 5688 passed, 11 skipped
• scripts/dump_openapi.py and scripts/check_docs.py run clean; pentestgpt --version prints 3.4.0; --help matches the documented 20 flags

Follow-ups (surfaced, not fixed here)

• testing_api.app registers 0 routes (include_router precedes the route decorators)
• monitoring API /api/v1/monitoring duplication (documented per decision; code untouched)
• os.getenv in two config classes vs the AppSettings convention; *_BASE_URL are code-set, not env-overridable
• cosmetic "v3.0" banners (deferred batch); two isort lines in CODE_QUALITY.md; a SECURITY.md CLI example mismatch

Note on commit count

origin/main is currently 3 commits behind local main, so this PR temporarily shows 3 pre-existing commits (c56a6f3, 9db0605, 079c7ef) on top of the 13 remediation commits. They drop off once main is synced.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Refreshed setup, getting-started, architecture, API, configuration, CI/CD, and contributing guides to match current behavior and CLI options.
  • Updated stealth and MITRE ATT&CK documentation, clarified Stealth Level naming, and revised API route overviews; removed the SDK examples index content.
  • Replaced the roadmap with a shorter pointer-based version and expanded documentation entry points.

• Chores

  • Updated the example environment configuration and tightened CI documentation validation with dedicated accuracy checks.
  • Added a local pre-check that blocks required gstack usage when the tool isn’t installed.

[coderabbitai]

Warning

Review limit reached

@SALhik, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 54 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 83e68fa6-cb76-478c-a169-ffa2018fb895

📥 Commits

Reviewing files that changed from the base of the PR and between fd69ace and 55133ab.

⛔ Files ignored due to path filters (1)

• poetry.lock is excluded by !**/*.lock

📒 Files selected for processing (2)

• CLAUDE.md
• config/stealth_default.json

📝 Walkthrough

Walkthrough

This PR adds Claude Code gstack enforcement, updates CI documentation validation and environment examples, and revises project, API, architecture, configuration, development, and getting-started documentation for current module paths, stealth terminology, workflows, and CLI usage.

Changes

Claude tooling and configuration

Layer / File(s)	Summary
gstack hook and settings .claude/hooks/check-gstack.sh, .claude/settings.json, CLAUDE.md	Adds a Skill pre-tool hook that checks for gstack and documents the required browsing workflow.
Documentation validation .github/workflows/quality.yml	Runs scripts/check_docs.py with fixed test environment variables instead of checking only for docs/api/.
Environment example cleanup .env.example	Removes obsolete provider, storage, security, rate-limit, upload, and payload settings and adds OAuth2 configuration.

Documentation overhaul

Layer / File(s)	Summary
Project entry points and index README.md, docs/README.md	Updates project naming, Quick Start guidance, documentation headings, and index links.
Roadmap and API documentation docs/ROADMAP.md, docs/api/AGENT_API.md, docs/api/SDK_EXAMPLES.md	Condenses roadmap and API documentation around current references and generated schemas; removes SDK examples.
Architecture and MITRE documentation docs/architecture/DETAILS.md, docs/architecture/DIAGRAMS.md, docs/architecture/MITRE_INTEGRATION.md, docs/architecture/README.md	Documents canonical MITRE and network packages, updates architecture material, and changes MITRE examples to current import paths.
Stealth implementation documentation docs/architecture/STEALTH.md, docs/architecture/STEALTH_IMPLEMENTATION.md	Renames the maximum stealth enum member, updates canonical module paths, and revises related examples, tests, and deployment snippets.
Configuration references docs/configuration/ENVIRONMENT_VARIABLES.md, docs/configuration/REFERENCE.md	Aligns environment and configuration documentation with current loading, provider, OAuth2, rate-limiting, feature-flag, and stealth settings.
Development workflow documentation docs/development/CI_CD.md, docs/development/CODE_QUALITY.md, docs/development/CONTRIBUTING.md	Updates workflow, quality, setup, Ruff, Bandit, Makefile, and Claude workflow guidance.
Getting-started CLI guidance docs/getting-started/README.md	Adds command-line options and reformats configuration preset documentation.

Estimated code review effort: 3 (Moderate) | ~30 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the PR’s main goal: fixing documentation to match the shipped code.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/documentation-accuracy-remediation-2026-07-01

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

docs/development/CONTRIBUTING.md (1)

265-267: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Replace the stale isort checklist item.

The surrounding guidance now standardizes on Ruff for import sorting, so the checklist should not point contributors back to isort.

♻️ Proposed fix

- [ ] Imports are properly sorted (isort)
+ [ ] Imports are properly sorted (Ruff)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/development/CONTRIBUTING.md` around lines 265 - 267, The checklist item
in CONTRIBUTING.md still references the old isort workflow, but the
import-sorting guidance should now align with Ruff. Update the checklist entry
near the import-ordering guidance to remove the isort mention and replace it
with the Ruff-based import sorting/check item, keeping the surrounding
contributor instructions consistent with the current tooling.

docs/architecture/STEALTH.md (1)

2495-2508: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Keep stealth_level as StealthLevel here. _increase_stealth assigns the raw string "maximum", but this section treats stealth_level as a StealthLevel enum everywhere else. That leaves current_level.value comparisons brittle and can break the next transition.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture/STEALTH.md` around lines 2495 - 2508, Keep
component.stealth_level as a StealthLevel enum in _increase_stealth and
_reduce_stealth, since the current code assigns a raw string while later logic
relies on current_level.value comparisons. Update the assignments in these
methods to use the enum members consistently, and ensure all transition checks
in _increase_stealth and _reduce_stealth compare against StealthLevel values
instead of string literals.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.env.example:
- Around line 55-58: The OAuth2 environment variables in the .env.example block
are out of the order expected by dotenv-linter. Reorder the entries under the
OAuth2 section so that OAUTH2_CLIENT_ID and OAUTH2_CLIENT_SECRET appear before
OAUTH2_ENABLED, keeping the rest of the section unchanged.

In `@docs/api/AGENT_API.md`:
- Around line 14-15: The API table descriptions for the `/agents/start` and
`/agents/stop` rows are too broad; update them to describe actions on a single
agent rather than the whole system. Use the existing agent handler semantics
from the `agent_api.py` endpoints that accept an `agent_id`, and revise the
wording in the `AGENT_API.md` table so the `start` and `stop` entries clearly
reflect per-agent behavior.

In `@docs/architecture/DIAGRAMS.md`:
- Around line 361-364: The flow label for the highest stealth branch is
misaligned with the `StealthLevel.MAXIMUM` preset. Update the diagram in the
branch handling `B -->|Maximum 10| ...` so it routes to `E[Maximum Stealth]`
instead of `F[Research Mode]`, keeping the `Aggressive Stealth`, `Balanced
Stealth`, and `Maximum Stealth` labels consistent with the existing `B` decision
mapping.

In `@docs/architecture/MITRE_INTEGRATION.md`:
- Around line 23-26: The deprecation note is too broad and should apply only to
the MITRE re-export shims, not the entire utils area. Update the
MITRE_INTEGRATION documentation around the utils section to clearly mark only
mitre_attack.py, mitre_planner.py, and mitre_kb.py as deprecated shim files,
while leaving the rest of pentestgpt/utils as active modules. Keep the wording
tied to those three filenames and their “re-export shim” role so the deprecation
scope is unambiguous.

In `@docs/architecture/README.md`:
- Line 9: The version displayed in the architecture README is outdated and
should be brought in sync with the current project release. Update the Current
Version text in the README content that includes the AutoPentester paper
reference so it shows 3.4.0 instead of 3.0.0, keeping the rest of the line
unchanged.

---

Outside diff comments:
In `@docs/architecture/STEALTH.md`:
- Around line 2495-2508: Keep component.stealth_level as a StealthLevel enum in
_increase_stealth and _reduce_stealth, since the current code assigns a raw
string while later logic relies on current_level.value comparisons. Update the
assignments in these methods to use the enum members consistently, and ensure
all transition checks in _increase_stealth and _reduce_stealth compare against
StealthLevel values instead of string literals.

In `@docs/development/CONTRIBUTING.md`:
- Around line 265-267: The checklist item in CONTRIBUTING.md still references
the old isort workflow, but the import-sorting guidance should now align with
Ruff. Update the checklist entry near the import-ordering guidance to remove the
isort mention and replace it with the Ruff-based import sorting/check item,
keeping the surrounding contributor instructions consistent with the current
tooling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 03c17402-cc8e-47a2-8853-9cedf48e7a76

📥 Commits

Reviewing files that changed from the base of the PR and between c5aeb47 and 3781f81.

⛔ Files ignored due to path filters (11)

• docs/api/_generated/agent_api.json is excluded by !**/_generated/**
• docs/api/_generated/cost_optimization_api.json is excluded by !**/_generated/**
• docs/api/_generated/detection_resistance_api.json is excluded by !**/_generated/**
• docs/api/_generated/effectiveness_api.json is excluded by !**/_generated/**
• docs/api/_generated/knowledge_api.json is excluded by !**/_generated/**
• docs/api/_generated/monitoring_api.json is excluded by !**/_generated/**
• docs/api/_generated/monitoring_api_secure.json is excluded by !**/_generated/**
• docs/api/_generated/network_api.json is excluded by !**/_generated/**
• docs/api/_generated/plugin_api.json is excluded by !**/_generated/**
• docs/api/_generated/stealth_api.json is excluded by !**/_generated/**
• docs/api/_generated/testing_api.json is excluded by !**/_generated/**

📒 Files selected for processing (35)

• .claude/hooks/check-gstack.sh
• .claude/settings.json
• .env.example
• .github/workflows/quality.yml
• CLAUDE.md
• README.md
• docs/README.md
• docs/ROADMAP.md
• docs/api/AGENT_API.md
• docs/api/README.md
• docs/api/SDK_EXAMPLES.md
• docs/architecture/DETAILS.md
• docs/architecture/DIAGRAMS.md
• docs/architecture/MITRE_INTEGRATION.md
• docs/architecture/README.md
• docs/architecture/STEALTH.md
• docs/architecture/STEALTH_IMPLEMENTATION.md
• docs/configuration/ENVIRONMENT_VARIABLES.md
• docs/configuration/REFERENCE.md
• docs/development/CI_CD.md
• docs/development/CODE_QUALITY.md
• docs/development/CONTRIBUTING.md
• docs/getting-started/README.md
• docs/guides/INTEGRATION.md
• docs/guides/PLUGINS.md
• docs/operations/DEPLOYMENT.md
• docs/operations/MONITORING.md
• pentestgpt/_version.py
• pentestgpt/agents/results_verifier.py
• pentestgpt/agents/tool_executor.py
• pyproject.toml
• requirements.txt
• scripts/check_docs.py
• scripts/dump_openapi.py
• tests/test_version_consistency.py

💤 Files with no reviewable changes (1)

• docs/api/SDK_EXAMPLES.md