docs: separate shared style guide from repo-specific config (#2304)

## Summary
Separate general Apify writing style rules from repository-specific
Markdown/Docusaurus conventions to
enable future reuse across other Apify teams.
- Move general formatting rules (headings, bold, italics, links,
numbers, parallel structure) from
content-standards.md into writing-style.md
  - Extract grammar mechanics into new grammar-rules.md
- Refocus content-standards.md on Markdown/Docusaurus specifics (front
matter, admonitions, code blocks,
  images)

After this PR, general files (`writing-style.md`, `grammar-rules.md`,
`terminology.md`) contain no
repo-specific content and can be extracted into a shared repository.
Repo-specific files
(`content-standards.md`, `file-organization.md`, `quality-standards.md`)
stay here.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Author: 3 people

.claude/README.md

@@ -9,10 +9,11 @@ This directory contains Claude Code configuration for the Apify documentation re
 ├── README.md              # This file - Quick start guide
 ├── instructions.md        # Main instructions for Claude Code
 ├── rules/                 # Canonical standards (auto-loaded)
-│   ├── writing-style.md   # Language, tone, grammar
-│   ├── content-standards.md  # Formatting, front matter, code
-│   ├── terminology.md     # Apify-specific terms
+│   ├── writing-style.md   # Prose voice and tone
+│   ├── content-standards.md  # Formatting and structure
+│   ├── terminology.md     # Product names and capitalization
 │   ├── file-organization.md  # Naming conventions
+│   ├── grammar-rules.md      # Grammar mechanics, punctuation, numbers, brand spelling
 │   └── quality-standards.md  # Quality checklist
 └── skills/                # Reusable skills for common tasks
     ├── doc-write/         # Documentation writing skill
@@ -73,11 +74,12 @@ Use /review-docs skill to review sources/platform/[file-name].md
 
 All documentation standards are in `.claude/rules/` (auto-loaded):
 
-1. **`writing-style.md`** - Language, tone, grammar, headings, word choice
-2. **`content-standards.md`** - Front matter, formatting, code examples, links, images
-3. **`terminology.md`** - Apify-specific capitalization and product names
-4. **`file-organization.md`** - File naming and directory structure
-5. **`quality-standards.md`** - Comprehensive pre-submission checklist
+1. **`writing-style.md`** - Prose voice and tone
+1. **`content-standards.md`** - Formatting and structure
+1. **`terminology.md`** - Product names and capitalization
+1. **`grammar-rules.md`** - Grammar mechanics, punctuation, numbers, brand spelling
+1. **`file-organization.md`** - File naming and directory structure
+1. **`quality-standards.md`** - Complete quality checklist
 
 Also reference:
 
@@ -92,16 +94,17 @@ Before submitting:
 ```bash
 npm run lint:md      # Check markdown
 npm run lint:code    # Check code
+vale "path/to/file.md" --minAlertLevel=error  # Check prose style
+npm run openapi:lint # Validate OpenAPI specs
 npm start            # Preview changes
-npm test             # Validate API specs
 ```
 
 ## Best practices
 
-1. **Read `AGENTS.md` first** - Vendor-agnostic documentation standards
+1. **Read `CLAUDE.md` first**
 2. **Check `.claude/rules/`** - Auto-loaded standards for writing, formatting, terminology
 3. **Use the appropriate skill** - Designed for specific documentation tasks
-4. **Run linters before committing** - `npm run lint:md` and `npm run lint:code`
+4. **Run linters before committing** - `npm run lint:md`, `npm run lint:code`, and `vale`
 5. **Review before submit** - Use `/review-docs` skill for final checks
 
 ## Need help?

.claude/claude.json

@@ -1,7 +1,6 @@
 {
   "instructions": "instructions.md",
   "context": [
-    "../AGENTS.md",
     "../CONTRIBUTING.md"
   ]
 }

.claude/instructions.md

@@ -1,18 +1,6 @@
 # Claude Code instructions for Apify documentation
 
-Read `AGENTS.md` first - it is the single source of truth for project architecture, commands, writing style, and terminology.
-
-## Claude Code specifics
-
-Detailed documentation standards are auto-loaded from `.claude/rules/`:
-
-- `writing-style.md` - Language, tone, grammar, headings
-- `content-standards.md` - Front matter, formatting, code examples, links, images
-- `terminology.md` - Apify product capitalization
-- `file-organization.md` - Naming and directory structure
-- `quality-standards.md` - Pre-submission checklist
-
-These rules expand on the standards in `AGENTS.md` with detailed examples and tables.
+`CLAUDE.md` (symlink to `AGENTS.md`) covers project architecture, commands, and common pitfalls. Documentation standards are auto-loaded from `.claude/rules/` - those are the canonical source for all writing, formatting, and terminology rules.
 
 ## Available skills
 

.claude/rules/content-standards.md

@@ -1,12 +1,6 @@
----
-description: Standard formatting rules for all Apify documentation
-globs: ["sources/**/*.md", "sources/**/*.mdx"]
-alwaysApply: true
----
-
 # Content Standards
 
-Canonical formatting standards for all Apify documentation. These rules ensure consistency across platform docs, academy tutorials, and API references.
+Markdown and Docusaurus formatting standards for Apify documentation. For general writing style rules (headings, text formatting, links, numbers), see `writing-style.md`.
 
 ## Front matter requirements
 
@@ -56,97 +50,18 @@ slug: /academy/tutorials/web-scraper
 ---
 ```
 
-## Headings
-
-### Casing
-
-**Sentence case only.** Capitalize only the first word and proper nouns.
-
-#### Common mistakes
-
-| Avoid (Title Case) | Prefer (Sentence case) | Rule |
-|-------------------|------------------------|------|
-| Store And Manage Data | Store and manage data | Lowercase articles, conjunctions, prepositions |
-| Getting Started With Actors | Get started with Actors | "Actors" stays capitalized (Apify product name) |
-| Use The Apify SDK | Use the Apify SDK | "SDK" stays capitalized (acronym) |
-| Advanced Web Scraping Techniques | Advanced web scraping techniques | Lowercase generic terms |
-| Configure GitHub Actions | Configure GitHub Actions | Preserve proper noun capitalization |
-| Connect To Google Sheets | Connect to Google Sheets | Lowercase prepositions ("to") |
-| Set Up Your Environment | Set up your environment | Lowercase articles ("your") |
-| API Reference Documentation | API reference documentation | Keep acronyms capitalized, rest lowercase |
-| Working With Docker Containers | Work with Docker containers | "Docker" stays capitalized (product name) |
-| Extend The Base Image | Extend the base image | Lowercase "the" mid-sentence |
-| How Do I Start? | How do I start? | Capitalize "I" in questions |
-| Understanding Request Queues | Understand request queues | Lowercase feature names |
-| Enable Standby Mode | Enable standby mode | Lowercase mode names |
-| Access The Apify Console | Access the Apify Console | "Apify Console" stays capitalized (product) |
-| Run Your First Actor | Run your first Actor | "Actor" capitalized, "your" lowercase |
-| Manage Node Modules | Manage node modules | Lowercase generic terms |
-| Step 1: install the dependencies | Step 1: Install the dependencies | Capitalize after colon (starts new clause) |
-| Option 2: use the alternative approach | Option 2: Use the alternative approach | Capitalize after colon (starts new clause) |
+## Heading hierarchy
 
-### Form
-
-**No gerunds (-ing forms).** Use noun phrases or imperatives.
-
-| Avoid | Prefer |
-|-------|--------|
-| Finding available tags | Available tags |
-| Getting started with Actors | Get started with Actors |
-| Understanding the API | API overview |
-
-### Hierarchy
-
-Follow proper heading hierarchy: H1 → H2 → H3. Never skip levels.
+Follow proper heading hierarchy: H2 → H3 → H4. Never skip levels. (H1 is the page title, set in front matter)
 
 ```markdown
-# Page Title (H1 - only one per page, usually from front matter)
-
-## Main Section (H2)
+## Main section (H2)
 
 ### Subsection (H3)
 
 #### Detail (H4 - use sparingly)
 ```
 
-## Text formatting
-
-### Bold
-
-**Do use bold for:**
-- UI elements (buttons, menus, fields, tabs)
-- Critical warnings or key terms that must stand out
-
-**Don't use bold for:**
-- List introductions or section labels
-- Code block introductions
-- General emphasis (use italics instead)
-- Structural labels when context is clear
-
-| Avoid | Prefer |
-|-------|--------|
-| **Examples:** | Examples: |
-| **In your Dockerfile**, use... | In your `Dockerfile`, use... |
-
-### Italics
-
-Use italics for emphasis and introducing new terms:
-
-| Use case | Example |
-|----------|---------|
-| New term introduction | An *Actor* is a serverless program... |
-| Emphasis | This step is *required* for the Actor to work |
-
-### Code formatting
-
-Use backticks for inline code:
-
-- File names: `Dockerfile`, `package.json`, `.actor/actor.json`
-- Commands: `npm install`, `docker build`
-- Config keys: `actorSpecification`, `dockerfile`
-- Variable names: `API_TOKEN`, `userId`
-- Code values: `true`, `null`, `"string"`
-
 ## Admonitions
 
 Use Docusaurus admonitions for important information. **All admonitions MUST have titles.**
@@ -268,27 +183,6 @@ FROM apify/actor-node-playwright:22
 
 ## Links
 
-### Descriptive link text
-
-Use action-oriented, descriptive link text. Avoid generic phrases like "click here" or "this link" - screen readers often read links out of context.
-
-| Avoid | Prefer |
-|-------|--------|
-| `[Click here](url)` to learn more | `[Learn about Actor pricing](url)` |
-| Read more about it `[here](url)` | Read the `[Actor development guide](url)` |
-| See the `[documentation](url)` | `[Read the API documentation](url)` |
-
-### Action verbs for links
-
-Match the verb to the content type:
-
-| Content type | Verbs |
-|--------------|-------|
-| Documentation | Read, View, Check, See |
-| Tutorials | Learn, Build, Follow |
-| Reference | Access, Browse, Explore |
-| Examples | View, Try, Clone |
-
 ### Internal vs external links
 
 **Internal links** (within apify-docs):
@@ -299,17 +193,6 @@ Match the verb to the content type:
 - Use full URLs: `[Playwright](https://playwright.dev)`
 - Make tool mentions navigable
 
-### Actor references
-
-First mention: Actor name with link, capitalized.
-
-```markdown
-[Website Content Crawler](https://apify.com/apify/website-content-crawler)
-can crawl websites and extract text content.
-```
-
-Subsequent mentions: Just the name, no link needed.
-
 ## Images
 
 ### Alt text
@@ -352,53 +235,15 @@ platform/
 │       └── run-button.png
 ```
 
-## Numbers and formatting
-
-### Thousands and decimals
-
-- Thousands: comma separator ($1,000)
-- Decimals: period ($9.8)
-
-### Money
-
-- Symbol before amount: $49 (not 49$)
-- Include currency: $49 USD for international context
-
-### Dates
-
-- Format: Month Day, Year
-- Example: August 5, 2024
-- Never: 5.8.2024 or 2024-08-05 in prose (ISO format OK in code)
-
-### Time
-
-- Format: 12-hour with space before AM/PM
-- Example: 5 PM, 11:30 AM
-- Uppercase: PM (not pm or p.m.)
-
-## Parallel structure
-
-All items in a list must follow the same grammatical pattern:
-
-**Avoid - mixed patterns:**
-```markdown
-1. Reproducibility - your builds behave the same
-1. Predictability - you know which version
-1. Easier to track down issues
-```
-
-**Prefer - consistent pattern:**
-```markdown
-1. Reproducibility - Your builds behave the same way
-1. Predictability - You know exactly which version you're running
-1. Debugging - Version-specific issues are easier to track down
-```
+## Lists
 
-## List types
+### List types
 
 - **Numbered lists**: Sequential steps where order matters
 - **Bullet points**: Non-sequential items, features, options
 
+### Numbered list convention
+
 In numbered lists, use `1.` for all items (not sequential numbers):
 
 ```markdown

.claude/rules/file-organization.md

@@ -1,9 +1,3 @@
----
-description: File naming conventions and directory structure standards
-globs: ["sources/**/*"]
-alwaysApply: true
----
-
 # File Organization Rules
 
 ## Naming conventions