Skip to content

Comments

chore: move docs for cleaner nav#4199

Closed
NathanFlurry wants to merge 4559 commits intomainfrom
02-12-chore_move_docs_for_cleaner_nav
Closed

chore: move docs for cleaner nav#4199
NathanFlurry wants to merge 4559 commits intomainfrom
02-12-chore_move_docs_for_cleaner_nav

Conversation

@NathanFlurry
Copy link
Member

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

NathanFlurry and others added 30 commits January 12, 2026 16:48
…3857)

### TL;DR

Improved inspector connection handling with better endpoint discovery and error handling.

### What changed?

- Added a new `getInspectorClientEndpoint` function that attempts to discover the correct client endpoint URL by checking metadata
- Fixed the KV key reference in `engine-data-provider.tsx` to use `KV_KEYS.INSPECTOR_TOKEN` instead of the entire `KV_KEYS` object
- Enhanced the connection process in `inspector-root.tsx` to use the new endpoint discovery function
- Added proper metadata schema validation using Zod
- Improved error handling for inspector connections

### How to test?

1. Attempt to connect to an inspector URL in the UI
2. Verify that the connection works with both direct URLs and URLs that require endpoint discovery
3. Test with invalid URLs to ensure proper error handling
4. Verify that the inspector token is correctly retrieved from KV storage

### Why make this change?

This change improves the reliability of connecting to inspector endpoints by implementing a discovery mechanism that can find the correct client endpoint URL. It handles various URL formats and validates the connection properly, making the inspector connection process more robust and user-friendly.
### TL;DR

Added command history functionality to the actor console input.

### What changed?

- Added state management for command history in `actor-console-input.tsx` using `useState` hooks
- Implemented up/down arrow key navigation through previously executed commands
- Added new props to the `ReplInput` component to handle history navigation
- Added keyboard event handlers for ArrowUp and ArrowDown keys

### How to test?

1. Open the actor console
2. Enter and execute multiple commands
3. Press the up arrow key to cycle through previously executed commands (newest to oldest)
4. Press the down arrow key to navigate forward through the history
5. Verify that pressing down at the end of history clears the input

### Why make this change?

This improves the developer experience when working with the actor console by allowing users to easily recall and reuse previously executed commands, similar to how terminal interfaces work. This saves time and reduces errors when users need to repeat or modify previous commands.
### TL;DR

Fixed a bug in the guard connectable inspector by improving error handling when token or metadata is missing.

### What changed?

- Reordered the destructured variables in the `useActorInspectorData` hook for better readability
- Enhanced the error condition check to verify that both `token` and `metadata` exist before rendering content
- Previously, the component only checked `isError` but now it also checks for the existence of required data

### How to test?

1. Navigate to a page with the actor inspector component
2. Test scenarios where token or metadata might be undefined:
   - Test with invalid actor IDs
   - Test with network failures
   - Test with partial data responses
3. Verify that the error handling works correctly and the component doesn't attempt to render with missing data

### Why make this change?

This change prevents potential runtime errors that could occur when the component tries to use `token` or `metadata` that might be undefined. The previous implementation only checked for explicit errors but didn't account for missing data, which could lead to unexpected behavior or crashes.
# Temporarily Disable Pagination and Update Connection Dialogs

### TL;DR

Temporarily disabled pagination in the engine data provider and updated connection dialogs with improved region selection and environment variable handling.

### What changed?

- Temporarily disabled pagination in the engine data provider
- Changed default mode from "serverfull" to "serverless" in connection dialogs
- Fixed region selection to use region name instead of ID in Railway and manual connection frames
- Added `RIVET_ENDPOINT` environment variable to Vercel template
- Added a new "variables" step to the Vercel connection flow
- Updated UI labels in the runner config toggle group (changed "Dedicated" to "Runners")
- Added support for prefixless endpoint environment variables

### How to test?

1. Verify that pagination is disabled in the engine data provider
2. Check that connection dialogs default to "serverless" mode
3. Confirm region selection works correctly in Railway and manual connection frames
4. Test the Vercel connection flow with the new "variables" step
5. Verify environment variables are correctly displayed with both prefixed and prefixless options

### Why make this change?

