Cadence-lang redesign + AI tools (MCP, federated search, llms.txt, AI chat, integrations)#306
Open
Aliserag wants to merge 6 commits into
Open
Cadence-lang redesign + AI tools (MCP, federated search, llms.txt, AI chat, integrations)#306Aliserag wants to merge 6 commits into
Aliserag wants to merge 6 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced May 1, 2026
Upstream unique cadence-mcp tools to onflow/flow-cli (security scan, validate args, doc search)
#307
Open
Aliserag
force-pushed
the
eval/pr285-cleanup
branch
from
4672950 to
3b627c2
Compare
Aliserag
force-pushed
the
eval/pr285-cleanup
branch
2 times, most recently
from
90ea450 to
d715c17
Compare
Aliserag
force-pushed
the
eval/pr285-cleanup
branch
from
d715c17 to
d2f09c1
Compare
Replace the Docusaurus site with a TanStack Start (file-based routing +
Nitro SSR) + Fumadocs (MDX docs engine) + Tailwind CSS v4 stack, deployed
on Vercel. Switch package manager from npm to Bun.
Key changes:
- Add vite.config.ts, source.config.ts, tsconfig.json, app.config.ts
- Replace src/pages + src/theme with src/routes (TanStack file-based routing)
- Add src/styles/app.css with Fumadocs theme tokens as CSS variables
- Add src/lib/{cn,source,layout.shared} utilities
- Add shadcn-style component primitives in src/components/ui/
- Delete babel.config.js, postcss.config.js, tailwind.config.js, sidebars.js
- Delete old Docusaurus src/pages, src/theme, src/css, src/ui, static/
- Migrate public/ assets (fonts, logos, favicons) from static/
- Add Dockerfile and CLAUDE.md for deployment and agent guidance
Aliserag
force-pushed
the
eval/pr285-cleanup
branch
from
f6b6006 to
23184e7
Compare
Restructure: move docs/ → content/docs/, .md → .mdx, remove Docusaurus syntax (admonitions, _category_.json), normalize cross-doc links to relative paths, add meta.json files for sidebar ordering. Content improvements on top of the structural move: - Tutorial series rewritten for Cadence 1.0 (entitlements, updated playground links, correct resource syntax throughout) - Forward-port PR #289: references clarification in language/references.mdx - Forward-port PR #290: ContractUpdateValidator scope fix in language/contract-updatability.mdx - Forward-port PR #291: testing-framework syntax modernization - Add frontmatter descriptions to design-patterns and security-best-practices - Fix Cadence syntax defects found during audit (casing, deprecated keywords)
- /api/chat: Anthropic streaming chat via @ai-sdk/anthropic (server-only key) - /api/search: Orama federated search over content/docs + external/onflow-docs - src/components/search.tsx: Cmd+/ search panel with AI answer pane, draggable, localStorage persistence - src/lib/external-search-index.ts: indexes onflow-docs submodule content - content/docs/ai-tools/: new documentation section covering the Cadence MCP server (flow mcp), Claude Code plugin, llm-endpoints, and editor integrations (Claude, Cursor, Codex, Gemini, Antigravity, OpenCode)
- public/robots.txt: adopt Content Signals policy (allow all bots; explicit GPTBot, Claude-Web, PerplexityBot, GoogleBot directives) - src/routes/llms[.]txt.ts: hand-crafted Cadence explainer for LLM context windows covering resources, transaction model, capabilities, cross-VM, randomness, and curated links - src/routes/llms-full[.]txt.ts: auto-generated full corpus via Fumadocs source loader (JSX-stripped, sorted by URL) - src/lib/derive-description.ts: extract first prose paragraph for meta descriptions when frontmatter description is absent - src/routes/og.docs.$.tsx + og.home.tsx: server-side OG images via @vercel/og / Satori using PNG base64 icons (SVG paths unsupported) - AGENTS.md: updated with stack overview, gotchas, and tools section for coding agents (flow-ai-tools plugin + flow mcp MCP server)
- src/components/MorphingAscii.tsx: ASCII art animation that morphs between Cadence code snippets on the landing page hero - src/routes/llms[.]mdx.docs.$.ts: per-page MDX plain-text endpoint at /llms.mdx/<doc-slug> for LLM-friendly single-page context fetching
…tifacts - .gitmodules + external/onflow-docs: pin onflow/docs submodule for federated Orama search (cross-site hits link to developers.flow.com) - scripts/generate-sitemap.ts: post-build sitemap generator - scripts/check-links.mjs: offline link-checker for MDX cross-references - scripts/update-ai-files.ts: utility to sync AI-facing content files - Remove docusaurus.config.js and package-lock.json (superseded by source.config.ts and bun.lock respectively)
Aliserag
force-pushed
the
eval/pr285-cleanup
branch
from
23184e7 to
56b3cd5
Compare
turbolent
reviewed
May 12, 2026
Member
turbolent
left a comment
turbolent
left a comment
There was a problem hiding this comment.
I reviewed the second commit, b126e4e, migrate and improve all documentation for Fumadocs.
What is the reason for switching from Docusaurus to Fumadocs? What are the problems we have with Docusaurus? To my knowledge we had no known issues and were happy with it.
The actual content improvements look good, the changes are mostly fixes 👍
What is the reason for changing all links from relative links to file to absolute paths? Is that needed for Dumadocs? We had previously changed it the other way round ... so now we're basically reverting it all back. This seems like busywork we can maybe avoid.
Member
There was a problem hiding this comment.
This file shouldn't be needed anymore, given the MCP server was removed
|
|
||
| :::warning | ||
|
|
||
| [!WARNING] |
Member
There was a problem hiding this comment.
This seems to be GitHub's callout syntax, not Docusaurus or now fumadocs
| @@ -384,15 +383,10 @@ The functions iterate over all stored objects in the particular domain, by calli | |||
| The `Bool` value returned from the callback function determines whether iteration continues. If the callback function returns `true`, iteration proceeds to the next stored object. If the callback function returns `false`, the iteration function stops. The specific order in which the objects are iterated over is undefined, as is the behavior when a path is added or removed from storage. | |||
|
|
|||
| :::warning | |||
Member
There was a problem hiding this comment.
It looks like fumadocs uses a different syntax for https://www.fumadocs.dev/docs/markdown#callouts, so I guess all of the callouts will need to be replaced
| @@ -1,7 +1,5 @@ | |||
| --- | |||
| title: Cadence Anti-Patterns | |||
| sidebar_position: 6 | |||
Member
There was a problem hiding this comment.
How is sidebar positioning handled in fumadocs. Are we just getting rid of the custom positioning?
| This is an opinionated list of best practices that Cadence developers should follow to write more secure Cadence code. | ||
|
|
||
| Some practices listed below might overlap with advice in the [Cadence Anti-Patterns] article, which is a recommended read as well. | ||
| Some practices listed below might overlap with advice in the [Cadence Anti-Patterns](./anti-patterns) article, which is a recommended read as well. |
Member
There was a problem hiding this comment.
All other pages where changed to "footnotes", this file is being reverted to inline links. We should keep it consistent
Comment on lines
+35
to
+37
| /// Declare Entitlements at the contract level — entitlements are | ||
| /// namespaced to their contract and referenced by access modifiers | ||
| /// on the contract's resources, structs, and functions. |
Member
There was a problem hiding this comment.
These comments explain the fix (why it was moved up here), but are no useful for readers
Suggested change
| /// Declare Entitlements at the contract level — entitlements are | |
| /// namespaced to their contract and referenced by access modifiers | |
| /// on the contract's resources, structs, and functions. |
turbolent
reviewed
May 12, 2026
| sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-ai-tools/main/scripts/install.sh)" | ||
| ``` | ||
|
|
||
| ## What's included |
Member
There was a problem hiding this comment.
This will likely get stale, maybe just link to flow-ai-tools
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
2 participants
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.
Summary
This PR ships the cadence-lang.org redesign + AI tools — a complete rewrite from Docusaurus to TanStack Start + Fumadocs + Vite + Tailwind v4 + Bun, with a new AI-native developer surface (MCP server, AI chat, federated search, integration guides for 6 editors, llms.txt + llms-full.txt). Originally authored by @lmcmz with substantial Cadence-content edits from @joshuahannan and earlier Cadence work from many contributors.
What's new
Framework migration
docs/→content/docs/;_category_.json→meta.jsonAI-native developer surface
flow mcp, the Flow CLI's built-in subcommand (Flow CLI ≥ v2.16.0; Peter Argue's port in flow-cli#2306). Single canonical install path; matches whatflow-ai-tools/scripts/install.shalready registers. The duplicatemcp-server/(Hao's npm@outblock/cadence-mcp) was removed from this PR — its 3 unique tools (security scan, JSON-CDC validation, doc search) tracked for upstream contribution in Upstream unique cadence-mcp tools to onflow/flow-cli (security scan, validate args, doc search) #307./api/chat— Anthropic streaming (defaultclaude-sonnet-4-6), with rate limiting (30/min/IP), max output tokens (2048), CORS lock, and message-history cap./api/search— Orama-powered search across bothcadence-lang.orgcontent anddevelopers.flow.com(via theexternal/onflow-docsgit submodule). Cross-site results link to absolute developers.flow.com URLs./llms.txt+/llms-full.txt— TanStack server routes serving deterministic LLM-optimized indexes of all 93 docs pages organized into 5 named sections./docs/ai-tools/— install instructions foronflow/flow-ai-tools(Claude Code marketplace with 11 Flow skills), MCP server install, LLM endpoints reference, and integration guides for Claude / Cursor / Codex / Gemini / Antigravity / OpenCode.@vercel/og+ Satori at/og/docs/<slug>/image.png.AGENTS.mdat repo root — guidance for AI coding agents working in this repo (TanStack/Fumadocs-aware).Follow-ups (tracked as separate issues)
Migrate— superseded bymcp-server/fromcadence-lang.orgtoonflow/flow-ai-toolsmcp-server/removal in this PRRename— superseded; now: deprecate@outblock/cadence-mcp→@onflow/cadence-mcpon npm@outblock/cadence-mcpwith a redirect notice pointing atflow mcpcadence_security_scan,cadence_validate_args, doc-search trio) intoonflow/flow-cli/internal/mcpexternal/onflow-docs/llms.txtentriesbuild/llms.txtartifact cleanupinterfaces.mdxfield-access widening,contracts.mdxupdate signatureTest plan
/,/docs,/docs/language/resources,/docs/tutorial/first-steps,/docs/ai-tools/mcp-serverall return 200/llms.txtreturns 200 with all 93 pages, 5 sections/llms-full.txtreturns 200 with all 93 pages content/api/chatreturns sensible responses (withANTHROPIC_API_KEYset)/api/search?query=resourcesreturns relevant top-3/og/docs/language/resources/image.pngrobots.txtcontainsContent-Signal:directiveCredits
Fix128type #268 (Fix128documentation), Edit Measuring Time and Testing articles #271 (Measuring Time + Testing edits)git log