docs: standards index and stale rules

.agents/skills/doc-write/SKILL.md

@@ -10,8 +10,8 @@ argument-hint: topic
 ## Process
 
 1. **Determine doc type** - platform docs, guide, or reference (tutorials → use `/tutorial`)
-2. **Research** - read related existing pages, check `standards/terminology.md` for product names
-3. **Create front matter** - title (sentence case), description (140-160 chars), sidebar_position, slug
+2. **Research** - read related existing pages, check `standards/style-guide.md` for product names
+3. **Create frontmatter** - title (sentence case), description (140-160 chars), sidebar_position, slug
 4. **Write content** following the structure for the doc type:
    - **Platform docs**: intro → prerequisites → main content → code examples → next steps
    - **Guides**: intro with goal → step-by-step instructions → verification → troubleshooting

.agents/skills/doc-write/references/process.md

@@ -14,10 +14,10 @@ Agent-agnostic workflow for writing or editing Apify documentation.
 ## Step 2: Research
 
 - Read 2-3 existing pages in the same directory to match patterns
-- Check `standards/terminology.md` for product name capitalization
+- Check `standards/style-guide.md` for product name capitalization
 - Identify related pages to link to
 
-## Step 3: Create front matter
+## Step 3: Create frontmatter
 
 ```yaml
 ---
@@ -52,7 +52,7 @@ Read the full existing page before making changes. Preserve the existing structu
 
 ### Description length
 
-Front matter `description` must be 140-160 characters for SEO. Focus on user value, not feature lists.
+Frontmatter `description` must be 140-160 characters for SEO. Focus on user value, not feature lists.
 
 ### Page doesn't match sibling pages
 

.agents/skills/review-docs/SKILL.md

@@ -12,23 +12,21 @@ argument-hint: file-path
 
 1. **Verify file version** - `git status` to confirm you have the latest
 2. **Run deterministic checks** (main process) - these are objective, no judgment needed:
+   - `vale --minAlertLevel=suggestion "<file>"` (prose style: voice, tone, terminology, grammar, headings, link text)
    - `pnpm lint:md` (heading hierarchy, list numbering, spacing)
    - `.agents/skills/review-docs/scripts/check-frontmatter.sh "<file>"` (description char count)
 
-   Vale runs separately as a repo-level PR check and via the TW's local editor extension - don't invoke it here. The delegated standards review (step 3) covers the same prose-style ground.
-3. **Delegated standards review** - spawn one subagent per standards file to check compliance. Each subagent reads the file being reviewed plus one standards file, and returns violations with line numbers and suggested fixes:
-   - Subagent 1: check against `standards/writing-style.md` (voice, tone, headings, links)
-   - Subagent 2: check against `standards/content-standards.md` (front matter, admonitions, code blocks)
-   - Subagent 3: check against `standards/terminology.md` (product names, article usage)
-   - Subagent 4: check against `standards/grammar-rules.md` (hyphenation, punctuation, brand spelling)
-   Launch all 4 in parallel.
-4. **Content review** (main process) - focus on what standards files don't cover:
+   Vale carries most of the style guide, so don't re-check its ground by hand. If it isn't installed, say so and note that prose coverage was skipped.
+
+   For a pull request, run all three over every changed `.md` and `.mdx` file and report per file.
+3. **Delegated review** - spawn two subagents in parallel, for what no tool can check. Each reads the page being reviewed plus one standards file, and returns findings with line numbers and suggested fixes:
+   - Subagent 1, `standards/style-guide.md`: bold outside UI elements and critical warnings, link text that doesn't say where it goes, non-parallel lists, missing serial commas, and loose use of "legacy", "alternative", or "deprecated"
+   - Subagent 2, `standards/page-structure.md`: stacked headings, concepts used before they're explained, screenshots that don't earn their place or break the treatment rules, admonitions that don't fit their content, outnumber one per H2 section, or carry content the prose needs
+4. **Content review** (main process) - focus on what neither tools nor standards cover:
    - Content structure (clear intro, logical flow, next steps)
    - Technical accuracy (code examples correct, API endpoints current)
    - Completeness (prerequisites listed, edge cases covered)
    - Code example quality (complete, runnable, commented where needed)
-5. **Format output** - merge subagent findings + deterministic results + content review per `.agents/skills/review-docs/references/review-format.md`
-
-Deterministic tools first, then delegated standards checks, then content review. Report tool failures as objective facts. Report standards and content findings as judgment calls.
+5. **Format output** - per `.agents/skills/review-docs/references/review-format.md`. Tool output goes in its own section, verbatim with rule names and line numbers. Judgment findings go in a separate section and must not restate anything a tool reported.
 
 For detailed process notes and edge cases, see `.agents/skills/review-docs/references/process.md`.

.agents/skills/review-docs/references/process.md

@@ -11,23 +11,24 @@ Agent-agnostic workflow for reviewing Apify documentation.
 
 These are objective - no judgment needed. Report all failures. Run in the main process (not in subagents).
 
+- `vale --minAlertLevel=suggestion "<file>"` (prose style: voice, tone, terminology, grammar, headings, link text)
 - `pnpm lint:md` (markdownlint: heading hierarchy, double spaces, list numbering)
 - `.agents/skills/review-docs/scripts/check-frontmatter.sh "<file>"` (description char count)
 
-Vale is not part of this skill. It runs as a repo-level PR check and via the TW's local editor extension, but devs aren't expected to install it, so shipping it in the per-file review flow would create dead weight. Prose-style coverage comes from the delegated standards review in step 3.
+Vale carries most of the style guide. Run it at suggestion level, since the default hides suggestions and some documented rules ship at that level. Report what it says rather than re-checking its ground by hand or handing it to a subagent.
 
-## Step 3: Delegated standards review
+If `vale` isn't installed, say so in the output. Don't substitute a subagent pass. The PR check runs at error level on changed files only, so a green check is not equivalent to a local run.
 
-Spawn one subagent per standards file to check compliance in parallel. Each subagent reads the file being reviewed plus one standards file, and returns violations with line numbers and suggested fixes.
+## Step 3: Delegated review
 
-- Subagent 1: check against `standards/writing-style.md` (voice, tone, headings, links)
-- Subagent 2: check against `standards/content-standards.md` (front matter, admonitions, code blocks)
-- Subagent 3: check against `standards/terminology.md` (product names, article usage)
-- Subagent 4: check against `standards/grammar-rules.md` (hyphenation, punctuation, brand spelling)
+Spawn subagents only for what no tool can check. Each reads the page being reviewed plus one standards file, and returns findings with line numbers and suggested fixes.
 
-Why subagents: each standards file gets dedicated attention. A single-pass review with a summary tends to miss edge cases (comma rules, article usage, brand spelling) that a focused read catches.
+- Subagent 1, `standards/style-guide.md`: bold on anything other than a UI element or a critical warning, link text that doesn't say where it goes, list items that break parallel structure, missing serial commas, and "legacy", "alternative", or "deprecated" used loosely
+- Subagent 2, `standards/page-structure.md`: stacked headings, concepts used before they're explained, screenshots that don't earn their place or break the treatment rules (light theme, `#F86606` border, no arrows or circles), admonition types that don't fit their content, admonitions past one per H2 section, and admonitions carrying content the prose needs
 
