Redesign Scope documentation with an interactive benchmark playground

[Wassim Chegham (manekinekko)]

Website walkthrough

A fresh, captioned 75-second tour of the single task-board example. It shows the explicit mock-data labels, supported and planned agents, a base profile with two alternate profiles, evaluation gates and a reusable criteria library, the expandable criteria graph, token counts and duration differences, animation playback, and dark mode. No live agents run in this example; all outcomes and metrics are invented.

scope-interactive-example-2026-09-21.mp4

Summary

Refresh the Astro + Starlight documentation website with a clearer landing page, task-oriented navigation, and an interactive benchmark example.

• Introduce a responsive light/dark design with distinct Portal, CLI, and API onboarding paths.
• Keep one simple task-board example with no scenario picker. Compare a base profile with two alternate profiles while the task and criteria stay fixed.
• Label the walkthrough as an Interactive example with a neutral Mock data badge and a No agents run here explanation. Replace live-looking profile statuses and use animation-specific playback labels.
• Show supported and planned agent integrations separately; only supported agents appear in the fictional sample runs.
• Explain evaluation gates and a reusable criteria library, with an expandable dependency graph and per-criterion outcomes.
• Show simulated input/output token counts, elapsed duration, and differences from the base profile alongside gate outcomes. Derive chart bars and table results from the same fixture.
• Retain inspectable stages, pause/replay controls, and reduced-motion and no-JavaScript fallbacks.
• Preserve Starlight search, the documentation reader, and all 200 generated pages.
• Fix project-base links for GitHub Pages, broken API-reference links, the homepage skip-link target, and small onboarding copy issues.
• Document the example behavior, UX review, and remaining content recommendations in website/README.md.

Reviewer focus

Explore the homepage, play and pause the animation, inspect each step, compare the profile variations, and expand the criteria graph and per-criterion results. The walkthrough uses one fixed task-board example, not scenario switching. Availability badges distinguish supported agents from planned or unavailable integrations. All outcomes, token counts, and durations are illustrative, not benchmark measurements or agent rankings.

GitHub Pages stays static. PR builds use /scope; deployment remains restricted to main.

Validation

• Production build at /scope/, preserving 200 pages.
• Seven website plugin tests cover project-base links and unchanged external URLs and code examples.
• Eight focused example data tests cover supported profiles, complete metrics, gate/criterion dependencies, chart counts, and token/time differences.
• Strict TypeScript checks on the example modules.
• Browser coverage for the single fixed example, mock labels, all four stages, playback, profile metrics, keyboard disclosures, six viewport widths, light/dark themes, reduced motion, and no JavaScript.
• GitHub build, gitleaks, and CLA checks passed for 03b88131; deployment is intentionally skipped for pull requests.

[Copilot]

🟡 Changes recommended

The new playground has an accessibility labeling mismatch and a runtime error path that should be corrected before merging.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR refreshes the Astro + Starlight documentation site with a redesigned landing experience and an interactive “benchmark playground”, while also fixing GitHub Pages base-path routing and updating documentation links/copy to match the new structure.

Changes:

• Replace the previous MDX splash homepage with an Astro-driven landing page that includes a progressive-enhancement playground (custom element controller + static HTML fallback).
• Add a Markdown/MDX remark plugin to safely prefix root-relative links under the GitHub Pages project base, and update site config/workflow to build static output correctly on PRs vs main.
• Fix/refresh documentation copy and links (notably REST API reference paths) and update website contributor/deployment notes.

File summaries

