docs(graph): rework the @ttsc/graph guide, README, and launch post#298
Merged
Conversation
Merge the Tools reference into Design (inline ITtscGraphApplication plus a type-source tab set), add a sourced Comparison page carrying the benchmark chart, and restructure every graph guide into a numbered H2/H3 hierarchy. Embed the summary chart on the Overview page, and slim benchmark/graph.mdx to the chart, commentary, and reproduce steps, deferring the contract to Design and the head-to-head to Comparison. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Focus the README on @ttsc/graph itself: install, connect an agent, a compact how-it-works, one benchmark image, and the 3D viewer. Move the competitor autopsy and the narrative to the launch post and Comparison guide, switch the banner to the graph OG image, and fix the launch-post and image links. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The house style forbids em-dashes; replace them in the pain/antidote table and the request-type list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reorganizes the @ttsc/graph documentation so each surface has a distinct purpose (guide as reference, README as landing, launch post as narrative) while removing duplicated content and adding a sourced comparison page.
Changes:
- Replaced the old “Tools” guide with a new “Design” reference page, and added a new “Comparison” page (including an embedded summary benchmark chart).
- Updated the Graph docs overview + viewer pages to match the numbered heading structure and to embed the summary benchmark chart on the overview.
- Slimmed the benchmark page, refreshed the package README as a lean landing, and applied the colon-style edits in the launch post.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| website/src/content/docs/graph/viewer.mdx | Adds numbered sections/subsections and clarifies viewer usage (run vs dump) and interpretation guidance. |
| website/src/content/docs/graph/tools.mdx | Removes the former Tools reference page (content migrated/restructured into Design). |
| website/src/content/docs/graph/index.mdx | Embeds the summary benchmark chart and updates navigation/structure to point to Design + Comparison. |
| website/src/content/docs/graph/design.mdx | New consolidated reference/design page including request/result contract explanation and live type-source tabs. |
| website/src/content/docs/graph/compare.mdx | New sourced comparison page with a matrix + embedded summary benchmark chart + source links. |
| website/src/content/docs/graph/_meta.ts | Updates the docs sidebar order/entries (Overview → Design → Comparison → 3D Viewer). |
| website/src/content/docs/benchmark/graph.mdx | Slims benchmark documentation to chart + interpretation + reproduce steps, linking out to Design/Comparison/launch post. |
| website/src/content/blog/i-made-ts-compiler-graph-mcp.mdx | Applies the house-style colon formatting in the pain/antidote table and request-type list. |
| packages/graph/README.md | Rewrites README as a lean landing page (install/connect/how it works/benchmark/3D) and updates banner/link targets. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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.
Intent
Rework the
@ttsc/graphdocumentation set so each surface has one job and stops duplicating the others: the launch post owns the story, the guide owns the reference, the README is a lean landing.Scope
website/src/content/docs/graph/): merged the Tools reference into Design (inlineITtscGraphApplicationplus a type-source tab set for the branch and payload types), added a sourced Comparison page (matrix + summary benchmark chart + per-tool source links), and restructured every page into a numbered H2/H3 hierarchy matching the launch post. Embedded the summary benchmark chart on the Overview page. Updated_meta.ts(Overview → Design → Comparison → 3D Viewer).benchmark/graph.mdx): slimmed to the chart, result commentary, and reproduce steps; the tool contract now links to Design and the head-to-head to Comparison.@ttsc/graphitself (install, connect, how it works, benchmark, 3D). The competitor autopsy and narrative move to the launch post and Comparison guide. Banner switched to the graph OG image; broken launch-post and image links fixed.Notes / deferred
serena) are sourced to each tool's own repo and docs as of mid-2026 and flagged as moving targets; they live only in Comparison to avoid double-maintenance.benchmark/graph.mdxintentionally keeps flat headings, matching its sibling benchmark pages.ITtscGraphApplicationshows theIDraftshape landing with the pending source PR; the liveLocalSourcetabs follow the source.Test plan
prettierrun on all changed files (blog and Comparison table normalized; the rest unchanged)./docs/graph/toolsor/docs/graph/comparison), Design type-source tabs balanced (11 items and 11 panels), the#3-sourcesanchor matches its heading.🤖 Generated with Claude Code