-Why not deterministic tools in subagents: subagents may have sandbox restrictions that prevent running Bash commands. Keep all tool execution in the main process.
+Everything else in the standards files is either enforced by Vale or checked by the scripts above. Subagents are only for judgment no rule can express, like whether an image carries information the prose doesn't, or whether `:::caution` is the right severity.
+
+Keep tool execution in the main process. Subagents may have sandbox restrictions that stop them running Bash.
 
 ## Step 4: Content review
 
@@ -36,17 +37,16 @@ Run in the main process. Focus on what neither deterministic tools nor standards
 - [ ] Content structure (clear intro, logical progression, next steps)
 - [ ] Technical accuracy (code examples correct, API endpoints current)
 - [ ] Completeness (prerequisites listed, edge cases addressed)
-- [ ] Text formatting judgment (is bold usage for a UI element or misuse?)
-- [ ] Link quality beyond "click here" (is the text genuinely descriptive?)
 - [ ] Code example quality (complete, runnable, commented where needed)
 
 ## Step 5: Format output
 
 Merge deterministic results + subagent findings + content review into structured output per `.agents/skills/review-docs/references/review-format.md`.
 
-- Tool findings are objective facts
-- Standards findings are rule-based judgment calls
+- Tool findings go in their own section, verbatim, with rule names and line numbers
+- Subagent findings are judgment calls against a documented rule
 - Content findings are subjective judgment calls
