docs: fix technical inaccuracies and add undocumented feature coverage#932
Open
aireilly wants to merge 2 commits intoambient-code:mainfrom
Open
docs: fix technical inaccuracies and add undocumented feature coverage#932aireilly wants to merge 2 commits intoambient-code:mainfrom
aireilly wants to merge 2 commits intoambient-code:mainfrom
Conversation
- Fix Jira auth from OAuth to API Token (email + token) in 3 files - Fix GitLab auth from OAuth to Personal Access Token in 3 files - Change Google Workspace to Google Drive (only Drive scopes exist) - Expand model list to all 7 models including Gemini, note feature-gating - Update runner description to polymorphic AG-UI server with multi-bridge support - Fix API route in architecture Mermaid diagram to actual endpoint - Clarify export behavior (Google Drive requires running session) - Fix S3 storage description (cluster-wide, not per-workspace) - Remove nonexistent AUTO_MERGE_ENABLED from Amber docs - Remove anthropomorphism from Amber docs (~18 instances) - Add inactivityTimeout documentation to sessions - Clarify UI-only constraints for max tokens and timeout - Fix integration scope from "global" to "user-scoped" - Fix title casing: "Quickstart" to "Quick start" - Fix "Connect with" to "Connect to" per style guide Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
New pages: - CLI reference (acpctl): authentication, config, project/session management, shell completion, environment variables - Scheduled sessions: cron-backed recurring sessions, schedule management, run history, concurrency policy - Public API reference (/v1/): endpoints, authentication, rate limiting, phase mapping, configuration New sections in existing pages: - Human-in-the-loop (HITL) interaction in sessions.md: question types, multi-select, tabbed multi-question flows - Feedback & observability in sessions.md: thumbs up/down, Langfuse tracing - Git operations in context-and-artifacts.md: repo status, branches, remotes, push, merge status, abandon changes - Runner types in architecture.md: bridge comparison table, model-to-runner mapping, capability differences, runner type registry - Expanded API keys in workspaces.md: creation flow, expiration options, usage examples, security best practices - Expanded permissions in workspaces.md: subject types, role capabilities, RBAC implementation, revoking access - Keyboard shortcuts in quickstart-ui.md: Cmd+K command palette Style fixes: - Convert all quickstart headings to sentence case - Convert scheduled sessions headings from gerund to imperative - Fix number formatting with commas in workspaces tables Technical review fixes: - Gemini CLI session persistence corrected to No - Public API phase mapping documents unmapped Stopped/Stopping states - CORS defaults include apps-crc.testing origin - CLI config path documented separately for Linux and macOS - Architecture page notes tracing is conditional on deployment config Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
WalkthroughDocumentation enhancements across concepts, getting-started, development, and ecosystem sections. Additions include new documentation files for Scheduled Sessions, Public API, and CLI reference. Existing files expanded with new sections (Human-in-the-loop, Feedback, Runner types), clarified technical details (API field mappings, integration auth methods), and updated terminology and phrasing for consistency. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
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. Comment Tip You can disable sequence diagrams in the walkthrough.Disable the |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/src/content/docs/getting-started/quickstart-ui.md (1)
65-65:⚠️ Potential issue | 🟠 MajorDon’t lock quickstart status text to a specific runtime implementation.
Line 65 references Kubernetes directly, which is an internal detail likely to drift. Use platform-agnostic wording to keep the quickstart durable.
Proposed doc change
-| **Creating** | Kubernetes is provisioning the agent container. | +| **Creating** | ACP is provisioning the session runtime. |As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/src/content/docs/getting-started/quickstart-ui.md` at line 65, Replace the platform-specific text in the table row "| **Creating** | Kubernetes is provisioning the agent container. |" with a platform-agnostic phrase (e.g., "The environment is provisioning the agent container." or "The platform is provisioning the agent container.") so the quickstart status doesn't reference an internal runtime implementation; update the string used in that table cell accordingly (look for the exact table row containing "**Creating**" and the "Kubernetes is provisioning the agent container." text and swap it for a neutral wording).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/src/content/docs/concepts/workspaces.md`:
- Around line 32-36: The docs statement that per-workspace custom S3 storage is
“planned” and unavailable is inaccurate; update
docs/src/content/docs/concepts/workspaces.md to reflect that storage can already
be configured per-project by using the project secret or falling back to
operator defaults (see getConfigForProject in
components/operator/internal/handlers/sessions.go). Edit the note to say that
per-project storage configuration is supported via project secrets, with
operator defaults as fallback, and that future UI/UX improvements may make
per-workspace configuration more user-friendly.
In `@docs/src/content/docs/ecosystem/amber.md`:
- Line 5: The copy makes absolute claims ("retains full awareness of every
file", "runs every lint check", "is always available") that can be falsified in
production; reword those phrases to a scoped, realistic statement such as
qualifying with "typically", "aims to", or "can help with", e.g., change the
clauses in the Amber description to indicate typical behavior or intent (refer
to the phrases "retains full awareness of every file", "runs every lint check",
and "is always available") so the text reflects likely behavior and failure
modes rather than absolute guarantees.
In `@docs/src/content/docs/extensions/public-api.md`:
- Line 191: The docs show the wrong default for CORS_ALLOWED_ORIGINS; update the
table entry for `CORS_ALLOWED_ORIGINS` in public-api.md so the default value in
the documentation matches the template's actual default (an empty string `""`)
instead of
`http://localhost:3000,http://localhost:8080,https://*.apps-crc.testing`; change
the default cell to `""` and leave the description unchanged.
In `@docs/src/content/docs/getting-started/quickstart-ui.md`:
- Line 44: Replace the hardcoded model/version list in the "**Model** -- Select
the LLM to use from the dropdown." sentence with a stable, generic instruction
like "Select an available model from the dropdown" and add a brief pointer to
the centralized models reference (and note that some models may be feature-gated
by administrators); update the sentence in quickstart-ui's "**Model**" section
to remove specific model names and instead refer readers to the models/reference
page for the current, authoritative list and feature-gate details.
---
Outside diff comments:
In `@docs/src/content/docs/getting-started/quickstart-ui.md`:
- Line 65: Replace the platform-specific text in the table row "| **Creating** |
Kubernetes is provisioning the agent container. |" with a platform-agnostic
phrase (e.g., "The environment is provisioning the agent container." or "The
platform is provisioning the agent container.") so the quickstart status doesn't
reference an internal runtime implementation; update the string used in that
table cell accordingly (look for the exact table row containing "**Creating**"
and the "Kubernetes is provisioning the agent container." text and swap it for a
neutral wording).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 50f3b773-4a83-4a45-a807-718fd9ea6865
📒 Files selected for processing (11)
docs/src/content/docs/concepts/context-and-artifacts.mddocs/src/content/docs/concepts/integrations.mddocs/src/content/docs/concepts/scheduled-sessions.mddocs/src/content/docs/concepts/sessions.mddocs/src/content/docs/concepts/workspaces.mddocs/src/content/docs/development/architecture.mddocs/src/content/docs/ecosystem/amber.mddocs/src/content/docs/extensions/public-api.mddocs/src/content/docs/getting-started/cli.mddocs/src/content/docs/getting-started/concepts.mddocs/src/content/docs/getting-started/quickstart-ui.md
Comment on lines
+32
to
+36
| Session state is stored using a cluster-wide S3-compatible backend (such as MinIO) configured by the platform administrator. | ||
|
|
||
| - Bucket name, endpoint, region | ||
| - Access key and secret key | ||
| :::note | ||
| Custom S3-compatible storage configuration per workspace is a planned feature. Currently, all workspaces share the cluster-wide storage backend. | ||
| ::: |
There was a problem hiding this comment.
Storage capability statement appears too absolute and likely inaccurate
The doc says per-workspace custom storage is “planned” and “currently not available,” but components/operator/internal/handlers/sessions.go shows storage is resolved via getnConfigForProject(...) from project secret or operator defaults. This suggests project-level configuration already exists in at least some deployments.
Suggested wording fix
-Session state is stored using a cluster-wide S3-compatible backend (such as MinIO) configured by the platform administrator.
+Session state is stored using an S3-compatible backend (such as MinIO), typically configured cluster-wide by the platform administrator.
:::note
-Custom S3-compatible storage configuration per workspace is a planned feature. Currently, all workspaces share the cluster-wide storage backend.
+By default, workspaces use the cluster-level storage configuration. Depending on deployment setup, project-level overrides may also be available.
:::🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/concepts/workspaces.md` around lines 32 - 36, The docs
statement that per-workspace custom S3 storage is “planned” and unavailable is
inaccurate; update docs/src/content/docs/concepts/workspaces.md to reflect that
storage can already be configured per-project by using the project secret or
falling back to operator defaults (see getConfigForProject in
components/operator/internal/handlers/sessions.go). Edit the note to say that
per-project storage configuration is supported via project secrets, with
operator defaults as fallback, and that future UI/UX improvements may make
per-workspace configuration more user-friendly.
| --- | ||
|
|
||
| [**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered colleague. She is a codebase intelligence agent that reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Think of Amber as a senior engineer who never forgets a file, never skips a lint check, and is always available. | ||
| [**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber retains full awareness of every file, runs every lint check, and is always available. |
There was a problem hiding this comment.
Avoid absolute guarantees that can be falsified in production.
“retains full awareness of every file,” “runs every lint check,” and “is always available” are hard guarantees that can fail due to permissions, configuration, or outages. Please scope these claims to typical behavior.
Suggested wording
-[**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber retains full awareness of every file, runs every lint check, and is always available.
+[**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your attached repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber maintains awareness of session-accessible files, runs configured lint checks, and is available whenever your deployment and integrations are online.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| [**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber retains full awareness of every file, runs every lint check, and is always available. | |
| [**Amber**](https://github.com/ambient-code/amber) is the Ambient Code Platform's AI-powered codebase intelligence agent. Amber reads your attached repositories, understands your project standards, and works alongside you -- from quick consultations to autonomous background maintenance. Amber maintains awareness of session-accessible files, runs configured lint checks, and is available whenever your deployment and integrations are online. |
🧰 Tools
🪛 LanguageTool
[style] ~5-~5: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s to autonomous background maintenance. Amber retains full awareness of every file, r...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/ecosystem/amber.md` at line 5, The copy makes absolute
claims ("retains full awareness of every file", "runs every lint check", "is
always available") that can be falsified in production; reword those phrases to
a scoped, realistic statement such as qualifying with "typically", "aims to", or
"can help with", e.g., change the clauses in the Amber description to indicate
typical behavior or intent (refer to the phrases "retains full awareness of
every file", "runs every lint check", and "is always available") so the text
reflects likely behavior and failure modes rather than absolute guarantees.
| | `PORT` | `8081` | Port the gateway listens on | | ||
| | `RATE_LIMIT_RPS` | `100` | Maximum requests per second per IP | | ||
| | `RATE_LIMIT_BURST` | `200` | Maximum burst size per IP | | ||
| | `CORS_ALLOWED_ORIGINS` | `http://localhost:3000,http://localhost:8080,https://*.apps-crc.testing` | Comma-separated list of allowed CORS origins | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the actual CORS_ALLOWED_ORIGINS default value in the service template
rg -n "CORS_ALLOWED_ORIGINS" -A 3 components/ambient-api-server/templates/Repository: ambient-code/platform
Length of output: 901
Update CORS_ALLOWED_ORIGINS default in documentation to match the actual default.
The documented default is http://localhost:3000,http://localhost:8080,https://*.apps-crc.testing, but the service template (components/ambient-api-server/templates/service-template.yml, line 95) defines it as an empty string (""). Update line 191 to reflect the correct default.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/extensions/public-api.md` at line 191, The docs show
the wrong default for CORS_ALLOWED_ORIGINS; update the table entry for
`CORS_ALLOWED_ORIGINS` in public-api.md so the default value in the
documentation matches the template's actual default (an empty string `""`)
instead of
`http://localhost:3000,http://localhost:8080,https://*.apps-crc.testing`; change
the default cell to `""` and leave the description unchanged.
| 2. In the create session dialog, configure: | ||
| - **Display name** (optional) -- A human-readable label for the session. | ||
| - **Model** -- Select the LLM to use from the dropdown (Claude Sonnet 4.5, Claude Opus 4.6, Claude Opus 4.5, or Claude Haiku 4.5). | ||
| - **Model** -- Select the LLM to use from the dropdown. Available models include Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, and Gemini 2.5 Flash (generally available), plus Claude Opus 4.6, Claude Sonnet 4.6, and Gemini 2.5 Pro (feature-gated, when enabled by your administrator). |
There was a problem hiding this comment.
Avoid hardcoding model/version inventory in Quick start.
Line 44 will age quickly and become inaccurate. In Quick start, prefer stable guidance (“select an available model”) and point to a dedicated models/reference page for the current list and feature gates.
Proposed doc change
- - **Model** -- Select the LLM to use from the dropdown. Available models include Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, and Gemini 2.5 Flash (generally available), plus Claude Opus 4.6, Claude Sonnet 4.6, and Gemini 2.5 Pro (feature-gated, when enabled by your administrator).
+ - **Model** -- Select an available LLM from the dropdown. Model availability and feature-gated access depend on your organization configuration; see the models reference for the current catalog.As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Model** -- Select the LLM to use from the dropdown. Available models include Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, and Gemini 2.5 Flash (generally available), plus Claude Opus 4.6, Claude Sonnet 4.6, and Gemini 2.5 Pro (feature-gated, when enabled by your administrator). | |
| - **Model** -- Select an available LLM from the dropdown. Model availability and feature-gated access depend on your organization configuration; see the models reference for the current catalog. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/src/content/docs/getting-started/quickstart-ui.md` at line 44, Replace
the hardcoded model/version list in the "**Model** -- Select the LLM to use from
the dropdown." sentence with a stable, generic instruction like "Select an
available model from the dropdown" and add a brief pointer to the centralized
models reference (and note that some models may be feature-gated by
administrators); update the sentence in quickstart-ui's "**Model**" section to
remove specific model names and instead refer readers to the models/reference
page for the current, authoritative list and feature-gate details.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation review and feature coverage update. Two commits:
Commit 1: Fix technical inaccuracies (
96f333c)Technical Reviewer agent scanned all 20 doc files against the codebase and found 21 issues (3 critical, 9 high, 9 low):
AUTO_MERGE_ENABLEDreferenced but doesn't existDocs Writer agents (4 in parallel) applied fixes across 7 files.
Docs Reviewer agent then reviewed the fixes and found 5 style errors:
Docs Writer agents (3 in parallel) fixed all style errors.
Technical Reviewer agent ran a final pass confirming all fixes were accurate, and caught one more critical issue (GitLab OAuth → PAT) plus 2 significant issues (export Google Drive requires running session, S3 description too vague).
Docs Writer agents (2 in parallel) fixed the remaining issues.
Net result: 7 files changed, 55 insertions, 65 deletions.
Commit 2: Add undocumented features (
2020079)Explore agents (3 in parallel) scanned the entire codebase to inventory all user-facing features:
Cross-referencing against existing docs identified 10 undocumented features.
Docs Writer agents (3 in parallel, HIGH priority) created new pages:
getting-started/cli.mdconcepts/scheduled-sessions.mdextensions/public-api.mdDocs Writer agents (3 in parallel, MEDIUM priority) added sections to existing pages:
Docs Writer agents (4 in parallel, remaining tasks) expanded/added:
Docs Reviewer agent reviewed all 8 files and found 14 errors + 18 warnings. Errors fixed directly:
Technical Reviewer agent reviewed all 8 files against code and found 3 critical + 5 significant issues. All fixed directly:
Yes→NoStopped/Stoppingphase documentation*.apps-crc.testingNet result: 8 files changed, 867 insertions, 17 deletions. 3 new pages, 7 new sections.
Agent execution summary
Test plan
npm run devindocs/renders all new pages without errorsacpctl --helpoutput🤖 Generated with Claude Code