File	Description
website/src/styles/landing.css	Replaces landing styling with new shared tokens + homepage/playground layout styles.
website/src/scripts/sample-agents.ts	Adds a shared illustrative agent roster used by the playground.
website/src/scripts/flow-demo.ts	Adds the custom element controller for the interactive playground (progressive enhancement).
website/src/plugins/remark-base-links.mjs	Adds a remark transform to prefix root-relative links with the Pages base path.
website/src/content/docs/resources/glossary.md	Updates glossary terminology/copy (criteria DAG wording, fixes stray text).
website/src/content/docs/resources/faq.md	Fixes REST API reference link target.
website/src/content/docs/reference/rest-api.md	Fixes REST API reference link target(s).
website/src/content/docs/index.mdx	Swaps the splash page markup to use the new Home Astro component.
website/src/content/docs/guides/submitting-requests-api.mdx	Updates REST API reference link target(s).
website/src/content/docs/guides/prioritizing-requests.mdx	Updates REST API reference link target(s).
website/src/content/docs/getting-started/install-cli.md	Fixes SCOPE_INSTALL_DIR usage so it applies to the installer process.
website/src/components/SiteTitle.astro	Simplifies logo styling (removes animated wave; adjusts sizing).
website/src/components/PageTitle.astro	Adds a homepage-only title override hook for Starlight layouts.
website/src/components/Home.astro	New Astro homepage component (landing sections, onboarding paths, base-aware links).
website/src/components/Header.astro	New homepage-specific header/nav composition (uses Starlight search + theme select).
website/src/components/FlowDemo.astro	New static playground markup (buttons, wiring SVG, aria-live announcements, noscript fallback).
website/README.md	Documents the redesign, local build/deploy behavior, and playground intent/constraints.
website/astro.config.mjs	Adds static output, remark-base-links plugin, new component overrides, and sidebar reorg.
website/.gitignore	Ignores Astro build artifact directory.
.github/workflows/static.yml	Adjusts build env so PRs build with /scope base while main uses Pages base path.

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Cedric Vidal (cedricvidal)]

Looks really good and directionally clearly what we want.

A few things to think about:

Scope playground screen

• Do you thing you could show what's supported today and what's not? A small visual indicator showing the coding agents supported today (copilot, claude) and the ones planned (codex, opencode, ...) would be great
• The judge step is not super clear. It currently shows gates but mentions criterias. Do you think you could mention gates explicitely and a library of reusable criterias. Do you think we should mention the graph? I wonder if it's not a bit too advanced for the home page.
• It would be great to show that we can compare a base profile to alternate profiles. Do you think that's possible?
• Token counts and duration are something people care about. Do you think we could show them?

The less searching, more building is really great!

[Wassim Chegham (manekinekko)]

Implemented all your suggestions Cedric Vidal (@cedricvidal) ;)

[Cedric Vidal (cedricvidal)]

Looks really good! A few more remarks:

• it's not clear what is updated in the playground when you change the scenario.
• the word "playground" and the green glowing bulb on the top left convey the idea that this is live when it's a mockup, maybe something to change a bit to avoid confusion

[Wassim Chegham (manekinekko)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Merged main into this branch (commit fe7df71). Resolved conflicts in .github/workflows/static.yml, website/astro.config.mjs, and website/README.md — deduplicated the two base-path remark plugins that were added independently on each branch, keeping main's tested remark-base-path.mjs and removing the redundant remark-base-links.mjs. Verified with pnpm test and pnpm build (200 pages, both with and without BASE_PATH=/scope).

[Wassim Chegham (manekinekko)]

Pushed all pending website changes in 03b8813 and replaced the old video in the PR description with a new 75-second recording of the current UI.

• Kept one simple task-board example and removed the scenario picker and switching logic.
• Renamed the walkthrough to "Interactive example", replaced the glowing status indicator with "Mock data", and made it explicit that no agents run here. Profile cards and playback controls no longer suggest live execution.
• Retained supported/planned agent badges, base-versus-alternate profile comparisons, gates and reusable criteria, the optional criteria graph, and fictional token/duration metrics. Chart bars and result tables now share the same fixture.
• Removed the redundant introductory sentence and updated the related documentation.

Local checks passed: eight example-data tests, seven website-plugin tests, strict TypeScript checks, and the 200-page production build with the /scope base. Browser checks covered all four stages, playback, disclosures, six viewport widths, both themes, reduced motion, and no JavaScript.

GitHub's build, gitleaks, and CLA checks passed for this commit. Deployment is intentionally skipped for pull requests. The working tree is clean.