+- Never restate a tool finding as a judgment finding. If `vale` reported it, it belongs in the automated section only
 - Prioritize by impact: critical → important → minor
 
 ## Edge cases
@@ -61,4 +61,4 @@ Check that both JavaScript and Python examples are present and functionally equi
 
 ### Markdownlint false positives on admonitions
 
-Markdownlint doesn't understand Docusaurus `:::` syntax natively. Check `.markdownlint.json` for configured exceptions. Rely on the delegated standards review for prose-style judgment.
+Markdownlint doesn't understand Docusaurus `:::` syntax natively. Check `.markdownlint.json` for configured exceptions. Missing admonition titles are Vale's job, so they show up in the tool output rather than here.

.agents/skills/review-docs/references/review-format.md

@@ -2,20 +2,36 @@
 
 Use this format when providing documentation review feedback.
 
+Report tool output and judgment separately. Tool findings are facts with a rule name and a line number, and the reader can act on them without trusting your reading. Judgment findings need an argument.
+
 ## Template
 
 ```markdown
 ## Documentation review: [File name]
 
+### Automated checks
+
+| Check | Result |
+| --- | --- |
+| `vale --minAlertLevel=suggestion` | [N errors, N warnings, N suggestions, or "not installed, prose coverage skipped"] |
+| `pnpm lint:md` | [pass, or N issues] |
+| `check-frontmatter.sh` | [PASS/WARN/FAIL with the character count] |
+
+Findings, verbatim, most severe first:
+
+- `path:line` `Rule.Name` - [message]
+
 ### Strengths
 
 - [What's done well]
 
 ### Issues found
 
-#### Style guide
+Judgment calls only. Anything a tool already reported belongs in the section above, not here.
+
+#### Standards
 
-- [ ] Issue 1: [Description]
+- [ ] Issue 1: [Description, naming the rule it violates]
   - Current: [Example from the doc]
   - Suggested: [Better version]
 
@@ -26,67 +42,36 @@ Use this format when providing documentation review feedback.
 ### Suggestions
 
 - [Optional improvement 1]
-- [Optional improvement 2]
 
 ### Priority fixes
 
-1. [Critical issue - must fix before publishing]
-1. [Important issue - should fix]
-1. [Minor issue - nice to have]
+1. [Critical - must fix before publishing]
+1. [Important - should fix]
+1. [Minor - nice to have]
 ```
 
-## Common issues with examples
-
-### Title case or gerund headings
+When reviewing a pull request rather than a single page, run the automated checks over every changed `.md` and `.mdx` file and report them per file. The repo-level PR check only gates errors on changed files, so a local run surfaces warnings and suggestions that CI won't.
 
-```markdown
-# Bad - Title Case
-## How To Create An Actor
-
-# Bad - Gerund
-## Creating an Actor
+## Common issues with examples
 
-# Good - Sentence case, simple present tense
-## Create an Actor
-```
+Vale reports most style violations with a rule name and line number, so this section covers only what it can't judge.
 
 ### Non-descriptive links
 
