From 3407a96e791eb8a89a14a235c512727376c2d9a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sat, 16 Aug 2025 13:04:46 +0200
Subject: [PATCH 1/9] docs: add .cursorignore

---
 .cursorignore | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 .cursorignore

diff --git a/.cursorignore b/.cursorignore
new file mode 100644
index 0000000000..dbb3609b59
--- /dev/null
+++ b/.cursorignore
@@ -0,0 +1,75 @@
+# Dependencies
+node_modules/
+package-lock.json
+yarn.lock
+apify-docs-theme/package-lock.json
+
+# Build artifacts and generated content
+build/
+dist/
+build-docs/
+.docusaurus/
+static/api/
+apify-api.yaml
+apify-api/openapi/code_samples/
+apify-api/docs/
+
+# Large generated files
+*.log
+*.pid
+*.seed
+*.tsbuildinfo
+
+# IDE and editor files
+.vscode/
+.idea/
+.history/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+pids/
+coverage/
+.nyc_output/
+
+# Generated types
+types/
+
+# Turbo cache
+.turbo/
+
+# Generated documentation
+# These are typically auto-generated, but require editing from time to time
+# sources/api/*
+# !sources/api/sidebars.js
+# !sources/api/getting-started.mdx
+
+# Large static files that are auto-generated
+static/api/openapi.json
+static/api/openapi.yaml
+
+# Generated routes and registry files
+.docusaurus/routes.js
+.docusaurus/routesChunkNames.json
+.docusaurus/registry.js
+.docusaurus/globalData.json
+.docusaurus/site-metadata.json
+.docusaurus/client-modules.js
+.docusaurus/docusaurus.config.mjs
+
+# Generated plugin directories
+.docusaurus/docusaurus-plugin-*/
+.docusaurus/docusaurus-theme-*/
+.docusaurus/@apify/
+
+# Generated code samples (these are auto-generated from OpenAPI specs)
+# Note: These are typically auto-generated, but you may need to edit them occasionally
+# Uncomment the lines below if you want to ignore them completely:
+# apify-api/openapi/code_samples/javascript/*.js
+# apify-api/openapi/code_samples/curl/*.sh
+
+# Generated requirements files
+apify-api/scripts/requirements.bin

From 755a735acbc94b7aab0cf47c65a4d10a77e3a75e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sun, 17 Aug 2025 11:52:24 +0200
Subject: [PATCH 2/9] add AGENT.md change cursor rules to be cursor specific

add AGENT.md
remake current cursor rules to be cursor specific
add new section to CONTRIBUTING.md
---
 .cursor/rules/api-documentation.mdc   |  65 ++++++++--
 .cursor/rules/content-formatting.mdc  |  88 ++++++++-----
 .cursor/rules/documentation-style.mdc |  92 +++++--------
 .cursorignore                         |   3 +
 AGENT.md                              | 179 ++++++++++++++++++++++++++
 CONTRIBUTING.md                       |  40 +++++-
 README.md                             |   1 +
 7 files changed, 363 insertions(+), 105 deletions(-)
 create mode 100644 AGENT.md

diff --git a/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc
index 4aa2733663..2df673cecc 100644
--- a/.cursor/rules/api-documentation.mdc
+++ b/.cursor/rules/api-documentation.mdc
@@ -1,21 +1,62 @@
 ---
-description: Standards for OpenAPI specifications and API code samples
+description: Cursor-specific rules for OpenAPI specifications and API documentation
 globs: ["apify-api/**/*.yaml", "apify-api/**/*.js"]
 alwaysApply: true
 ---
 
-# API Documentation Rules
+# Cursor-Specific API Documentation Rules
 
-## OpenAPI specifications
+## Cursor OpenAPI Workflow
 
-- Follow **RESTful conventions** for endpoint design
-- Use **descriptive operation IDs** following camelCase
-- Include **comprehensive examples** for all endpoints
-- Provide **clear parameter descriptions**
+### Using Cursor for OpenAPI Editing
 
-## Code samples
+- Leverage Cursor's YAML syntax highlighting for OpenAPI files
+- Use Cursor's JSON schema validation for OpenAPI specifications
+- Use Cursor's autocomplete for OpenAPI keywords and properties
 
