docs: Refactor of Build with AI section

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

@@ -1,125 +1,99 @@
 ---
 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, refer to Apify Docs via llms.txt, and follow best practices for 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, reference Apify Docs via llms.txt, and follow best practices to build Actors efficiently with AI coding 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.
+You will learn several approaches to building Apify Actors with the help of AI coding assistants. This guide includes independent instructions, tools, and best practices that you can use individually or combine together. Each section focuses on a specific part of the process such as prompt usage, Actor templates, Apify MCP server tools, or documentation integration, so you can follow only the parts that fit your development style.
 
-## `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 such as [Cursor](https://www.cursor.com/), [Claude Code](https://www.claude.com/product/claude-code) or [GitHub Copilot](https://github.com/features/copilot):
 
-<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.
+<PromptButton prompt={AGENTS_PROMPT} title="Use pre-built prompt for your AI coding assistant" />
 
-#### Cursor
+The prompt guides AI coding assistants such as Cursor, Claude Code or GitHub Copilot to help users create and deploy an Apify Actor step by step. It walks through setting up the Actor structure, configuring all required files, installing dependencies, running it locally, logging in, and pushing it to the Apify platform and following Apify’s best practices.
 
-Go to: **Settings -> Cursor Settings -> Indexing & Docs -> Add Doc**.
+### Quick Start
 
-Now, you can just provide the link to Apify `llms-full.txt`:
+1. Create directory: `mkdir my-new-actor`
+1. Open the directory in _Cursor_, _Claude Code_, _VS Code with GitHub Copilot_, etc.
+1. Copy the prompt above and paste it into your AI coding assistant (Agent or Chat)
+1. Run it, and develop your first actor with the help of AI
 
-```markdown
-https://docs.apify.com/llms-full.txt
-```
-
-![Add llms-full.txt to Cursor](./images/cursor.png)
-
-#### Windsurf
-
-Open Windsurf Cascade, and add context via `@web`:
+:::info Avoid copy-pasting
 
-![Add llms-full.txt to Windsurf](./images/windsurf.png)
-
-:::note Windsurf @docs
-
-Windsurf provides the `@docs` command, but you cannot customize it. It means that you cannot add your own documentation.
+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. You can use the [Apify CLI](/cli/docs) to create Actors from Actor Templates.
 
-:::note GitHub Copilot and documentation
-
-Similar to Windsurf, GitHub Copilot does not provide an option for adding your own documentation.
-
-:::
-
-#### 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)
+```bash
+apify create
+```
 
-## View pages as markdown
+If you do not have Apify CLI installed, see the [installation guide](/cli/docs/installation).
 
-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.' }) {
@@ -56,7 +56,7 @@ export default function PromptButton({ prompt = QUICK_START_PROMPT, title = 'Use
                         className={styles['toggle-button']}
                         onClick={togglePrompt}
                     >
-                        {showPrompt ? 'Hide the prompt' : 'Show the prompt'}
+                        {showPrompt ? 'Hide prompt' : 'Show prompt'}
                     </button>
                     <button
                         className={`${styles['copy-button']} ${copied ? styles.copied : ''}`}

src/components/PromptButton.module.css

@@ -14,7 +14,7 @@
 }
 
 /* Apply margin-bottom only when the next sibling is not a heading */
-.prompt-card:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)) {
+.prompt-card:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)), .full-prompt-container:not(:has(+ h1, + h2, + h3, + h4, + h5, + h6)) {
   margin-bottom: var(--ifm-leading);
 }
 
@@ -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,13 +127,25 @@
 .toggle-button:hover {
   background: var(--ifm-color-primary);
   color: var(--ifm-color-primary-contrast-background);
-  transform: translateY(-1px);
 }
 
 .toggle-button:active {
   transform: translateY(0);
 }
 
+/* Dark theme: make secondary button appear as white pill with dark text */
+html[data-theme='dark'] .toggle-button {
+  background: #ffffff;
+  color: #111827; /* nearly black for contrast */
+  border-color: #e5e7eb; /* subtle gray border */
+}
+
+html[data-theme='dark'] .toggle-button:hover {
+  background: #f8fafc; /* slight hover tint, keep white look */
+  color: #111827;
+  border-color: #d1d5db;
+}
+
 .full-prompt {
   margin-top: 1.2rem;
   padding: 1.2rem;