feat(docs): everforest refresh, ask-the-codebase search, and seo

[jahvon]

Summary

Reworks flowexec.io: a real design system instead of a 57-line override file, a way to ask
questions the guides don't answer, and the SEO/social tags the site never had.

Almost entirely docs and tools/docsgen. The one runtime change is a second commit fixing three
flag usage strings that made flow --help print types that do not exist — see the last section.

---

Design

The site was stock VitePress with a custom.css that was mostly !important hero sizing and a
drop-shadow(5px 5px 100px #D699B6). There was no .dark {} block at all — dark mode was
VitePress's default greys with an aqua accent painted on top.

• styles/tokens.css maps Everforest onto VitePress's variable contract for both modes. Light-mode
  accents are darkened from the published palette, which lands near 2.8:1 on cream — under the
  4.5:1 link text needs. Every value is checked against its own background.
• styles/rhythm.css / styles/overrides.css: hairline rules instead of shadows, a 12px radius,
  a looser vertical rhythm, cards that change border colour and never scale.
• Shiki's bundled everforest-light/everforest-dark replace GitHub's blues in code blocks.
• Home page rebuilt: eyebrow, numbered sections, an install strip carrying the latest release tag
  (fetched at build time, with a fallback so a rate-limited CI build still succeeds), and a card
  grid in place of the emoji feature list.
• An ambient canvas backdrop on the home page. Pauses on hidden tabs, holds a static frame under
  prefers-reduced-motion, reads its colours from the theme variables.

Ask the codebase

⌘K local search is untouched and still instant. Alongside it, an Ask AI button (⌘I) opens a
panel that queries DeepWiki's public MCP endpoint directly from the browser — no proxy, no new
deploy surface, no secrets. The existing search modal also grows a bridge row that hands the current
query across.

Worth knowing when reviewing:

• The endpoint is public, unauthenticated, and answers Access-Control-Allow-Origin: *. It is also
  undocumented and unversioned, so the UI fails to a plain "ask on DeepWiki" link rather than a
  broken modal. Direct-from-browser also means no caching — every ask costs the full ~15s.
• Model output is rendered through markdown-it with html: false. That is the sanitisation
  boundary; nothing reaches the DOM as markup.
• The bridge row depends on three VitePress-internal selectors (.VPLocalSearchBox, .shell,
  #localsearch-input). All three are feature-detected — if an upgrade renames any of them the
  bridge disappears and the standalone button carries on.
• Attribution is permanent in the panel footer, and guides/ai-tools.md says plainly that answers
  are model-generated and can lag main.

Reference docs (tools/docsgen)

Cobra's markdown is a flat dump, and the flag listings were the worst of it — fixed-width
columns that overflowed the content column and clipped their own descriptions off the right edge.
A new post-processing pass rewrites them into tables, gives fences a language, and turns the
command name into a real page title instead of an h2 with a section rule.

The parser is deliberately conservative: anything it cannot parse falls back to a verbatim code
block rather than a mangled table. It handles Cobra's backtick-derived placeholders that contain
spaces and wrapped description lines.

Two bugs fixed on the config reference:

• The Required column was empty on every top-level property table. The template read
  {{IsRequired .Required $key}} inside a range, where . is the property — so it consulted
  the property's own required list rather than the page's. template is required and reported
  nothing.
• ✘ meant required, which reads as the exact opposite. Now Yes.

SEO

There were no Open Graph tags, no Twitter card, no canonical, and no social image, so a link to
flowexec.io previewed as a bare URL.

• Per-page canonical, og:* and twitter:* via transformPageData; site-wide image, card type,
  theme-color, apple-touch-icon, and a SoftwareApplication JSON-LD block.
• cleanUrls: true. The sitemap advertised .html URLs that Cloudflare Pages 308-redirects,
  while internal links were already extensionless — so every sitemap entry pointed at a redirect and
  both forms were reachable. Sitemap, links, and canonicals now agree.
• Per-page descriptions come from the generators for all 66 reference pages (Cobra summaries and
  schema descriptions), so they stay correct as commands change. The 23 authored pages are written
  by hand.

Guides

integrations.md split into Containers (the exec.container field with its full option table,
plus running the CLI from the image) and GitHub Actions (inputs and outputs read from
action.yaml). Both sit under a new Integrations group alongside AI Tools. All inbound links and
llms.txt repointed.

Containers covers the Python support from #439–#443 that landed while this was in flight: the
interpreter-dependent entrypoint default, and the host Python env vars that are dropped at the
container boundary regardless of inheritEnv.

Also: nav collapsed from five items to three (the two reference sections became one menu), a
Dockery Labs footer, and docs/public/demo.gif deleted — 3 MB, orphaned, nothing referenced it.

---

Testing

• flow validate passes: lint 0 issues, unit + e2e green, 10 flow files valid.
• npm run build clean; VitePress dead-link checking is on, so the guide restructure is verified.
• The Ask panel was exercised end to end in a real browser — the CORS call completes, the SSE
  stream parses, markdown renders. Two bugs found that way and fixed: DeepWiki separates frames
  with \r\n\r\n rather than \n\n, and the modal is v-if-mounted so a watch on the open flag
  registered too late to ever autofocus the input.
• Checked in light and dark, including the generated reference pages.

Not verified: Chrome would not give me a viewport above ~960px for part of the session, so the
desktop tier of the hero mark sizing was confirmed by reading the compiled CSS rather than by eye.
Worth a glance on a wide screen.

Second commit: a flag-rendering bug this surfaced

Cobra's UnquoteUsage treats a backticked span in a flag's usage string as an explicit
value-name override — the documented way to write --port `number` . Three flags used
backticks meaning inline code, so Cobra took the quoted text as the placeholder and
flow --help advertised types that do not exist:

      --cmd flow logs
      --spec flow logs
  -t, --template flow set template

Dropping the backticks restores the type-derived placeholder — stringArray, string, string.
Verified against a built binary before and after; no test asserts on these strings.

The template flag carried a second, independent problem: there is no flow set template
command. Templates are registered with flow template add, so that sentence pointed at
something that has never existed. Corrected in the same change.

This is a CLI behaviour change rather than a docs one, but it belongs here: the new reference
tables put the value placeholder under a column headed Type, which makes flow logs read as a
type far more loudly than the old code block did. Shipping the docs overhaul without it would mean
knowingly publishing the wrong output.

🤖 Generated with Claude Code

https://claude.ai/code/session_012mnVfKRbSbYV43gdjcdxdX

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!