Repository navigation
feat(site): night shift identity, diagrams and the remote protocol page - #7
Merged
Merged
Conversation
Give the site the look of the tool it documents: amber phosphor on a raw-denim indigo ground, JetBrains Mono for headings and code and IBM Plex Sans for text, both self-hosted. The overalls motif carries the brand: the logo and favicon are a bib pocket holding the prompt, with two straps and brass rivets, and rivets replace the window buttons of the landing-page terminal, which runs one app as a CLI, a REPL and an MCP server. Printing uses the light palette whatever the screen theme. Replace the ASCII diagrams with inline SVG components that follow the theme and stay searchable: layering and execution phases on Architecture, the scoped-context tree, and the remote administration flow. src/components/diagrams/README.md describes their vocabulary. Add the social card the page metadata already referenced, rendered from src/assets/og-image.svg by npm run og:image. Fix content found along the way: - Architecture named an `IReplMiddleware` type that Repl does not have; middleware is registered with `app.Use(...)` - the Architecture table described Telnet as layered over WebSocket only and had no rows for Repl.Remote and Repl.Remote.Defaults - the pipeline stage list on Pipelines & Integration rendered its link as plain text
Remote Protocol (reference/remote-protocol) describes the experimental JSON-RPC 2.0 profile behind Repl.Remote for anyone writing a client: Content-Length framing, the methods, a one-shot call, a terminal session, error codes, cancellation, and security limits. Four drawings show the layers, one framed message, and both message sequences. Ten new diagrams illustrate existing pages: MCP surfaces, MCP interactivity modes, DI session scopes, source and output paging, process signals, middleware nesting, feedback streams, module reuse, hosted sessions, and agent discovery. Bracket.astro and MessageSequence.astro are shared building blocks, and metrics.ts measures diagram text from the CSS font sizes. Along the way: - The MCP tier table now says a prompt's own default is used in every mode before failing. - The DI lifetime table now names the BuildMcpServerOptions() exception.
Paged Results gains five visuals: - a decision tree that picks a ReplPageSource helper; - FromAsyncEnumerable reopening its stream for each page; - rows read when filtering in the query versus after the fetch; - what an offset and a keyset cursor make the store touch; - the MCP round trip of _replCursor and pageInfo. The three row diagrams share one cell vocabulary (cells.ts, CellRow, CellLegend) and a new rt-cell-kept class. That class gives a returned row a tinted fill, so it stays distinct from a row that was only read.
MCP revision 2026-07-28 changes how a server reaches back to its client: - SEP-2577 deprecates roots and sampling, along with logging. - SEP-2322 replaces server-initiated requests, elicitation's included, with multi round-trip requests, which Repl 0.12 has not adopted. MCP — Advanced now advises new applications against all three features. A caution at the top and one per section say what to use instead, and the capabilities table notes the status of each feature. Examples on the other MCP pages use the default PrefillThenFail mode and mark the elicitation and sampling modes as legacy. Also fixed: - The cookbook and the interactivity caution relied on IMcpClientRoots.IsAllowed, which Repl does not have. The cookbook section, renamed Restrict file paths, now checks paths against directories from the server's configuration and warns that the check does not resolve symbolic links. - MCP — Advanced now says that soft roots are set by the agent and that the server cannot see whether a person approved a destructive call. - PrefillThenFail and PrefillThenElicitation are now described as the code behaves: the prompt's default comes before failing, and elicitation falls back to sampling.
Cursor Patterns gains five visuals: - what page 2 returns after a row is inserted, with an offset, a keyset and a snapshot cursor; - what an offset and a keyset cursor make the store touch; - an external API page token passing through the handler; - one time window paged by count; - the cursor checks Repl makes and the ones only the handler can make. The samples now match the drawings and the checklist: - The offset, keyset and snapshot parsers refuse a cursor they cannot decode instead of starting over. - The snapshot is scoped to its owner. - The nextLink check pins scheme, host, port and collection path instead of a URL prefix. - The range cursor carries the last event's timestamp and id, so the next page starts strictly after it. - The checklist notes that the interactive pager skips Repl's cursor checks, and that a cursor carrying ids needs authenticated protection bound to its owner. Shared drawing helpers: - CellRow takes optional per-cell labels and draws the keyset seek mark. - cells.ts holds the lane layout of the three lane diagrams. - metrics.ts holds Bracket's layout, so its callers size their viewBox from it.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
The Configuration page said UseCliProfile() disables the REPL. In 0.12 no profile does: each one assigns InteractivePolicy.Auto. The Profiles section now covers: - what each profile changes, in a table: signal ownership and the exit command; - that UseDefaultInteractive() and UseCliProfile() behave the same; - how to ship a tool without a REPL: set InteractivePolicy.Prevent after the profile; - use cases for each profile, including the hosts where the embedded profile's signal setting matters; - that a profile is optional, and how chained profiles combine; - why to call the profile before Options(...) and UseSpectreConsole(). Other pages said the REPL, Tab completion or the exit command depend on UseDefaultInteractive(). They now agree with the Profiles section.
…note Hosting Remote: the WebSocket caution recommended endpoint authorization but never mentioned the Origin header. CORS does not apply to WebSockets, so a browser that attaches cookies or Windows authentication by itself lets another page open the socket. The caution now covers: - the cases SameSite does not stop; - AllowedOrigins, or an exact Origin check before AcceptWebSocketAsync; - that the Origin check is not authentication. Paged Results: with FromOffset, pageInfo.totalCount is whatever the handler passes, unchanged by a client-side filter. The page said it reflected the unfiltered source.
autocarl
approved these changes
Nov 4, 2026
autocarl
left a comment
autocarl
left a comment
Contributor
There was a problem hiding this comment.
Reviewed the incremental delta from 4010af3 to exact head fa1a853. No concrete introduced P0–P2 finding in that delta. This approval is for #7's changes, not a waiver of the two outstanding findings on its prerequisite #6; fix and merge #6 first.
Cross-checked remote protocol methods, errors, terminal lifecycle, profiles, MCP changes and cursor recipes against released v0.12.0 source. Independent read-only reviews covered technical/diagram semantics and theme/Astro/SVG/landing changes. docs:validate passes, the complete local build succeeds (332 HTML pages), and a complete generated-site scan reports no broken internal links or anchors. The OG-image generation command also succeeds. The GitHub docs check is green. The final 81d8e53 -> fa1a853 follow-up changes only two prose paragraphs; I re-reviewed that delta against the FromOffset implementation and the official ASP.NET Core WebSocket origin guidance, reran docs validation and the Astro build, and reused the unchanged real API metadata.
Limits: UI assessment was source-level, not a browser screenshot/rendering audit. Existing dependency-audit advisories were not attributed to the new font additions. No merge or product-code changes performed.
carldebilly
added a commit
that referenced
this pull request
Nov 4, 2026
feat(site): land #7 on main
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
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.
A visual identity for the site, "Night shift", with an overalls motif, then diagrams across the docs, a page on the remote protocol, and a few corrections found while drawing. Stacked on #6, the 0.12 content PR; merge that one first.
Identity
>prompt, with two straps and brass rivets.public/og-image.png) rendered fromsrc/assets/og-image.svgbynpm run og:image. The page metadata referenced this image, but the file did not exist.Landing page
[x]/[+]checklists, and "Where to go next" is anls docs/listing.Diagrams
Inline SVG components, coloured from theme variables, scrolling instead of shrinking on narrow screens.
src/components/diagrams/README.mddescribes the drawing vocabulary;metrics.ts,cells.ts,Bracket.astro,MessageSequence.astroandCellRow.astroare the shared building blocks.New page
Remote Protocol (
reference/remote-protocol.mdx): the experimental JSON-RPC 2.0 profile behindRepl.Remote, for anyone writing a client: Content-Length framing, methods, a one-shot call, a terminal session, error codes, cancellation, security limits.Corrections found along the way
IReplMiddlewaretype that Repl does not have, described Telnet wrongly and had no rows forRepl.RemoteandRepl.Remote.Defaults.BuildMcpServerOptions()exception.IMcpClientRoots.IsAllowed(path)does not exist; the cookbook now checks paths against configured directories and warns about symbolic links.UseCliProfile()disables the REPL. No profile does; the Configuration page now says what each one changes, with use cases.Originheader: CORS does not apply to WebSockets, soAllowedOriginsor an exact check is needed whenever a browser can reach the endpoint.totalCountreflects the unfiltered source; withFromOffsetit is whatever the handler passes.Verification
npm run docs:validateandnpm run buildpass.dist/.