-- Include examples in **multiple languages** (JavaScript, Python, cURL)
-- Use **realistic data** in examples
-- Show **error handling** where appropriate
-- Include **authentication examples**
+### Cursor-Specific API Documentation Tasks
+
+- Use Cursor Chat to "validate this OpenAPI specification"
+- Ask "generate code examples for this endpoint"
+- Request "check for consistency across similar endpoints"
+
+## Cursor Code Sample Generation
+
+### Using Cmd+K for API References
+
+- Use `@apify-api/openapi/paths/**/*.yaml` to reference endpoint definitions
+- Use `@apify-api/openapi/components/schemas/**/*.yaml` to reference data models
+- Use `@AGENT.md` to reference API documentation standards
+
+### Cursor-Specific Code Sample Workflow
+
+```yaml
+# When editing OpenAPI files in Cursor:
+# 1. Use Cursor's YAML validation
+# 2. Leverage autocomplete for OpenAPI keywords
+# 3. Use Cursor Chat to generate examples
+# 4. Use Cursor's search to find similar patterns
+```
+
+## File-Specific Cursor Rules
+
+### For OpenAPI Specification Files (`apify-api/openapi/**/*.yaml`)
+
+- Use Cursor's YAML syntax highlighting and validation
+- Leverage Cursor's autocomplete for OpenAPI 3.0 keywords
+- Use Cursor's search to find similar endpoint patterns
+- Use Cursor Chat to validate OpenAPI compliance
+
+### For Generated Code Samples (`apify-api/openapi/code_samples/**/*.js`)
+
+- Use Cursor's JavaScript syntax highlighting
+- Leverage Cursor's autocomplete for JavaScript APIs
+- Use Cursor's search to find similar code patterns
+- Use Cursor Chat to improve code examples
+
+## Cursor Quality Assurance for APIs
+
+- Use Cursor's YAML validation for OpenAPI files
+- Leverage Cursor's search to ensure endpoint naming consistency
+- Use Cursor Chat to review API documentation completeness
+- Use Cursor's autocomplete to maintain OpenAPI specification standards
diff --git a/.cursor/rules/content-formatting.mdc b/.cursor/rules/content-formatting.mdc
index 8056e0f351..7a549c7fd8 100644
--- a/.cursor/rules/content-formatting.mdc
+++ b/.cursor/rules/content-formatting.mdc
@@ -1,58 +1,80 @@
 ---
-description: Content formatting standards for MDX files and code examples
+description: Cursor-specific content formatting rules for MDX and markdown files
 globs: ["sources/**/*.md", "sources/**/*.mdx"]
 alwaysApply: true
 ---
 
-# Content Formatting Rules
+# Cursor-Specific Content Formatting
 
-## Front matter (MDX files)
+## Cursor MDX/Markdown Features
 
+### Syntax Highlighting in Cursor
+
+- Use language-specific code blocks for proper syntax highlighting
+- Leverage Cursor's MDX component autocomplete
+- Use Cursor's markdown preview for real-time formatting verification
+
+### Cursor-Specific Code Block Handling
+
+```markdown
+# For JavaScript examples
+```javascript
+// Cursor will provide syntax highlighting and autocomplete
+const example = "properly formatted";
+```
+
+# For YAML frontmatter
 ```yaml
 ---
-title: "Clear, action-oriented title"
-description: "140-160 character description that explains the value"
-sidebar_position: 1
-slug: /path/to/page
+title: "Example"
+description: "Description"
 ---
 ```
 
-## Text emphasis
+# For API examples
+```bash
+curl -X GET "https://api.apify.com/v2/acts"
+```
+```
 
-- **Bold** for UI elements, buttons, menu items
-- *Italics* for emphasis and new terms
-- `code` for inline code, file names, paths, variables
-- Use code blocks with language specification for examples
+## Cursor Workflow for Formatting
 
-## Admonitions
+### Using Cursor Chat for Formatting Help
 
-Use admonitions to highlight important information:
+- Ask "format this markdown table properly"
+- Request "add syntax highlighting to this code block"
+- Use "check this frontmatter for proper YAML syntax"
 
-```markdown
-:::note Important information
-Your note content here.
-:::
+### Using Cmd+K for Quick Formatting
 
-:::tip Pro tip
-Helpful tip for users.
-:::
+- Use `@AGENT.md` to reference formatting standards
+- Use `@sources/**/*.mdx` to find similar MDX patterns
+- Use `@apify-api/**/*.yaml` to reference API examples
 
-:::info Additional context
-Background information.
-:::
+## Cursor-Specific Admonition Handling
+
+When using admonitions in Cursor:
 
-:::caution Warning
-Something to be careful about.
+```markdown
+:::note Cursor Tip
+Use Cursor's markdown preview to verify admonition formatting
 :::
 
