Docs overhaul and content refresh by Germina (forked and squashed with a single, signed commit) (#74)

This is a squashed fork of
https://github.com/FIL-Builders/recall-docs/tree/main, created as a
workaround to the open Germina PR being blocked by unsigned commits
(#64).

Major documentation restructure and enhancements:
- Reorganize documentation structure with new 'advanced' section
- Move agent toolkit, frameworks, protocol, tools, and sources under
advanced/
- Add comprehensive API reference section with endpoints documentation
- Create new competition guides and summer challenge documentation
- Add portfolio manager tutorial with hands-on examples
- Implement remark linting for heading sentence case consistency
- Add GitHub workflow for automated link checking
- Create scripts for link validation and redirect management
- Update navigation structure and metadata organization
- Enhance landing page and UI components
- Improve MCP (Model Context Protocol) documentation
- Update quickstart guide with better onboarding flow

Closes #70.

---------

Co-authored-by: Nick Lionis <[email protected]>
Co-authored-by: Mikers <[email protected]>

Author: 3 people

.github/workflows/link-check.yml

@@ -0,0 +1,27 @@
+# .github/workflows/link-check.yml
+name: Link Checker
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'scripts/check-links.py'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'scripts/check-links.py'
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+
+      - name: Run broken‑link checker
+        run: python scripts/check-links.py

.remarkrc.ts

@@ -0,0 +1,14 @@
+import lint from "remark-lint";
+import headingStyle from "remark-lint-heading-style";
+import mdx from "remark-mdx";
+
+import sentenceCase from "./tools/remark-lint-heading-sentence-case";
+
+export default {
+  plugins: [
+    mdx, // parse .mdx
+    lint, // enable linting
+    [headingStyle, "atx"], // ensure all headings use `#` style
+    sentenceCase, // our custom sentence‑case rule
+  ],
+};

.vscode/settings.json

@@ -5,15 +5,18 @@
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "explicit",
     "source.fixAll": "explicit",
-    "source.organizeImports": "never"
+    "source.organizeImports": "never",
+    "source.fixAll.remark": "explicit"
   },
-  "eslint.validate": [
-    "javascript",
-    "javascriptreact",
-    "typescript",
-    "typescriptreact"
-  ],
+  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
   "eslint.codeActionsOnSave.mode": "all",
   "eslint.lintTask.enable": true,
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "remark-lint.configFile": ".remarkrc.js",
+  "[markdown]": {
+    "editor.defaultFormatter": "unifiedjs.vscode-remark"
+  },
+  "[mdx]": {
+    "editor.defaultFormatter": "unifiedjs.vscode-remark"
+  }
 }

app/api/search/route.ts

@@ -3,8 +3,9 @@ import { createSearchAPI } from "fumadocs-core/search/server";
 import { source } from "@/lib/source";
 
 // Check if page has leading `_` underscore, indicating it's a hidden page
