docs: add detailed agent instructions for testing and spellchecking

- Add section on testing and verifying changes locally
- Add comprehensive spellchecking guidance with dictionary setup
- Add documentation versioning guidelines
- Reference human-centric guidelines (DCO, PR etiquette) to CONTRIBUTING.md
- Add troubleshooting section for spellcheck failures

Signed-off-by: Jonah Kowall <[email protected]>

Author: jkowall

AGENTS.md

@@ -19,6 +19,10 @@ Before making changes, familiarize yourself with:
 The CONTRIBUTING.md file contains all necessary information for setting up,
 building, linting, and making changes to the documentation.
 
+**For human-centric guidelines** such as DCO (Developer Certificate of Origin)
+signing, PR etiquette, and community interaction, refer to [CONTRIBUTING.md](CONTRIBUTING.md)
+and the [general contributing guidelines](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md).
+
 ## Agentic Workflow Tips
 
 ### Repository Structure
@@ -41,6 +45,125 @@ efficiently:
 - **Deployment**: Netlify automatically deploys from the `main` branch
 - **Preview**: Netlify creates preview deployments for PRs
 
+### Testing and Verifying Changes
+
+Before submitting a PR, verify your changes locally:
+
+#### 1. Setup (First Time Only)
+
+```bash
+npm install
+```
+
+This installs all dependencies including the required Hugo version.
+
+#### 2. Run the Site Locally
+
+```bash
+make develop
+# or
+npm run serve
+```
+
+This starts a local server at [localhost:1313](http://localhost:1313) with hot
+reload. Verify your changes render correctly in the browser.
+
+#### 3. Build the Site
+
+```bash
+npm run build
+```
+
+Ensure the build completes without errors before submitting a PR.
+
+#### 4. Run All Checks
+
+Run these commands to verify CI will pass:
+
+```bash
+npm run check:format      # Check code formatting
+npm run check:spelling    # Run spellcheck
+npm run check:links:internal  # Check internal links (faster)
+npm run check:filenames   # Check filename conventions
+```
+
+For comprehensive link checking (including external links):
+
+```bash
+npm run check:links:all   # Check all links (slower, builds site first)
+```
+
+#### 5. Fix Common Issues
+
+```bash
+npm run fix:format        # Auto-fix formatting issues
+npm run fix:filenames     # Convert underscores to hyphens in filenames
+npm run fix               # Run both fixes
+```
+
+### Code Quality Checks
+
+Before creating a PR, run the following checks to ensure CI passes:
+
+```bash
+npm run check:format      # Check code formatting
+npm run check:spelling    # Run spellcheck
+npm run check:links:internal  # Check internal links
+npm run check:filenames   # Check filename conventions
+```
+
+To automatically fix issues:
+
+```bash
+npm run fix:format        # Fix formatting issues
+npm run fix:filenames     # Fix filename convention violations
+```
+
+### Spellchecking
+
+The repository uses [cspell](https://cspell.org/) for spellchecking. Configuration
+is in `.cspell.yml` with custom dictionaries in the `.cspell/` directory.
+
+#### Running Spellcheck
+
+```bash
+npm run check:spelling
+```
+
+This checks all content in `content/` and markdown files in `layouts/`.
+
+#### Adding Words to the Dictionary
+
+If the spellchecker flags a legitimate word (technical term, proper noun, etc.):
+
+1. **For general technical terms**: Add to `.cspell/project-words.txt`
+2. **For people's names**: Add to `.cspell/project-names-src.txt`
+
+**Important rules for `project-words.txt`:**
+
+- Words must be sorted alphabetically (case-insensitive)
+- One word per line
+- The file is case-sensitive, so add the exact casing needed
+- Run `sort -c --ignore-case .cspell/project-words.txt` to verify sorting
+
+Example of adding a word:
+
+```bash
+# Add the word in the correct alphabetical position
+# Then verify the file is properly sorted:
+sort -c --ignore-case .cspell/project-words.txt
+```
+
+#### Verifying Spellcheck Passes
+
+After adding words:
+
+```bash
+npm run check:spelling
+```
+
+If no output and exit code 0, the spellcheck passes.
+
 ### Troubleshooting
 
 #### Link Checker Issues
@@ -67,6 +190,25 @@ If CI complains about filename conventions:
 npm run fix:filenames
 ```
 
+#### Spellcheck Failures
+
+If spellcheck fails:
+
+1. Review the flagged words in the output
+2. If the word is misspelled, fix it in the content
+3. If the word is legitimate, add it to the appropriate dictionary file
+4. Ensure `project-words.txt` remains sorted alphabetically
+
+### Documentation Versioning
+
+When making documentation changes:
+
+- **New features/changes**: Edit files in `content/docs/v2/_dev/` (for next release)
+- **Fixes for current version**: Apply to both `_dev/` and the most recent version
+  directory (e.g., `content/docs/v2/2.x/`) so changes appear immediately on the
+  live site
+- **Backporting**: Update older version directories if the fix applies to them
+
 ### Additional Resources
 
 - [Hugo Documentation](https://gohugo.io/documentation/)