-:::danger Critical
-Critical information that could cause issues.
+:::tip Cursor Feature
+Leverage Cursor's autocomplete for consistent admonition syntax
 :::
 ```
 
-## Code examples
+## File-Specific Formatting Rules
+
+### For MDX Files (`sources/**/*.mdx`)
+
+- Use Cursor's MDX syntax highlighting
+- Leverage component imports with proper TypeScript support
+- Use Cursor's JSX autocomplete for custom components
+
+### For Markdown Files (`sources/**/*.md`)
 
-- Use **code tabs** for multiple language examples
-- Include **complete, runnable examples**
-- Add **comments** to explain complex code
-- Use **syntax highlighting** for all code blocks
+- Use Cursor's markdown preview for formatting verification
+- Leverage Cursor's spell check for content quality
+- Use Cursor's link validation for internal references
diff --git a/.cursor/rules/documentation-style.mdc b/.cursor/rules/documentation-style.mdc
index 46aaa84e18..1cd9bac770 100644
--- a/.cursor/rules/documentation-style.mdc
+++ b/.cursor/rules/documentation-style.mdc
@@ -1,81 +1,55 @@
 ---
-description: Documentation style guidelines and writing standards for Apify docs
+description: Cursor-specific documentation style rules for Apify docs
 globs: ["sources/**/*.md", "sources/**/*.mdx"]
 alwaysApply: true
 ---
 
-# Documentation Style Guidelines
+# Cursor-Specific Documentation Rules
 
-## Project overview
+## Context-Aware Writing
 
-This is the Apify documentation repository containing platform documentation, academy content, and API reference. The project uses Docusaurus with MDX, OpenAPI specifications, and follows Microsoft style guide principles.
+When editing documentation in Cursor, consider the broader context:
 
-## Documentation structure
+- **Cross-references**: When mentioning other pages, use Cursor's file navigation to verify links
+- **Consistency checks**: Use Cursor's search to ensure terminology consistency across files
+- **Code examples**: Leverage Cursor's syntax highlighting and validation for code blocks
 
-- **Platform docs**: `/sources/platform/` - Core platform features and functionality
-- **Academy**: `/sources/academy/` - Educational content, tutorials, and courses
-- **API reference**: `/apify-api/` - Generated from OpenAPI specifications
+## Cursor-Specific Workflows
 
-## Writing style & guidelines
+### Using Cursor Chat for Documentation
 
-### Language & tone
+- Ask Cursor to "review this documentation for clarity and completeness"
+- Use "explain this technical concept in simpler terms" for complex topics
+- Request "suggest improvements for this tutorial structure"
 
-- Use **US English** spelling and grammar
-- Write in **inclusive language** - avoid gendered terms and assumptions
-- Use **active voice** whenever possible
-- Write for a **technical audience** but keep explanations clear and accessible
-- Avoid directional language (don't use "left/right")
-- Be **action-oriented** in descriptions and titles
+### Using Cmd+K for Quick Edits
 
-### Technical writing best practices
+- Use `@AGENT.md` to reference the main documentation standards
+- Use `@sources/**/*.md` to search across all documentation files
+- Use `@apify-api/**/*.yaml` to reference API specifications
 
-- **Start with the user's goal** - what are they trying to accomplish?
-- **Use clear, concise sentences** - avoid unnecessary complexity
-- **Provide context** before diving into technical details
-- **Use consistent terminology** throughout the documentation
-- **Include examples** for complex concepts
-- **Structure content logically** - from basic to advanced concepts
+## File-Specific Guidance
 
-### Microsoft style guide compliance
+### For Platform Documentation (`sources/platform/**/*.md`)
 
-- Use **sentence case** for headings (except main titles)
-- Use **title case** for UI elements and proper nouns
-- **Bold** for UI elements, buttons, menu items
-- _Italics_ for emphasis and new terms
-- `code` for inline code, file names, and technical terms
-- Use **numbered lists** for sequential steps
-- Use **bullet points** for non-sequential items
+- Focus on practical, actionable guidance
+- Include real-world examples and use cases
+- Reference related API endpoints when applicable
 
-## Common patterns
+### For Academy Content (`sources/academy/**/*.md`)
 
-### Tutorial structure
+- Structure content for learning progression
+- Include hands-on exercises and examples
+- Provide clear prerequisites and next steps
 
-1. **Introduction** - What will the user learn?
-2. **Prerequisites** - What do they need to know/have?
-3. **Step-by-step instructions** - Clear, numbered steps
-4. **Code examples** - Complete, working examples
-5. **Summary** - What they accomplished and next steps
+### For MDX Files
 
-### Troubleshooting sections
+- Leverage Cursor's MDX syntax highlighting
+- Use component imports and JSX syntax appropriately
+- Ensure proper frontmatter formatting
 
-- **Common issues** and solutions
-- **Error messages** and their meanings
-- **Debugging steps** for complex problems
-- **Contact information** for additional help
+## Quality Assurance in Cursor
 
-## Accessibility guidelines
-
-- Use **descriptive link text** (avoid "click here")
-- Include **alt text** for all images
-- Use **proper heading hierarchy** (H1 → H2 → H3)
-- Write **clear, concise content**
-
-## SEO best practices
-
-- Use **descriptive page titles**
-- Include **relevant keywords** naturally
-- Write **meta descriptions** (140-160 characters)
-- Use **proper heading structure**
-- Include **internal links** to related content
-
-Remember: The goal is to help users succeed with Apify. Every piece of documentation should serve that purpose by being clear, accurate, and actionable.
+- Use Cursor's spell check for documentation files
+- Leverage Cursor's markdown preview for formatting verification
+- Use Cursor's search to find similar content and maintain consistency
diff --git a/.cursorignore b/.cursorignore
index dbb3609b59..add8344fdb 100644
--- a/.cursorignore
+++ b/.cursorignore
@@ -73,3 +73,6 @@ static/api/openapi.yaml
 
 # Generated requirements files
 apify-api/scripts/requirements.bin
+
+# AGENT.md is the primary vendor-agnostic rules file
+# .cursor/rules/ contains Cursor-specific rules with advanced features
diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 0000000000..8938ad051e
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1,179 @@
+# Apify Documentation Standards
+
+## Project Overview
+
+This is the Apify documentation repository containing platform documentation, academy content, and API reference. The project uses Docusaurus with MDX, OpenAPI specifications, and follows Microsoft style guide principles.
+
+## Documentation Structure
+
+- **Platform docs**: `/sources/platform/` - Core platform features and functionality
+- **Academy**: `/sources/academy/` - Educational content, tutorials, and courses
+- **API reference**: `/apify-api/` - Generated from OpenAPI specifications
+
+## Writing Style & Guidelines
+
+### Language & Tone
+
+- Use **US English** spelling and grammar
+- Write in **inclusive language** - avoid gendered terms and assumptions
+- Use **active voice** whenever possible
+- Write for a **technical audience** but keep explanations clear and accessible
+- Avoid directional language (don't use "left/right")
+- Be **action-oriented** in descriptions and titles
+
+### Technical Writing Best Practices
+
+- **Start with the user's goal** - what are they trying to accomplish?
+- **Use clear, concise sentences** - avoid unnecessary complexity
+- **Provide context** before diving into technical details
+- **Use consistent terminology** throughout the documentation
+- **Include examples** for complex concepts
+- **Structure content logically** - from basic to advanced concepts
+
+### Microsoft Style Guide Compliance
+
+- Use **sentence case** for headings
+- Use **title case** for UI elements and proper nouns
+- **Bold** for UI elements, buttons, menu items
+- _Italics_ for emphasis and new terms
+- `code` for inline code, file names, and technical terms
+- Use **numbered lists** for sequential steps
+- Use **bullet points** for non-sequential items
+
+## Content Formatting Standards
+
+### Front Matter (MDX files)
+
+```yaml
+---
+title: "Clear, action-oriented title"
+description: "140-160 character description that explains the value"
+sidebar_position: 1
+slug: /path/to/page
+---
+```
+
+### Text Emphasis
+
+- **Bold** for UI elements, buttons, menu items
+- _Italics_ for emphasis and new terms
+- `code` for inline code, file names, paths, variables
+- Use code blocks with language specification for examples
+
+### Admonitions
+
+Use admonitions to highlight important information:
+
+```markdown
+:::note Important information
+Your note content here.
+:::
+
+:::tip Pro tip
+Helpful tip for users.
+:::
+
+:::info Additional context
+Background information.
+:::
+
+:::caution Warning
+Something to be careful about.
+:::
+
+:::danger Critical
+Critical information that could cause issues.
+:::
+```
+
+### Code Examples
+
+- Use **code tabs** for multiple language examples
+- Include **complete, runnable examples**
+- Add **comments** to explain complex code
+- Use **syntax highlighting** for all code blocks
+
+## API Documentation Rules
+
+### OpenAPI Specifications
+
+- Follow **RESTful conventions** for endpoint design
+- Use **descriptive operation IDs** following camelCase
+- Include **comprehensive examples** for all endpoints
+- Provide **clear parameter descriptions**
+
+### Code Samples
+
+- Include examples in **multiple languages** (JavaScript, Python, cURL)
+- Use **realistic data** in examples
+- Show **error handling** where appropriate
+- Include **authentication examples**
+
+## Common Patterns
+
+### Tutorial Structure
+
+1. **Introduction** - What will the user learn?
+2. **Prerequisites** - What do they need to know/have?
+3. **Step-by-step instructions** - Clear, numbered steps
+4. **Code examples** - Complete, working examples
+5. **Summary** - What they accomplished and next steps
+
+### Troubleshooting Sections
+
+- **Common issues** and solutions
+- **Error messages** and their meanings
+- **Debugging steps** for complex problems
+- **Contact information** for additional help
+
+## Accessibility Guidelines
+
+- Use **descriptive link text** (avoid "click here")
+- Include **alt text** for all images
+- Use **proper heading hierarchy** (H1 → H2 → H3)
+- Write **clear, concise content**
+
+## SEO Best Practices
+
+- Use **descriptive page titles**
+- Include **relevant keywords** naturally
+- Write **meta descriptions** (140-160 characters)
+- Use **proper heading structure**
+- Include **internal links** to related content
+
+## File Organization Rules
+
+### Naming Conventions
+
+- Use **kebab-case** for file names: `web-scraping-basics.md`
+- Use **descriptive names** that reflect content
+- Group related files in **logical directories**
+
+### Directory Structure
+
+```text
+sources/
+├── platform/          # Platform documentation
+│   ├── actors/        # Actor-related content
+│   ├── storage/       # Storage documentation
+│   └── integrations/  # Integration guides
+└── academy/           # Educational content
+    ├── tutorials/     # Step-by-step guides
+    ├── webscraping/   # Web scraping courses
+    └── glossary/      # Terminology and definitions
+```
+
+## Quality Standards
+
+When creating or editing content, ensure:
+
+- [ ] Content follows Microsoft style guide (sentence case headings, proper emphasis)
+- [ ] Front matter includes proper title, description, and metadata
+- [ ] Code examples are complete and include proper syntax highlighting
+- [ ] All links use descriptive text (avoid "click here")
+- [ ] Images include meaningful alt text
+- [ ] Content uses inclusive language and active voice
+- [ ] Headings follow proper hierarchy (H1 → H2 → H3)
+- [ ] Content is clear, concise, and action-oriented
+
+Remember: The goal is to help users succeed with Apify. Every piece of documentation should serve that purpose by being clear, accurate, and actionable.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d9b5db074..0e16968c1d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,7 +88,7 @@ You should be able to open https://docs.apify.loc in your browser and run all th
 1. Text emphasis:
 
     - use **Bold** for UI elements
-    - use *Italics* for emphasis
+    - use _Italics_ for emphasis
     - use `code` for inline code, by using back-ticks (\`\`\)
     - use code blocks with language specification
     - use [code tabs](https://docusaurus.io/docs/markdown-features/tabs) whenever you want to include examples of implementation in more than one language
@@ -127,6 +127,44 @@ You should be able to open https://docs.apify.loc in your browser and run all th
 - Avoid repetitive keywords
 - Avoid the word "documentation" in descriptions
 
+## AI Assistant Rules Structure
+
+This project uses a hybrid approach for AI assistant rules to ensure consistency across different tools while leveraging Cursor-specific features.
+
+### Structure Overview
+
+#### Vendor-Agnostic Rules
+
+- **`AGENT.md`** - Primary vendor-agnostic rules file containing core documentation standards
+
+#### Cursor-Specific Rules
+
+- **`.cursor/rules/documentation-style.mdc`** - Cursor-specific documentation guidelines
+- **`.cursor/rules/content-formatting.mdc`** - Cursor-specific formatting rules
+- **`.cursor/rules/api-documentation.mdc`** - Cursor-specific API documentation rules
+- **`.cursor/rules/quality-standards.mdc`** - Cursor-specific quality guidelines
+- **`.cursor/rules/file-organization.mdc`** - Cursor-specific file organization rules
+
+### Usage
+
+#### For General AI Assistants
+
+- Reference `AGENT.md` for vendor-agnostic documentation standards
+
+#### For Cursor-Specific Features
+
+- Use `.cursor/rules/*.mdc` files for Cursor-specific workflows
+- Leverage glob patterns and `alwaysApply` settings
+- Use Cursor Chat and Cmd+K with `@AGENT.md` references
+
+### File Targeting
+
+Each `.mdc` file uses glob patterns to target specific file types:
+
+- **`documentation-style.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]`
+- **`content-formatting.mdc`**: `["sources/**/*.md", "sources/**/*.mdx"]`
+- **`api-documentation.mdc`**: `["apify-api/**/*.yaml", "apify-api/**/*.js"]`
+
 ## Repository structure
 
 ### Theme management
