docs: refresh AI-Q 2.2 architecture

[AjayThorve]

Overview

Refresh the release/2.2 architecture documentation so the diagram and surrounding guidance match the current implementation:

• Replace both published light-mode architecture assets with the updated diagram.
• Explain the dynamic deep-research path, concurrent reusable researcher workers, shared research state, role-scoped read-only skills, and optional job-scoped execution boundary.
• Align the README, 2.2 changelog, skills/sandbox example, configuration reference, installation guide, and FAQ with current Modal/OpenShell behavior and the shipped data-source inventory.
• Preserve the notebook's absolute GitHub image URL for Brev and Google Colab launch contexts.

This is documentation-only and does not change runtime behavior.

DCO sign-off for the squash commit

Signed-off-by: Ajay Thorve athorve@nvidia.com
Signed-off-by: Ajay Thorve 20476096+AjayThorve@users.noreply.github.com

Validation

• Strict Sphinx HTML build: make -C docs SPHINXBUILD=../.venv/bin/sphinx-build SPHINXOPTS='-W --keep-going -n' html
• Sphinx link check completed; all checked URLs passed except the unchanged https://you.com/docs/quickstart, which returned HTTP 403 to the checker.
• uv lock --check
• git diff --check
• Applicable commit hooks passed: merge-conflict, added-large-files, EOF, trailing-whitespace, and detect-secrets checks. The Markdown link-check hook was skipped because the local Homebrew Node binary cannot load libsimdjson.29.dylib; Sphinx link checking was run directly as described above.
• Tests are not applicable because this PR changes documentation and image assets only.
• I updated documentation for user-facing or contributor-facing changes.
• I confirmed this PR does not include secrets, credentials, or internal-only data.
• I certify this contribution under the Developer Certificate of Origin (DCO) and signed my commits with git commit -s or an equivalent sign-off.
• I replaced the DCO sign-off placeholder with my GitHub commit identity and kept the required angle brackets around the email address.

Where should reviewers start?

Start with docs/source/architecture/overview.md and docs/source/_static/AIQ-arch-light.png, then review docs/source/architecture/agents/deep-researcher.md for the implementation-boundary explanation.

Related Issues

• None.

Summary by CodeRabbit

• Documentation
  • Clarified that deep-research jobs use per-job physical sandboxes (Modal and OpenShell each create one) with fail-closed policy attestation, checkpoints, and durable artifact capture.
  • Expanded sandboxing/security docs, including execution boundaries, shared research state, and role-based skill assignments.
  • Updated setup/configuration guidance for additional web-search providers (Exa, You.com, Nimble, and others).
  • Extended knowledge-layer options to include Azure AI Search.
• Chores
  • Refreshed secret-scan metadata (.secrets.baseline) to reflect updated README detection details.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 457f1a5b-5838-4e8e-bd2d-7ddadb1cc791

📥 Commits

Reviewing files that changed from the base of the PR and between 9b51659 and 48d73f9.

📒 Files selected for processing (2)

• .secrets.baseline
• README.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: Pytest and Coverage
• GitHub Check: Script Validation
• GitHub Check: Lint and Hooks

🧰 Additional context used

📓 Path-based instructions (2)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Keep changes inside this repository, avoid editing adjacent repositories, and scope changes to the smallest relevant independent package, especially under sources/.
Run the narrowest relevant validation command first and broaden to the full suite only when a change crosses shared boundaries.
Keep pull requests scoped, exclude unrelated files and generated artifacts, never include secrets, and provide validation commands and results.