-```markdown
-# Bad
-To learn more, click [here](link).
-
-# Good
-Learn more about [Actor input schemas](/actors/development/input-schema).
-```
-
-### Missing front matter description
+Vale catches a literal "click here". It can't tell whether other link text is genuinely descriptive.
 
 ```markdown
 # Bad
----
-title: "Actors"
----
+To learn more, see the [documentation](link).
 
 # Good
----
-title: "Create an Actor"
-description: "Learn how to build and deploy your first Actor with step-by-step instructions covering setup, development, and testing."
----
-```
-
-### Long or feature-focused description
-
-```markdown
-# Bad - Too long (190 chars) and feature-focused
-description: "This comprehensive documentation guide will teach you everything you need to know about creating, configuring, and deploying Actors on the Apify platform from start to finish."
-
-# Good - Value-focused (145 chars)
-description: "Build and deploy Actors efficiently with this guide covering setup, development, testing, and best practices for production use."
+Learn more about [Actor input schemas](/actors/development/input-schema).
 ```
 
 ### Bold used for emphasis
 
+Vale can't tell a UI element from emphasis, so this one is always a judgment call.
+
 ```markdown
 # Bad - bold used for emphasis
 Click the button and **ensure you verify** the settings.
@@ -95,38 +80,25 @@ Click the button and **ensure you verify** the settings.
 Click the **Save & Run** button and ensure you verify the settings.
 ```
 
-### Missing admonition title
+### Feature-focused description
 
-```markdown
-# Bad - no title (REQUIRED)
-:::tip
-Use pagination for large datasets.
-:::
-
-# Good - has title
-:::tip Performance
-Use pagination for large datasets.
-:::
-```
-
-### Incorrect Apify terminology
+`check-frontmatter.sh` verifies the 140-160 character range. It can't tell whether the description sells the feature or the outcome.
 
 ```markdown
-# Bad
-The Apify Console allows you to manage your Apify actors.
+# Bad - feature-focused
+description: "This comprehensive documentation guide will teach you everything you need to know about creating, configuring, and deploying Actors on the Apify platform."
 
-# Good
-Apify Console allows you to manage your Apify Actors.
+# Good - value-focused
+description: "Build and deploy Actors efficiently, covering local setup, development, testing, and the practices that keep them reliable once they run in production."
 ```
 
 ## Quality gate
 
 A document is ready for publication when:
 
-- All checklist items pass
-- Automated linting passes
-- Content is technically accurate
-- Examples are tested and working
-- Style guide is followed consistently
+- `vale` reports no errors, and any remaining warnings are deliberate
+- `pnpm lint:md` passes
+- `check-frontmatter.sh` passes, or warns on a description you've deliberately kept
+- The judgment items in `standards/quality-standards.md` are satisfied
+- Content is technically accurate, and examples are tested and working
 - No broken links
-- Proper front matter included

.agents/skills/review-docs/scripts/check-frontmatter.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Validates front matter description is 140-160 characters.
+# Validates frontmatter description is 140-160 characters.
 # Usage: check-frontmatter.sh <file-path>
 
 set -euo pipefail
@@ -16,21 +16,32 @@ if [ ! -f "$FILE" ]; then
     exit 1
 fi
 
