docs: Refactor of Build with AI section

sources/platform/actors/development/quick_start/build_with_ai.md

@@ -1,125 +1,101 @@
 ---
 title: Build with AI
 sidebar_position: 3
-description: Learn how to set up your environment, choose the right tools, and establish workflows for effective vibe coding
+description: Use pre-built prompts, use Apify docs via llms.txt, and follow best practices to effective vibe coding.
 slug: /actors/development/quick-start/build-with-ai
 toc_max_heading_level: 4
 ---
 
-**Set up your environment, choose tools, and build workflows for effective AI development.**
+**Use pre-built prompts, use Apify docs via llms.txt, and follow best practices to build Actors efficiently with AI assistants.**
 
 ---
 
-import { RULES_AND_INSTRUCTIONS_PROMPT } from "@site/src/utils/ai-prompts";
+import { AGENTS_PROMPT } from "@site/src/utils/agents-prompt";
 import PromptButton from "@site/src/components/PromptButton";
+import InstallMCPButton from "@site/src/components/InstallMCPButton";
+import copyForAI from "./images/copy-for-ai.png";
 
-This guide explains how to enhance your development workflow by leveraging `llms.txt` and `llms-full.txt` with an AI assistant. You will learn how to provide foundational context and further refine AI's behavior with specific rules and instruction files.
+This guide shows you how to build Actors efficiently with AI coding assistants. You'll learn how to use pre-built instructions, integrate Apify documentation into your AI editor, and apply best practices for AI-assisted development.
 
-## `llms.txt` and `llms-full.txt`
+## AI coding assistant instructions
 
