docs: reset Relay documentation to living guides - #230
Merged
Conversation
CrimsonSoul
enabled auto-merge
August 7, 2026 16:11
📝 WalkthroughWalkthroughThe pull request aligns Relay documentation with the current architecture, security controls, workspace model, Knowledge behavior, Relay Web operation, and screenshot set. It also removes obsolete implementation plans and the ChangesCurrent architecture and runtime
Security and operational guidance
Workspace and interaction guidance
README and planning cleanup
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@docs/architecture.md`:
- Around line 113-117: Update the “Server/client presence” section in
architecture.md to accurately describe Relay Web presence behavior: remove the
claim that Relay Web sessions write client_presence heartbeat records, and state
that only desktop clients write those records unless the implementation is
intentionally changed. Keep the description of server subscriptions and the
authorization disclaimer consistent with the actual flow.
In `@README.md`:
- Around line 13-14: Update the workspace naming in the README so the Snapshot
list and the Core Features section use the same canonical label, replacing the
inconsistent Status/Service Status wording while preserving the existing
workspace description.
🪄 Autofix
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: CHILL
Plan: Pro Plus
Run ID: 94c7e3f2-fe74-4b24-92b2-3e2eda582800
⛔ Files ignored due to path filters (12)
docs/screenshots/alerts.pngis excluded by!**/*.pngdocs/screenshots/cloud-status.pngis excluded by!**/*.pngdocs/screenshots/compose.pngis excluded by!**/*.pngdocs/screenshots/data-manager.pngis excluded by!**/*.pngdocs/screenshots/knowledge.pngis excluded by!**/*.pngdocs/screenshots/oncall-popout.pngis excluded by!**/*.pngdocs/screenshots/oncall.pngis excluded by!**/*.pngdocs/screenshots/people.pngis excluded by!**/*.pngdocs/screenshots/radar.pngis excluded by!**/*.pngdocs/screenshots/servers.pngis excluded by!**/*.pngdocs/screenshots/settings-modal.pngis excluded by!**/*.pngdocs/screenshots/toast.pngis excluded by!**/*.png
📒 Files selected for processing (97)
.gitignoreREADME.mddocs/DESIGN.mddocs/DEVELOPMENT.mddocs/README.mddocs/SECURITY.mddocs/architecture.mddocs/knowledge-base.mddocs/relay-web.mddocs/superpowers/plans/2026-05-28-alert-reminders.mddocs/superpowers/plans/2026-05-29-alert-reminder-management.mddocs/superpowers/plans/2026-05-29-critical-reminder-visual.mddocs/superpowers/plans/2026-06-01-cohesive-reminder-popup.mddocs/superpowers/plans/2026-06-13-dynatrace-popouts.mddocs/superpowers/plans/2026-07-14-knowledge-pdf-link-navigation.mddocs/superpowers/plans/2026-07-14-read-only-pdf-knowledge-base.mddocs/superpowers/plans/2026-07-15-compact-shell-and-dynatrace-ticket-references.mddocs/superpowers/plans/2026-07-15-managed-knowledge-base.mddocs/superpowers/plans/2026-07-15-privileged-access-foundation.mddocs/superpowers/plans/2026-07-15-remote-operator-administration.mddocs/superpowers/plans/2026-07-15-resumable-pocketbase-knowledge-uploads.mddocs/superpowers/plans/2026-07-17-continuous-wiki-pdf-reader.mddocs/superpowers/plans/2026-07-17-role-accounts-and-operator-retirement.mddocs/superpowers/plans/2026-07-17-unified-knowledge-workspace-and-notes-removal.mddocs/superpowers/plans/2026-07-18-collapsible-wiki-library.mddocs/superpowers/plans/2026-07-18-compact-wiki-library-drawer.mddocs/superpowers/plans/2026-07-18-fixed-role-usernames.mddocs/superpowers/plans/2026-07-18-privileged-pairing-layout-containment.mddocs/superpowers/plans/2026-07-18-relay-motion-modal-system.mddocs/superpowers/plans/2026-07-18-wiki-management-operational-alignment.mddocs/superpowers/plans/2026-07-20-cloud-status-freshness-links.mddocs/superpowers/plans/2026-07-20-cloud-status-outage-toasts.mddocs/superpowers/plans/2026-07-20-owner-setup-username.mddocs/superpowers/plans/2026-07-20-pdf-outline-quality.mddocs/superpowers/plans/2026-07-20-relay-web-backup.mddocs/superpowers/plans/2026-07-21-startup-performance.mddocs/superpowers/plans/2026-07-22-persistent-windows-runtime-bootstrap.mddocs/superpowers/plans/2026-07-23-wiki-upload-recovery-and-cover-polish.mddocs/superpowers/plans/2026-07-28-radar-page-and-navigation.mddocs/superpowers/plans/2026-07-29-radar-indicator-and-original-page-link.mddocs/superpowers/plans/2026-07-29-radar-queue-notifications-and-sidebar-indicator.mddocs/superpowers/plans/2026-07-29-radar-warning-and-critical-toasts.mddocs/superpowers/plans/2026-07-31-finding-only-scanner-gates.mddocs/superpowers/plans/2026-07-31-test-branch-security-enforcement.mddocs/superpowers/plans/2026-08-03-juniper-mist-cloud-status.mddocs/superpowers/plans/2026-08-05-relay-alerts-action-hierarchy.mddocs/superpowers/plans/2026-08-05-relay-cloud-degradation-threshold.mddocs/superpowers/plans/2026-08-05-relay-navigation-and-triage.mddocs/superpowers/plans/2026-08-05-relay-search-record-navigation.mddocs/superpowers/plans/2026-08-06-all-tab-toolbar-search-alignment.mddocs/superpowers/specs/2026-05-28-alert-reminders-design.mddocs/superpowers/specs/2026-05-29-alert-reminder-management-design.mddocs/superpowers/specs/2026-05-29-critical-reminder-visual-design.mddocs/superpowers/specs/2026-06-01-cohesive-reminder-popup-design.mddocs/superpowers/specs/2026-06-13-dynatrace-popouts-design.mddocs/superpowers/specs/2026-07-13-passwordless-operator-profiles-design.mddocs/superpowers/specs/2026-07-14-knowledge-pdf-links-design.mddocs/superpowers/specs/2026-07-14-read-only-pdf-knowledge-base-design.mddocs/superpowers/specs/2026-07-15-compact-shell-and-dynatrace-ticket-references-design.mddocs/superpowers/specs/2026-07-15-privileged-operators-and-knowledge-management-design.mddocs/superpowers/specs/2026-07-15-resumable-pocketbase-knowledge-uploads-design.mddocs/superpowers/specs/2026-07-17-role-accounts-and-knowledge-workspace-design.mddocs/superpowers/specs/2026-07-18-collapsible-wiki-library-design.mddocs/superpowers/specs/2026-07-18-compact-wiki-library-drawer-design.mddocs/superpowers/specs/2026-07-18-compose-alerts-operational-frame-design.mddocs/superpowers/specs/2026-07-18-compose-toolbar-avatar-alignment-design.mddocs/superpowers/specs/2026-07-18-fixed-role-usernames-design.mddocs/superpowers/specs/2026-07-18-knowledge-directory-typography-design.mddocs/superpowers/specs/2026-07-18-knowledge-splash-square-nav-design.mddocs/superpowers/specs/2026-07-18-relay-motion-modal-system-design.mddocs/superpowers/specs/2026-07-18-wiki-management-operational-alignment-design.mddocs/superpowers/specs/2026-07-19-wiki-exact-fuzzy-search-design.mddocs/superpowers/specs/2026-07-19-wiki-first-class-polish-and-reliability-design.mddocs/superpowers/specs/2026-07-20-cloud-status-freshness-links-design.mddocs/superpowers/specs/2026-07-20-cloud-status-outage-toasts-design.mddocs/superpowers/specs/2026-07-20-owner-setup-username-design.mddocs/superpowers/specs/2026-07-20-pdf-outline-quality-design.mddocs/superpowers/specs/2026-07-20-relay-web-backup-design.mddocs/superpowers/specs/2026-07-21-startup-performance-design.mddocs/superpowers/specs/2026-07-22-persistent-windows-runtime-design.mddocs/superpowers/specs/2026-07-23-wiki-upload-recovery-and-cover-polish-design.mddocs/superpowers/specs/2026-07-28-radar-page-and-navigation-design.mddocs/superpowers/specs/2026-07-29-radar-indicator-and-original-page-link-design.mddocs/superpowers/specs/2026-07-29-radar-queue-notifications-and-sidebar-indicator-design.mddocs/superpowers/specs/2026-07-29-radar-warning-and-critical-toast-design.mddocs/superpowers/specs/2026-07-31-finding-only-scanner-gates-design.mddocs/superpowers/specs/2026-07-31-relay-web-feature-parity-design.mddocs/superpowers/specs/2026-07-31-retire-mac-releases-design.mddocs/superpowers/specs/2026-07-31-test-branch-security-enforcement-design.mddocs/superpowers/specs/2026-08-03-juniper-mist-cloud-status-design.mddocs/superpowers/specs/2026-08-04-compose-teams-handoff-design.mddocs/superpowers/specs/2026-08-05-relay-tab-operator-workflows-design.mddocs/superpowers/specs/2026-08-06-all-tab-toolbar-search-alignment-design.mddocs/ui-mockups/full-redesign/README.mddocs/ui-mockups/full-redesign/app.jsdocs/ui-mockups/full-redesign/index.htmldocs/ui-mockups/full-redesign/styles.css
💤 Files with no reviewable changes (37)
- .gitignore
- docs/superpowers/plans/2026-05-29-alert-reminder-management.md
- docs/superpowers/plans/2026-07-21-startup-performance.md
- docs/superpowers/plans/2026-07-31-finding-only-scanner-gates.md
- docs/superpowers/plans/2026-07-15-privileged-access-foundation.md
- docs/superpowers/plans/2026-07-31-test-branch-security-enforcement.md
- docs/superpowers/plans/2026-06-13-dynatrace-popouts.md
- docs/superpowers/plans/2026-07-18-fixed-role-usernames.md
- docs/superpowers/plans/2026-07-18-collapsible-wiki-library.md
- docs/superpowers/plans/2026-07-18-compact-wiki-library-drawer.md
- docs/superpowers/plans/2026-07-18-wiki-management-operational-alignment.md
- docs/superpowers/plans/2026-07-15-remote-operator-administration.md
- docs/superpowers/plans/2026-07-23-wiki-upload-recovery-and-cover-polish.md
- docs/superpowers/plans/2026-06-01-cohesive-reminder-popup.md
- docs/superpowers/plans/2026-07-20-owner-setup-username.md
- docs/superpowers/plans/2026-07-28-radar-page-and-navigation.md
- docs/superpowers/plans/2026-07-20-cloud-status-outage-toasts.md
- docs/superpowers/plans/2026-07-20-relay-web-backup.md
- docs/superpowers/plans/2026-07-29-radar-warning-and-critical-toasts.md
- docs/superpowers/plans/2026-05-29-critical-reminder-visual.md
- docs/superpowers/plans/2026-07-15-resumable-pocketbase-knowledge-uploads.md
- docs/superpowers/plans/2026-07-17-role-accounts-and-operator-retirement.md
- docs/superpowers/plans/2026-07-15-compact-shell-and-dynatrace-ticket-references.md
- docs/superpowers/plans/2026-07-20-pdf-outline-quality.md
- docs/superpowers/plans/2026-07-15-managed-knowledge-base.md
- docs/superpowers/plans/2026-07-17-continuous-wiki-pdf-reader.md
- docs/superpowers/plans/2026-08-03-juniper-mist-cloud-status.md
- docs/superpowers/plans/2026-07-29-radar-queue-notifications-and-sidebar-indicator.md
- docs/superpowers/plans/2026-05-28-alert-reminders.md
- docs/superpowers/plans/2026-07-17-unified-knowledge-workspace-and-notes-removal.md
- docs/superpowers/plans/2026-08-05-relay-alerts-action-hierarchy.md
- docs/superpowers/plans/2026-07-14-knowledge-pdf-link-navigation.md
- docs/superpowers/plans/2026-07-14-read-only-pdf-knowledge-base.md
- docs/superpowers/plans/2026-07-20-cloud-status-freshness-links.md
- docs/superpowers/plans/2026-07-22-persistent-windows-runtime-bootstrap.md
- docs/superpowers/plans/2026-07-18-privileged-pairing-layout-containment.md
- docs/superpowers/plans/2026-07-29-radar-indicator-and-original-page-link.md
Comment on lines
+113
to
+117
| ### Server/client presence | ||
|
|
||
| - Connect to an existing Relay server URL | ||
| - Coordinate ordinary app-user authentication in the main process so the renderer connection, | ||
| enhanced Wiki search, PDF and cover clients, and reconnect sync do not independently spend the | ||
| server's authentication rate-limit budget | ||
| - Write a `client_presence` heartbeat every 30 seconds with the client hostname | ||
| - Hide the client-count sidebar block because it is server-only operator context | ||
| Desktop clients and Relay Web sessions write bounded heartbeat records. Server mode subscribes to | ||
| active client records and presents their sanitized host/browser labels; the server itself is not | ||
| counted. Presence is operational status, not an authorization mechanism. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C 6 'client_presence|heartbeat|host.*label|browser.*session|presence' \
src/main src/preload src/renderer src/shared docs/architecture.md docs/relay-web.md || trueRepository: CrimsonSoul/Relay
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '--- files mentioning client_presence or CLIENT_PRESENCE (non-test only) ---\n'
rg -n -C 8 'CLIENT_PRESENCE|client_presence|presenceLabel|getClientHostname|SERVER|subscription|event:|heartbeat' \
-g '!**/*.test.ts*' -g '!**/*.test.tsx' \
src/main src/preload src/renderer src/shared docs || true
printf '\n--- candidate source sizes ---\n'
for f in \
src/main/app/processLifecycle.ts \
src/main/web/routes/sessionRoutes.ts \
src/shared/IPC_CHANNELS.ts \
src/shared/webApi.ts \
src/renderer/src/runtime/webBridge/desktopFallbackApi.ts \
src/renderer/src/components/__tests__/Sidebar.test.tsx \
src/renderer/src/components/Sidebar.tsx \
src/renderer/src/components/__tests__/SettingsModal.lifecycle.test.tsx \
; do
[ -f "$f" ] && echo "$f: $(wc -l < "$f")"
doneRepository: CrimsonSoul/Relay
Length of output: 246
🏁 Script executed:
#!/bin/bash
Set -euo pipefail
printf '%s\n' '--- files mentioning client_presence or CLIENT_PRESENCE (non-test only) ---'
rg -n -C 8 'CLIENT_PRESENCE|client_presence|presenceLabel|getClientHostname|SERVER|subscription|event:|heartbeat' \
-g '!**/*.test.ts*' -g '!**/*.test.tsx' \
src/main src/preload src/renderer src/shared docs || true
printf '%s\n' '--- candidate source sizes ---'
for f in \
src/main/app/processLifecycle.ts \
src/main/web/routes/sessionRoutes.ts \
src/shared/IPC_CHANNELS.ts \
src/shared/webApi.ts \
src/renderer/src/runtime/webBridge/desktopFallbackApi.ts \
src/renderer/src/components/Sidebar.tsx \
; do
[ -f "$f" ] && echo "$f: $(wc -l < "$f")"
doneRepository: CrimsonSoul/Relay
Length of output: 50374
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- all non-test occurrences of key identifiers ---'
python3 - <<'PY'
import pathlib
patterns = ['client_presence', 'CLIENT_PRESENCE', 'presenceLabel', 'getClientHostname']
for path in pathlib.Path('src').rglob('*'):
if any(part.endswith('.test.ts') or part.endswith('.test.tsx') for part in path.parts):
continue
try:
text = path.read_text(errors='ignore')
except Exception:
continue
for i, line in enumerate(text.splitlines(), 1):
if not any(p in line for p in patterns):
continue
if any(s in text[max(0,i-200):i+200] for s in patterns):
print(f'{path}:{i} ...{line.strip()}...')
PY
printf '%s\n' '--- source slices ---'
for f in \
src/main/web/routes/sessionRoutes.ts \
src/shared/webApi.ts \
src/renderer/src/components/Sidebar.tsx \
src/renderer/src/runtime/webBridge/desktopFallbackApi.ts \
src/shared/webApi.ts \
src/main/pocketbase/schema/collectionCatalog.ts \
; do
if [ -f "$f" ]; then
echo "--- $f ---"
wc -l "$f"
rg -n -C 10 'client_presence|CLIENT_PRESENCE|presenceLabel|getClientHostname|events|heartbeat|cacheWrite|cacheRead|clientPresence' "$f" || true
fi
done
printf '%s\n' '--- heartbeat-related non-code files ---'
rg -n -C 8 '\bheartbeat\b|presenceLabel|Web ·' -g '!**/*.test.ts*' -g '!**/*.test.tsx' docs src/shared src/main/web src/main/app src/renderer/src 2>/dev/null | head -n 240 || trueRepository: CrimsonSoul/Relay
Length of output: 34860
Clarify which client_presence records Relay Web writes.
docs/architecture.md says Relay Web sessions write client_presence heartbeat records, but the current web-session flow only writes into WebSessionStore.presenceLabel and its SSE heartbeats go through /relay-api/v1/session/events, not client_presence. Update the architecture text, or move Relay Web heartbeats into client_presence and reflect that in docs/relay-web.md.
🤖 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.md` around lines 113 - 117, Update the “Server/client
presence” section in architecture.md to accurately describe Relay Web presence
behavior: remove the claim that Relay Web sessions write client_presence
heartbeat records, and state that only desktop clients write those records
unless the implementation is intentionally changed. Keep the description of
server subscriptions and the authorization disclaimer consistent with the actual
flow.
Comment on lines
+13
to
+14
| - Seven top-level workspaces: Compose, Alerts, On-Call, Knowledge, Status, Dynatrace Problems, and Dispatcher Radar | ||
| - Wiki, Contacts, and Servers grouped as retained destinations inside Knowledge |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use one workspace name consistently.
The Snapshot names the workspace Status, but the Core Features section names it Service Status on Line 36. Use the canonical product label in both places so readers do not interpret them as different workspaces.
🤖 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 `@README.md` around lines 13 - 14, Update the workspace naming in the README so
the Snapshot list and the Core Features section use the same canonical label,
replacing the inconsistent Status/Service Status wording while preserving the
existing workspace description.
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
Verification
npm test(183 unit files passed, 1 skipped; 4 cache files passed; 230 renderer files passed)npx prettier --check $(git ls-files "*.md")git diff --checkSummary by CodeRabbit