-# Extract description from YAML front matter
-DESCRIPTION=$(awk '/^---$/{if(++c==2)exit}c==1&&/^description:/{sub(/^description:\s*/, ""); gsub(/^["'\''"]|["'\''"]$/, ""); print}' "$FILE")
+# Extract description from YAML frontmatter
+DESCRIPTION=$(awk '/^---$/{if(++c==2)exit}c==1&&/^description:/{sub(/^description:[[:space:]]*/, ""); gsub(/^["'\''"]|["'\''"]$/, ""); print}' "$FILE")
 
 if [ -z "$DESCRIPTION" ]; then
-    echo "FAIL: No description found in front matter"
+    echo "FAIL: No description found in frontmatter"
     exit 1
 fi
 
 LENGTH=${#DESCRIPTION}
 
-if [ "$LENGTH" -ge 140 ] && [ "$LENGTH" -le 160 ]; then
-    echo "PASS: Description is $LENGTH characters (140-160 range)"
+# The documented rule is 140-160 characters. Five characters either side warn
+# instead of failing, so a description that reads well isn't padded or trimmed
+# to hit an exact count.
+MIN=140
+MAX=160
+TOLERANCE=5
+
+if [ "$LENGTH" -ge "$MIN" ] && [ "$LENGTH" -le "$MAX" ]; then
+    echo "PASS: Description is $LENGTH characters ($MIN-$MAX range)"
+    exit 0
+elif [ "$LENGTH" -ge "$((MIN - TOLERANCE))" ] && [ "$LENGTH" -le "$((MAX + TOLERANCE))" ]; then
+    echo "WARN: Description is $LENGTH characters (target $MIN-$MAX, within the $TOLERANCE-character tolerance)"
+    echo "  Description: $DESCRIPTION"
     exit 0
 else
-    echo "FAIL: Description is $LENGTH characters (expected 140-160)"
+    echo "FAIL: Description is $LENGTH characters (expected $MIN-$MAX)"
     echo "  Description: $DESCRIPTION"
     exit 1
 fi

.agents/skills/tutorial/SKILL.md

@@ -11,7 +11,7 @@ argument-hint: topic
 
 1. **Identify tutorial type** - platform tutorial, academy tutorial, or integration tutorial
 2. **Research** - read related docs, check existing tutorials for style reference
-3. **Create front matter** - title (sentence case), description (140-160 chars), sidebar_position, slug
+3. **Create frontmatter** - title (sentence case), description (140-160 chars), sidebar_position, slug
 4. **Write 8-section structure**:
    1. Introduction with learning objectives
    2. Prerequisites (tools, accounts, knowledge)

.agents/skills/tutorial/references/process.md

@@ -14,7 +14,7 @@ Agent-agnostic workflow for creating structured Apify tutorials.
 - Check existing tutorials for style reference
 - Identify prerequisites the reader needs
 
-## Step 3: Create front matter
+## Step 3: Create frontmatter
 
 ```yaml
 ---
@@ -52,7 +52,7 @@ Each step should have a clear action verb, expected result, and verification. Co
 
 ### Build fails after adding tutorial
 
-Verify front matter has all required fields. Run `pnpm build` to catch broken links and slug issues.
+Verify frontmatter has all required fields. Run `pnpm build` to catch broken links and slug issues.
 
 ### Code examples don't render correctly
 

.agents/skills/tutorial/references/tutorial-template.md

@@ -2,7 +2,7 @@
 
 Complete 8-section template for Apify tutorials. Adapt sections based on tutorial type (platform, academy, integration).
 
-## Section 1: Front matter
+## Section 1: Frontmatter
 
 ```yaml
 ---

.claude/README.md

@@ -80,11 +80,9 @@ Use /review-docs skill to review sources/platform/[file-name].md
 
 All documentation standards are in `standards/` at the repo root:
 
-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. **`README.md`** - Index: what to read when, and how rules are enforced
+1. **`style-guide.md`** - Voice and tone, headings, text formatting, links, numbers, grammar, Apify terminology
+1. **`page-structure.md`** - Frontmatter, admonitions, code blocks, images, lists, file naming
 1. **`quality-standards.md`** - Complete quality checklist
 
 Also reference:

.cursor/rules/content-formatting.mdc

@@ -3,5 +3,5 @@ description: Content formatting standards for markdown and MDX files
 globs: ["sources/**/*.md", "sources/**/*.mdx"]
 alwaysApply: true
 ---
-For content formatting rules (front matter, admonitions, code blocks, images, lists), see `standards/content-standards.md`.
-For writing style rules (headings, tone, links, numbers), see `standards/writing-style.md`.
+For content formatting rules (frontmatter, admonitions, code blocks, images, lists), see `standards/page-structure.md`.
+For writing style rules (headings, tone, links, numbers), see `standards/style-guide.md`.