[codex] Improve agent documentation discoverability - #224
Open
TommyBez wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughThis PR adds a docs index generator and validation command, updates repo guidance to use generated docs indexes, and adds many feature-scoped documentation pages and generated section indexes across agent runtime, platform, integrations, and product surfaces. ChangesRepository documentation overhaul
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
Poem
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
TommyBez
marked this pull request as ready for review
June 15, 2026 18:35
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/agent-events/overview.md (1)
27-31:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winKeep this overview within the docs line limit.
This file is one line over the repository rule for non-index markdown under
docs/. Drop the trailing blank line or otherwise trim the body so it stays at 30 lines or fewer.As per coding guidelines, non-index markdown files under
docs/must stay at 30 lines or fewer.🔧 Minimal fix
- `packages/ai/agent-runtime/server/agent-event-transcript.ts` - `packages/ai/agent-runtime/workflows/agent-events/workflow.ts` -🤖 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/agent-events/overview.md` around lines 27 - 31, The file docs/agent-events/overview.md exceeds the repository rule of 30 lines maximum for non-index markdown files under docs/. Reduce the file to 30 lines or fewer by removing the trailing blank line and/or trimming the body content to comply with the documentation guidelines.Source: Coding guidelines
docs/scheduler/overview.md (1)
1-31:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winTrim this doc to 30 lines.
As per coding guidelines, non-index markdown files under
docs/must stay at 30 lines or fewer, and this file is 31 lines long. Please condense one line or move detail into a sibling doc.🤖 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/scheduler/overview.md` around lines 1 - 31, The file docs/scheduler/overview.md is currently 31 lines, exceeding the 30-line maximum requirement for non-index markdown files under docs/. Reduce the file to 30 lines or fewer by either removing one blank line between sections, condensing one of the bullet points slightly, or moving the entire Anchors section (including the ## Anchors header and the four anchor file references) to a separate sibling document that can be referenced from the main overview.Source: Coding guidelines
docs/sub-agents/overview.md (1)
1-31:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winKeep both overview docs within the 30-line limit.
As per coding guidelines, non-index markdown files under
docs/must stay at 30 lines or fewer; both files are currently 31 lines.
docs/sub-agents/overview.md#L1-L31: remove one blank line or move one subsection into a sibling doc.docs/dreaming/overview.md#L1-L31: remove one blank line or move one subsection into a sibling doc.🤖 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/sub-agents/overview.md` around lines 1 - 31, Both documentation files exceed the 30-line limit for non-index markdown files under docs/ and must be reduced. In docs/sub-agents/overview.md (lines 1-31), reduce the content to 30 lines or fewer by either removing one blank line or moving one subsection (such as the Anchors section) to a related sibling document. In docs/dreaming/overview.md (lines 1-31), apply the same approach to reduce that file to 30 lines or fewer. Choose the same reduction strategy (blank line removal or subsection relocation) for both files to maintain consistency.Source: Coding guidelines
🧹 Nitpick comments (1)
docs/agent-events/streams.md (1)
18-18: ⚡ Quick winReplace the abbreviated source anchor.
.../transcript/route.tsis ambiguous and makes the source reference harder to follow. Spell out the full path so the doc stays precise and navigable.♻️ Suggested edit
-Source: `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts`; `.../transcript/route.ts`; `server/agent-event-transcript.ts`; `hooks/use-agent-event-live-transcript.ts`. +Source: `apps/api/app/api/agents/[agentId]/events/[eventId]/stream/route.ts`; `apps/api/app/api/agents/[agentId]/events/[eventId]/transcript/route.ts`; `server/agent-event-transcript.ts`; `hooks/use-agent-event-live-transcript.ts`.🤖 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/agent-events/streams.md` at line 18, In the Source reference line, the path `.../transcript/route.ts` is abbreviated and ambiguous, making it difficult to navigate the documentation. Replace this abbreviated path with the complete full path to the transcript route file so that readers can easily locate the exact source file being referenced. Ensure all source file references in the line are fully qualified paths rather than abbreviated versions.
🤖 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 `@scripts/docs-index.ts`:
- Around line 225-233: The shouldGenerateIndex() function only returns true for
directories with more than one non-index markdown file, which means a directory
that previously had a generated index.md can become stale if files are removed.
Modify the condition to also return true if a directory already contains an
existing index.md file, ensuring that previously generated indexes continue to
be validated and potentially updated or cleaned up, even if the directory no
longer meets the multi-file threshold.
---
Outside diff comments:
In `@docs/agent-events/overview.md`:
- Around line 27-31: The file docs/agent-events/overview.md exceeds the
repository rule of 30 lines maximum for non-index markdown files under docs/.
Reduce the file to 30 lines or fewer by removing the trailing blank line and/or
trimming the body content to comply with the documentation guidelines.
In `@docs/scheduler/overview.md`:
- Around line 1-31: The file docs/scheduler/overview.md is currently 31 lines,
exceeding the 30-line maximum requirement for non-index markdown files under
docs/. Reduce the file to 30 lines or fewer by either removing one blank line
between sections, condensing one of the bullet points slightly, or moving the
entire Anchors section (including the ## Anchors header and the four anchor file
references) to a separate sibling document that can be referenced from the main
overview.
In `@docs/sub-agents/overview.md`:
- Around line 1-31: Both documentation files exceed the 30-line limit for
non-index markdown files under docs/ and must be reduced. In
docs/sub-agents/overview.md (lines 1-31), reduce the content to 30 lines or
fewer by either removing one blank line or moving one subsection (such as the
Anchors section) to a related sibling document. In docs/dreaming/overview.md
(lines 1-31), apply the same approach to reduce that file to 30 lines or fewer.
Choose the same reduction strategy (blank line removal or subsection relocation)
for both files to maintain consistency.
---
Nitpick comments:
In `@docs/agent-events/streams.md`:
- Line 18: In the Source reference line, the path `.../transcript/route.ts` is
abbreviated and ambiguous, making it difficult to navigate the documentation.
Replace this abbreviated path with the complete full path to the transcript
route file so that readers can easily locate the exact source file being
referenced. Ensure all source file references in the line are fully qualified
paths rather than abbreviated versions.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bb9bc861-7bc2-4a0a-b750-a6e2d60f349e
📒 Files selected for processing (138)
.github/PULL_REQUEST_TEMPLATE.mdAGENTS.mdCONTRIBUTING.mdREADME.mddocs/ARCHITECTURE.mddocs/SLACK_INTEGRATION.mddocs/adr/0004-agent-skills-use-dedicated-sandboxes.mddocs/adr/index.mddocs/agent-chat/api-contract.mddocs/agent-chat/edge-cases.mddocs/agent-chat/flow.mddocs/agent-chat/index.mddocs/agent-chat/invariants.mddocs/agent-chat/overview.mddocs/agent-chat/state.mddocs/agent-chat/tests.mddocs/agent-creation-chat/edge-cases.mddocs/agent-creation-chat/flow.mddocs/agent-creation-chat/index.mddocs/agent-creation-chat/invariants.mddocs/agent-creation-chat/overview.mddocs/agent-creation-chat/state.mddocs/agent-creation-chat/tests.mddocs/agent-edit-chat/edge-cases.mddocs/agent-edit-chat/flow.mddocs/agent-edit-chat/index.mddocs/agent-edit-chat/invariants.mddocs/agent-edit-chat/overview.mddocs/agent-edit-chat/state.mddocs/agent-edit-chat/tests.mddocs/agent-events/concurrency-idempotency.mddocs/agent-events/event-kinds.mddocs/agent-events/index.mddocs/agent-events/overview.mddocs/agent-events/state-machine.mddocs/agent-events/streams.mddocs/agent-management/configuration-contract.mddocs/agent-management/edge-cases.mddocs/agent-management/flow.mddocs/agent-management/index.mddocs/agent-management/invariants.mddocs/agent-management/overview.mddocs/agent-management/product-shell.mddocs/agent-management/state.mddocs/agent-management/tests.mddocs/agent-memory/index.mddocs/agent-memory/overview.mddocs/agent-memory/sandbox-files-contract.mddocs/agent-skills/index.mddocs/agent-skills/package-lifecycle.mddocs/agent-skills/runtime.mddocs/auth-account/index.mddocs/auth-account/otp-flow.mddocs/auth-account/overview.mddocs/budgets/accounting.mddocs/budgets/index.mddocs/budgets/overview.mddocs/cache-revalidation/cache-map.mddocs/cache-revalidation/index.mddocs/cache-revalidation/overview.mddocs/cache-revalidation/revalidation-flow.mddocs/channels-slack/channel-contract.mddocs/channels-slack/index.mddocs/channels-slack/overview.mddocs/connections/connector-authoring.mddocs/connections/credential-taxonomy.mddocs/connections/index.mddocs/connections/overview.mddocs/data/core-tables.mddocs/data/index.mddocs/data/migrations.mddocs/dreaming/overview.mddocs/email-templates/components.mddocs/email-templates/index.mddocs/email-templates/overview.mddocs/email-templates/sending.mddocs/heartbeat/overview.mddocs/index.mddocs/inference/index.mddocs/inference/provider-authoring.mddocs/inference/providers.mddocs/launch-video/index.mddocs/launch-video/manifest.mddocs/launch-video/overview.mddocs/launch-video/rendering.mddocs/marketing-site/content.mddocs/marketing-site/index.mddocs/marketing-site/overview.mddocs/marketing-site/routing.mddocs/platform/env-matrix.mddocs/platform/index.mddocs/platform/routing.mddocs/platform/test-matrix.mddocs/platform/workspaces.mddocs/realtime-turns/edge-cases.mddocs/realtime-turns/flow.mddocs/realtime-turns/index.mddocs/realtime-turns/invariants.mddocs/realtime-turns/overview.mddocs/realtime-turns/runtime-spec.mddocs/realtime-turns/state.mddocs/realtime-turns/tests.mddocs/runtime-cache/index.mddocs/runtime-cache/overview.mddocs/runtime-cache/redis-requirements.mddocs/scheduler/index.mddocs/scheduler/overview.mddocs/scheduler/recovery.mddocs/scheduler/schedule-contract.mddocs/security-edge/botid-contracts.mddocs/security-edge/index.mddocs/security-edge/overview.mddocs/security-edge/proxy-rules.mddocs/simplification-plan-agent-workflows.mddocs/sub-agents/index.mddocs/sub-agents/invocation-events.mddocs/sub-agents/overview.mddocs/tool-sandboxes/index.mddocs/tool-sandboxes/manifest-authoring.mddocs/tool-sandboxes/overview.mddocs/tools/catalog.mddocs/tools/index.mddocs/tools/maintainer-tool-authoring.mddocs/tools/reconnect-and-audit.mddocs/ui-system/ai-elements.mddocs/ui-system/components.mddocs/ui-system/index.mddocs/ui-system/overview.mddocs/ui-system/product-shell.mddocs/waitlist/index.mddocs/waitlist/overview.mddocs/waitlist/status-transitions.mddocs/workflow-runtime/extension-guide.mddocs/workflow-runtime/index.mddocs/workflow-runtime/overview.mdpackage.jsonpackages/shared/content/blog/posts.tsscripts/docs-index.ts
💤 Files with no reviewable changes (3)
- docs/simplification-plan-agent-workflows.md
- docs/SLACK_INTEGRATION.md
- docs/ARCHITECTURE.md
Comment on lines
+225
to
+233
| function shouldGenerateIndex( | ||
| directory: DocsDirectory, | ||
| docsRoot: string | ||
| ): boolean { | ||
| return ( | ||
| directory.absolutePath === docsRoot || | ||
| collectNonIndexMarkdownFiles(directory).length > 1 | ||
| ) | ||
| } |
There was a problem hiding this comment.
Keep existing folder indexes under validation.
shouldGenerateIndex() only tracks directories with more than one non-index doc, so a folder that once had a generated index.md can drop to one file and then stop being rewritten or checked. That leaves stale generated indexes behind and breaks the “generated indexes stay authoritative” contract.
🤖 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 `@scripts/docs-index.ts` around lines 225 - 233, The shouldGenerateIndex()
function only returns true for directories with more than one non-index markdown
file, which means a directory that previously had a generated index.md can
become stale if files are removed. Modify the condition to also return true if a
directory already contains an existing index.md file, ensuring that previously
generated indexes continue to be validated and potentially updated or cleaned
up, even if the directory no longer meets the multi-file threshold.
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
Validation
Note: pnpm verify was not rerun because this workspace still lacks .env.local / DATABASE_URL. The shell also warns that Node is v22.21.0 while the repo declares >=24.
Summary by CodeRabbit
Documentation
Chores