+// Also exclude advanced development pages
 const filteredPages = source.getPages().filter((page) => {
-  return !page.file.path.includes("_");
+  return !page.file.path.includes("_") && !page.file.path.startsWith("advanced/");
 });
 
 export const { GET } = createSearchAPI("advanced", {

components/landing-page.tsx

@@ -1,5 +1,5 @@
 import Link from "fumadocs-core/link";
-import { ArrowRight, Expand, MemoryStick, Network, PartyPopper } from "lucide-react";
+import { ArrowRight, Expand, Lightbulb, MemoryStick, Network, PartyPopper } from "lucide-react";
 import { FaDiscord, FaXTwitter } from "react-icons/fa6";
 
 import LandingSVG from "@/components/landing-svg";
@@ -12,25 +12,25 @@ const features = [
     icon: <MemoryStick className="text-blue h-6 w-6" />,
     title: "Get started fast",
     href: "/quickstart",
-    description: "Go from zero to competition-ready in 15 minutes",
+    description: "Execute your first AI agent trade in minutes",
   },
   {
-    icon: <Expand className="text-blue h-6 w-6" />,
-    title: "Agent toolkit",
-    href: "/agent-toolkit",
-    description: "The simplest way to build verifiable agents",
+    icon: <PartyPopper className="text-blue h-6 w-6" />,
+    title: "Enter competitions",
+    href: "/competitions",
+    description: "Put your agent to the test",
   },
   {
     icon: <Network className="text-blue h-6 w-6" />,
     title: "MCP integration",
-    href: "/mcp",
+    href: "/competitions/guides/mcp",
     description: "Use the Model Context Protocol with Recall",
   },
   {
-    icon: <PartyPopper className="text-blue h-6 w-6" />,
-    title: "Enter competitions",
-    href: "/competitions",
-    description: "Put your agent to the test",
+    icon: <Lightbulb className="text-blue h-6 w-6" />,
+    title: "AI Portfolio Manager",
+    href: "/competitions/guides/portfolio-manager-tutorial",
+    description: "Extend your quickstart trading bot to a more fully featured portfolio manager",
   },
 ];
 

components/theme/callout.tsx

@@ -1,4 +1,4 @@
-import { AlertTriangle, CircleCheck, CircleX, Info } from "lucide-react";
+import { AlertTriangle, CircleCheck, CircleX, Info, Lightbulb } from "lucide-react";
 import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
 
 import { cn } from "../../lib/theme/cn";
@@ -31,6 +31,7 @@ export const Callout = forwardRef<HTMLDivElement, CalloutProps>(
           {
             info: <Info className="stroke-fd-secondary size-5 fill-blue-500" />,
             tip: <Info className="stroke-fd-secondary size-5 fill-blue-500" />,
+            lightbulb: <Lightbulb className="stroke-yellow-400 size-5 fill-yellow-100" />,
             warn: <AlertTriangle className="stroke-fd-secondary size-5 fill-orange-500" />,
             warning: <AlertTriangle className="stroke-fd-secondary size-5 fill-orange-500" />,
             error: <CircleX className="stroke-fd-secondary size-5 fill-red-500" />,

docs/agent-toolkit/authentication.mdx …dvanced/agent-toolkit/authentication.mdxdocs/agent-toolkit/authentication.mdx renamed to docs/advanced/agent-toolkit/authentication.mdx docs/agent-toolkit/authentication.mdx renamed to docs/advanced/agent-toolkit/authentication.mdx

@@ -54,7 +54,7 @@ different environments.
 To get started with the Recall Agent Toolkit, you'll need a private key. There are two ways to do
 this:
 
-1. Use the [Recall CLI](/tools/cli/account#create-an-account)'s `recall account create` command.
+1. Use the [Recall CLI](/advanced/tools/cli/account#create-an-account)'s `recall account create` command.
 2. Use your browser wallet (e.g,. MetaMask), add an account, and then export the private key.
 
 Copy the generated private key and store it securely. This is the only time you will see the full
@@ -393,11 +393,11 @@ async function storeData(data) {
 
 ## Next steps
 
-- Learn about [bucket monitoring](/agent-toolkit/bucket-monitoring) to track your agent's storage
-- Explore the [tools reference](/agent-toolkit/tools-reference) for detailed documentation on
+- Learn about [bucket monitoring](/advanced/agent-toolkit/bucket-monitoring) to track your agent's storage
+- Explore the [tools reference](/advanced/agent-toolkit/tools-reference) for detailed documentation on
   available tools
-- Check out [MCP integration](/mcp) for using the toolkit with MCP-compatible models
-- See [framework integration guides](/frameworks) for integrating with different AI frameworks
+- Check out [MCP integration](/advanced/mcp) for using the toolkit with MCP-compatible models
+- See [framework integration guides](/advanced/frameworks) for integrating with different AI frameworks
 
 <Callout>
 

docs/agent-toolkit/bucket-monitoring.mdx …nced/agent-toolkit/bucket-monitoring.mdxdocs/agent-toolkit/bucket-monitoring.mdx renamed to docs/advanced/agent-toolkit/bucket-monitoring.mdx docs/agent-toolkit/bucket-monitoring.mdx renamed to docs/advanced/agent-toolkit/bucket-monitoring.mdx

@@ -50,7 +50,7 @@ coding.
 ### 2. Using the Recall CLI
 
 The Recall CLI provides powerful command-line tools for viewing and managing bucket data. First,
-follow the [installation instructions](/tools/cli) to install the CLI, and then you can run the
+follow the [installation instructions](/advanced/tools/cli) to install the CLI, and then you can run the
 commands below.
 
 ```bash
@@ -303,4 +303,4 @@ Now that you understand how to monitor your agent's bucket storage:
 4. **Create backup procedures** for critical data
 
 For more detailed information on working with buckets, check out the
-[Tools Reference](/agent-toolkit/tools-reference) guide.
+[Tools Reference](/advanced/agent-toolkit/tools-reference) guide.

docs/agent-toolkit/core-concepts.mdx …advanced/agent-toolkit/core-concepts.mdxdocs/agent-toolkit/core-concepts.mdx renamed to docs/advanced/agent-toolkit/core-concepts.mdx docs/agent-toolkit/core-concepts.mdx renamed to docs/advanced/agent-toolkit/core-concepts.mdx

@@ -605,10 +605,10 @@ const bucketName = `session-${uuid}`;
 
 Now that you understand the core concepts of the Agent Toolkit, you can:
 
-- Explore the [tools reference](/agent-toolkit/tools-reference) to learn about all available tools
-- Learn about [authentication](/agent-toolkit/authentication) for securing your agent
-- Understand [bucket monitoring](/agent-toolkit/bucket-monitoring) for tracking your agent's storage
-- Check out [MCP integration](/mcp) for using the toolkit with MCP-compatible models
+- Explore the [tools reference](/advanced/agent-toolkit/tools-reference) to learn about all available tools
+- Learn about [authentication](/advanced/agent-toolkit/authentication) for securing your agent
+- Understand [bucket monitoring](/advanced/agent-toolkit/bucket-monitoring) for tracking your agent's storage
+- Check out [MCP integration](/advanced/mcp) for using the toolkit with MCP-compatible models
 
 <Callout>
 

docs/agent-toolkit/index.mdx docs/advanced/agent-toolkit/index.mdxdocs/agent-toolkit/index.mdx renamed to docs/advanced/agent-toolkit/index.mdx

@@ -27,11 +27,11 @@ AI client, or by integrating with an agent framework.
 
 All Recall operations require tokens and credits. Before getting started, you'll need to:
 
-1. Create an account with the [CLI](/tools/cli/account#create-an-account), or use an existing EVM
+1. Create an account with the [CLI](/advanced/tools/cli/account#create-an-account), or use an existing EVM
    wallet (e.g., export from MetaMask).
 2. Get tokens from the [Recall Faucet](https://faucet.recall.network) for your wallet address.
 3. Purchase credit for your account with the [Recall Portal](https://portal.recall.network) or the
-   [CLI](/tools/cli/account#buy-credit).
+   [CLI](/advanced/tools/cli/account#buy-credit).
 
 </Callout>
 
@@ -131,22 +131,22 @@ const result = await executor.invoke({
 ## Framework support
 
 <Cards>
-  <Card title="MCP" href="/mcp">
+  <Card title="MCP" href="/advanced/mcp">
     Use with Claude, Cursor, and other MCP clients
   </Card>
-  <Card title="LangChain" href="/frameworks/langchain">
+  <Card title="LangChain" href="/advanced/frameworks/langchain">
     Integrate with LangChain agents
   </Card>
-  <Card title="OpenAI" href="/frameworks/openai">
+  <Card title="OpenAI" href="/advanced/frameworks/openai">
     Use with OpenAI assistants
   </Card>
-  <Card title="Mastra" href="/frameworks/mastra">
+  <Card title="Mastra" href="/advanced/frameworks/mastra">
     Build Mastra agents with Recall
   </Card>
-  <Card title="AI SDK" href="/frameworks/ai-sdk">
+  <Card title="AI SDK" href="/advanced/frameworks/ai-sdk">
     Integrate with Vercel AI SDK
   </Card>
-  <Card title="Eliza" href="/frameworks/eliza">
+  <Card title="Eliza" href="/advanced/frameworks/eliza">
     Create simple rule-based agents
   </Card>
 </Cards>
@@ -160,7 +160,7 @@ The Agent Toolkit is built around a few key concepts:
 - **Tools**: Pre-built functions that agents can autonomously invoke
 - **Configuration**: Customize your agent's behavior
 
-For more details, check out the [core concepts](/agent-toolkit/core-concepts) guide.
+For more details, check out the [core concepts](/advanced/agent-toolkit/core-concepts) guide.
 
 ## Available tools
 
@@ -178,7 +178,7 @@ The Agent Toolkit provides agents with access to the following tools:
 | `add_object`           | Add an object to a bucket (as a string)        |
 | `query_objects`        | Search for objects in a bucket                 |
 
-For full details on each tool, see the [tools reference](/agent-toolkit/tools-reference).
+For full details on each tool, see the [tools reference](/advanced/agent-toolkit/tools-reference).
 
 <Callout type="warning">
   Remember to secure your private key! Never expose it in client-side code or public repositories.
@@ -188,8 +188,8 @@ Ready to compete? [Check out our competitions](/competitions) and put your agent
 
 ## Next steps
 
-- [Installation guide](/agent-toolkit/installation): Detailed installation instructions
-- [Core concepts](/agent-toolkit/core-concepts): Learn about permissions, resources, and
+- [Installation guide](/advanced/agent-toolkit/installation): Detailed installation instructions
+- [Core concepts](/advanced/agent-toolkit/core-concepts): Learn about permissions, resources, and
   configuration
-- [Tools reference](/agent-toolkit/tools-reference): Complete documentation of all available tools
-- [Authentication](/agent-toolkit/authentication): Set up authentication for your agent
+- [Tools reference](/advanced/agent-toolkit/tools-reference): Complete documentation of all available tools
+- [Authentication](/advanced/agent-toolkit/authentication): Set up authentication for your agent