diff --git a/README.md b/README.md
index 5d6aa91f6d..21e27b6937 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ Before contributing, read these essential resources:
 
 - [Contributing guidelines](CONTRIBUTING.md)
 - [Documentation style guide](CONTRIBUTING.md#documentation-style-guide)
+- [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure)
 
 ## Documentation architecture
 

From 7c4fdb222e5bc80706d90e26f87087fe6671d3b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sun, 17 Aug 2025 12:04:53 +0200
Subject: [PATCH 3/9] enhance README & CONTRIBUTING guidelines

---
 .../config/vocabularies/Docs/accept.txt       |  1 +
 CONTRIBUTING.md                               | 15 ++++---
 README.md                                     | 42 ++++++++++++++++---
 3 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/.github/styles/config/vocabularies/Docs/accept.txt b/.github/styles/config/vocabularies/Docs/accept.txt
index 589b45daae..490afb8638 100644
--- a/.github/styles/config/vocabularies/Docs/accept.txt
+++ b/.github/styles/config/vocabularies/Docs/accept.txt
@@ -123,3 +123,4 @@ walkthroughs?
 
 ul
 [Aa]gno
+pnpm
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e16968c1d..6ddccd39c4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,9 +10,10 @@
 
 ### Prerequisites
 
-1. Git
-2. Node.js
-3. GitHub access
+1. **Git**
+2. **Node.js 22** (see [.nvmrc](.nvmrc) file)
+3. **GitHub access**
+4. **npm** or **pnpm** package manager
 
 ### Installation steps
 
@@ -312,21 +313,21 @@ Add languages by adding new folders at the appropriate path level.
 
 ### Linting
 
-1. Markdown:
+1. **Markdown**:
 
     ```bash
     npm run lint:md # Checks for any issues using markdownlint
     npm run lint:md:fix # Applies fixes
     ```
 
-2. Code:
+2. **Code**:
 
     ```bash
     npm run lint:code # Checks .js & .ts files
     npm run lint:code:fix # Applies fixes
     ```
 
-3. Prose:
+3. **Prose**:
 
     - Use [Vale](https://vale.sh/) for content linting
     - Configure exceptions in `accepts.txt`
@@ -347,3 +348,5 @@ Add languages by adding new folders at the appropriate path level.
 
 - [Docusaurus documentation](https://docusaurus.io/docs)
 - [Vale style guide](https://vale.sh/docs)
+- [OpenAPI specification](https://spec.openapis.org/oas/v3.1.0)
+- [Redocly documentation](https://redocly.com/docs/)
diff --git a/README.md b/README.md
index 21e27b6937..e1fdbf2f5b 100644
--- a/README.md
+++ b/README.md
@@ -21,13 +21,43 @@ Our documentation ecosystem consists of:
   - [Python](https://docs.apify.com/sdk/python/)
 - **CLI documentation** - [CLI docs](https://docs.apify.com/cli/)
 
-## Getting started
+## Getting Started
 
-Before contributing, read these essential resources:
+**Before contributing, read these essential resources:**
 
-- [Contributing guidelines](CONTRIBUTING.md)
-- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide)
-- [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure)
+- [Contributing guidelines](CONTRIBUTING.md) - Complete setup and contribution process
+- [Documentation style guide](CONTRIBUTING.md#documentation-style-guide) - Writing standards and formatting
+- [AI Assistant Rules Structure](CONTRIBUTING.md#ai-assistant-rules-structure) - AI tool configuration
+
+### Prerequisites
+
+- **Node.js 22** (see [.nvmrc](.nvmrc))
+- **npm** or **pnpm**
+- **Git**
+
+### Quick Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/apify/apify-docs.git
+cd apify-docs
+
+# Install dependencies
+npm install
+
+# Start development server
+npm start
+```
+
+The site will be available at `http://localhost:3000`
+
+### Available Scripts
+
+- `npm start` - Start development server with API docs
+- `npm run build` - Build for production
+- `npm run lint` - Run all linting checks
+- `npm run lint:fix` - Fix linting issues automatically
+- `npm run api:rebuild` - Regenerate API documentation
 
 ## Documentation architecture
 
@@ -57,7 +87,7 @@ Our documentation is built using:
 - **Automated Deployment**: CI/CD pipeline for continuous updates
 - **nginx routing**: Handles subdomain routing and redirects
 
-## Need help
+### Need help
 
 - For contribution questions, see our [Contributing Guidelines](CONTRIBUTING.md)
 - For technical issues, [create a GitHub issue](https://github.com/apify/apify-docs/issues/new)

From 85baaa5726b4d2097f9c48221d753ffc93366f49 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sun, 7 Sep 2025 23:11:05 +0200
Subject: [PATCH 4/9] mention how to verify Cursor rules application

---
 CONTRIBUTING.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ddccd39c4..768f1f75f5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -146,6 +146,8 @@ This project uses a hybrid approach for AI assistant rules to ensure consistency
 - **`.cursor/rules/quality-standards.mdc`** - Cursor-specific quality guidelines
 - **`.cursor/rules/file-organization.mdc`** - Cursor-specific file organization rules
 
+To verify rule application, hover over attached rules in the Cursor chat window.
+
 ### Usage
 
 #### For General AI Assistants

From 4503f3d2e10c8172ef43cffe317e14d3dff04f9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sun, 7 Sep 2025 23:12:42 +0200
Subject: [PATCH 5/9] fix title case to sentence case in CONTRIBUTING.md

---
 CONTRIBUTING.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 768f1f75f5..636b93ee6d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to Apify Documentation
+# Contributing to Apify documentation
 
 ## Before you start
 
@@ -128,17 +128,17 @@ You should be able to open https://docs.apify.loc in your browser and run all th
 - Avoid repetitive keywords
 - Avoid the word "documentation" in descriptions
 
-## AI Assistant Rules Structure
+## AI Assistant rules structure
 
 This project uses a hybrid approach for AI assistant rules to ensure consistency across different tools while leveraging Cursor-specific features.
 
-### Structure Overview
+### Structure overview
 
-#### Vendor-Agnostic Rules
+#### Vendor-agnostic rules
 
 - **`AGENT.md`** - Primary vendor-agnostic rules file containing core documentation standards
 
-#### Cursor-Specific Rules
+#### Cursor-specific rules
 
 - **`.cursor/rules/documentation-style.mdc`** - Cursor-specific documentation guidelines
 - **`.cursor/rules/content-formatting.mdc`** - Cursor-specific formatting rules
@@ -150,17 +150,17 @@ To verify rule application, hover over attached rules in the Cursor chat window.
 
 ### Usage
 
-#### For General AI Assistants
+#### For general AI assistants
 
 - Reference `AGENT.md` for vendor-agnostic documentation standards
 
-#### For Cursor-Specific Features
+#### For Cursor-specific features
 
 - Use `.cursor/rules/*.mdc` files for Cursor-specific workflows
 - Leverage glob patterns and `alwaysApply` settings
 - Use Cursor Chat and Cmd+K with `@AGENT.md` references
 
-### File Targeting
+### File targeting
 
 Each `.mdc` file uses glob patterns to target specific file types:
 

From 26651195dff962bd58ee135eaccb56f0de9d690f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Sun, 7 Sep 2025 23:19:58 +0200
Subject: [PATCH 6/9] fix markdownlint issue

---
 .cursor/rules/content-formatting.mdc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.cursor/rules/content-formatting.mdc b/.cursor/rules/content-formatting.mdc
index 7a549c7fd8..268529c596 100644
--- a/.cursor/rules/content-formatting.mdc
+++ b/.cursor/rules/content-formatting.mdc
@@ -24,6 +24,7 @@ const example = "properly formatted";
 ```
 
 # For YAML frontmatter
+
 ```yaml
 ---
 title: "Example"
@@ -32,10 +33,11 @@ description: "Description"
 ```
 
 # For API examples
+
 ```bash
 curl -X GET "https://api.apify.com/v2/acts"
 ```
-```
+
 
 ## Cursor Workflow for Formatting
 

From 50c36bd319069d2de01a77a0a44c947178496398 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Mon, 8 Sep 2025 17:58:26 +0200
Subject: [PATCH 7/9] typo fix

---
 AGENT.md => AGENTS.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename AGENT.md => AGENTS.md (100%)

diff --git a/AGENT.md b/AGENTS.md
similarity index 100%
rename from AGENT.md
rename to AGENTS.md

From f35cb1b6d37a4f12fd89cb9ef73bfbed28c7502a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Mon, 8 Sep 2025 18:00:18 +0200
Subject: [PATCH 8/9] fix vale

---
 .github/styles/config/vocabularies/Docs/accept.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/styles/config/vocabularies/Docs/accept.txt b/.github/styles/config/vocabularies/Docs/accept.txt
index 490afb8638..f060e4b925 100644
--- a/.github/styles/config/vocabularies/Docs/accept.txt
+++ b/.github/styles/config/vocabularies/Docs/accept.txt
@@ -84,6 +84,7 @@ preconfigured
 [Tt]rello
 [Pp]refill
 [Gg]umloop
+[Rr]edocly
 
 [Mm]ultiselect
 
@@ -123,4 +124,4 @@ walkthroughs?
 
 ul
 [Aa]gno
-pnpm
\ No newline at end of file
+pnpm

From 1fd86037f5afa799577881386986f7fced770022 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Olender?=
 <92638966+TC-MO@users.noreply.github.com>
Date: Mon, 8 Sep 2025 18:04:00 +0200
Subject: [PATCH 9/9] consistency for AGENTS.md

---
 .cursor/rules/api-documentation.mdc   | 2 +-
 .cursor/rules/content-formatting.mdc  | 2 +-
 .cursor/rules/documentation-style.mdc | 2 +-
 .cursorignore                         | 2 +-
 CONTRIBUTING.md                       | 6 +++---
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.cursor/rules/api-documentation.mdc b/.cursor/rules/api-documentation.mdc
index 2df673cecc..2086f69a60 100644
--- a/.cursor/rules/api-documentation.mdc
+++ b/.cursor/rules/api-documentation.mdc
@@ -26,7 +26,7 @@ alwaysApply: true
 
 - Use `@apify-api/openapi/paths/**/*.yaml` to reference endpoint definitions
 - Use `@apify-api/openapi/components/schemas/**/*.yaml` to reference data models
-- Use `@AGENT.md` to reference API documentation standards
+- Use `@AGENTS.md` to reference API documentation standards
 
 ### Cursor-Specific Code Sample Workflow
 
diff --git a/.cursor/rules/content-formatting.mdc b/.cursor/rules/content-formatting.mdc
index 268529c596..400d9f8d63 100644
--- a/.cursor/rules/content-formatting.mdc
+++ b/.cursor/rules/content-formatting.mdc
@@ -49,7 +49,7 @@ curl -X GET "https://api.apify.com/v2/acts"
 
 ### Using Cmd+K for Quick Formatting
 
-- Use `@AGENT.md` to reference formatting standards
+- Use `@` to reference formatting standards
 - Use `@sources/**/*.mdx` to find similar MDX patterns
 - Use `@apify-api/**/*.yaml` to reference API examples
 
diff --git a/.cursor/rules/documentation-style.mdc b/.cursor/rules/documentation-style.mdc
index 1cd9bac770..515124052c 100644
--- a/.cursor/rules/documentation-style.mdc
+++ b/.cursor/rules/documentation-style.mdc
@@ -24,7 +24,7 @@ When editing documentation in Cursor, consider the broader context:
 
 ### Using Cmd+K for Quick Edits
 
-- Use `@AGENT.md` to reference the main documentation standards
+- Use `@AGENTS.md` to reference the main documentation standards
 - Use `@sources/**/*.md` to search across all documentation files
 - Use `@apify-api/**/*.yaml` to reference API specifications
 
diff --git a/.cursorignore b/.cursorignore
index add8344fdb..bff2cfec08 100644
--- a/.cursorignore
+++ b/.cursorignore
@@ -74,5 +74,5 @@ static/api/openapi.yaml
 # Generated requirements files
 apify-api/scripts/requirements.bin
 
-# AGENT.md is the primary vendor-agnostic rules file
+# AGENTS.md is the primary vendor-agnostic rules file
 # .cursor/rules/ contains Cursor-specific rules with advanced features
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 636b93ee6d..f7d22312da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -136,7 +136,7 @@ This project uses a hybrid approach for AI assistant rules to ensure consistency
 
 #### Vendor-agnostic rules
 
-- **`AGENT.md`** - Primary vendor-agnostic rules file containing core documentation standards
+- **`AGENTS.md`** - Primary vendor-agnostic rules file containing core documentation standards
 
 #### Cursor-specific rules
 
@@ -152,13 +152,13 @@ To verify rule application, hover over attached rules in the Cursor chat window.
 
 #### For general AI assistants
 
-- Reference `AGENT.md` for vendor-agnostic documentation standards
+- Reference `AGENTS.md` for vendor-agnostic documentation standards
 
 #### For Cursor-specific features
 
 - Use `.cursor/rules/*.mdc` files for Cursor-specific workflows
 - Leverage glob patterns and `alwaysApply` settings
-- Use Cursor Chat and Cmd+K with `@AGENT.md` references
+- Use Cursor Chat and Cmd+K with `@AGENTS.md` references
 
 ### File targeting