These changes improve the connection experience by defaulting to serverless mode, which is more appropriate for most users. The pagination disabling is a temporary fix for an issue that needs to be addressed later. The environment variable improvements ensure better compatibility with various deployment platforms, particularly Vercel, by providing both prefixed and prefixless options.
### TL;DR

Fixed a typo in the `prefixlessEndpoint` parameter and improved the Actor Inspector UI with better loading states and version information.

### What changed?

- Fixed a typo in the `EnvVariables` component, renaming `prefixlessEndpint` to `prefixlessEndpoint`
- Added loading spinners to Actor Inspector tabs (Connections, Events, State)
- Added version information display in the Actor General tab
- Created a new `ActorRunner` component to display runner information
- Improved error handling and UI feedback for outdated RivetKit versions
- Exported the `Row` component from `runners-table.tsx` for reuse
- Enhanced the Inspector connection status UI with better feedback
- Added minimum version requirement check for RivetKit (2.0.35)

### How to test?

1. Verify the environment variables are correctly displayed in the Vercel connection form
2. Test the Actor Inspector with both up-to-date and outdated RivetKit versions
3. Check that loading states display correctly in the Actor Inspector tabs
4. Verify that version information appears in the Actor General tab
5. Confirm that runner information displays properly in the Actor Runner component

### Why make this change?

These changes improve the user experience by providing better feedback during loading states and clearer error messages when using outdated versions of RivetKit. The typo fix ensures consistent naming throughout the codebase, and the addition of version information helps users understand compatibility requirements. The enhanced UI feedback makes it easier for users to understand the connection status of the Actor Inspector.
### TL;DR

Swapped pagination functionality between actors and another endpoint.

### What changed?

- Re-enabled pagination for actors by uncommenting the code that checks if the number of actors is less than `RECORDS_PER_PAGE` and returns the pagination cursor
- Temporarily disabled pagination for another endpoint by commenting out the cursor return and adding a FIXME comment with the same attribution (@NathanFlurry)

### How to test?

1. Navigate to a page that displays actors
2. Verify that pagination works correctly when there are more actors than fit on a single page
3. Check that the other endpoint (which had pagination disabled) doesn't attempt to load additional pages

### Why make this change?

It appears that pagination was temporarily disabled for actors but should now be re-enabled, while pagination for another endpoint needs to be temporarily disabled. This change ensures the correct pagination behavior for each endpoint.
### TL;DR

Improved actor inspector reliability by updating query retry logic and fixing the inspector guard component.

### What changed?

- Added retry configuration to actor metadata query options:
  - Set `retry: 0` to prevent automatic retries
  - Added `retryDelay: 5_000` to wait 5 seconds between retries
  - Set `refetchInterval` to periodically refresh data (5 seconds in one case, 1 second in another)
- Moved query configuration from the component level to the query options
- Fixed the `InspectorGuard` component to properly handle error states and data availability:
  - Now checks for missing data or errors before checking loading state
  - Shows the `OutdatedInspector` component when data is unavailable or there's an error

### How to test?

1. Open the actor inspector for any actor
2. Verify that the inspector loads correctly
3. Temporarily disconnect from the network and verify the inspector shows the outdated state
4. Reconnect and verify the inspector recovers properly

### Why make this change?

This change improves the reliability of the actor inspector by ensuring proper error handling and implementing a consistent retry strategy. The updated logic ensures users see appropriate feedback when the inspector can't connect to an actor, and the periodic refetching helps maintain up-to-date information.
### TL;DR

Added error reporting for runner configuration health checks using PostHog.

### What changed?

- Extended the `queryMeta` interface to include a new `reportType` field
- Added PostHog error reporting in the query cache's `onError` handler when a `reportType` is specified
- Implemented the error reporting specifically for runner configuration health checks by setting `reportType: "runner-config-serverless-health-check"` in the connection check query

### How to test?

1. Trigger a failed runner configuration health check
2. Verify that PostHog captures an event with type "runner-config-health-check" containing the error details and query key

### Why make this change?

This change improves error tracking for runner configuration health checks, allowing us to better understand and diagnose issues users encounter when setting up serverless runners. By capturing these errors in PostHog, we can analyze patterns and improve the configuration experience.
### TL;DR

Enable authentication requirement for Plain chat widget.

### What changed?

