[Docs] Add comprehensive coding standards and linting improvements

.all-contributorsrc

@@ -0,0 +1,37 @@
+{
+  "projectName": "wp-docs",
+  "projectOwner": "lightspeedwp",
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectDescription": "WordPress documentation and Copilot assets for LightSpeed WordPress projects",
+  "projectWebsite": "https://lightspeedwp.agency",
+  "license": "GPL-3.0-or-later",
+  "files": [
+    "README.md"
+  ],
+  "imageSize": 100,
+  "commit": false,
+  "commitConvention": "conventional",
+  "contributors": [
+    {
+      "login": "lightspeedwp",
+      "name": "LightSpeedWP",
+      "avatar_url": "https://avatars.githubusercontent.com/u/lightspeedwp?v=4",
+      "profile": "https://github.com/lightspeedwp",
+      "contributions": [
+        "ideas",
+        "fundingFinding",
+        "projectManagement",
+        "business",
+        "code",
+        "design",
+        "doc",
+        "infra",
+        "maintenance",
+        "test"
+      ]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "linkToUsage": true
+}

.all-contributorsrc-docs.md

@@ -0,0 +1,60 @@
+# All Contributors Configuration Documentation
+
+This document explains the configuration options used in `.all-contributorsrc` for the wp-docs project.
+
+## Configuration Options
+
+### Basic Project Information
+
+- `projectName`: "wp-docs" - WordPress documentation and Copilot assets repository
+- `projectOwner`: "lightspeedwp" - GitHub organization that owns the repository
+- `repoType`: "github" - Type of version control system
+- `repoHost`: "https://github.com" - Base URL for the repository host
+- `projectDescription`: "WordPress documentation and Copilot assets for LightSpeed WordPress projects"
+- `projectWebsite`: "https://lightspeedwp.agency" - Official project website URL
+- `license`: "GPL-3.0-or-later" - Project license identifier
+
+### Display Settings
+
+- `files`: ["README.md"] - Array of files where contributor information will be displayed
+- `imageSize`: 100 - Size of contributor avatar images in pixels
+- `contributorsPerLine`: 7 - Number of contributors to display per line in the README
+- `linkToUsage`: true - Whether to include a link to all-contributors usage information
+
+### Git Integration
+
+- `commit`: false - Whether to automatically commit changes (disabled for manual control)
+- `commitConvention`: "conventional" - Commit message convention to follow
+
+### Contributors Array
+
+Each contributor object contains:
+
+- `login`: GitHub username/handle
+- `name`: Display name for the contributor
+- `avatar_url`: GitHub profile avatar image URL
+- `profile`: Link to contributor's GitHub profile
+- `contributions`: Array of contribution types
+
+## Contribution Types Used in This Project
+
+### LightSpeedWP Organization
+
+The organization contributes across all areas of the project:
+
+- `ideas`: Contributed ideas and concepts for WordPress documentation standards
+- `fundingFinding`: Helped find funding for the project development
+- `projectManagement`: Managed project tasks and coordination
+- `business`: Handled business aspects and strategy
+- `code`: Wrote automation scripts and tooling
+- `design`: Created design systems and documentation structure
+- `doc`: Wrote comprehensive WordPress documentation and guides
+- `infra`: Set up and maintained development infrastructure
+- `maintenance`: Ongoing project maintenance and updates
+- `test`: Wrote tests and performed quality assurance
+
+## Usage Commands
+
+- `npm run contributors:add` - Add a new contributor
+- `npm run contributors:generate` - Generate contributor table
+- `npm run contributors:check` - Check contributor configuration

.coderabbit.yml

@@ -1,16 +1,131 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# Configuration tailored for wp-docs (WordPress block/theme documentation & Copilot asset library)
+# Reference: https://docs.coderabbit.ai/guides/configure-coderabbit/
+
+# Set review language to UK English to match repository documentation standards (see AGENTS.md)
+language: "en-GB" # Align with AGENTS.md (UK English for documentation); code identifiers remain unchanged.
+
+# Disable early access features for stable, consistent review experience
+early_access: false
+
 reviews:
+  profile: "balanced"
+  request_changes_workflow: true
+  high_level_summary: true
+  review_status: true
+  collapse_walkthrough: false
+  poem: false
+  # Exclude paths that don't need review (dependencies, build outputs, temporary agent files)
+  path_filters:
+    - "!**/node_modules/**"
+    - "!**/dist/**"
+    - "!**/.agent_work/**"
+  auto_review:
+    enabled: true
+    drafts: false
+    ignore_title_keywords:
+      - "WIP"
+      - "DO NOT MERGE"
+    base_branches:
+      - main
+      - develop
+      - docs/*
+      - instructions/*
+      - prompts/*
+      - chatmodes/*
+      - chore/*
+
+  # Targeted instruction sets per path
   path_instructions:
     - path: "**/*.md"
       instructions: |
-        Review the Markdown documentation for:
-        - Clarity and conciseness of explanations
-        - Consistent formatting and heading structure
-        - Proper use of code blocks and inline code
-        - Correct spelling, grammar, and punctuation
-        - Accurate and up-to-date technical information
-        - Useful internal and external links
-        - Well-organized sections and logical flow
-
-  Additional context:
-  - The repository contains documentation focused on block theme and block plug-in development topics for WordPress and related technologies.
-  - Please ensure that technical docs are developer-friendly, accurate, and up-to-date.
+        Documentation Review Focus:
+        - One sentence per line where practical (improves diff clarity)
+        - Clear hierarchy (h1 once; meaningful h2/h3 order; no level skipping)
+        - UK English spelling (colour, organisation, behaviour) except in code/API examples
+        - Accessibility & inclusivity of examples (avoid ableist / gendered assumptions)
+        - Accuracy: WordPress APIs, Gutenberg block concepts, theme.json tokens
+        - Remove duplication; prefer canonical cross-links instead of copy/paste
+        - Ensure internal links resolve (relative paths) & external links use HTTPS
+        - For long lists: consider tables for scanability; ensure no trailing placeholder text
+        - For code samples: prefer minimal, runnable, security-conscious examples (escaping, sanitisation)
+        Reject only for: factual errors, unsafe patterns, structural incoherence—not minor stylistic opinions.
+    - path: ".github/instructions/*.instructions.md"
+      instructions: |
+        Instruction Files Review:
+        - Front matter: description (single quoted), applyTo pattern present
+        - Scope clarity: no overlap with other instruction files without rationale
+        - Consistency with existing security/a11y/performance standards
+        - Avoid redundancy—reference shared guidance instead of restating
+        - Ensure examples use current WordPress APIs & escaping (esc_html, esc_attr, wp_kses_post)
+        - Flag ambiguous or aspirational language (“probably”, “maybe”)—prefer imperative clarity
+    - path: ".github/prompts/*.prompts.md"
+      instructions: |
+        Prompt Files Review:
+        - Front matter: description, mode (agent|ask), encourage model & tools fields
+        - Name reflects task (lowercase-hyphen) & not a duplicate of existing prompt
+        - Body: single authoritative task pattern; avoid multi‑persona drift
+        - No hidden side effects (should not instruct destructive repository changes unless clearly labelled)
+        - Ensure migration: legacy .prompt.md references removed or marked deprecated
+    - path: ".github/chatmodes/*.chatmodes.md"
+      instructions: |
+        Chat Modes Review:
+        - Front matter includes description & optional tools list sized to stated purpose
+        - No overlap with consolidated modes (e.g., planning, accessibility) unless extension is explicit
+        - Deprecation blocks present for replaced variants (deprecated: true, replacement: <file>)
+        - Check persona scope creep (avoid over-promising omnipotent abilities)
+        - Security: discourage broad autonomous destructive behaviour
+    - path: ".github/scripts/*.js"
+      instructions: |
+        Script Review:
+        - Focus: correctness, idempotence, error handling, path safety
+        - Avoid unnecessary fs sync loops in hot paths (acceptable for small repo generation tasks)
+        - Ensure backward compatibility notes retained during migrations
+        - Prefer descriptive constant names over comments explaining magic values
+    - path: ".github/workflows/*.yml"
+      instructions: |
+        Workflow Review:
+        - Principle of least privilege (scoped permissions: contents: read where possible)
+        - Caching correctness (restore-keys order, hash input stability)
+        - No plaintext secrets; encourage use of secrets store
+        - Matrix limits reasonable; avoid unbounded strategy expansion
+    - path: "**/*.php"
+      instructions: |
+        PHP Review (WordPress Focus):
+        - Input sanitisation (sanitize_text_field, esc_url_raw, absint) & output escaping (esc_html/esc_attr) applied appropriately
+        - Capability checks (current_user_can) instead of role names
+        - Nonces for state‑changing actions; verify with check_admin_referer
+        - Avoid direct access to superglobals in templates—wrap in helper functions
+        - Performance: no unbounded WP_Query loops; leverage caching where justified
+    - path: "**/*.js"
+      instructions: |
+        JavaScript Review:
+        - No direct innerHTML with unsanitised content
+        - Avoid large synchronous operations blocking main thread
+        - Prefer WP packages (@wordpress/*) over reinventing editor APIs
+        - Accessibility: focus management on dynamic components; ARIA only if semantics missing
+    - path: "**/*.py"
+      instructions: |
+        Python Review:
+        - Note: _, pgettext, ngettext variations are globally defined (ignore undefined warnings)
+        - Prefer pathlib & context managers; parameterise any SQL; no shell string concatenation
+    - path: "user_docs/en/changes.md"
+      instructions: |
+        Changelog Review:
+        - Each entry links an issue or PR (#123) and optional @author handle
+        - Group multi-line entries under a bullet with sub-items
+        - No future tense for released changes; use past or imperative for unreleased
+
+  reviewers:
+    - default
+
+tools:
+  github-checks:
+    enabled: true
+  ruff:
+    enabled: true
+  markdownlint:
+    enabled: true
+
+chat:
+  auto_reply: true

.editorconfig

@@ -1,21 +1,21 @@
 # EditorConfig is awesome: https://EditorConfig.org
 
-# top-most EditorConfig file
+# Indicate this is the top-most EditorConfig file (stop searching parent directories)
 root = true
 
-# All files
+# Universal settings for all files in the repository
 [*]
-indent_style = space
-indent_size = 2
-end_of_line = lf
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
+indent_style = space          # Use spaces instead of tabs for consistency
+indent_size = 2               # Standard 2-space indentation for most files
+end_of_line = lf              # Unix-style line endings for cross-platform compatibility
+charset = utf-8               # UTF-8 encoding for international character support
+trim_trailing_whitespace = true  # Remove trailing whitespace to keep files clean
+insert_final_newline = true   # Ensure files end with a newline for POSIX compliance
 
-# Markdown files
+# Markdown files - preserve trailing spaces (used for line breaks) and allow long lines
 [*.md]
-trim_trailing_whitespace = false
-max_line_length = off
+trim_trailing_whitespace = false  # Preserve intentional trailing spaces for markdown line breaks
+max_line_length = off            # Allow long lines for readability (handled by markdownlint)
 
 # JSON files
 [*.json]

.eslintrc.config.md

@@ -0,0 +1,51 @@
+# ESLint Configuration Documentation
+
+This document explains the ESLint configuration in `.eslintrc.json` for the wp-docs repository.
+
+## Configuration Overview
+
+The ESLint configuration ensures consistent JavaScript code quality across all script files in the repository, including automation scripts and any WordPress-related JavaScript.
+
+## Configuration Breakdown
+
+### Environment Settings (`env`)
+- **`browser: true`** - Enable browser globals (window, document, etc.) for client-side scripts
+- **`es2022: true`** - Enable ES2022 features and syntax
+- **`node: true`** - Enable Node.js globals and scope for automation scripts
+
+### Extended Configurations (`extends`)
+- **`eslint:recommended`** - Standard ESLint recommended rules for code quality
+- **`prettier`** - Disable ESLint formatting rules that conflict with Prettier formatting
+
+### Parser Options (`parserOptions`)
+- **`ecmaVersion: "latest"`** - Use the latest ECMAScript version for modern syntax
+- **`sourceType: "module"`** - Enable ES6 modules (import/export syntax)
+
+### Custom Rules (`rules`)
+- **`indent: ["error", 4]`** - Enforce 4-space indentation (matches Prettier config)
+- **`linebreak-style: ["error", "unix"]`** - Enforce Unix line endings (LF)
+- **`quotes: ["error", "single"]`** - Enforce single quotes for strings
+- **`semi: ["error", "always"]`** - Require semicolons for statement termination
+- **`no-console: "warn"`** - Warn about console statements (acceptable in scripts)
+- **`no-unused-vars: "warn"`** - Warn about unused variables (helps catch errors)
+
+### Ignore Patterns (`ignorePatterns`)
+Files and directories excluded from linting:
+- **`node_modules/`** - Third-party dependencies
+- **`dist/`** - Build output directory
+- **`build/`** - Alternative build output directory
+
+## Usage
+
+The configuration is automatically applied when running:
+- `npm run lint:js` - Lint JavaScript files
+- `npm run lint:fix` - Auto-fix linting issues where possible
+
+## WordPress Development Notes
+
+This configuration is designed to work well with:
+- WordPress Gutenberg block development (modern JavaScript)
+- Node.js automation scripts in `.github/scripts/`
+- Build tools and development utilities
+
+The rules align with WordPress JavaScript coding standards while allowing modern ES6+ syntax for development tooling.

.eslintrc.json

@@ -0,0 +1,24 @@
+{
+    "env": {
+        "browser": true,
+        "es2022": true,
+        "node": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "prettier"
+    ],
+    "parserOptions": {
+        "ecmaVersion": "latest",
+        "sourceType": "module"
+    },
+    "rules": {
+        "indent": ["error", 4],
+        "linebreak-style": ["error", "unix"],
+        "quotes": ["error", "single"],
+        "semi": ["error", "always"],
+        "no-console": "warn",
+        "no-unused-vars": "warn"
+    },
+    "ignorePatterns": ["node_modules/", "dist/", "build/"]
+}

.gitattributes

@@ -1,7 +1,7 @@
-# Set default behavior to automatically normalize line endings.
+# Set default behavior to automatically normalize line endings for cross-platform compatibility
 * text=auto eol=lf
 
-# Explicitly declare text files to be normalized and converted to native line endings on checkout.
+# Explicitly declare text files to ensure consistent line ending handling across platforms
 *.md text eol=lf
 *.txt text eol=lf
 *.js text eol=lf
@@ -14,11 +14,11 @@
 *.ts text eol=lf
 *.sh text eol=lf
 
-# Windows-specific files that should retain CRLF line endings
+# Windows-specific script files that require CRLF line endings to function properly
 *.bat text eol=crlf
 *.cmd text eol=crlf
 
-# Binary files that should not be modified
+# Binary files that should not have line ending conversion or text processing applied
 *.png binary
 *.jpg binary
 *.jpeg binary