-Search engines weren't built for Large Language Models (LLMs), but they needs context. That's why we've created [`llms.txt`](https://docs.apify.com/llms.txt) and [`llms-full.txt`](https://docs.apify.com/llms-full.txt) for our documentation. These files follow the [growing standard](https://llmstxt.org/) for LLMs consumption.
+Use the following prompt in your AI coding assistant ([Cursor](https://www.cursor.com/), [Claude Code](https://www.claude.com/product/claude-code), [GitHub Copilot](https://github.com/features/copilot), etc.):
 
-<table>
-  <thead>
-    <tr>
-      <th>File</th>
-      <th>Purpose</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>llms.txt</code></td>
-      <td>Contains index of the docs page in Markdown, with links to all subpages in Markdown.</td>
-    </tr>
-    <tr>
-      <td>
-        <code style={{ whiteSpace: 'nowrap' }}>llms-full.txt</code>
-      </td>
-      <td>Contains a full dump of documentation in Markdown.</td>
-    </tr>
-  </tbody>
-</table>
-
-### Use llms.txt and llms-full.txt
-
-LLMs don't automatically discover `llms.txt` files, you need to add the link manually. Some tools like [Cursor](https://www.cursor.com/) provide settings for this.
-
-#### Cursor
-
-Go to: **Settings -> Cursor Settings -> Indexing & Docs -> Add Doc**.
-
-Now, you can just provide the link to Apify `llms-full.txt`:
-
-```markdown
-https://docs.apify.com/llms-full.txt
-```
-
-![Add llms-full.txt to Cursor](./images/cursor.png)
+<PromptButton prompt={AGENTS_PROMPT} title="Use pre-built prompt for your AI coding assistant" />
 
-#### Windsurf
+### Quick Start
 
-Open Windsurf Cascade, and add context via `@web`:
+- _Step 1_: Create directory: `mkdir my-new-actor`
+- _Step 2_: Open the directory in _Cursor_, _Claude Code_, _VS Code with GitHub Copilot_, etc.
+- _Step 3_: Copy the prompt above and paste it into your AI coding assistant (Agent or Chat)
+- _Step 4_: Run it, and develop your first actor with the help of AI 🎉
 
-![Add llms-full.txt to Windsurf](./images/windsurf.png)
+:::info Start in an AI coding assistant
 
-:::note Windsurf @docs
-
-Windsurf provides the `@docs` command, but you cannot customize it. It means that you cannot add your own documentation.
+To maximize efficiency, copy the prompt to Cursor, VS Code with GitHub Copilot, or another AI coding assistant. The AI will follow the guide step-by-step, and you'll avoid copy-pasting from tools like ChatGPT or Claude.
 
 :::
 
-#### GitHub Copilot
-
-Open Copilot Chat mode, and add context via `#fetch`:
+## Use Actor templates with AGENTS.md
 
-![Add llms.txt to Copilot](./images/github-copilot.png)
+All [Actor Templates](https://apify.com/templates) have AGENTS.md that will help you with AI coding. If you prefer a more traditional approach, run the following command:
 
-:::note GitHub Copilot and documentation
+:::info Install Apify CLI
 
-Similar to Windsurf, GitHub Copilot does not provide an option for adding your own documentation.
+If you don't have Apify CLI installed, install it first. Check the [installation guide](/cli/docs/installation).
 
 :::
 
-#### Ask AI
-
-New to Apify? Ask questions and provide the `llms.txt` link. Popular AI models can search the web. With the right context, you get better answers:
-
-![Ask about Apify](./images/claude.png)
-
-## View pages as markdown
+```bash
+apify create
+```
 
-Every page in Apify documentation is available in markdown format. Simply add `.md` to any documentation URL to access the raw markdown content.
+The command above will guide you through Apify Actor initialization, where you select an Actor Template that works for you. The result is an initialized Actor (with AGENTS.md) ready for development.
 
-For example:
+## Use Apify MCP Server
 
-- [https://docs.apify.com/platform](https://docs.apify.com/platform) → [https://docs.apify.com/platform.md](https://docs.apify.com/platform.md)
-- [https://docs.apify.com/api](https://docs.apify.com/api) → [https://docs.apify.com/api.md](https://docs.apify.com/api.md)
+The Apify MCP Server has tools to search and fetch documentation. If you set it up in your AI editor, it will help you improve the generated code by providing additional context to the AI.
 
-This is useful when you want to:
+:::info Use Apify MCP server configuration
 
-- Copy documentation content for AI prompts
-- Reference exact markdown syntax
-- Access content programmatically
+We have prepared the [Apify MCP server configuration](https://mcp.apify.com/), which you can configure for your needs.
 
-## Add rules
+:::
 
-To get the most from AI Code Editors, add rules or instructions.
+## Provide context to assistants
 
-See how to set up rules for your AI Code Editors:
+Every page in the Apify documentation has a _Copy for LLM_ button. You can use it to add additional context to your AI assistant, or even open the page in ChatGPT, Claude, or Perplexity and ask additional questions.
 
-- [Cursor Rules](https://docs.cursor.com/en/context/rules)
-- [Windsurf Rules](https://docs.windsurf.com/windsurf/cascade/memories#rules)
-- [GitHub Copilot instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
+<img src={copyForAI} alt="Copy for LLM" width="250" />
 
-### Apify rules and instructions
+## Use `llms.txt` and `llms-full.txt`
 
-The best rules and instructions are specific for individual use cases, but we provide a prompt to help you get start with creating rules and instructions:
+Search engines weren't built for Large Language Models (LLMs), but LLMs need context. That's why we've created [`llms.txt`](https://docs.apify.com/llms.txt) and [`llms-full.txt`](https://docs.apify.com/llms-full.txt) for our documentation. These files can provide additional context if you link them.
 
-<PromptButton prompt={RULES_AND_INSTRUCTIONS_PROMPT}/>
+<table>
+  <thead>
+    <tr>
+      <th>File</th>
+      <th>Purpose</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>llms.txt</code></td>
+      <td>Contains index of the docs page in Markdown, with links to all subpages in Markdown.</td>
+    </tr>
+    <tr>
+      <td>
+        <code style={{ whiteSpace: 'nowrap' }}>llms-full.txt</code>
+      </td>
+      <td>Contains a full dump of documentation in Markdown.</td>
+    </tr>
+  </tbody>
+</table>
 
-:::info Keep your rules and instructions up to date
+:::note Provide link to AI assistants
 
-As the project evolves, you might introduce new things. Always make sure that your rules and instructions are up to date.
+LLMs don't automatically discover `llms.txt` files, you need to add the link manually to improve the quality of answers.
 
 :::
 

src/components/InstallMCPButton.jsx

@@ -0,0 +1,26 @@
+import React from 'react';
+
+import { ExternalLinkIcon } from '@apify/ui-icons';
+import { Text } from '@apify/ui-library';
+
+import styles from './InstallMCPButton.module.css';
+
+export default function InstallMCPButton({ link, label = 'Install MCP', children }) {
+    if (!link) return null;
+
+    return (
+        <a href={link} className={styles.button} target="_blank" rel="noopener noreferrer">
+            <div className={styles.wrapper}>
+                <div className={styles.iconWrapper} aria-hidden>
+                    <ExternalLinkIcon size={16} className={styles.icon} />
+                </div>
+                <Text
+                    size="regular"
+                    className={styles.label}
+                >
+                    {children || label}
+                </Text>
+            </div>
+        </a>
+    );
+}

src/components/InstallMCPButton.module.css

@@ -0,0 +1,54 @@
+.wrapper {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    color: var(--ifm-color-content);
+}
+
+.button {
+    width: fit-content;
+    display: inline-flex;
+    align-items: center;
+    height: 3rem;
+
+    display: flex;
+    align-items: center;
+    border-radius: 8px;
+    border: 1px solid var(--color-Neutral_SeparatorSubtle);
+    background-color: var(--color-Neutral_BackgroundMuted);
+
+    cursor: pointer;
+    transition: background-color 0.2s ease-in-out;
+
+    &:hover {
+        background-color: var(--color-Neutral_BackgroundMuted);
+    }
+}
+
+.label {
+    height: 100%;
+    display: flex;
+    align-items: center;
+    padding-right: 0.8rem;
+    min-width: 9.3rem;
+
+    /* prevents font size glitch when loading the page */
+    margin: 0px;
+    font-size: 1.4rem;
+    font-weight: 400;
+    font-family: Inter, sans-serif;
+}
+
+.button:hover {
+    background-color: var(--color-Neutral_BackgroundMuted);
+    color: var(--ifm-color-content);
+}
+
+.iconWrapper {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding-left: 0.8rem;
+    padding-right: 0.4rem;
+    height: 100%;
+}

src/components/PromptButton.jsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 
-import { QUICK_START_PROMPT } from '../utils/ai-prompts';
+import { QUICK_START_PROMPT } from '../utils/quick-start-prompt';
 import styles from './PromptButton.module.css';
 
 export default function PromptButton({ prompt = QUICK_START_PROMPT, title = 'Use pre-built prompt to get started faster.' }) {

src/components/PromptButton.module.css

@@ -85,7 +85,6 @@
 .copy-button:hover {
   background: var(--ifm-color-primary-darker);
   border-color: var(--ifm-color-primary-darker);
-  transform: translateY(-1px);
 }
 
 .copy-button:active {
@@ -128,7 +127,6 @@
 .toggle-button:hover {
   background: var(--ifm-color-primary);
   color: var(--ifm-color-primary-contrast-background);
-  transform: translateY(-1px);
 }
 
 .toggle-button:active {