Added the `requireAuthentication: true` parameter to the Plain.init configuration in the frontend Vite cloud config file.

### How to test?

1. Load the application in cloud environment
2. Verify that the Plain chat widget requires authentication before allowing users to interact with it
3. Confirm that unauthenticated users cannot access the chat functionality

### Why make this change?

This change enhances security by ensuring that only authenticated users can access the live chat support feature, preventing potential abuse from anonymous users and providing better user tracking for support interactions.
### TL;DR

Fixed the DSN format by swapping the token and engine namespace positions.

### What changed?

Corrected the DSN (Data Source Name) string format in the `useRivetDsn` hook. The previous implementation incorrectly placed the token before the engine namespace in the DSN URL. This PR swaps their positions to follow the correct format: `https://{engineNamespace}:{token}@{endpoint}`.

### How to test?

1. Verify that connections to the data provider work correctly with the new DSN format
2. Test both serverless and admin token scenarios to ensure proper authentication
3. Check that endpoints with both HTTP and HTTPS protocols are handled correctly

### Why make this change?

The incorrect DSN format was likely causing authentication issues when connecting to the data provider. This fix ensures that the DSN follows the expected format where the engine namespace comes before the token in the URL, which is required for proper authentication and connection to the service.
### TL;DR

Added validation to ensure serverless endpoints end with `/api/rivet`

### What changed?

Modified the `endpointSchema` validation in `connect-manual-serverless-form.tsx` to require that endpoints must end with `/api/rivet`. This adds an additional validation check beyond the existing requirements that the endpoint is non-empty and a valid URL.

### How to test?

1. Navigate to the manual serverless connection form
2. Try entering various endpoint URLs:
   - A URL that doesn't end with `/api/rivet` should show the new validation error
   - A URL that properly ends with `/api/rivet` should pass validation
3. Verify the error message "Endpoint must end with /api/rivet" appears when validation fails

### Why make this change?

This validation ensures users provide correctly formatted endpoints that will work with our API. Adding this constraint prevents connection errors that would occur when users attempt to connect with incompatible endpoint formats.
jog1t and others added 19 commits February 10, 2026 19:35
# Description

This PR removes the unused `waitForNames` method from the `QueueManager` class and reorganizes imports across several files to improve code organization. It also fixes the Drizzle ORM exports by creating a new `sqlite-core.ts` file that re-exports specific functions from the Drizzle ORM package, rather than exporting everything directly.

Additionally, the PR updates the `createFileSystemOrMemoryDriver` function to accept an options object instead of separate parameters, making the API more flexible and consistent.

## Type of change

- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

The changes have been tested with the existing test suite to ensure that the removal of the unused method and the reorganization of imports don't break any functionality.

## Checklist:

- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my feature works
- [x] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
…eout (#4171)

# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
# Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] This change requires a documentation update

## How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

## Checklist:

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
@railway-app railway-app bot temporarily deployed to rivet-frontend / rivet-pr-4199 February 16, 2026 08:01 Destroyed
@railway-app
Copy link

railway-app bot commented Feb 16, 2026

🚅 Deployed to the rivet-pr-4199 environment in rivet-frontend

Service Status Web Updated (UTC)
frontend-cloud 🕐 Queued (View Logs) Web Feb 16, 2026 at 8:01 am
website 🕐 Queued (View Logs) Web Feb 16, 2026 at 8:01 am
ladle 🕐 Queued (View Logs) Web Feb 16, 2026 at 8:01 am
mcp-hub 🕐 Queued (View Logs) Web Feb 16, 2026 at 8:01 am
frontend-inspector 🕐 Queued (View Logs) Web Feb 16, 2026 at 8:01 am

@graphite-app graphite-app bot changed the base branch from 02-12-chore_move_k8s_in_to_deploy_folder to main February 16, 2026 08:01
@graphite-app graphite-app bot closed this Feb 16, 2026
Copy link
Member Author

NathanFlurry commented Feb 16, 2026


How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

@claude
Copy link

claude bot commented Feb 16, 2026

PR Review: Documentation Reorganization

Summary

This PR reorganizes documentation and deployment files for cleaner navigation. The changes include:

  • Moving K8s deployment files from k8s/ to deploy/k8s/
  • Consolidating internal documentation from scattered locations (docs/engine/, engine/contrib-docs/, contrib-docs/, rivetkit-typescript/contrib-docs/) into a unified docs-internal/ directory
  • Adding a new section to CLAUDE.md about agent notes storage
  • Adding new content to docs-internal/engine/GUARD.md explaining Gateway proxying for actors

Files Changed: 35 files (+27/-41 lines)
Type: Refactoring/Organization


Positive Aspects

Clear organizational improvement - Consolidating documentation from multiple scattered locations (docs/engine/, engine/contrib-docs/, contrib-docs/, rivetkit-typescript/contrib-docs/) into a single docs-internal/ directory significantly improves discoverability.

Logical separation - The deploy/k8s/ structure better reflects that K8s files are deployment artifacts, not core codebase.

Documentation enhancement - The new content in GUARD.md provides valuable context about Gateway proxying, WebSocket routing, and hibernation that was previously missing.

Agent-friendly changes - The new CLAUDE.md section about .agents/notes/ storage provides clear guidance for AI agents working with the codebase.


Issues & Concerns

1. Missing Broken Link Updates ⚠️

The PR moves many files but may not update all references to them:

  • K8s documentation: Any references to k8s/ paths in READMEs, scripts, or other docs should be updated to deploy/k8s/
  • Internal doc cross-references: Files like HIBERNATING_WS.md referenced in the new GUARD.md content, and potentially other internal docs that cross-reference each other, need verification
  • CLAUDE.md references: The CLAUDE.md file itself may have references to old doc paths that need updating

Recommendation: Run a comprehensive search for broken links:

# Check for references to old paths
rg "docs/engine/" --type md
rg "engine/contrib-docs/" --type md
rg "contrib-docs/" --type md
rg "rivetkit-typescript/contrib-docs/" --type md
rg "k8s/" --type md --type yaml --type sh

2. Typo in Path Name

There's a typo in the directory structure:

  • docs-internal/engine/design-choicse/EMBEDDED_KV.md

Should be design-choices not design-choicse.

Recommendation: Fix the typo in the directory name.

3. Incomplete PR Description 📝

The PR template sections are not filled out:

  • No description of what changes were made
  • No type of change checked
  • No testing information
  • Checklist items not completed

Recommendation: Fill out the PR template to provide context for reviewers and future reference.

4. Git History Consideration 🤔

With 100 commits in this PR, the history may be noisy. Since this is primarily a file reorganization:

Recommendation: Consider squashing commits to create a clean history, especially if many commits are just "move file X" operations.

5. Documentation about the Documentation 📚

The reorganization is significant but there's no migration guide or explanation:

Recommendation: Consider adding a note in docs-internal/README.md or similar explaining:

  • The new structure
  • Why it was reorganized
  • How to find specific topics

6. GUARD.md Content Quality ✍️

The new content added to GUARD.md has some minor writing issues:

Line 92-93:

"Rivet Engine transmits HTTP requests and WebSocket messages via the runner protocol to the actor's corresponding runner's WebSocket"

This is awkwardly phrased with "runner's runner's". Consider:

"Rivet Engine transmits HTTP requests and WebSocket messages via the runner protocol to the corresponding actor runner's WebSocket"

Line 101:

"The Gateway allows us to implement hibernatable WebSockets"

The phrase "allows us to" is somewhat informal for technical documentation. Consider:

"The Gateway enables hibernatable WebSockets"


Testing Recommendations

  1. Verify all internal doc links still resolve correctly
  2. Test any scripts that reference moved K8s files
  3. Ensure CI/CD pipelines that may reference old paths still work
  4. Verify the website build succeeds (if it pulls from these doc locations)

Security & Performance

✅ No security concerns - this is purely organizational.
✅ No performance impact - file moves don't affect runtime behavior.


Verdict

This is a valuable cleanup that will improve maintainability. However, it needs:

  1. MUST FIX: Fix the design-choicsedesign-choices typo
  2. SHOULD FIX: Update all references to moved files (search for broken links)
  3. SHOULD FIX: Complete the PR description
  4. NICE TO HAVE: Minor writing improvements in GUARD.md
  5. NICE TO HAVE: Add a README explaining the new docs-internal structure

Overall: Approve with requested changes ✅ (pending the MUST FIX items)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants