feat(site): migrate docs site to VitePress and redesign landing page

[waynesun09]

Why

The existing docs site is a custom Svelte 5 SPA (web/docs/) that looks polished but lacks baseline documentation features users expect:

• No full-text search across docs
• No sidebar navigation with collapsible sections or active-page highlighting
• No table of contents (per-page heading outline)
• No previous/next page navigation
• No "Edit this page on GitHub" links
• No mobile-responsive documentation layout
• Not indexable by search engines (SPA renders client-side)
• Not readable by agents/tools without deserializing minified JS

Each of these would need to be built from scratch and maintained in a bespoke doc framework. VitePress provides all of them out of the box, with an active community maintaining accessibility, i18n, and edge-case handling.

The docs are also reorganized with a user-focused reading sequence: Getting Started → Agents → User Guides → Concepts → Reference → Infrastructure → Contributing.

Static HTML output means docs load instantly (no JS bundle to parse), are indexable by search engines, and can be read directly by tools and agents.

Summary

• Replace custom Svelte 5 + Vite docs SPA (web/docs/) with VitePress static site generator (website/)
• Redesign standalone landing page (web/public/index.html) with fullsend brand identity, interactive timeline, agent showcase, and full light/dark theme support
• Add CLI Reference section with dedicated pages for fullsend github, fullsend inference, and fullsend mint commands
• Fix broken agent page icons by converting <img> HTML tags to markdown image syntax
• Fix stale web/docs/ references in eslint.config.js that crash ESLint after the SPA deletion
• Add hash-route redirect for legacy SPA URLs (/docs/#/vision → /docs/vision)

Details

Landing page (web/public/index.html)

• Full brand redesign: Plus Jakarta Sans typography, fullsend lime/navy palette, frosted glass navbar
• Interactive hero with animated GitHub timeline showing the full agent pipeline (triage → code → review → fix → retro)
• Light/dark theme toggle with localStorage persistence and system preference detection
• "The Loop" SDLC cycle grid showing all 6 pipeline stages with numbered sequence
• Agent cards section with GitHub App avatars and detailed capability descriptions for all 6 agents
• "Built for trust" design principles: OpenShell Sandbox, prompt injection defense, guarded paths, customizable, transparent, human-in-the-loop
• Three-step Getting Started section with correct CLI commands
• Multi-column footer with project links, resources, and license info
• WCAG AA color contrast, focus-visible outlines, scroll-reveal animations, inline SVG icons, Firefox scrollbar support

VitePress setup (website/)

• Migrated from Docusaurus to VitePress, unifying the build layer on Vite alongside the existing Svelte admin SPA
• Brand-aligned custom CSS with light/dark theme support
• Sidebar and nav configuration for docs and CLI reference
• Vue syntax escaping preprocessor for markdown (handles {}, {{}}, and non-HTML tags in code blocks)
• Legacy hash-route redirect script for bookmarked SPA URLs

Lint tooling

• Removed stale web/docs/ imports and globs from eslint.config.js (ESLint crashed on deleted svelte.config.js)
• Scoped ESLint to web/admin/ only (VitePress upstream uses Prettier, not ESLint)
• Added Prettier + Stylelint coverage for website/.vitepress/ files
• Updated lint-staged and pre-commit trigger patterns

CLI Reference

• docs/cli/README.md — overview with command groups and global flags
• docs/cli/github.md — fullsend github subcommands (setup, enroll, unenroll, set, status, sync-scaffold, uninstall)
• docs/cli/inference.md — fullsend inference subcommands (provision, deprovision, status)
• docs/cli/mint.md — fullsend mint subcommands (deploy, add-role, remove-role, enroll, unenroll, status, token)

Agent icon fix

• Converted <img src="icons/X.png"> to ![X agent icon](icons/X.png) in 5 agent pages
• Added CSS to constrain icon width to 80px

Test plan

• Landing page renders at / with theme toggle, timeline animation, and all sections
• Light and dark themes switch correctly with persistence across reloads
• VitePress docs build succeeds (cd website && npm run build)
• Sidebar navigation, search, and table of contents work correctly
• Legacy hash URLs (/docs/#/vision, /docs/#/agents/triage::heading) redirect correctly
• Agent icons render correctly on all 6 agent pages
• CLI Reference pages render with correct content
• ESLint passes (npm run lint)
• Existing docs pages render correctly (no regressions)
• PR preview deployment includes both landing page and docs site

[qodo-code-review]

PR Summary by Qodo

Docs: migrate site from Svelte SPA to Docusaurus
📝 Documentation ⚙️ Configuration changes 🕐 40+ Minutes

Description

• Replace custom Svelte/Vite docs SPA with a Docusaurus site built from docs/.
• Add CLI Reference sidebar and pages for fullsend github, inference, and mint.
• Update CI/deploy bundling and doc styling (agent icons, sidebar ordering, footer links).

Diagram

graph TD
  ci["GitHub Actions"] --> vite["Vite build (admin)"] --> bundle[("Deploy bundle")]
  docs[/"docs/ markdown"/] --> docusaurus["Docusaurus build"] --> bundle[("Deploy bundle")] --> worker["Cloudflare Worker"] --> browser(("User browser"))
  ci --> docusaurus["Docusaurus build"]

  subgraph Legend
    direction LR
    _pipe["Build step"] ~~~ _asset[("Static assets")] ~~~ _doc[/"Markdown source"/] ~~~ _user(("External user"))
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep Svelte SPA + improve markdown pipeline

• ➕ Retains existing hash-routing UX and custom sidebar behavior
• ➕ Avoids introducing React/Docusaurus dependency tree
• ➖ Ongoing maintenance burden for custom markdown rendering, link rewriting, and security sanitization
• ➖ Harder to add common docs features (search, versioning, i18n, theming) without more custom work

2. Use a lighter static generator (MkDocs / Astro Starlight)

• ➕ Potentially smaller runtime/dependency footprint than Docusaurus
• ➕ Strong markdown ergonomics; less MDX/JSX surface area
• ➖ Would require a different ecosystem/tooling decision and migration effort
• ➖ Less alignment with Docusaurus sidebar/nav patterns already implemented here

3. Render docs directly from GitHub (no site build)

• ➕ Minimal build/deploy complexity
• ➕ No additional runtime dependencies
• ➖ Poorer UX for navigation, cross-linking, and structured reference sections
• ➖ Does not integrate cleanly with the existing Cloudflare Worker-hosted /docs/ experience

Recommendation: Proceed with the Docusaurus migration: it meaningfully reduces bespoke docs-rendering code (and its security/maintenance surface) while preserving the /docs/ URL structure via baseUrl: '/docs/' + routeBasePath: '/'. The main follow-up risk to watch is link correctness and MDX edge cases (mitigated here via the brace-escaping markdown preprocessor).

Files changed (23) +822 / -52

Refactor (1) +1 / -12

vite.config.tsRemove Vite docs SPA build inputs and /docs dev fallback +1/-12

Remove Vite docs SPA build inputs and /docs dev fallback

• Eliminates the docs Svelte plugin and virtual docs build plugin, removes '/docs/' SPA fallback routing, and drops docs-related test glob configuration.

vite.config.ts

Documentation (14) +422 / -13

fix.mdConvert agent icon to markdown image syntax +1/-1

Convert agent icon to markdown image syntax

• Replaces the inline HTML '<img>' with a markdown image so Docusaurus markdown processing and styling apply consistently.

docs/agents/fix.md

prioritize.mdConvert agent icon to markdown image syntax +1/-1

Convert agent icon to markdown image syntax

• Replaces the inline HTML '<img>' with a markdown image for consistent rendering in the new docs site.

docs/agents/prioritize.md

retro.mdConvert agent icon to markdown image syntax +1/-1

Convert agent icon to markdown image syntax

• Replaces the inline HTML '<img>' with a markdown image for Docusaurus compatibility and shared CSS sizing.

docs/agents/retro.md

review.mdConvert agent icon to markdown image syntax +1/-1

Convert agent icon to markdown image syntax

• Replaces the inline HTML '<img>' with a markdown image so the icon is styled uniformly across agent pages.

docs/agents/review.md

triage.mdConvert agent icon to markdown image syntax +1/-1

Convert agent icon to markdown image syntax

• Replaces the inline HTML '<img>' with a markdown image, aligning with the Docusaurus markdown pipeline.

docs/agents/triage.md

README.mdAdd CLI Reference overview page +38/-0

Add CLI Reference overview page

• Introduces a top-level CLI overview with installation guidance, command group links, and global authentication notes.

docs/cli/README.md

github.mdDocument 'fullsend github' commands and flags +120/-0

Document 'fullsend github' commands and flags

• Adds a dedicated reference page describing 'fullsend github' subcommands, usage examples, key flags, and required OAuth scopes.

docs/cli/github.md

inference.mdDocument 'fullsend inference' provisioning lifecycle +87/-0

Document 'fullsend inference' provisioning lifecycle

• Adds reference documentation for provisioning/deprovisioning/status commands, including required IAM roles and required GCP APIs.

docs/cli/inference.md

mint.mdDocument 'fullsend mint' deployment and operations +162/-0

Document 'fullsend mint' deployment and operations

• Adds a comprehensive reference page for mint deploy/role management/enrollment/status/token flows, including IAM roles and API requirements.

docs/cli/mint.md

README.mdAlign frontmatter with Docusaurus sidebar metadata +2/-1

Align frontmatter with Docusaurus sidebar metadata

• Replaces 'order' with Docusaurus 'sidebar_position' and sets a root 'slug' so the Getting Started index can serve as the docs landing route.

docs/guides/getting-started/README.md

configuring-github.mdUpdate frontmatter for Docusaurus ordering +1/-1

Update frontmatter for Docusaurus ordering

• Switches from 'order' to 'sidebar_position' to preserve nav ordering under the new Docusaurus sidebar.

docs/guides/getting-started/configuring-github.md

getting-inference.mdUpdate frontmatter for Docusaurus ordering +1/-1

Update frontmatter for Docusaurus ordering

• Switches from 'order' to 'sidebar_position' to integrate cleanly into the Docusaurus sidebar config.

docs/guides/getting-started/getting-inference.md

org-mode.mdUpdate frontmatter for Docusaurus ordering +1/-1

Update frontmatter for Docusaurus ordering

• Switches from 'order' to 'sidebar_position' to keep consistent nav ordering after the migration.

docs/guides/getting-started/org-mode.md

site-deployment.mdUpdate deployment docs for Docusaurus build output +5/-4

Update deployment docs for Docusaurus build output

• Rewrites deployment documentation to reflect that '/docs/' is now built by Docusaurus ('website/build/') instead of the removed Vite/Svelte docs SPA ('web/dist/docs/').

docs/site-deployment.md

Other (8) +399 / -27

site-build.ymlBuild and bundle Docusaurus output for /docs deployment +9/-3

Build and bundle Docusaurus output for /docs deployment

• Extends npm caching to include 'website/package-lock.json', adds a dedicated Docusaurus build step, and updates bundling to copy 'website/build/' into '_bundle/public/docs/' instead of the removed Vite docs output.

.github/workflows/site-build.yml

package.jsonRemove docs SPA checks/lint rules and markdown pipeline deps +10/-24

Remove docs SPA checks/lint rules and markdown pipeline deps

• Drops scripts and lint-staged globs targeting 'web/docs', and removes markdown-rendering dependencies that were only needed for the custom docs SPA pipeline.

package.json

docusaurus.config.tsAdd Docusaurus configuration with markdown brace preprocessor +154/-0

Add Docusaurus configuration with markdown brace preprocessor

• Defines the new docs site configuration: 'baseUrl: '/docs/'', docs loaded from '../docs' at 'routeBasePath: '/'', multi-sidebar navbar items, footer links, Prism languages, and a markdown preprocessor that escapes '{}' outside code blocks to avoid MDX parsing issues.

website/docusaurus.config.ts

package.jsonIntroduce Docusaurus app dependencies and scripts +44/-0

Introduce Docusaurus app dependencies and scripts

• Adds a standalone 'website/' package with Docusaurus/React dependencies and standard dev/build scripts for local docs iteration and CI builds.

website/package.json

sidebars.tsDefine docs and CLI multi-sidebar structure +152/-0

Define docs and CLI multi-sidebar structure

• Creates two sidebars: a dedicated CLI Reference sidebar, and the main docs sidebar with categories (Getting Started, Agents, Guides, Reference, Infrastructure, Contributing, Internals) including autogenerated sections.

website/sidebars.ts

custom.cssAdd site theme tokens and agent icon sizing rule +24/-0

Add site theme tokens and agent icon sizing rule

• Sets primary color variables for light/dark themes and adds a targeted CSS rule to constrain agent icon images (based on alt text) to 80px width.

website/src/css/custom.css

.gitkeepAdd placeholder for Docusaurus static directory +0/-0

Add placeholder for Docusaurus static directory

• Keeps the 'website/static/' directory in version control for future static assets.

website/static/.gitkeep

tsconfig.jsonAdd TypeScript config for Docusaurus project +6/-0

Add TypeScript config for Docusaurus project

• Configures TypeScript using the Docusaurus base tsconfig and sets 'baseUrl' for module resolution.

website/tsconfig.json

[github-actions]

Site preview

Preview: https://7cb7e980-site.fullsend-ai.workers.dev

Commit: 0c1f1ae432f81e345eb8eb868833f6f5d219ed74

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 51 rules

✅ Skills: writing-user-docs, writing-adrs

1. ESLint imports deleted docs 🐞 Bug ☼ Reliability

Description

eslint.config.js still imports and configures Svelte linting for web/docs, but this PR deletes
web/docs/svelte.config.js; ESLint will fail while loading its config even when linting only
web/admin.

Code

web/docs/svelte.config.js[L1-4]

-import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
-
-/** @type {import('@sveltejs/vite-plugin-svelte').SvelteConfig} */
-export default { preprocess: vitePreprocess() };

Relevance

⭐⭐⭐ High

Team fixes CI/runtime config breakages (PR #2576); ESLint config introduced/maintained recently (PR
#625).

PR-#2576
PR-#625

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The ESLint config still imports ./web/docs/svelte.config.js and references web/docs/** globs,
but the PR deletes web/docs/svelte.config.js, making the import fail at runtime.

eslint.config.js[1-55]
package.json[8-22]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`eslint.config.js` imports `./web/docs/svelte.config.js` and includes `web/docs/**` file globs, but the PR deletes the entire `web/docs` app (including `web/docs/svelte.config.js`). This will cause ESLint to throw during config evaluation, breaking `npm run lint` and any tooling that loads ESLint config.

## Issue Context
The root `package.json` scripts were updated to lint only `web/admin`, but ESLint still loads the same global config file first.

## Fix Focus Areas
- eslint.config.js[1-55]
- package.json[8-22]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Fence detection misses indents 🐞 Bug ≡ Correctness

Description

The Docusaurus markdown preprocessor only toggles code-fence mode when a line starts with ``` at
column 0, so indented fenced blocks (e.g. inside lists) are treated as normal text and {} in code
blocks gets escaped.

Code

website/docusaurus.config.ts[R23-33]

+    preprocessor: ({fileContent}) => {
+      // Escape { and } outside fenced code blocks so they aren't parsed as JSX expressions
+      const lines = fileContent.split('\n');
+      let inCodeFence = false;
+      return lines.map(line => {
+        if (/^```/.test(line)) {
+          inCodeFence = !inCodeFence;
+          return line;
+        }
+        if (inCodeFence) return line;
+        // Also skip inline code spans — only escape braces NOT inside backticks

Relevance

⭐⭐ Medium

No historical evidence: website/docusaurus.config.ts is new; no prior review patterns for this
markdown preprocessor logic.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The preprocessor only checks ^``, so it won't enter inCodeFence` for indented fences; the
referenced doc contains an indented fenced JSON snippet with {} that will be escaped.

website/docusaurus.config.ts[18-52]
docs/guides/infrastructure/infrastructure-reference.md[105-116]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The markdown preprocessor escapes `{`/`}` outside fenced code blocks, but it only recognizes fences that begin at the start of the line (`/^```/`). Markdown allows indented fences (common under list items), so braces inside those code blocks will be escaped and rendered incorrectly.

## Issue Context
Example in the current docs: an indented fenced JSON block under a list item contains `{...}` and will become `\{...\}`.

## Fix Focus Areas
- website/docusaurus.config.ts[18-52]
- docs/guides/infrastructure/infrastructure-reference.md[105-116]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Favicon file not added 🐞 Bug ⚙ Maintainability

Description

Docusaurus is configured to use img/favicon.ico, but the PR doesn’t add that file under
website/static/img/, so the built site will ship without the intended favicon.

Code

website/docusaurus.config.ts[R6-12]

+  title: 'Fullsend',
+  tagline: 'Autonomous SDLC agents for your codebase',
+  favicon: 'img/favicon.ico',
+
+  url: 'https://fullsend.sh',
+  baseUrl: '/docs/',
+

Relevance

⭐⭐ Medium

No historical evidence: website/ is new and not on default branch, so no prior favicon/asset
patterns found.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The config references img/favicon.ico, while the only committed static content shown for
website/static/ is a .gitkeep placeholder (no favicon asset is introduced by this PR).

website/docusaurus.config.ts[5-12]
website/static/.gitkeep[1-1]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`website/docusaurus.config.ts` sets `favicon: 'img/favicon.ico'`, but the PR only adds an empty `website/static/` placeholder. This results in a broken/missing favicon on the published docs site.

## Issue Context
Docusaurus resolves `favicon` relative to the site static directory (`website/static`).

## Fix Focus Areas
- website/docusaurus.config.ts[6-12]
- website/static/.gitkeep[1-1]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 7:56 PM UTC · Ended 7:57 PM UTC
Commit: 7f5ce3c · View workflow run →

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 7:56 PM UTC · Completed 7:57 PM UTC
Commit: 5f80b57 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 8:08 PM UTC · Completed 8:09 PM UTC
Commit: 6d66d6b · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 10:04 PM UTC · Ended 10:05 PM UTC
Commit: 7f5ce3c · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 10:08 PM UTC · Completed 10:09 PM UTC
Commit: c1aca03 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 10:15 PM UTC · Completed 10:16 PM UTC
Commit: 228784b · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 10:30 PM UTC · Completed 10:31 PM UTC
Commit: c8b5b6b · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ❌ Failure · Started 10:40 PM UTC · Completed 10:41 PM UTC
Commit: b177b47 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:52 PM UTC · Completed 2:13 PM UTC
Commit: 1ad602d · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:32 PM UTC · Completed 2:47 PM UTC
Commit: dd29635 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:48 PM UTC · Completed 4:02 PM UTC
Commit: 236cbd1 · View workflow run →

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] stale-doc

Documents a --region flag with default 'global' for 'inference provision', but the Go CLI code (internal/cli/inference.go) does not define this flag. The available flags are --project, --pool, --provider, and --dry-run. Users following these docs would get an 'unknown flag' error.

Suggested fix: Remove the --region row from the inference provision flags table, or add the flag to the Go CLI if it is intended to be configurable.

[fullsend-ai-review]

[medium] stale-doc

Documents 'mint add-role' with a --app-id flag, but the Go CLI code (internal/cli/mint_setup.go) defines --slug instead. The CLI looks up the app ID from the slug via the GitHub API. The documented example '--app-id ""' would produce an 'unknown flag' error.

Suggested fix: Replace --app-id with --slug in the example command and flags table. Note that the CLI discovers the app ID from the slug automatically.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:06 PM UTC · Completed 4:23 PM UTC
Commit: 0c1f1ae · View workflow run →

Review findings addressed in latest commits — accessibility fixes, escapeLine multi-backtick handling, mobile nav, reduced-motion support.

[fullsend-ai-retro]

🤖 Retro · ❌ Terminated · Started 4:19 PM UTC · Ended 4:29 PM UTC
Commit: ea2ca95 · View workflow run →

[fullsend-ai-review]

Review skipped — this PR is already merged.

The /fs-review command only reviews open pull requests.

_{Posted by fullsend post-review check}

[fullsend-ai-retro]

🤖 Finished Retro · ❌ Failure · Started 4:19 PM UTC · Completed 4:29 PM UTC
Commit: 0c1f1ae · View workflow run →