**/*: Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
Add or update tests for behavior changes.

Files:

• README.md

{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}

⚙️ CodeRabbit configuration file

{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.

Files:

• README.md

🔇 Additional comments (2)

README.md (1)

69-69: LGTM!

Also applies to: 140-143, 215-215, 229-232, 246-254, 299-299, 475-482, 493-493

.secrets.baseline (1)

136-136: LGTM!

Also applies to: 358-358

---

Walkthrough

Documentation and generated metadata now describe per-job Modal/OpenShell sandboxing, policy attestation, execution boundaries, expanded data-source setup, roadmap updates, and Azure AI Search support.

Changes

Documentation alignment

Layer / File(s)	Summary
Sandbox execution contract README.md, CHANGELOG.md, docs/source/customization/configuration-reference.md, docs/source/examples/skills-sandbox/*	Documentation specifies one sandbox per deep-research job, OpenShell policy attestation and deletion, and debug-only shared attachment.
Architecture and execution boundaries docs/source/architecture/agents/deep-researcher.md, docs/source/architecture/overview.md	Architecture docs define shared state, role-based skills, data-source components, and the AI-Q-to-sandbox execution boundary.
Setup and integration references README.md, docs/source/get-started/installation.md, docs/source/resources/faq.md	Setup guidance adds Exa and You.com installation paths, broadens provider requirements, updates roadmap coverage, and documents Azure AI Search.
Generated documentation metadata .secrets.baseline	The README match line number and secrets-baseline generation timestamp are refreshed.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA-AI-Blueprints/aiq#286: Updates related /shared/ and research-note artifact-handling semantics.
• NVIDIA-AI-Blueprints/aiq#322: Overlaps on DeepAgents sandbox and OpenShell documentation.
• NVIDIA-AI-Blueprints/aiq#387: Covers related per-job OpenShell isolation and policy-attestation documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits and accurately summarizes the documentation refresh.
Description check	✅ Passed	The description matches the template with overview, DCO sign-off, validation, reviewers, and related issues sections.
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 ajay/docs-2.2-architecture-update

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@README.md`:
- Around line 140-143: Update the README’s provider configuration table and
setup instructions to fully document every newly advertised source: Exa,
SerpAPI, and SearchAPI, including their correct environment-variable names,
installation or setup commands, and usage examples where applicable. Review the
added Exa installation guidance and existing commands for accuracy and remove or
narrow provider claims that cannot be supported by complete instructions.

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: f6eca19d-e20c-4da6-b956-9cb67bcf9f7d

📥 Commits

Reviewing files that changed from the base of the PR and between 356f641 and 9b51659.

⛔ Files ignored due to path filters (2)

• docs/assets/AIQ-arch-light.png is excluded by !**/*.png
• docs/source/_static/AIQ-arch-light.png is excluded by !**/*.png

📒 Files selected for processing (9)

• .secrets.baseline
• CHANGELOG.md
• README.md
• docs/source/architecture/agents/deep-researcher.md
• docs/source/architecture/overview.md
• docs/source/customization/configuration-reference.md
• docs/source/examples/skills-sandbox/index.md
• docs/source/get-started/installation.md
• docs/source/resources/faq.md

📜 Review details

⏰ Context from checks skipped due to timeout. (3)

• GitHub Check: Lint and Hooks
• GitHub Check: Script Validation
• GitHub Check: Pytest and Coverage

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Keep changes inside this repository, avoid editing adjacent repositories, and scope changes to the smallest relevant independent package, especially under sources/.
Run the narrowest relevant validation command first and broaden to the full suite only when a change crosses shared boundaries.
Keep pull requests scoped, exclude unrelated files and generated artifacts, never include secrets, and provide validation commands and results.

**/*: Do not include secrets, credentials, private hostnames, internal-only logs, customer data, or generated local artifacts.
Add or update tests for behavior changes.

Files:

• CHANGELOG.md
• docs/source/customization/configuration-reference.md
• docs/source/resources/faq.md
• docs/source/architecture/agents/deep-researcher.md
• docs/source/get-started/installation.md
• docs/source/architecture/overview.md
• docs/source/examples/skills-sandbox/index.md
• README.md

docs/source/**/*

📄 CodeRabbit inference engine (AGENTS.md)

Update canonical documentation under docs/source/ when behavior, configuration, or workflows change; do not duplicate full documentation pages into skills.

Files:

• docs/source/customization/configuration-reference.md
• docs/source/resources/faq.md
• docs/source/architecture/agents/deep-researcher.md
• docs/source/get-started/installation.md
• docs/source/architecture/overview.md
• docs/source/examples/skills-sandbox/index.md

{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}

⚙️ CodeRabbit configuration file

{docs/**,README.md,CONTRIBUTING.md,SECURITY.md,CODE-OF-CONDUCT.md}: Review documentation for command accuracy, branch-name consistency, current CI and copy-pr-bot behavior, public
vs internal boundary clarity, stale examples, and links that no longer match the repository layout.

Files:

• docs/source/customization/configuration-reference.md
• docs/source/resources/faq.md
• docs/source/architecture/agents/deep-researcher.md
• docs/source/get-started/installation.md
• docs/source/architecture/overview.md
• docs/source/examples/skills-sandbox/index.md
• README.md

🔇 Additional comments (9)

CHANGELOG.md (1)

26-26: LGTM!

README.md (1)

69-69: LGTM!

Also applies to: 289-289, 465-472, 483-483

docs/source/customization/configuration-reference.md (1)

655-655: LGTM!

docs/source/examples/skills-sandbox/index.md (1)

9-15: LGTM!

Also applies to: 32-40, 116-121, 228-229

docs/source/architecture/overview.md (1)

25-42: LGTM!

Also applies to: 52-55

docs/source/architecture/agents/deep-researcher.md (1)

127-145: LGTM!

.secrets.baseline (1)

136-136: LGTM!

Also applies to: 358-358

docs/source/get-started/installation.md (1)

54-54: LGTM!

Also applies to: 100-100

docs/source/resources/faq.md (1)

70-70: LGTM!

[tanleach]

LGTM

[raykallen]

lgtm

[AjayThorve]

/merge